From jdo-commits-return-290-apmail-db-jdo-commits-archive=www.apache.org@db.apache.org Mon Mar 28 18:25:23 2005 Return-Path: Delivered-To: apmail-db-jdo-commits-archive@www.apache.org Received: (qmail 63522 invoked from network); 28 Mar 2005 18:25:23 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 28 Mar 2005 18:25:23 -0000 Received: (qmail 59472 invoked by uid 500); 28 Mar 2005 18:25:23 -0000 Mailing-List: contact jdo-commits-help@db.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: jdo-dev@db.apache.org Delivered-To: mailing list jdo-commits@db.apache.org Received: (qmail 59448 invoked by uid 99); 28 Mar 2005 18:25:22 -0000 X-ASF-Spam-Status: No, hits=-9.8 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from minotaur.apache.org (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.28) with SMTP; Mon, 28 Mar 2005 10:25:18 -0800 Received: (qmail 63475 invoked by uid 65534); 28 Mar 2005 18:25:17 -0000 Message-ID: <20050328182517.63473.qmail@minotaur.apache.org> Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Mailer: svnmailer-1.0.0-dev Date: Mon, 28 Mar 2005 18:25:17 -0000 Subject: svn commit: r159273 [4/5] - in incubator/jdo/trunk/api20: ./ src/java/ src/java/javax/ src/java/javax/jdo/ src/java/javax/jdo/datastore/ src/java/javax/jdo/identity/ src/java/javax/jdo/listener/ src/java/javax/jdo/spi/ test/ test/java/ test/java/javax/ test/java/javax/jdo/ test/java/javax/jdo/identity/ test/java/javax/jdo/listener/ To: jdo-commits@db.apache.org From: clr@apache.org X-Virus-Checked: Checked X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N Added: incubator/jdo/trunk/api20/src/java/javax/jdo/spi/I18NHelper.java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax= /jdo/spi/I18NHelper.java?view=3Dauto&rev=3D159273 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- incubator/jdo/trunk/api20/src/java/javax/jdo/spi/I18NHelper.java (added) +++ incubator/jdo/trunk/api20/src/java/javax/jdo/spi/I18NHelper.java Mon Ma= r 28 10:25:05 2005 @@ -0,0 +1,356 @@ +/* + * Copyright 2005 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at=20 + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software=20 + * distributed under the License is distributed on an "AS IS" BASIS,=20 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= .=20 + * See the License for the specific language governing permissions and=20 + * limitations under the License. + */ + +/* + * I18NHelper.java + * + */ + +package javax.jdo.spi; + +import java.util.*; +import java.text.MessageFormat; +import java.security.AccessController; +import java.security.PrivilegedAction; + +import javax.jdo.JDOFatalInternalException; + +/** Helper class for constructing messages from bundles. The intended usa= ge + * of this class is to construct a new instance bound to a bundle, as in + *

+ * I18NHelper msg =3D I18NHelper.getInstance("javax.jdo.Bundle"); + *

+ * This call uses the class loader that loaded the I18NHelper class to find + * the specified Bundle. The class provides two overloaded getInstance + * methods allowing to specify a different class loader:=20 + * {@link #getInstance(Class cls)} looks for a bundle + * called "Bundle.properties" located in the package of the specified clas= s=20 + * object and {@link #getInstance(String bundleName,ClassLoader loader)}=20 + * uses the specified class loader to find the bundle. + *

+ * Subsequently, instance methods can be used to format message strings=20 + * using the text from the bundle, as in=20 + *

+ * throw new JDOFatalInternalException (msg.msg("ERR_NoMetadata", cl= s=2EgetName())); + * @since 1.0.1 + * @version 1.0.2 + */ =20 +public class I18NHelper { + + /** Bundles that have already been loaded=20 + */ + private static Hashtable bundles =3D new Hashtable(); + =20 + /** Helper instances that have already been created=20 + */ + private static Hashtable helpers =3D new Hashtable(); + =20 + /** The default locale for this VM. + */ + private static Locale locale =3D Locale.getDefault(); + =20 + /** The bundle used by this instance of the helper. + */ + private ResourceBundle bundle =3D null; + + /** Throwable if ResourceBundle couldn't be loaded + */ + private Throwable failure =3D null; + + /** The unqualified standard name of a bundle. */ + private static final String bundleSuffix =3D ".Bundle"; // NOI18N + + /** Constructor */ + private I18NHelper() { + } + + /** Constructor for an instance bound to a bundle. + * @param bundleName the name of the resource bundle + * @param loader the class loader from which to load the resource + * bundle + */ + private I18NHelper (String bundleName, ClassLoader loader) { + try { + bundle =3D loadBundle (bundleName, loader); + } + catch (Throwable e) { + failure =3D e; + } + } + =20 + /** An instance bound to a bundle. This method uses the current class=20 + * loader to find the bundle. + * @param bundleName the name of the bundle + * @return the helper instance bound to the bundle + */ + public static I18NHelper getInstance (String bundleName) { + return getInstance (bundleName, I18NHelper.class.getClassLoader()); + } + + /** An instance bound to a bundle. This method figures out the bundle = name + * for the class object's package and uses the class' class loader to + * find the bundle. Note, the specified class object must not be + * null. + * @param cls the class object from which to load the resource bundle + * @return the helper instance bound to the bundle + */ + public static I18NHelper getInstance (final Class cls) { + ClassLoader classLoader =3D (ClassLoader) AccessController.doPrivi= leged ( + new PrivilegedAction () { + public Object run () { + return cls.getClassLoader(); + } + } + ); + String bundle =3D getPackageName (cls.getName()) + bundleSuffix; + return getInstance (bundle, classLoader); + } + + /** An instance bound to a bundle. This method uses the specified class + * loader to find the bundle. Note, the specified class loader must not + * be null. + * @param bundleName the name of the bundle + * @param loader the class loader from which to load the resource + * bundle + * @return the helper instance bound to the bundle + */ + public static I18NHelper getInstance (String bundleName,=20 + ClassLoader loader) { + I18NHelper helper =3D (I18NHelper) helpers.get (bundleName); + if (helper !=3D null) { + return helper; + } + helper =3D new I18NHelper(bundleName, loader); + helpers.put (bundleName, helper); + // if two threads simultaneously create the same helper, return th= e first + // one to be put into the Hashtable. The other will be garbage co= llected. + return (I18NHelper) helpers.get (bundleName); + } + + /** Message formatter + * @param messageKey the message key + * @return the resolved message text + */ + public String msg (String messageKey) { + assertBundle (messageKey); + return getMessage (bundle, messageKey); + } + + /** Message formatter + * @param messageKey the message key + * @param arg1 the first argument + * @return the resolved message text + */ + public String msg (String messageKey, Object arg1) { + assertBundle (messageKey); + return getMessage (bundle, messageKey, arg1); + } + + /** Message formatter + * @param messageKey the message key + * @param arg1 the first argument + * @param arg2 the second argument + * @return the resolved message text + */ + public String msg (String messageKey, Object arg1, Object arg2) { + assertBundle (messageKey); + return getMessage (bundle, messageKey, arg1, arg2); + } + + /** Message formatter + * @param messageKey the message key + * @param arg1 the first argument + * @param arg2 the second argument + * @param arg3 the third argument + * @return the resolved message text + */ + public String msg (String messageKey, Object arg1, Object arg2, Object= arg3) { + assertBundle (messageKey); + return getMessage (bundle, messageKey, arg1, arg2, arg3); + } + + /** Message formatter + * @param messageKey the message key + * @param args the array of arguments + * @return the resolved message text + */ + public String msg (String messageKey, Object[] args) { + assertBundle (messageKey); + return getMessage (bundle, messageKey, args); + } + + /** Message formatter + * @param messageKey the message key + * @param arg the argument + * @return the resolved message text + */ + public String msg (String messageKey, int arg) { + assertBundle (messageKey); + return getMessage(bundle, messageKey, arg); + } + =20 + /** Message formatter + * @param messageKey the message key + * @param arg the argument + * @return the resolved message text + */ + public String msg (String messageKey, boolean arg) { + assertBundle (messageKey); + return getMessage(bundle, messageKey, arg); + } + =20 + //=3D=3D=3D=3D=3D=3D=3D=3D=3D Internal helper methods =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + + /** + * Load ResourceBundle by bundle name + * @param bundleName the name of the bundle + * @param loader the class loader from which to load the resource bund= le + * @return the ResourceBundle + */ + final private static ResourceBundle loadBundle( + String bundleName, ClassLoader loader) { + ResourceBundle messages =3D (ResourceBundle)bundles.get(bundleName= ); + + if (messages =3D=3D null) //not found as loaded - add + { + messages =3D ResourceBundle.getBundle(bundleName, locale, load= er); + bundles.put(bundleName, messages); + } + return messages; + } + + /** Assert resources available + * @param key the message key=20 + * @since 1.0.2 + * @throws JDOFatalInternalException if the resource bundle could not + * be loaded during construction. + */ + private void assertBundle (String key) { + if (failure !=3D null) + throw new JDOFatalInternalException ( + "No resources could be found to annotate error message key= :\"" +=20 + key + "\"", failure); + } + + /** + * Returns message as String + * @param messages the resource bundle + * @param messageKey the message key + * @return the resolved message text + */ + final private static String getMessage(ResourceBundle messages, String= messageKey)=20 + { + return messages.getString(messageKey); + } + + /** + * Formats message by adding array of arguments + * @param messages the resource bundle + * @param messageKey the message key + * @param msgArgs an array of arguments to substitute into the message + * @return the resolved message text + */ + final private static String getMessage(ResourceBundle messages, String= messageKey, Object msgArgs[])=20 + { + for (int i=3D0; iObject argument. + * @param messages the resource bundle + * @param messageKey the message key + * @param arg the argument + * @return the resolved message text + */ + final private static String getMessage(ResourceBundle messages, String= messageKey, Object arg)=20 + { + Object []args =3D {arg}; + return getMessage(messages, messageKey, args); + } + =20 + /** + * Formats message by adding two Object arguments. + * @param messages the resource bundle + * @param messageKey the message key + * @param arg1 the first argument + * @param arg2 the second argument + * @return the resolved message text + */ + final private static String getMessage(ResourceBundle messages, String= messageKey, Object arg1, + Object arg2)=20 + { + Object []args =3D {arg1, arg2}; + return getMessage(messages, messageKey, args); + } + =20 + /** + * Formats message by adding three Object arguments. + * @param messages the resource bundle + * @param messageKey the message key + * @param arg1 the first argument + * @param arg2 the second argument + * @param arg3 the third argument + * @return the resolved message text + */ + final private static String getMessage(ResourceBundle messages, String= messageKey, Object arg1, + Object arg2, Object arg3)=20 + { + Object []args =3D {arg1, arg2, arg3}; + return getMessage(messages, messageKey, args); + } + + /** + * Formats message by adding an int as an argument. + * @param messages the resource bundle + * @param messageKey the message key + * @param arg the argument + * @return the resolved message text + */ + final private static String getMessage(ResourceBundle messages, String= messageKey, int arg)=20 + { + Object []args =3D {new Integer(arg)}; + return getMessage(messages, messageKey, args); + } + =20 + /** + * Formats message by adding a boolean as an argument. + * @param messages the resource bundle + * @param messageKey the message key + * @param arg the argument + * @return the resolved message text + */ + final private static String getMessage(ResourceBundle messages, String= messageKey, boolean arg)=20 + { + Object []args =3D {String.valueOf(arg)}; + return getMessage(messages, messageKey, args); + } + + /** =20 + * Returns the package portion of the specified class. + * @param className the name of the class from which to extract the=20 + * package=20 + * @return package portion of the specified class + */ =20 + final private static String getPackageName(final String className) + {=20 + final int index =3D className.lastIndexOf('.'); + return ((index !=3D -1) ? className.substring(0, index) : ""); // = NOI18N + } +} Added: incubator/jdo/trunk/api20/src/java/javax/jdo/spi/JDOImplHelper.java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax= /jdo/spi/JDOImplHelper.java?view=3Dauto&rev=3D159273 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- incubator/jdo/trunk/api20/src/java/javax/jdo/spi/JDOImplHelper.java (ad= ded) +++ incubator/jdo/trunk/api20/src/java/javax/jdo/spi/JDOImplHelper.java Mon= Mar 28 10:25:05 2005 @@ -0,0 +1,587 @@ +/* + * Copyright 2005 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at=20 + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software=20 + * distributed under the License is distributed on an "AS IS" BASIS,=20 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= .=20 + * See the License for the specific language governing permissions and=20 + * limitations under the License. + */ + +/* + * JDOImplHelper.java + * + */ + +package javax.jdo.spi; + +import java.util.HashMap; +import java.util.WeakHashMap; +import java.util.HashSet; +import java.util.Map; +import java.util.Set; +import java.util.List; +import java.util.ArrayList; +import java.util.Iterator; +import java.util.Collection; +import java.util.Collections; + +import javax.jdo.spi.JDOPermission; +import javax.jdo.JDOFatalUserException; +import javax.jdo.JDOFatalInternalException; + +/** This class is a helper class for JDO implementations. It contains met= hods + * to register metadata for persistence-capable classes and to perform com= mon + * operations needed by implementations, not by end users. + *

JDOImplHelper allows construction of instances of persi= stence-capable + * classes without using reflection. + *

Persistence-capable classes register themselves via a static method=20 + * at class load time. + * There is no security restriction on this access. JDO implementations + * get access to the functions provided by this class only if they are + * authorized by the security manager. To avoid having every call go thro= ugh + * the security manager, only the call to get an instance is checked. Onc= e an=20 + * implementation + * has an instance, any of the methods can be invoked without security che= cks. + * @version 1.0.2 + * + */ +public class JDOImplHelper extends java.lang.Object { + =20 + /** This synchronized HashMap contains a static mapping of + * PersistenceCapable class to + * metadata for the class used for constructing new instances. New en= tries + * are added by the static method in each PersistenceCapable class. + * Entries are never removed. + */ =20 + private static Map registeredClasses =3D Collections.synchronizedMap(n= ew HashMap ()); + =20 + /** This Set contains all classes that have registered for setStateMan= ager + * permissions via authorizeStateManagerClass. + */ + private static Map authorizedStateManagerClasses =3D new WeakHashMap(); + + /** This list contains the registered listeners for RegisterClas= sEvents. + */ + private static List listeners =3D new ArrayList(); + + /** The singleton JDOImplHelper instance. + */ =20 + private static JDOImplHelper jdoImplHelper =3D new JDOImplHelper(); + =20 + /** The Internationalization message helper. + */ + private final static I18NHelper msg =3D I18NHelper.getInstance ("javax= .jdo.Bundle"); + =20 + /** Creates new JDOImplHelper */ + private JDOImplHelper() { + } + =20 + /** Get an instance of JDOImplHelper. This method + * checks that the caller is authorized for JDOPermission("getMe= tadata"), + * and if not, throws SecurityException. + * @return an instance of JDOImplHelper. + * @throws SecurityException if the caller is not authorized for JDOPe= rmission("getMetadata"). + */ =20 + public static JDOImplHelper getInstance()=20 + throws SecurityException { =20 + SecurityManager sec =3D System.getSecurityManager(); + if (sec !=3D null) {=20 + // throws exception if caller is not authorized + sec.checkPermission (JDOPermission.GET_METADATA); + } + return jdoImplHelper; + } + =20 + /** Get the field names for a PersistenceCapable class. = The order=20 + * of fields is the natural ordering of the String class = (without + * considering localization). + * @param pcClass the PersistenceCapable class. + * @return the field names for the class. + */ =20 + public String[] getFieldNames (Class pcClass) { + Meta meta =3D getMeta (pcClass); + return meta.getFieldNames(); + } + + /** Get the field types for a PersistenceCapable class. = The order + * of fields is the same as for field names. + * @param pcClass the PersistenceCapable class. + * @return the field types for the class. + */ =20 + public Class[] getFieldTypes (Class pcClass) { + Meta meta =3D getMeta (pcClass); + return meta.getFieldTypes(); + } + =20 + /** Get the field flags for a PersistenceCapable class. = The order + * of fields is the same as for field names. + * @param pcClass the PersistenceCapable class. + * @return the field types for the class. + */ =20 + public byte[] getFieldFlags (Class pcClass) { + Meta meta =3D getMeta (pcClass); + return meta.getFieldFlags(); + } + =20 + /** Get the persistence-capable superclass for a PersistenceCapa= ble class. + * @param pcClass the PersistenceCapable class. + * @return The PersistenceCapable superclass for this cla= ss, + * or null if there isn't one. + */ =20 + public Class getPersistenceCapableSuperclass (Class pcClass) { + Meta meta =3D getMeta (pcClass); + return meta.getPersistenceCapableSuperclass(); + } + =20 + =20 + /** Create a new instance of the class and assign its jdoStateMa= nager. + * The new instance has its jdoFlags set to LOAD_RE= QUIRED. + * @see PersistenceCapable#jdoNewInstance(StateManager sm) + * @param pcClass the PersistenceCapable class. + * @param sm the StateManager which will own the new inst= ance. + * @return the new instance, or null if the class is not = registered. + */ =20 + public PersistenceCapable newInstance (Class pcClass, StateManager sm)= { + Meta meta =3D getMeta (pcClass); + PersistenceCapable pcInstance =3D meta.getPC(); + return pcInstance =3D=3D null?null:pcInstance.jdoNewInstance(sm); + } + =20 + /** Create a new instance of the class and assign its jdoStateMa= nager and=20 + * key values from the ObjectId. If the oid parameter is null, + * no key values are copied. + * The new instance has its jdoFlags set to LOAD_RE= QUIRED. + * @see PersistenceCapable#jdoNewInstance(StateManager sm, Object oid) + * @param pcClass the PersistenceCapable class. + * @param sm the StateManager which will own the new inst= ance. + * @return the new instance, or null if the class is not = registered. + * @param oid the ObjectId instance from which to copy key field value= s=2E + */ =20 + public PersistenceCapable newInstance=20 + (Class pcClass, StateManager sm, Object oid) { + Meta meta =3D getMeta (pcClass); + PersistenceCapable pcInstance =3D meta.getPC(); + return pcInstance =3D=3D null?null:pcInstance.jdoNewInstance(sm, o= id); + } + =20 + /** Create a new instance of the ObjectId class of this + * PersistenceCapable class. + * @param pcClass the PersistenceCapable class. + * @return the new ObjectId instance, or null if the clas= s is not registered. + */ =20 + public Object newObjectIdInstance (Class pcClass) { + Meta meta =3D getMeta (pcClass); + PersistenceCapable pcInstance =3D meta.getPC(); + return pcInstance =3D=3D null?null:pcInstance.jdoNewObjectIdInstan= ce(); + } + =20 + /** Create a new instance of the ObjectId class of this Persiste= nceCapable + * class, using the String form of the constructor. + * @return the new ObjectId instance, or null if the clas= s is not registered. + * @param str the String form of the object id + * @param pcClass the PersistenceCapable class. + */ =20 + public Object newObjectIdInstance (Class pcClass, String str) { + Meta meta =3D getMeta (pcClass); + PersistenceCapable pcInstance =3D meta.getPC(); + return pcInstance =3D=3D null?null:pcInstance.jdoNewObjectIdInstan= ce(str); + } + =20 + /** Copy fields from an outside source to the key fields in the Object= Id. + * This method is generated in the PersistenceCapable cla= ss to + * generate a call to the field manager for each key field in the Obje= ctId. =20 + *

For example, an ObjectId class that has three key fields (= int id,=20 + * String name, and Float salary) would have= the method generated: + *

+ * void jdoCopyKeyFieldsToObjectId (Object oid, ObjectIdFieldSupplier = fm) { + *
oid.id =3D fm.fetchIntField (0); + *
oid.name =3D fm.fetchStringField (1); + *
oid.salary =3D fm.fetchObjectField (2); + *
} + *

The implementation is responsible for implementing the=20 + * ObjectIdFieldSupplier to provide the values for the ke= y fields. + * @param pcClass the PersistenceCapable Class. + * @param oid the ObjectId target of the copy. + * @param fm the field manager that supplies the field values. + */ =20 + public void copyKeyFieldsToObjectId=20 + (Class pcClass, PersistenceCapable.ObjectIdFieldSupplier fm, Object oi= d) { + Meta meta =3D getMeta (pcClass); + PersistenceCapable pcInstance =3D meta.getPC(); + if (pcInstance =3D=3D null) { + throw new JDOFatalInternalException ( + msg.msg("ERR_AbstractClassNoIdentity", pcClass.getName()))= ; //NOI18N + } + pcInstance.jdoCopyKeyFieldsToObjectId(fm, oid); + } + + /** Copy fields to an outside source from the key fields in the Object= Id. + * This method is generated in the PersistenceCapable cla= ss to generate + * a call to the field manager for each key field in the ObjectId. For + * example, an ObjectId class that has three key fields (int id<= /code>, + * String name, and Float salary) would have= the method generated: + *

void jdoCopyKeyFieldsFromObjectId + *
(PersistenceCapable oid, ObjectIdFieldConsumer fm) { + *
fm.storeIntField (0, oid.id); + *
fm.storeStringField (1, oid.name); + *
fm.storeObjectField (2, oid.salary); + *
} + *

The implementation is responsible for implementing the + * ObjectIdFieldConsumer to store the values for the key = fields. + * @param pcClass the PersistenceCapable class + * @param oid the ObjectId source of the copy. + * @param fm the field manager that receives the field values. + */ =20 + public void copyKeyFieldsFromObjectId + (Class pcClass, PersistenceCapable.ObjectIdFieldConsumer fm, Object oi= d) { + Meta meta =3D getMeta (pcClass); + PersistenceCapable pcInstance =3D meta.getPC(); + if (pcInstance =3D=3D null) { + throw new JDOFatalInternalException ( + msg.msg("ERR_AbstractClassNoIdentity", pcClass.getName()))= ; //NOI18N + } + pcInstance.jdoCopyKeyFieldsFromObjectId(fm, oid); + } + =20 + /** Register metadata by class. The registration will be done in the + * class named JDOImplHelper loaded by the same or an + * ancestor class loader as the PersistenceCapable class + * performing the registration.=20 + * + * @param pcClass the PersistenceCapable class + * used as the key for lookup. + * @param fieldNames an array of String field names for p= ersistent and transactional fields + * @param fieldTypes an array of Class field types + * @param fieldFlags the Field Flags for persistent and transactional = fields + * @param pc an instance of the PersistenceCapable class + * @param persistenceCapableSuperclass the most immediate superclass t= hat is PersistenceCapable + */ =20 + public static void registerClass (Class pcClass,=20 + String[] fieldNames, Class[] fieldTypes,=20 + byte[] fieldFlags, Class persistenceCapableSuperclass, + PersistenceCapable pc) { + if (pcClass =3D=3D null)=20 + throw new NullPointerException(msg.msg("ERR_NullClass")); + Meta meta =3D new Meta (fieldNames, fieldTypes,=20 + fieldFlags, persistenceCapableSuperclass, pc); + registeredClasses.put (pcClass, meta); + + // handle class registration listeners + synchronized (listeners) { + if (!listeners.isEmpty()) { + RegisterClassEvent event =3D new RegisterClassEvent( + jdoImplHelper, pcClass, fieldNames, fieldTypes,=20 + fieldFlags, persistenceCapableSuperclass); + for (Iterator i =3D listeners.iterator(); i.hasNext();) { + RegisterClassListener crl =3D=20 + (RegisterClassListener)i.next(); + if (crl !=3D null) { + crl.registerClass(event); + } + } + } + } + } + =20 + /** + * Unregister metadata by class loader. This method unregisters all + * registered PersistenceCapable classes loaded by the + * specified class loader. Any attempt to get metadata for unregistered + * classes will result in a JDOFatalUserException.=20 + * @param cl the class loader. + * @since 1.0.2 + */ + public void unregisterClasses (ClassLoader cl) + { + SecurityManager sec =3D System.getSecurityManager(); + if (sec !=3D null) {=20 + // throws exception if caller is not authorized + sec.checkPermission (JDOPermission.MANAGE_METADATA); + } + synchronized(registeredClasses) { + for (Iterator i =3D registeredClasses.keySet().iterator(); i.h= asNext();) { + Class pcClass =3D (Class)i.next(); + // Note, the pc class was registered by calling the static + // method JDOImplHelper.registerClass. This means the + // JDOImplHelper class loader is the same as or an ancestor + // of the class loader of the pc class. In this case method + // getClassLoader does not perform a security check for + // RuntimePermission("getClassLoader") and thus we do not=20 + // need a privileged block for the getClassLoader call. + if ((pcClass !=3D null) && (pcClass.getClassLoader() =3D= =3D cl)) { + // unregister pc class, if its class loader is the + // specified one. + i.remove(); + } + } + } + } + + /** + * Unregister metadata by class. This method unregisters the specified + * class. Any further attempt to get metadata for the specified class = will + * result in a JDOFatalUserException.=20 + * @param pcClass the PersistenceCapable class to be unre= gistered. + * @since 1.0.2 + */ + public void unregisterClass (Class pcClass) + { + if (pcClass =3D=3D null)=20 + throw new NullPointerException(msg.msg("ERR_NullClass")); + SecurityManager sec =3D System.getSecurityManager(); + if (sec !=3D null) {=20 + // throws exception if caller is not authorized + sec.checkPermission (JDOPermission.MANAGE_METADATA); + } + registeredClasses.remove(pcClass); + } + + /**=20 + * Add the specified RegisterClassListener to the listene= r list. + * @param crl the listener to be added + */ + public void addRegisterClassListener (RegisterClassListener crl) { + HashSet alreadyRegisteredClasses =3D null; + synchronized (listeners) { + listeners.add(crl); + // Make a copy of the existing set of registered classes. + // Between these two lines of code, any number of new class re= gistrations + // might occur, and will then all wait until this synchronized= block completes. + // Some of the class registrations might be delivered twice to + // the newly registered listener. + alreadyRegisteredClasses =3D new HashSet (registeredClasses.ke= ySet()); + } + // new registrations will call the new listener while the followin= g occurs + // notify the new listener about already-registered classes + for (Iterator it =3D alreadyRegisteredClasses.iterator(); it.hasNe= xt();) { + Class pcClass =3D (Class)it.next(); + Meta meta =3D getMeta (pcClass); + RegisterClassEvent event =3D new RegisterClassEvent( + this, pcClass, meta.getFieldNames(), meta.getFieldTypes(),=20 + meta.getFieldFlags(), meta.getPersistenceCapableSuperclass= ()); + crl.registerClass (event); + } + } + + /**=20 + * Remove the specified RegisterClassListener from the li= stener list. + * @param crl the listener to be removed + */ + public void removeRegisterClassListener (RegisterClassListener crl) { + synchronized (listeners) { + listeners.remove(crl); + } + } + + /** + * Returns a collection of class objects of the registered=20 + * persistence-capable classes. + * @return registered persistence-capable classes + */ + public Collection getRegisteredClasses() { + return Collections.unmodifiableCollection(registeredClasses.keySet= ()); + } + + /** Look up the metadata for a PersistenceCapable class. + * @param pcClass the Class. + * @return the Meta for the Class. + */ =20 + private static Meta getMeta (Class pcClass) { + Meta ret =3D (Meta) registeredClasses.get (pcClass); + if (ret =3D=3D null) { + throw new JDOFatalUserException( + msg.msg ("ERR_NoMetadata", pcClass.getName())); //NOI18N + } + return ret; + } + =20 + /** Register a class authorized to replaceStateManager. The caller of + * this method must be authorized for JDOPermission("setStateManager"). + * During replaceStateManager, a persistence-capable class will call + * the corresponding checkAuthorizedStateManager and the class of the + * instance of the parameter must have been registered. + * @param smClass a Class that is authorized for JDOPermission("setSta= teManager"). + * @throws SecurityException if the caller is not authorized for JDOPe= rmission("setStateManager"). + * @since 1.0.1 + */ + public static void registerAuthorizedStateManagerClass (Class smClass)=20 + throws SecurityException { + if (smClass =3D=3D null)=20 + throw new NullPointerException(msg.msg("ERR_NullClass")); + SecurityManager sm =3D System.getSecurityManager(); + if (sm !=3D null) { + sm.checkPermission(JDOPermission.SET_STATE_MANAGER); + } + synchronized (authorizedStateManagerClasses) { + authorizedStateManagerClasses.put(smClass, null); + } + } + =20 + /** Register classes authorized to replaceStateManager. The caller of + * this method must be authorized for JDOPermission("setStateManager"). + * During replaceStateManager, a persistence-capable class will call + * the corresponding checkAuthorizedStateManager and the class of the + * instance of the parameter must have been registered. + * @param smClasses a Collection of Classes that are authorized for JD= OPermission("setStateManager"). + * @throws SecurityException if the caller is not authorized for JDOPe= rmission("setStateManager"). + * @since 1.0.1 + */ + public static void registerAuthorizedStateManagerClasses (Collection s= mClasses)=20 + throws SecurityException { + SecurityManager sm =3D System.getSecurityManager(); + if (sm !=3D null) { + sm.checkPermission(JDOPermission.SET_STATE_MANAGER); + synchronized (authorizedStateManagerClasses) { + for (Iterator it =3D smClasses.iterator(); it.hasNext();) { + Object smClass =3D it.next(); + if (!(smClass instanceof Class)) { + throw new ClassCastException( + msg.msg("ERR_StateManagerClassCast",=20 + smClass.getClass().getName())); + } + registerAuthorizedStateManagerClass((Class)it.next()); + } + } + } + } + =20 + /** Check that the parameter instance is of a class that is authorized= for + * JDOPermission("setStateManager"). This method is called by the + * replaceStateManager method in persistence-capable classes. + * A class that is passed as the parameter to replaceStateManager must= be + * authorized for JDOPermission("setStateManager"). To improve perfor= mance, + * first the set of authorized classes is checked, and if not present,= a + * regular permission check is made. The regular permission check req= uires + * that all callers on the stack, including the persistence-capable cl= ass + * itself, must be authorized for JDOPermission("setStateManager"). + * @param sm an instance of StateManager whose class is to be checked. + * @since 1.0.1 + */ + public static void checkAuthorizedStateManager (StateManager sm) { + checkAuthorizedStateManagerClass(sm.getClass()); + } + + /** Check that the parameter instance is a class that is authorized for + * JDOPermission("setStateManager"). This method is called by the + * constructors of JDO Reference Implementation classes. + * @param smClass a Class to be checked for JDOPermission("setStateMan= ager") + * @since 1.0.1 + */ + public static void checkAuthorizedStateManagerClass (Class smClass) { + final SecurityManager scm =3D System.getSecurityManager(); + if (scm =3D=3D null) { + // if no security manager, no checking. + return; + } + synchronized(authorizedStateManagerClasses) { + if (authorizedStateManagerClasses.containsKey(smClass)) { + return; + } + } + + // if not already authorized, perform "long" security checking. + scm.checkPermission(JDOPermission.SET_STATE_MANAGER); + } + + /** This is a helper class to manage metadata per persistence-capable + * class. The information is used at runtime to provide field names a= nd + * field types to the JDO Model. + * + * This is the value of the HashMap which + * relates the PersistenceCapable Class + * as a key to the metadata. + */ =20 + static class Meta { + =20 + /** Construct an instance of Meta. + * @param fieldNames An array of String + * @param fieldTypes An array of Class + * @param fieldFlags an array of int + * @param persistenceCapableSuperclass the most immediate Pe= rsistenceCapable superclass + * @param pc An instance of the PersistenceCapable cl= ass + */ =20 + Meta (String[] fieldNames, Class[] fieldTypes, byte[] fieldFlags, + Class persistenceCapableSuperclass, PersistenceCapable pc) { + this.fieldNames =3D fieldNames; + this.fieldTypes =3D fieldTypes; + this.fieldFlags =3D fieldFlags; + this.persistenceCapableSuperclass =3D persistenceCapableSuperc= lass; + this.pc =3D pc; + } + =20 + /** This is an array of field names used + * for the Model at runtime. The field + * is passed by the static class initialization. + */ + String fieldNames[]; + =20 + /** Get the field names from the metadata. + * @return the array of field names. + */ + String[] getFieldNames() { + return fieldNames; + } + =20 + /** This is an array of field types used + * for the Model at runtime. The field + * is passed by the static class initialization. + */ + Class fieldTypes[]; + =20 + /** Get the field types from the metadata. + * @return the array of field types. + */ + Class[] getFieldTypes() { + return fieldTypes; + } + =20 + /** This is an array of field flags used + * for the Model at runtime. The field + * is passed by the static class initialization. + */ + byte fieldFlags[]; + =20 + /** Get the field types from the metadata. + * @return the array of field types. + */ + byte[] getFieldFlags() { + return fieldFlags; + } + + /** This is the Class instance of the Persisten= ceCapable superclass. + */ + Class persistenceCapableSuperclass; + =20 + /** Return the PersistenceCapable superclass. + * @return the PersistenceCapable superclass + */ + Class getPersistenceCapableSuperclass() { + return persistenceCapableSuperclass; + } + /** This is an instance of PersistenceCapable, + * used at runtime to create new instances. + */ + PersistenceCapable pc; + =20 + /** Get an instance of the PersistenceCapable class. + * @return an instance of the PersistenceCapable Class=2E + */ + PersistenceCapable getPC() { + return pc; + } + =20 + /** Return the string form of the metadata. + * @return the string form + */ + public String toString() { + return "Meta-" + pc.getClass().getName(); //NOI18N + } + } +} Added: incubator/jdo/trunk/api20/src/java/javax/jdo/spi/JDOPermission.java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax= /jdo/spi/JDOPermission.java?view=3Dauto&rev=3D159273 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- incubator/jdo/trunk/api20/src/java/javax/jdo/spi/JDOPermission.java (ad= ded) +++ incubator/jdo/trunk/api20/src/java/javax/jdo/spi/JDOPermission.java Mon= Mar 28 10:25:05 2005 @@ -0,0 +1,133 @@ +/* + * Copyright 2005 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at=20 + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software=20 + * distributed under the License is distributed on an "AS IS" BASIS,=20 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= .=20 + * See the License for the specific language governing permissions and=20 + * limitations under the License. + */ + +package javax.jdo.spi; + +/** + * The JDOPermission class is for operations that are reserve= d for JDO=20 + * implementations and should not be called by other code. A + * JDOPermission is a named permission and has no + * actions. There are two names currently defined. Each named permission + * has a corresponding public static final field which contains an instance + * of the named permission. + *

+ * The following table + * provides a summary description of what each named permission allows, + * and discusses the risks of granting code the permission. + *

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * =20 + * =20 + * + * + *
Permission Target NameWhat the Permission AllowsRisks of Allowing this Permission
setStateManagerThis allows setting the StateManager for an instance= of PersistenceCapable.=20 + * The StateManager + * has unlimited access to get and set persistent and transactional fiel= ds of + * the PersistenceCapable instance.This is dangerous in that information (possibly confidential)=20 + * normally unavailable would be accessible to malicious code.
getMetadataThis allows getting metadata for any PersistenceCapable class that has + * registered with JDOImplHelper.This is dangerous in that metadata information (possibly confiden= tial)=20 + * normally unavailable would be accessible to malicious code.
manageMetadataThis allows managing metadata for any PersistenceCapable class that has + * registered with JDOImplHelper.This is dangerous in that metadata information (possibly confiden= tial)=20 + * normally unavailable would be manageable (modifiable) by malicious co= de.
closePersistenceManagerFactoryThis allows closing a PersistenceManagerFactory, + * thereby releasing resources.This is dangerous in that resources bound to the + * PersistenceManagerFactory would be releaseable by + * malicious code.
+ * + * @see java.security.Permission + * @see java.security.BasicPermission + * @see javax.jdo.spi.JDOImplHelper + * @see javax.jdo.spi.PersistenceCapable + * @version 1.0.2 + */ +public final +class JDOPermission extends java.security.BasicPermission { + =20 + /** + * Constructs a JDOPermission with the specified name. + * + * @param name the name of the JDOPermission + */ + public JDOPermission(String name) { + super(name); + } + + /** + * Constructs a JDOPermission with the specified name and= actions. + * The actions should be null; they are ignored. This + * constructor exists for use by the Policy object + * to instantiate new Permission objects. + * + * @param name the name of the JDOPermission + * @param actions should be null. + */ + public JDOPermission(String name, String actions) { + super(name, actions); + } + + /** An instance of JDOPermission to be used for + * getMetadata permission checking. + */ + public final static JDOPermission GET_METADATA =3D=20 + new JDOPermission("getMetadata"); // NOI18N + =20 + /** An instance of JDOPermission to be used for + * manageMetadata permission checking. + * @since 1.0.2 + */ + public final static JDOPermission MANAGE_METADATA =3D=20 + new JDOPermission("manageMetadata"); // NOI18N + =20 + /** An instance of JDOPermission to be used for + * setStateManager permission checking. + */ + public final static JDOPermission SET_STATE_MANAGER =3D=20 + new JDOPermission("setStateManager"); // NOI18N + =20 + /** An instance of JDOPermission to be used for + * closePersistenceManagerFactory permission checking. + * @since 1.0.1 + */ + public final static JDOPermission CLOSE_PERSISTENCE_MANAGER_FACTORY = =3D=20 + new JDOPermission("closePersistenceManagerFactory"); // NOI18N + =20 +} Added: incubator/jdo/trunk/api20/src/java/javax/jdo/spi/PersistenceCapable.= java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax= /jdo/spi/PersistenceCapable.java?view=3Dauto&rev=3D159273 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- incubator/jdo/trunk/api20/src/java/javax/jdo/spi/PersistenceCapable.jav= a (added) +++ incubator/jdo/trunk/api20/src/java/javax/jdo/spi/PersistenceCapable.jav= a Mon Mar 28 10:25:05 2005 @@ -0,0 +1,564 @@ +/* + * Copyright 2005 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at=20 + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software=20 + * distributed under the License is distributed on an "AS IS" BASIS,=20 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= .=20 + * See the License for the specific language governing permissions and=20 + * limitations under the License. + */ + +package javax.jdo.spi; + +import javax.jdo.PersistenceManager; +import javax.jdo.JDOHelper; // for javadoc + +/** + * + * @version 2.0 + */ + +/** + * A class that can be managed by a JDO implementation must implement this= interface. + * + *

Every class whose instances can be managed by a JDO PersistenceManag= er must + * implement the PersistenceCapable interface. + * + *

This interface defines methods that allow the implementation to mana= ge + * the instances. It also defines methods that allow a JDO aware + * application to examine the runtime state of instances. For example, + * an application can discover whether the instance is persistent, transac= tional, + * dirty, new, or deleted; and to get its associated + * PersistenceManager if it has one. + * + *

In the Reference Implementation, the JDO Enhancer modifies the class + * to implement PersistenceCapable prior to loading the class into the run= time + * environment. The Reference Enhancer also adds code to implement the + * methods defined by PersistenceCapable. + * + *

The extra methods in the PersistenceCapable interface might be genera= ted + * by pre-processing a .java file, or might be generated from a tool direc= tly. + * The exact technique for generating the extra methods is not specified by + * JDO. + * + *

The PersistenceCapable interface is designed to avoid name conflicts + * in the scope of user-defined classes. All of its declared method + * names are prefixed with 'jdo'. + */ +public interface PersistenceCapable { + /** If jdoFlags is set to READ_WRITE_OK, then the fields in the defaul= t fetch group + * can be accessed for read or write without notifying the StateManage= r=2E + */ + static final byte READ_WRITE_OK =3D 0; + =20 + /** If jdoFlags is set to LOAD_REQUIRED, then the fields in the defaul= t fetch group + * cannot be accessed for read or write without notifying the StateMan= ager. + */ + static final byte LOAD_REQUIRED =3D 1; + =20 + /** If jdoFlags is set to READ_OK, then the fields in the default fetc= h group + * can be accessed for read without notifying the StateManager. + */ + static final byte READ_OK =3D -1; + =20 + /** If jdoFieldFlags for a field includes CHECK_READ, then + * the field has been enhanced to call the jdoStateManager on read + * if the jdoFlags setting is not READ_OK or READ_WRITE_OK. + */ + static final byte CHECK_READ =3D 1; + =20 + /** If jdoFieldFlags for a field includes MEDIATE_READ, then + * the field has been enhanced to always call the jdoStateManager + * on all reads. + */ + static final byte MEDIATE_READ =3D 2; + =20 + /** If jdoFieldFlags for a field includes CHECK_WRITE, + * then the field has been enhanced to call the + * jdoStateManager on write if the jdoFlags setting is not + * READ_WRITE_OK;. + */ + static final byte CHECK_WRITE =3D 4; + =20 + /** If jdoFieldFlags for a field includes MEDIATE_WRITE, then + * the field has been enhanced to always call the jdoStateManager + * on all writes. + */ + static final byte MEDIATE_WRITE =3D 8; + =20 + /** If jdoFieldFlags for a field includes SERIALIZABLE, + * then the field is not declared as TRANSIENT. + */ + static final byte SERIALIZABLE =3D 16; + =20 + /** Return the associated PersistenceManager if there is one. + * Transactional and persistent instances return the associated + * PersistenceManager. + * + *

Transient non-transactional instances return null. + *

This method always delegates to the StateManager if it is non-nu= ll. + * @return the PersistenceManager associated with this instance. + */ + PersistenceManager jdoGetPersistenceManager(); + =20 + /** This method sets the StateManager instance that manages the state + * of this instance. This method is normally used by the StateManager + * during the process of making an instance persistent, transient, + * or transactional. + * + * The caller of this method must have JDOPermission for the instance, + * if the instance is not already owned by a StateManager. + * If the parameter is null, and the StateManager approves the change, + * then the jdoFlags field will be reset to READ_WRITE_OK. + * If the parameter is not null, and the security manager approves + * the change, then the jdoFlags field will be reset to LOAD_REQUIRED. + * @param sm The StateManager which will own this instance, or null + * to reset the instance to transient state + * @throws SecurityException if the caller does not have JDOPermission + * @see JDOPermission + */ + void jdoReplaceStateManager(StateManager sm) + throws SecurityException; + =20 + /** The owning StateManager uses this method to ask the instance to + * provide the value of the single field identified by fieldNumber. + * @param fieldNumber the field whose value is to be provided by + * a callback to the StateManager's + * providedXXXField method + */ + void jdoProvideField(int fieldNumber); + =20 + /** The owning StateManager uses this method to ask the instance to + * provide the values of the multiple fields identified by fieldNumber= s=2E + * @param fieldNumbers the fields whose values are to be provided by + * multiple callbacks to the StateManager's + * providedXXXField method + */ + void jdoProvideFields(int[] fieldNumbers); + =20 + /** The owning StateManager uses this method to ask the instance to + * replace the value of the single field identified by number. + * @param fieldNumber the field whose value is to be replaced by + * a callback to the StateManager's + * replacingXXXField method + */ + void jdoReplaceField(int fieldNumber); + =20 + /** The owning StateManager uses this method to ask the instance to + * replace the values of the multiple fields identified by number. + * @param fieldNumbers the fields whose values are to be replaced by + * multiple callbacks to the StateManager's + * replacingXXXField method + */ + void jdoReplaceFields(int[] fieldNumbers); + =20 + /** The owning StateManager uses this method to ask the instance to + * replace the value of the flags by calling back the StateManager + * replacingFlags method. + */ + void jdoReplaceFlags(); + =20 + /** Copy field values from another instance of the same class + * to this instance. + *

This method will throw an exception if the other instance is + * not managed by the same StateManager as this instance. + * @param other the PC instance from which field values are to be copi= ed + * @param fieldNumbers the field numbers to be copied into this instan= ce + */ + void jdoCopyFields(Object other, int[] fieldNumbers); + =20 + /** Explicitly mark this instance and this field dirty. + * Normally, PersistenceCapable classes are able to detect changes made + * to their fields. However, if a reference to an array is given to a + * method outside the class, and the array is modified, then the + * persistent instance is not aware of the change. This API allows the + * application to notify the instance that a change was made to a fiel= d=2E + * + *

The field name should be the fully qualified name, including pack= age + * name and class name of the class declaring the field. This allows + * unambiguous identification of the field to be marked dirty. + * If multiple classes declare the same field, and + * if the package and class name are not provided by the parameter in + * this API, then the field marked + * dirty is the field declared by the most derived class. + *

Transient instances ignore this method. + *

+ * @param fieldName the name of the field to be marked dirty. + */ + void jdoMakeDirty(String fieldName); + =20 + /** Return a copy of the JDO identity associated with this instance. + * + *

Persistent instances of PersistenceCapable classes have a JDO id= entity + * managed by the PersistenceManager. This method returns a copy of t= he + * ObjectId that represents the JDO identity. + * + *

Transient instances return null. + * + *

The ObjectId may be serialized + * and later restored, and used with a PersistenceManager from the sam= e JDO + * implementation to locate a persistent instance with the same data s= tore + * identity. + * + *

If the JDO identity is managed by the application, then the Obje= ctId may + * be used with a PersistenceManager from any JDO implementation that = supports + * the PersistenceCapable class. + * + *

If the JDO identity is not managed by the application or the dat= a store, + * then the ObjectId returned is only valid within the current transac= tion. + *

If the JDO identity is being changed in the transaction, this me= thod + * returns the object id as of the beginning of the current transactio= n=2E + * + * @see PersistenceManager#getObjectId(Object pc) + * @see PersistenceManager#getObjectById(Object oid, boolean validate) + * @return a copy of the ObjectId of this instance as of the beginning= of the transaction. + */ + Object jdoGetObjectId(); + =20 + /** Return a copy of the JDO identity associated with this instance. + * This method is the same as jdoGetObjectId if the identity of the + * instance has not changed in the current transaction. + *

If the JDO identity is being changed in the transaction, this me= thod + * returns the current object id as modified in the current transactio= n=2E + * + * @see #jdoGetObjectId() + * @see PersistenceManager#getObjectId(Object pc) + * @see PersistenceManager#getObjectById(Object oid, boolean validate) + * @return a copy of the ObjectId of this instance as modified in the = transaction. + */ + Object jdoGetTransactionalObjectId(); + =20 + /** Return the version of this instance. + * @return the version + * @since 2.0 + */ + Object jdoGetVersion(); + =20 + /** Tests whether this object is dirty. + * + * Instances that have been modified, deleted, or newly + * made persistent in the current transaction return true. + * + *

Transient instances return false. + *

+ * @see JDOHelper#isDirty(Object pc) + * @see JDOHelper#makeDirty(Object pc, String fieldName) + * @see #jdoMakeDirty(String fieldName) + * @return true if this instance has been modified in the current tran= saction. + */ + boolean jdoIsDirty(); + =20 + /** Tests whether this object is transactional. + * + * Instances whose state is associated with the current transaction + * return true. + * + *

Transient instances return false. + *

+ * @see JDOHelper#isTransactional(Object pc) + * @see PersistenceManager#makeTransactional(Object pc) + * @return true if this instance is transactional. + */ + boolean jdoIsTransactional(); + =20 + /** Tests whether this object is persistent. + * Instances that represent persistent objects in the data store + * return true. + * @see JDOHelper#isPersistent(Object pc) + * @see PersistenceManager#makePersistent(Object pc) + * @return true if this instance is persistent. + */ + boolean jdoIsPersistent(); + =20 + /** Tests whether this object has been newly made persistent. + * + * Instances that have been made persistent in the current transaction + * return true. + * + *

Transient instances return false. + *

+ * @see JDOHelper#isNew(Object pc) + * @see PersistenceManager#makePersistent(Object pc) + * @return true if this instance was made persistent + * in the current transaction. + */ + boolean jdoIsNew(); + =20 + /** Tests whether this object has been deleted. + * + * Instances that have been deleted in the current transaction return = true. + * + *

Transient instances return false. + *

+ * @see JDOHelper#isDeleted(Object pc) + * @see PersistenceManager#deletePersistent(Object pc) + * @return true if this instance was deleted + * in the current transaction. + */ + boolean jdoIsDeleted(); + =20 + /** Tests whether this object has been detached. + * + * Instances that have been detached return true. + * + *

Transient instances return false. + *

+ * @see JDOHelper#isDetached(Object pc) + * @return true if this instance is detached. + * @since 2.0 + */ + boolean jdoIsDetached(); + =20 + /** Return a new instance of this class, with the jdoStateManager set = to the + * parameter, and jdoFlags set to LOAD_REQUIRED. + *

This method is used as a performance optimization as an alternat= ive to + * using reflection to construct a new instance. It is used by the + * JDOImplHelper class method newInstance. + * @return a new instance of this class. + * @see JDOImplHelper#newInstance(Class pcClass, StateManager sm) + * @param sm the StateManager that will own the new instance. + */ + PersistenceCapable jdoNewInstance(StateManager sm); + =20 + /** Return a new instance of this class, with the jdoStateManager set = to the + * parameter, key fields initialized to the values in the oid, and jdo= Flags + * set to LOAD_REQUIRED. + *

This method is used as a performance optimization as an alternat= ive to + * using reflection to construct a new instance of a class that uses + * application identity. It is used by the + * JDOImplHelper class method newInstance. + * @return a new instance of this class. + * @see JDOImplHelper#newInstance(Class pcClass, StateManager sm) + * @param sm the StateManager that will own the new instance. + * @param oid an instance of the object id class (application identity= )=2E + */ + PersistenceCapable jdoNewInstance(StateManager sm, Object oid); + =20 + /** Create a new instance of the ObjectId class for this PersistenceCa= pable class. + * The fields will have their Java default values. + * @return the new instance created. + */ + Object jdoNewObjectIdInstance(); + =20 + /** Create a new instance of the class used for JDO identity, using the + * key constructor of the object id class. It is intended only for sin= gle + * field identity. The identity + * instance returned has no relationship with the values of the primar= y key + * fields of the persistence-capable instance on which the method is c= alled. + * If the key is the wrong class for the object id class, null is retu= rned. + * @return the new instance created. + * @param o the String form of the object identity + * @since 2.0 + */ + Object jdoNewObjectIdInstance(Object o); + =20 + /** Copy fields from this PersistenceCapable instance to the Object Id= instance. + * @param oid the ObjectId target of the key fields + */ + void jdoCopyKeyFieldsToObjectId(Object oid); + =20 + /** Copy fields from an outside source to the key fields in the Object= Id. + * This method is generated in the PersistenceCapable class to generate + * a call to the field manager for each key field in the ObjectId. For + * example, an ObjectId class that has three key fields (int id, + * String name, and Float salary) would have the method generated: + *

void jdoCopyKeyFieldsToObjectId + *

(ObjectIdFieldSupplier fm, Object objectId) { + *

EmployeeKey oid =3D (EmployeeKey)objectId; + *

oid.id =3D fm.fetchIntField (0); + *

oid.name =3D fm.fetchStringField (1); + *

oid.salary =3D fm.fetchObjectField (2); + *

} + *

The implementation is responsible for implementing the + * ObjectIdFieldSupplier to produce the values for the key fields. + * @param oid the ObjectId target of the copy. + * @param fm the field supplier that supplies the field values. + */ + void jdoCopyKeyFieldsToObjectId(ObjectIdFieldSupplier fm, Object oid); + =20 + /** Copy fields to an outside source from the key fields in the Object= Id. + * This method is generated in the PersistenceCapable class to generate + * a call to the field manager for each key field in the ObjectId. For + * example, an ObjectId class that has three key fields (int id, + * String name, and Float salary) would have the method generated: + *

void copyKeyFieldsFromObjectId + *

(ObjectIdFieldConsumer fm, Object objectId) { + *

EmployeeKey oid =3D (EmployeeKey)objectId; + *

fm.storeIntField (0, oid.id); + *

fm.storeStringField (1, oid.name); + *

fm.storeObjectField (2, oid.salary); + *

} + *

The implementation is responsible for implementing the + * ObjectIdFieldManager to store the values for the key fields. + * @param oid the ObjectId source of the copy. + * @param fm the field manager that receives the field values. + */ + void jdoCopyKeyFieldsFromObjectId(ObjectIdFieldConsumer fm, Object oid= ); + =20 + /** This interface is a convenience interface that allows an instance = to + * implement both ObjectIdFieldSupplier and ObjectIdFieldConsumer. + */ + static interface ObjectIdFieldManager extends ObjectIdFieldConsumer, O= bjectIdFieldSupplier {} + =20 + /** This interface is used to provide fields to the Object id instance= . It is used + * by the method copyKeyFieldsToObjectId. When the method is called, = the + * generated code calls the instance of ObjectIdFieldManager for each = field in + * the object id. + */ + static interface ObjectIdFieldSupplier { + =20 + /** Fetch one field from the field manager. This field will be st= ored in the + * proper field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @return the value of the field to be stored into the ObjectId. + */ + boolean fetchBooleanField(int fieldNumber); + =20 + /** Fetch one field from the field manager. This field will be st= ored in the + * proper field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @return the value of the field to be stored into the ObjectId. + */ + char fetchCharField(int fieldNumber); + =20 + /** Fetch one field from the field manager. This field will be st= ored in the + * proper field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @return the value of the field to be stored into the ObjectId. + */ + byte fetchByteField(int fieldNumber); + =20 + /** Fetch one field from the field manager. This field will be st= ored in the + * proper field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @return the value of the field to be stored into the ObjectId. + */ + short fetchShortField(int fieldNumber); + =20 + /** Fetch one field from the field manager. This field will be st= ored in the + * proper field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @return the value of the field to be stored into the ObjectId. + */ + int fetchIntField(int fieldNumber); + =20 + /** Fetch one field from the field manager. This field will be st= ored in the + * proper field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @return the value of the field to be stored into the ObjectId. + */ + long fetchLongField(int fieldNumber); + =20 + /** Fetch one field from the field manager. This field will be st= ored in the + * proper field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @return the value of the field to be stored into the ObjectId. + */ + float fetchFloatField(int fieldNumber); + =20 + /** Fetch one field from the field manager. This field will be st= ored in the + * proper field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @return the value of the field to be stored into the ObjectId. + */ + double fetchDoubleField(int fieldNumber); + =20 + /** Fetch one field from the field manager. This field will be st= ored in the + * proper field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @return the value of the field to be stored into the ObjectId. + */ + String fetchStringField(int fieldNumber); + =20 + /** Fetch one field from the field manager. This field will be st= ored in the + * proper field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @return the value of the field to be stored into the ObjectId. + */ + Object fetchObjectField(int fieldNumber); + } + =20 + /** This interface is used to store fields from the Object id instance= . It is used + * by the method copyKeyFieldsFromObjectId. When the method is called= , the + * generated code calls the instance of ObjectIdFieldManager for each = field in + * the object id. + */ + static interface ObjectIdFieldConsumer { + =20 + /** Store one field into the field manager. This field was retrie= ved from + * the field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @param value the value of the field from the ObjectId. + */ + void storeBooleanField(int fieldNumber, boolean value); + =20 + /** Store one field into the field manager. This field was retrie= ved from + * the field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @param value the value of the field from the ObjectId. + */ + void storeCharField(int fieldNumber, char value); + =20 + /** Store one field into the field manager. This field was retrie= ved from + * the field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @param value the value of the field from the ObjectId. + */ + void storeByteField(int fieldNumber, byte value); + =20 + /** Store one field into the field manager. This field was retrie= ved from + * the field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @param value the value of the field from the ObjectId. + */ + void storeShortField(int fieldNumber, short value); + =20 + /** Store one field into the field manager. This field was retrie= ved from + * the field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @param value the value of the field from the ObjectId. + */ + void storeIntField(int fieldNumber, int value); + =20 + /** Store one field into the field manager. This field was retrie= ved from + * the field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @param value the value of the field from the ObjectId. + */ + void storeLongField(int fieldNumber, long value); + =20 + /** Store one field into the field manager. This field was retrie= ved from + * the field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @param value the value of the field from the ObjectId. + */ + void storeFloatField(int fieldNumber, float value); + =20 + /** Store one field into the field manager. This field was retrie= ved from + * the field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @param value the value of the field from the ObjectId. + */ + void storeDoubleField(int fieldNumber, double value); + =20 + /** Store one field into the field manager. This field was retrie= ved from + * the field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @param value the value of the field from the ObjectId. + */ + void storeStringField(int fieldNumber, String value); + =20 + /** Store one field into the field manager. This field was retrie= ved from + * the field of the ObjectId. + * @param fieldNumber the field number of the key field. + * @param value the value of the field from the ObjectId. + */ + void storeObjectField(int fieldNumber, Object value); + } +} Added: incubator/jdo/trunk/api20/src/java/javax/jdo/spi/RegisterClassEvent.= java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax= /jdo/spi/RegisterClassEvent.java?view=3Dauto&rev=3D159273 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- incubator/jdo/trunk/api20/src/java/javax/jdo/spi/RegisterClassEvent.jav= a (added) +++ incubator/jdo/trunk/api20/src/java/javax/jdo/spi/RegisterClassEvent.jav= a Mon Mar 28 10:25:05 2005 @@ -0,0 +1,122 @@ +/* + * Copyright 2005 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at=20 + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software=20 + * distributed under the License is distributed on an "AS IS" BASIS,=20 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= .=20 + * See the License for the specific language governing permissions and=20 + * limitations under the License. + */ + +/* + * RegisterClassEvent.java + * + */ + +package javax.jdo.spi; + +import java.util.EventObject; + +/** + * A RegisterClassEvent event gets delivered whenever a persi= stence-capable + * class registers itself with the JDOImplHelper. + * + * @version 1.0 + */ +public class RegisterClassEvent=20 + extends EventObject +{ + /** The class object of the registered persistence-capable class */ + protected Class pcClass; + + /** The names of managed fields of the persistence-capable class */ + protected String[] fieldNames; =20 + + /** The types of managed fields of the persistence-capable class */ + protected Class[] fieldTypes; + + /** The flags of managed fields of the persistence-capable class */ + protected byte[] fieldFlags; + + /** */ + protected Class persistenceCapableSuperclass;=20 + + /**=20 + * Constructs a new RegisterClassEvent. + * @param helper the JDOImplHelper instance + * @param registeredClass the persistence-capable class + * @param fieldNames the names of the managed fields + * @param fieldTypes the types of the managed fields + * @param fieldFlags the flags of the managed fields + * @param persistenceCapableSuperclass the persistence-capable supercl= ass + **/ + public RegisterClassEvent(JDOImplHelper helper, + Class registeredClass,=20 + String[] fieldNames,=20 + Class[] fieldTypes, + byte[] fieldFlags, + Class persistenceCapableSuperclass) + { + super(helper); + this.pcClass =3D registeredClass; + this.fieldNames =3D fieldNames; + this.fieldTypes =3D fieldTypes; + this.fieldFlags =3D fieldFlags; + this.persistenceCapableSuperclass =3D persistenceCapableSuperclass; + } + + /** + * Returns the class object of the registered persistence-capable clas= s=2E + * @return the persistence-capable class. + */ + public Class getRegisteredClass() + { + return pcClass; + } + =20 + /** =20 + * Returns the names of the managed field of the persistence-capable c= lass. + * @return the names of the managed fields + */ + public String[] getFieldNames() + { + return fieldNames; + } + + /** + * Returns the types of the managed field of the persistence-capable c= lass. + * @return the types of the managed fields + */ + public Class[] getFieldTypes() + { + return fieldTypes; + } + + /** + * Returns the flags of the managed field of the persistence-capable c= lass. + * @return the flags of the managed fields + */ + public byte[] getFieldFlags() + { + return fieldFlags; + } + + /** + * Returns the class object of the persistence-capable superclass. + * @return the persistence-capable superclass. + */ + public Class getPersistenceCapableSuperclass() + { + return persistenceCapableSuperclass; + } + =20 +} + + + Added: incubator/jdo/trunk/api20/src/java/javax/jdo/spi/RegisterClassListen= er.java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax= /jdo/spi/RegisterClassListener.java?view=3Dauto&rev=3D159273 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- incubator/jdo/trunk/api20/src/java/javax/jdo/spi/RegisterClassListener.= java (added) +++ incubator/jdo/trunk/api20/src/java/javax/jdo/spi/RegisterClassListener.= java Mon Mar 28 10:25:05 2005 @@ -0,0 +1,43 @@ +/* + * Copyright 2005 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at=20 + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software=20 + * distributed under the License is distributed on an "AS IS" BASIS,=20 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= .=20 + * See the License for the specific language governing permissions and=20 + * limitations under the License. + */ + +/* + * RegisterClassListener.java + * + */ + +package javax.jdo.spi; + +import java.util.EventListener; + +/** + * A "RegisterClassEvent" event gets fired whenever a persistence-capable = class=20 + * is loaded and gets registered with the JDOImplHelper. You = can register a=20 + * RegisterClassListener so as to be notified of any registra= tion of a=20 + * persistence-capable class. + * + * @version 1.0 + */ +public interface RegisterClassListener=20 + extends EventListener +{ + /** + * This method gets called when a persistence-capable class is registe= red. + * @param event a RegisterClassEvent instance describing = the registered=20 + * class plus metadata. + */ + public void registerClass(RegisterClassEvent event); +} Added: incubator/jdo/trunk/api20/src/java/javax/jdo/spi/StateInterrogation.= java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax= /jdo/spi/StateInterrogation.java?view=3Dauto&rev=3D159273 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- incubator/jdo/trunk/api20/src/java/javax/jdo/spi/StateInterrogation.jav= a (added) +++ incubator/jdo/trunk/api20/src/java/javax/jdo/spi/StateInterrogation.jav= a Mon Mar 28 10:25:05 2005 @@ -0,0 +1,177 @@ +/* + * Copyright 2005 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at=20 + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software=20 + * distributed under the License is distributed on an "AS IS" BASIS,=20 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= .=20 + * See the License for the specific language governing permissions and=20 + * limitations under the License. + */ + +/* + * StateInterrogation.java + * + */ +=20 +package javax.jdo.spi; + +import javax.jdo.PersistenceManager; + +/** + * This interface is implemented by a non-binary-compatible JDO implementa= tion + * to provide state interrogation for non-enhanced persistent classes. + * + * An instance that implements this interface is registered with the + * {@link JDOImplHelper}. + * @version 2.0 + * @since 2.0 + */ +public interface StateInterrogation { + + + /** Tests whether the parameter instance is persistent. + * + * Instances that represent persistent objects in the data store=20 + * return true.=20 + * + *

Transient instances and instances of classes=20 + * that do not implement PersistenceCapable return = false. + *

+ * @see PersistenceManager#makePersistent(Object pc) + * @see PersistenceCapable#jdoIsPersistent() + * @param pc the PersistenceCapable instance. + * @return true if the parameter instance is persistent. + */ + Boolean isPersistent (Object pc); + + /** Tests whether the parameter instance is transactional. + * + * Instances whose state is associated with the current transaction=20 + * return true.=20 + * + *

Transient instances and instances of classes=20 + * that do not implement PersistenceCapable return = false. + * @see PersistenceCapable#jdoIsTransactional() + * @param pc the PersistenceCapable instance. + * @return true if the parameter instance is transactiona= l=2E + */ + Boolean isTransactional (Object pc); + =20 + /** Tests whether the parameter instance is dirty. + * + * Instances that have been modified, deleted, or newly=20 + * made persistent in the current transaction return true. + * + *

Transient instances and instances of classes=20 + * that do not implement PersistenceCapable return = false. + *

+ * @see StateManager#makeDirty(PersistenceCapable pc, String fieldName) + * @see PersistenceCapable#jdoIsDirty() + * @param pc the PersistenceCapable instance. + * @return true if the parameter instance has been modifi= ed in the current transaction. + */ + Boolean isDirty (Object pc); + + /** Tests whether the parameter instance has been newly made persisten= t=2E + * + * Instances that have been made persistent in the current transaction=20 + * return true. + * + *

Transient instances and instances of classes=20 + * that do not implement PersistenceCapable return = false. + *

+ * @see PersistenceManager#makePersistent(Object pc) + * @see PersistenceCapable#jdoIsNew() + * @param pc the PersistenceCapable instance. + * @return true if the parameter instance was made persis= tent + * in the current transaction. + */ + Boolean isNew (Object pc); + + /** Tests whether the parameter instance has been deleted. + * + * Instances that have been deleted in the current transaction return = true. + * + *

Transient instances and instances of classes=20 + * that do not implement PersistenceCapable return = false. + *

+ * @see PersistenceManager#deletePersistent(Object pc) + * @see PersistenceCapable#jdoIsDeleted() + * @param pc the PersistenceCapable instance. + * @return true if the parameter instance was deleted + * in the current transaction. + */ + Boolean isDeleted (Object pc); + =20 + /** Return the associated PersistenceManager if there is = one. + * Transactional and persistent instances return the associated + * PersistenceManager. =20 + * + *

Transient non-transactional instances and instances of classes=20 + * that do not implement PersistenceCapable return = null. + * @see PersistenceCapable#jdoGetPersistenceManager() + * @param pc the PersistenceCapable instance. + * @return the PersistenceManager associated with the par= ameter instance. + */ + PersistenceManager getPersistenceManager (Object pc); + =20 + /** Return a copy of the JDO identity associated with the parameter in= stance. + * + *

Persistent instances of PersistenceCapable classes = have a JDO identity + * managed by the PersistenceManager. This method return= s a copy of the + * ObjectId that represents the JDO identity. =20 + *=20 + *

Transient instances and instances of classes=20 + * that do not implement PersistenceCapable return = null. + * + *

The ObjectId may be serialized + * and later restored, and used with a PersistenceManager= from the same JDO + * implementation to locate a persistent instance with the same data s= tore + * identity. + * + *

If the JDO identity is managed by the application, then the Obje= ctId may + * be used with a PersistenceManager from any JDO impleme= ntation that supports + * the PersistenceCapable class. + * + *

If the JDO identity is not managed by the application or the dat= a store, + * then the ObjectId returned is only valid within the current transac= tion. + *

+ * @see PersistenceManager#getObjectId(Object pc) + * @see PersistenceCapable#jdoGetObjectId() + * @see PersistenceManager#getObjectById(Object oid, boolean validate) + * @param pc the PersistenceCapable instance. + * @return a copy of the ObjectId of the parameter instance as of the = beginning of the transaction. + */ + Object getObjectId (Object pc); + + /** Return a copy of the JDO identity associated with the parameter in= stance. + * + * @see PersistenceCapable#jdoGetTransactionalObjectId() + * @see PersistenceManager#getObjectById(Object oid, boolean validate) + * @param pc the PersistenceCapable instance. + * @return a copy of the ObjectId of the parameter instance as modifie= d in this transaction. + */ + Object getTransactionalObjectId (Object pc); + =20 + /** Explicitly mark the parameter instance and field dirty. + * Normally, PersistenceCapable classes are able to detec= t changes made + * to their fields. However, if a reference to an array is given to a + * method outside the class, and the array is modified, then the + * persistent instance is not aware of the change. This API allows the + * application to notify the instance that a change was made to a fiel= d=2E + * + *

Transient instances and instances of classes=20 + * that do not implement PersistenceCapable ignore this m= ethod. + * @see PersistenceCapable#jdoMakeDirty(String fieldName) + * @param pc the PersistenceCapable instance. + * @param fieldName the name of the field to be marked dirty. + */ + boolean makeDirty (Object pc, String fieldName); + +} \ No newline at end of file