javax.jdo.spi

Class JDOImplHelper


public class JDOImplHelper
extends java.lang.Object

This class is a helper class for JDO implementations. It contains methods to register metadata for persistence-capable classes and to perform common operations needed by implementations, not by end users.

JDOImplHelper allows construction of instances of persistence-capable classes without using reflection.

Persistence-capable classes register themselves via a static method 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 through the security manager, only the call to get an instance is checked. Once an implementation has an instance, any of the methods can be invoked without security checks.

Version:
1.0.2

Nested Class Summary

static interface
JDOImplHelper.StateInterrogationBooleanReturn
This is an interface used to interrogate the state of an instance that does not implement PersistenceCapable.
static interface
JDOImplHelper.StateInterrogationObjectReturn
This is an interface used to interrogate the state of an instance that does not implement PersistenceCapable.
static interface
JDOImplHelper.StringConstructor
Construct an instance of a key class using a String as input.

Method Summary

void
addRegisterClassListener(RegisterClassListener crl)
Add the specified RegisterClassListener to the listener list.
void
addStateInterrogation(StateInterrogation si)
Add a StateInterrogation to the list.
static void
checkAuthorizedStateManager(StateManager sm)
Check that the parameter instance is of a class that is authorized for JDOPermission("setStateManager").
static void
checkAuthorizedStateManagerClass(Class smClass)
Check that the parameter instance is a class that is authorized for JDOPermission("setStateManager").
static Object
construct(String className, String keyString)
Construct an instance of the parameter class, using the keyString as an argument to the constructor.
void
copyKeyFieldsFromObjectId(Class pcClass, PersistenceCapable.ObjectIdFieldConsumer fm, Object oid)
Copy fields to an outside source from the key fields in the ObjectId.
void
copyKeyFieldsToObjectId(Class pcClass, PersistenceCapable.ObjectIdFieldSupplier fm, Object oid)
Copy fields from an outside source to the key fields in the ObjectId.
byte[]
getFieldFlags(Class pcClass)
Get the field flags for a PersistenceCapable class.
String[]
getFieldNames(Class pcClass)
Get the field names for a PersistenceCapable class.
Class[]
getFieldTypes(Class pcClass)
Get the field types for a PersistenceCapable class.
static JDOImplHelper
getInstance()
Get an instance of JDOImplHelper.
Class
getPersistenceCapableSuperclass(Class pcClass)
Get the persistence-capable superclass for a PersistenceCapable class.
Collection
getRegisteredClasses()
Returns a collection of class objects of the registered persistence-capable classes.
PersistenceCapable
newInstance(Class pcClass, StateManager sm)
Create a new instance of the class and assign its jdoStateManager.
PersistenceCapable
newInstance(Class pcClass, StateManager sm, Object oid)
Create a new instance of the class and assign its jdoStateManager and key values from the ObjectId.
Object
newObjectIdInstance(Class pcClass)
Create a new instance of the ObjectId class of this PersistenceCapable class.
Object
newObjectIdInstance(Class pcClass, Object obj)
Create a new instance of the class used by the parameter Class for JDO identity, using the key constructor of the object id class.
Object
nonBinaryCompatibleGet(Object pc, JDOImplHelper.StateInterrogationObjectReturn sibr)
Return an object associated with a non-binary-compatible instance.
boolean
nonBinaryCompatibleIs(Object pc, JDOImplHelper.StateInterrogationBooleanReturn sibr)
Determine the state of a non-binary-compatible instance.
void
nonBinaryCompatibleMakeDirty(Object pc, String fieldName)
Mark a non-binary-compatible instance dirty.
static void
registerAuthorizedStateManagerClass(Class smClass)
Register a class authorized to replaceStateManager.
static void
registerAuthorizedStateManagerClasses(Collection smClasses)
Register classes authorized to replaceStateManager.
static void
registerClass(Class pcClass, String[] fieldNames, Class[] fieldTypes, byte[] fieldFlags, Class persistenceCapableSuperclass, PersistenceCapable pc)
Register metadata by class.
void
registerDateFormat(DateFormat df)
Register a DateFormat instance for use with constructing Date instances.
Object
registerStringConstructor(Class cls, JDOImplHelper.StringConstructor sc)
Register special StringConstructor instances.
void
removeRegisterClassListener(RegisterClassListener crl)
Remove the specified RegisterClassListener from the listener list.
void
removeStateInterrogation(StateInterrogation si)
Remove a StateInterrogation from the list.
void
unregisterClass(Class pcClass)
Unregister metadata by class.
void
unregisterClasses(ClassLoader cl)
Unregister metadata by class loader.

Method Details

addRegisterClassListener

