Getting and Constructing Identity Objects

The PersistenceManager interface provides four methods that get JDO identity objects or are useful for constructing them.

 public Object getObjectId(Object adObject) public Object getTransactionalObjectId(Object adObject) public Class getObjectIdClass(Class adClass) public Object newObjectIdInstance(Class adClass, String identityString) 

Using these four methods, the application can get identity objects and construct identity objects.

Every persistent application data object has a JDO identity associated with it. Application data objects that are JDO-transient, transient-clean, and transient-dirty do not have an associated JDO identity. The getObjectId method returns the JDO identity object associated with the persistent object. This method may be called whether the transaction is active or not.

If an implementation supports the javax.jdo.option.ChangeApplicationIdentity option, it allows the application to change the values in the application data object's key fields. If this is done within a transaction, the original, pre-change application identity can be obtained from the object by the getObjectId method, and the new, post-change JDO identity can be obtained from the object with the getTransactionalObjectId method. After the transaction commits, the new application identity becomes the identity that is returned from the getObjectId method.

The specification is not clear on what behavior to expect if the application identity fields are changed outside a transaction with the NontransactionalWrite property turned on. In any event, it is not an operation that most applications will want to perform.

The identity object returned from getObjectId or getTransactionalObjectId is a copy of the identity object maintained internally by the JDO implementation. Nothing that the application can do to the identity object returned has any effect on the identity maintained internally by JDO.

Every object identity class is required to support a toString method and a constructor that accepts a string as formatted by the toString method. The idea is to be able to construct a copy of the identity object by passing the string from the toString method to the constructor that accepts a string. The string returned from the identity object's toString method is called the identity string. It is also sometimes called the stringified JDO identity, but the term identity string sounds better. Armed with the ability to generate and use identity strings, services can ship to remote clients information about a range of application data objects along with the identity string for each object, and the client (including HTML clients) can respond by shipping back identity strings together with the information that they want to change. A significant benefit is that the service may not have to maintain conversational state for these clients.

When the application wishes to construct an application identity object, it typically knows the identity class to construct and it has the values of the application-defined key fields. As a result, the application can typically invoke the Java new operator on the application identity class. The application may also use reflection to construct the application identity object. To use reflection, the application must know the application identity class. The getObjectIdClass method returns the identity class for any application data class. In summary, to construct directly or by reflection the application identity object, the application must know the application identity class, which it might get from the getObjectIdClass method, and it must know the key values.

When the application wishes to construct a datastore identity object, it must have the identity string. Although it could use reflection to invoke the constructor in the identity class that accepts the identity string, the application can avoid the complexity and performance cost of invoking reflection by calling the newObjectIdInstance method. This method requires the Class of the application data object whose identity is being constructed. The newObjectIdInstance method also works with the identity string from application identity objects.

Although JDO implementations may use one datastore identity class, they may also use multiple datastore identity classes. For this reason, when using reflection to construct datastore identity, it is still necessary to determine the datastore identity class for the application data class. Calling the getObjectIdClass method is one way to get the identity class that goes with an application data class.

Note

When designing how your application will construct identity objects, keep in mind that your application must know either the class of the identity object or the class of the application data object for which the identity is being constructed. Except when the application data classes are related by inheritance, the application should define a different application identity class for each application data class. The JDO implementation may use more than one datastore identity class as well.