db-jdo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From c..@apache.org
Subject svn commit: r230926 - in /incubator/jdo/trunk/api20/src/java/javax/jdo/spi: Detachable.java PersistenceCapable.java StateManager.java
Date Mon, 08 Aug 2005 23:46:52 GMT
Author: clr
Date: Mon Aug  8 16:46:49 2005
New Revision: 230926

URL: http://svn.apache.org/viewcvs?rev=230926&view=rev
Log:
Changed detachment contract per Proposed Final Draft specification.

Modified:
    incubator/jdo/trunk/api20/src/java/javax/jdo/spi/Detachable.java
    incubator/jdo/trunk/api20/src/java/javax/jdo/spi/PersistenceCapable.java
    incubator/jdo/trunk/api20/src/java/javax/jdo/spi/StateManager.java

Modified: incubator/jdo/trunk/api20/src/java/javax/jdo/spi/Detachable.java
URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax/jdo/spi/Detachable.java?rev=230926&r1=230925&r2=230926&view=diff
==============================================================================
--- incubator/jdo/trunk/api20/src/java/javax/jdo/spi/Detachable.java (original)
+++ incubator/jdo/trunk/api20/src/java/javax/jdo/spi/Detachable.java Mon Aug  8 16:46:49 2005
@@ -14,44 +14,33 @@
  * limitations under the License.
  */
 
-/*
- * Detachable.java
- *
- */
-
 package javax.jdo.spi;
 
 /**
  * This interface is implemented by classes that can be detached from the
  * persistence context and later attached. The interface includes the 
- * contract by which the StateManager can set the object id and version
+ * contract by which the StateManager can set the object id, version,
+ * BitSet of loaded fields, and BitSet of modified fields 
  * so they are preserved while outside the persistence environment.
+ * <P>The detached state is stored as a field in each instance of Detachable. 
+ * The field is serialized so as to maintain the state of the instance 
+ * while detached. While detached, only the BitSet of modified fields 
+ * will be modified. The structure of the Object[] jdoDetachedState
+ * is as follows:
+ *  <ul><li>jdoDetachedState[0]: the Object Id of the instance
+ * </li><li>jdoDetachedState[1]: the Version of the instance
+ * </li><li>jdoDetachedState[2]: a BitSet of loaded fields
+ * </li><li>jdoDetachedState[3]: a BitSet of modified fields
+ * </li></ul>
  * @version 2.0
- * @since 2.0
  */
+
 public interface Detachable {
-    
-    /** Replace the object id in the detached object.
-     */
-    void jdoReplaceObjectId();
-    
-    /** Replace the version in the detached object.
-     */
-    void jdoReplaceVersion();
-    
-    /** Provide the loaded field list in the detached object.
-     */
-    void jdoProvideLoadedFieldList();
-    
-    /** Replace the loaded field list in the detached object.
-     */
-    void jdoReplaceLoadedFieldList();
-    
-    /** Provide the modified field list in the detached object.
-     */
-    void jdoProvideModifiedFieldList();
-    
-    /** Replace the modified field list in the detached object.
-     */
-    void jdoReplaceModifiedFieldList();
+
+    /** This method calls the StateManager with the current detached 
+     * state instance as a parameter and replaces the current detached 
+     * state instance with the value provided by the StateManager.  
+     * @since 2.0
+     */    
+    public void jdoReplaceDetachedState();
 }