public void addRegisterClassListener(RegisterClassListener crl)
Add the specified RegisterClassListener to the listener list.
Parameters:
crl - the listener to be added

addStateInterrogation

public void addStateInterrogation(StateInterrogation si)
Add a StateInterrogation to the list. Create a new list in case there is an iterator open on the original list.

checkAuthorizedStateManager

public static void checkAuthorizedStateManager(StateManager sm)
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 performance, first the set of authorized classes is checked, and if not present, a regular permission check is made. The regular permission check requires that all callers on the stack, including the persistence-capable class itself, must be authorized for JDOPermission("setStateManager").
Parameters:
sm - an instance of StateManager whose class is to be checked.
Since:
1.0.1

checkAuthorizedStateManagerClass

public static void checkAuthorizedStateManagerClass(Class smClass)
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.
Parameters:
smClass - a Class to be checked for JDOPermission("setStateManager")
Since:
1.0.1

construct

public static Object construct(String className,
                               String keyString)
Construct an instance of the parameter class, using the keyString as an argument to the constructor. If the class has a StringConstructor instance registered, use it. If not, try to find a constructor for the class with a single String argument. Otherwise, throw a JDOUserException.
Parameters:
className - the name of the class
keyString - the String parameter for the constructor
Returns:
the result of construction

copyKeyFieldsFromObjectId

public void copyKeyFieldsFromObjectId(Class pcClass,
                                      PersistenceCapable.ObjectIdFieldConsumer 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 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 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.

Parameters:
pcClass - the PersistenceCapable class
fm - the field manager that receives the field values.
oid - the ObjectId source of the copy.

copyKeyFieldsToObjectId

public void copyKeyFieldsToObjectId(Class pcClass,
                                    PersistenceCapable.ObjectIdFieldSupplier fm,
                                    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 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 (Object oid, ObjectIdFieldSupplier fm) {
oid.id = fm.fetchIntField (0);
oid.name = fm.fetchStringField (1);
oid.salary = fm.fetchObjectField (2);
}

The implementation is responsible for implementing the ObjectIdFieldSupplier to provide the values for the key fields.

Parameters:
pcClass - the PersistenceCapable Class.
fm - the field manager that supplies the field values.
oid - the ObjectId target of the copy.

getFieldFlags

public byte[] getFieldFlags(Class pcClass)
Get the field flags for a PersistenceCapable class. The order of fields is the same as for field names.
Parameters:
pcClass - the PersistenceCapable class.
Returns:
the field types for the class.

getFieldNames

public String[] getFieldNames(Class pcClass)
Get the field names for a PersistenceCapable class. The order of fields is the natural ordering of the String class (without considering localization).
Parameters:
pcClass - the PersistenceCapable class.
Returns:
the field names for the class.

getFieldTypes

public Class[] getFieldTypes(Class pcClass)
Get the field types for a PersistenceCapable class. The order of fields is the same as for field names.
Parameters:
pcClass - the PersistenceCapable class.
Returns:
the field types for the class.

getInstance

public static JDOImplHelper getInstance()
            throws SecurityException
Get an instance of JDOImplHelper. This method checks that the caller is authorized for JDOPermission("getMetadata"), and if not, throws SecurityException.
Returns:
an instance of JDOImplHelper.

getPersistenceCapableSuperclass

public Class getPersistenceCapableSuperclass(Class pcClass)
Get the persistence-capable superclass for a PersistenceCapable class.
Parameters:
pcClass - the PersistenceCapable class.
Returns:
The PersistenceCapable superclass for this class, or null if there isn't one.

getRegisteredClasses

public Collection getRegisteredClasses()
Returns a collection of class objects of the registered persistence-capable classes.
Returns:
registered persistence-capable classes

newInstance

public PersistenceCapable newInstance(Class pcClass,
                                      StateManager sm)
Create a new instance of the class and assign its jdoStateManager. The new instance has its jdoFlags set to LOAD_REQUIRED.
Parameters:
pcClass - the PersistenceCapable class.
sm - the StateManager which will own the new instance.
Returns:
the new instance, or null if the class is not registered.
See Also:
PersistenceCapable.jdoNewInstance(StateManager sm)

newInstance

public PersistenceCapable newInstance(Class pcClass,
                                      StateManager sm,
                                      Object oid)
Create a new instance of the class and assign its jdoStateManager and 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_REQUIRED.
Parameters:
pcClass - the PersistenceCapable class.
sm - the StateManager which will own the new instance.
oid - the ObjectId instance from which to copy key field values.
Returns:
the new instance, or null if the class is not registered.
See Also:
PersistenceCapable.jdoNewInstance(StateManager sm, Object oid)

newObjectIdInstance

public Object newObjectIdInstance(Class pcClass)
Create a new instance of the ObjectId class of this PersistenceCapable class. It is intended only for application identity. This method should not be called for classes that use single field identity; newObjectIdInstance(Class, Object) should be used instead. If the class has been enhanced for datastore identity, or if the class is abstract, null is returned.
Parameters:
pcClass - the PersistenceCapable class.
Returns:
the new ObjectId instance, or null if the class is not registered.

newObjectIdInstance

public Object newObjectIdInstance(Class pcClass,
                                  Object obj)
Create a new instance of the class used by the parameter Class for JDO identity, using the key constructor of the object id class. It is intended for single field identity. The identity 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.

For classes that use single field identity, if the parameter is of one of the following types, the behavior must be as specified:

  • Number or Character: the parameter must be the single field type or the wrapper class of the primitive field type; the parameter is passed to the single field identity constructor
  • ObjectIdFieldSupplier: the field value is fetched from the ObjectIdFieldSupplier and passed to the single field identity constructor
  • String: the String is passed to the single field identity constructor
Parameters:
pcClass - the PersistenceCapable class.
obj - the Object form of the object id
Returns:
the new ObjectId instance, or null if the class is not registered.
Since:
2.0

nonBinaryCompatibleGet

public Object nonBinaryCompatibleGet(Object pc,
                                     JDOImplHelper.StateInterrogationObjectReturn sibr)
Return an object associated with a non-binary-compatible instance. Delegate to all registered StateInterrogation instances until one of them handles the call (returns a non-null answer). The caller provides the stateless "method object" that does the actual call to the StateInterrogation instance.

nonBinaryCompatibleIs

public boolean nonBinaryCompatibleIs(Object pc,
                                     JDOImplHelper.StateInterrogationBooleanReturn sibr)
Determine the state of a non-binary-compatible instance. Delegate to all registered StateInterrogation instances until one of them handles the call (returns a non-null Boolean with the answer). The caller provides the stateless "method object" that does the actual call to the StateInterrogation instance.

nonBinaryCompatibleMakeDirty

public void nonBinaryCompatibleMakeDirty(Object pc,
                                         String fieldName)
Mark a non-binary-compatible instance dirty. Delegate to all registered StateInterrogation instances until one of them handles the call.

registerAuthorizedStateManagerClass

public static void registerAuthorizedStateManagerClass(Class smClass)
            throws SecurityException
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.
Parameters:
smClass - a Class that is authorized for JDOPermission("setStateManager").
Since:
1.0.1

registerAuthorizedStateManagerClasses

public static void registerAuthorizedStateManagerClasses(Collection smClasses)
            throws SecurityException
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.
Parameters:
smClasses - a Collection of Classes that are authorized for JDOPermission("setStateManager").
Since:
1.0.1

registerClass

public static void registerClass(Class pcClass,
                                 String[] fieldNames,
                                 Class[] fieldTypes,
                                 byte[] fieldFlags,
                                 Class persistenceCapableSuperclass,
                                 PersistenceCapable pc)
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.
Parameters:
pcClass - the PersistenceCapable class used as the key for lookup.
fieldNames - an array of String field names for persistent and transactional fields
fieldTypes - an array of Class field types
fieldFlags - the Field Flags for persistent and transactional fields
persistenceCapableSuperclass - the most immediate superclass that is PersistenceCapable
pc - an instance of the PersistenceCapable class

registerDateFormat

public void registerDateFormat(DateFormat df)
Register a DateFormat instance for use with constructing Date instances. The default is the default DateFormat instance. If the new instance implements SimpleDateFormat, get its pattern for error messages.
Parameters:
df - the DateFormat instance to use

registerStringConstructor

public Object registerStringConstructor(Class cls,
                                        JDOImplHelper.StringConstructor sc)
Register special StringConstructor instances. These instances are for constructing instances from String parameters where there is no String constructor for them.
Parameters:
cls - the class to register a StringConstructor for
sc - the StringConstructor instance
Returns:
the previous StringConstructor registered for this class

removeRegisterClassListener

public void removeRegisterClassListener(RegisterClassListener crl)
Remove the specified RegisterClassListener from the listener list.
Parameters:
crl - the listener to be removed

removeStateInterrogation

public void removeStateInterrogation(StateInterrogation si)
Remove a StateInterrogation from the list. Create a new list in case there is an iterator open on the original list.

unregisterClass

public void unregisterClass(Class pcClass)
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.
Parameters:
pcClass - the PersistenceCapable class to be unregistered.
Since:
1.0.2

unregisterClasses

public void unregisterClasses(ClassLoader cl)
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.
Parameters:
cl - the class loader.
Since:
1.0.2