Modified: 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?rev=230926&r1=230925&r2=230926&view=diff
==============================================================================
--- incubator/jdo/trunk/api20/src/java/javax/jdo/spi/PersistenceCapable.java (original)
+++ incubator/jdo/trunk/api20/src/java/javax/jdo/spi/PersistenceCapable.java Mon Aug  8 16:46:49
2005
@@ -20,22 +20,15 @@
 import javax.jdo.JDOHelper; // for javadoc
 
 /**
- *
- * @version 2.0
- */
-
-/**
- * A class that can be managed by a JDO implementation must implement this interface.
- *
- * <P>Every class whose instances can be managed by a JDO PersistenceManager must
- * implement the PersistenceCapable interface.
+ * A class that can be managed by a binary-compatible JDO implementation 
+ * must implement this interface.
  *
  * <P>This interface defines methods that allow the implementation to manage
  * 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, transactional,
- * dirty, new, or deleted; and to get its associated
- * PersistenceManager if it has one.
+ * dirty, new, deleted, or detached; and to get its associated
+ * PersistenceManager, object identity, and version if it has one.
  *
  * <P>In the Reference Implementation, the JDO Enhancer modifies the class
  * to implement PersistenceCapable prior to loading the class into the runtime
@@ -50,6 +43,7 @@
  * <P>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'.
+ * @version 2.0
  */
 public interface PersistenceCapable {
     /** If jdoFlags is set to READ_WRITE_OK, then the fields in the default fetch group
@@ -62,13 +56,6 @@
      */
     static final byte LOAD_REQUIRED = 1;
     
-    /** If jdoFlags is set to DETACHED, then fields identified as loadedFields
-     * can be read and written without having a StateManager. Fields modified
-     * while detached are kept track of as modifiedFields.
-     * @since 2.0
-     */
-    static final byte DETACHED = 2;
-    
     /** If jdoFlags is set to READ_OK, then the fields in the default fetch group
      * can be accessed for read without notifying the StateManager.
      */
@@ -347,8 +334,18 @@
      */
     PersistenceCapable jdoNewInstance(StateManager sm, Object oid);
     
-    /** Create a new instance of the ObjectId class for this PersistenceCapable class.
-     * The fields will have their Java default values.
+    /** Create a new instance of the 
+     * ObjectId class for this PersistenceCapable class.
+     * This method creates a new instance of the class used for JDO identity.
+     * It is intended only for application identity. If the class has been 
+     * enhanced for datastore identity, or if the class is abstract, 
+     * null is returned.
+     * <P>For classes using single field identity, this method must be called 
+     * on an instance of a persistence-capable class with its primary key 
+     * field initialized (not null), or a 
+     * <code>JDONullIdentityException</code> is thrown.
+     * <P>The instance returned is initialized with the value(s) of the 
+     * primary key field(s) of the instance on which the method is called.
      * @return the new instance created.
      */
     Object jdoNewObjectIdInstance();
@@ -359,41 +356,63 @@
      * instance returned has no relationship with the values of the primary key
      * fields of the persistence-capable instance on which the method is called.
      * If the key is the wrong class for the object id class, null is returned.
+     * <P>For classes that use single field identity, if the parameter is of one 
+     * of the following types, the behavior must be as specified:
+     * <ul><li><code>Number</code>: the numeric value of the proper
type 
+     * is extracted from
+     * the parameter and passed to the single field identity constructor
+     * </li><li><code>ObjectIdFieldProvider</code>: the numeric value

+     * of the proper type
+     * is fetched from the <code>ObjectIdFieldProvider</code> and passed to the

+     * single field identity constructor
+     * </li><li><code>String</code>: the String is passed to the

+     * single field identity constructor
+     * </li></ul>
      * @return the new instance created.
-     * @param o the String form of the object identity
+     * @param o the object identity constructor parameter
      * @since 2.0
      */
     Object jdoNewObjectIdInstance(Object o);
     
-    /** Copy fields from this PersistenceCapable instance to the Object Id instance.
+    /** Copy fields from this PersistenceCapable instance to the Object Id 
+     * instance. For classes using single field identity, this method always
+     * throws <code>JDOUserException</code>.
      * @param oid the ObjectId target of the key fields
      */
     void jdoCopyKeyFieldsToObjectId(Object oid);
     
     /** Copy fields from an outside source to the key fields in the ObjectId.
-     * This method is generated in the PersistenceCapable class to generate
+     * This method is generated in the <code>PersistenceCapable</code>
+     * 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:
+     * example, an ObjectId class that has three key fields <code>(int id,
+     * String name, and Float salary)</code> would have the method generated:
+     * <code>
      * <P>void jdoCopyKeyFieldsToObjectId
-     * <P>        (ObjectIdFieldSupplier fm, Object objectId) {
-     * <P>    EmployeeKey oid = (EmployeeKey)objectId;
-     * <P>    oid.id = fm.fetchIntField (0);
-     * <P>    oid.name = fm.fetchStringField (1);
-     * <P>    oid.salary = fm.fetchObjectField (2);
+     * <P>(ObjectIdFieldSupplier fm, Object objectId) {
+     * <P>EmployeeKey oid = (EmployeeKey)objectId;
+     * <P>oid.id = fm.fetchIntField (0);
+     * <P>oid.name = fm.fetchStringField (1);
+     * <P>oid.salary = fm.fetchObjectField (2);
      * <P>}
+     * </code>
      * <P>The implementation is responsible for implementing the
-     * ObjectIdFieldSupplier to produce the values for the key fields.
+     * <code>ObjectIdFieldSupplier</code> to produce the values 
+     * for the key fields.
+     * <P>For classes using single field identity, this method always
+     * throws <code>JDOUserException</code>.
      * @param oid the ObjectId target of the copy.
      * @param fm the field supplier that supplies the field values.
      */
     void jdoCopyKeyFieldsToObjectId(ObjectIdFieldSupplier fm, Object oid);
     
-    /** Copy fields to an outside source from the key fields in the ObjectId.
-     * This method is generated in the PersistenceCapable class to generate
+    /** Copy fields to an outside consumer from the key fields in the ObjectId.
+     * This method is generated in the <code>PersistenceCapable</code>
+     * 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:
+     * example, an ObjectId class that has three key fields <code>(int id,
+     * String name, and Float salary)</code> would have the method generated:
+     * <code>
      * <P>void copyKeyFieldsFromObjectId
      * <P>        (ObjectIdFieldConsumer fm, Object objectId) {
      * <P>     EmployeeKey oid = (EmployeeKey)objectId;
@@ -401,15 +420,18 @@
      * <P>     fm.storeStringField (1, oid.name);
      * <P>     fm.storeObjectField (2, oid.salary);
      * <P>}
+     * </code>
      * <P>The implementation is responsible for implementing the
-     * ObjectIdFieldManager to store the values for the key fields.
+     * <code>ObjectIdFieldConsumer</code> 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);
     
     /** This interface is a convenience interface that allows an instance to
-     * implement both ObjectIdFieldSupplier and ObjectIdFieldConsumer.
+     * implement both <code>ObjectIdFieldSupplier</code> and 
+     * <code>ObjectIdFieldConsumer</code>.
      */
     static interface ObjectIdFieldManager extends ObjectIdFieldConsumer, ObjectIdFieldSupplier
{}
     

Modified: incubator/jdo/trunk/api20/src/java/javax/jdo/spi/StateManager.java
URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax/jdo/spi/StateManager.java?rev=230926&r1=230925&r2=230926&view=diff
==============================================================================
--- incubator/jdo/trunk/api20/src/java/javax/jdo/spi/StateManager.java (original)
+++ incubator/jdo/trunk/api20/src/java/javax/jdo/spi/StateManager.java Mon Aug  8 16:46:49
2005
@@ -397,120 +397,82 @@
      */    
     void providedObjectField (PersistenceCapable pc, int field, Object currentValue);
 
-    /** The replacing value of the field in the calling instance
+    /** The replacement value of the field in the calling instance.
      * @param pc the calling <code>PersistenceCapable</code> instance
      * @param field the field number
      * @return the new value for the field
      */    
     boolean replacingBooleanField (PersistenceCapable pc, int field);
 
-    /** The replacing value of the field in the calling instance
+    /** The replacement value of the field in the calling instance.
      * @param pc the calling <code>PersistenceCapable</code> instance
      * @param field the field number 
      * @return the new value for the field
      */    
     char replacingCharField (PersistenceCapable pc, int field);
 
-    /** The replacing value of the field in the calling instance
+    /** The replacement value of the field in the calling instance.
      * @param pc the calling <code>PersistenceCapable</code> instance
      * @param field the field number 
      * @return the new value for the field
      */    
     byte replacingByteField (PersistenceCapable pc, int field);
 
-    /** The replacing value of the field in the calling instance
+    /** The replacement value of the field in the calling instance.
      * @param pc the calling <code>PersistenceCapable</code> instance
      * @param field the field number 
      * @return the new value for the field
      */    
     short replacingShortField (PersistenceCapable pc, int field);
 
-    /** The replacing value of the field in the calling instance
+    /** The replacement value of the field in the calling instance.
      * @param pc the calling <code>PersistenceCapable</code> instance
      * @param field the field number 
      * @return the new value for the field
      */    
     int replacingIntField (PersistenceCapable pc, int field);
 
-    /** The replacing value of the field in the calling instance
+    /** The replacement value of the field in the calling instance.
      * @param pc the calling <code>PersistenceCapable</code> instance
      * @param field the field number 
      * @return the new value for the field
      */    
     long replacingLongField (PersistenceCapable pc, int field);
 
-    /** The replacing value of the field in the calling instance
+    /** The replacement value of the field in the calling instance.
      * @param pc the calling <code>PersistenceCapable</code> instance
      * @param field the field number 
      * @return the new value for the field
      */    
     float replacingFloatField (PersistenceCapable pc, int field);
 
-    /** The replacing value of the field in the calling instance
+    /** The replacement value of the field in the calling instance.
      * @param pc the calling <code>PersistenceCapable</code> instance
      * @param field the field number 
      * @return the new value for the field
      */    
     double replacingDoubleField (PersistenceCapable pc, int field);
 
-    /** The replacing value of the field in the calling instance
+    /** The replacement value of the field in the calling instance.
      * @param pc the calling <code>PersistenceCapable</code> instance
      * @param field the field number 
      * @return the new value for the field
      */    
     String replacingStringField (PersistenceCapable pc, int field);
 
-    /** The replacing value of the field in the calling instance
+    /** The replacement value of the field in the calling instance.
      * @param pc the calling <code>PersistenceCapable</code> instance
      * @param field the field number 
      * @return the new value for the field
      */    
     Object replacingObjectField (PersistenceCapable pc, int field);
-
-    /** The replacing value of the object id in the calling instance.
-     * @param pc the calling <code>PersistenceCapable</code> instance
-     * @param oid the current value of the oid
-     * @return the new value for the oid
-     * @since 2.0
-     */
-    Object replacingObjectId (PersistenceCapable pc, Object oid);
     
-    /** The replacing value of the version in the calling instance.
-     * @param pc the calling <code>PersistenceCapable</code> instance
-     * @param version the current value of the version
-     * @return the new value for the version
-     * @since 2.0
-     */
-    Object replacingVersion (PersistenceCapable pc, Object version);
-
-    /** The provided value of the loaded field list in the calling instance.
-     * @param pc the calling <code>PersistenceCapable</code> instance
-     * @param loaded the current value of the loaded field list
-     * @since 2.0
-     */
-    void providedLoadedFieldList (PersistenceCapable pc, BitSet loaded);
-
-    /** The replacing value of the loaded field list in the calling instance.
-     * @param pc the calling <code>PersistenceCapable</code> instance
-     * @param loaded the current value of the loaded field list
-     * @return the replacement value for the loaded field list
-     * @since 2.0
-     */
-    BitSet replacingLoadedFieldList (PersistenceCapable pc, BitSet loaded);
-
-    /** The provided value of the modified field list in the calling instance.
-     * @param pc the calling <code>PersistenceCapable</code> instance
-     * @param modified the current value of the modified field list
-     * @since 2.0
-     */
-    void providedModifiedFieldList (PersistenceCapable pc, BitSet modified);
-
-    /** The replacing value of the modified field list in the calling instance.
-     * @param pc the calling <code>PersistenceCapable</code> instance
-     * @param modified the current value of the modified field list
-     * @return the replacement value for the modified field list
+    /** The replacement value of the detached state in the calling instance.
+     * @param pc the calling <code>Detachable</code> instance
+     * @param state the current value of the detached state
+     * @return the replacement value for the detached state
      * @since 2.0
      */
-    BitSet replacingModifiedFieldList (PersistenceCapable pc, BitSet modified);
+    Object[] replacingDetachedState (Detachable pc, Object[] state);
 }
 



Mime
View raw message