org.datanucleus.enhancer

Class EnhancementHelper

java.lang.Object

org.datanucleus.enhancer.EnhancementHelper

public class EnhancementHelper
extends Object

Helper class for the DN bytecode enhancement contract. It contains methods to register metadata for persistable classes and to perform common operations needed by implementations, not by end users.

It allows construction of instances of persistable classes without using reflection.

Persistable classes register themselves via a static method at class load time. There is no security restriction on this access.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EnhancementHelper.RegisterClassEvent
static interface	EnhancementHelper.RegisterClassListener
static interface	EnhancementHelper.StringConstructor Construct an instance of a key class using a String as input.

Method Summary

Modifier and Type	Method and Description
void	addRegisterClassListener(EnhancementHelper.RegisterClassListener crl) Add the specified RegisterClassListener to the listener 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, Persistable.ObjectIdFieldConsumer fm, Object oid) Copy fields to an outside source from the key fields in the ObjectId.
void	copyKeyFieldsToObjectId(Class pcClass, Persistable.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 Persistable class.
String[]	getFieldNames(Class pcClass) Get the field names for a Persistable class.
Class[]	getFieldTypes(Class pcClass) Get the field types for a Persistable class.
static EnhancementHelper	getInstance()
Class	getPersistableSuperclass(Class pcClass) Get the persistence-capable superclass for a Persistable class.
Collection<Class>	getRegisteredClasses() Returns a collection of class objects of the registered persistable classes.
Persistable	newInstance(Class pcClass, StateManager sm) Create a new instance of the class and assign its StateManager.
Persistable	newInstance(Class pcClass, StateManager sm, Object oid) Create a new instance of the class and assign its StateManager and key values from the ObjectId.
Object	newObjectIdInstance(Class pcClass) Create a new instance of the ObjectId class of this Persistable 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.
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 persistableSuperclass, Persistable pc) Register metadata by class.
void	registerDateFormat(DateFormat df) Register a DateFormat instance for use with constructing Date instances.
Object	registerStringConstructor(Class cls, EnhancementHelper.StringConstructor sc) Register special StringConstructor instances.
void	removeRegisterClassListener(EnhancementHelper.RegisterClassListener crl) Remove the specified RegisterClassListener from the listener list.
void	unregisterClass(Class pcClass) Unregister metadata by class.
void	unregisterClasses(ClassLoader cl) Unregister metadata by class loader.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static EnhancementHelper getInstance()

getFieldNames

public String[] getFieldNames(Class pcClass)

Get the field names for a Persistable class. The order of fields is the natural ordering of the String class (without considering localization).

Parameters:

pcClass - the Persistable class.

Returns:

the field names for the class.

getFieldTypes

public Class[] getFieldTypes(Class pcClass)

Get the field types for a Persistable class. The order of fields is the same as for field names.

Parameters:

pcClass - the Persistable class.

Returns:

the field types for the class.

getFieldFlags

public byte[] getFieldFlags(Class pcClass)

Get the field flags for a Persistable class. The order of fields is the same as for field names.

Parameters:

pcClass - the Persistable class.

Returns:

the field types for the class.

getPersistableSuperclass

public Class getPersistableSuperclass(Class pcClass)

Get the persistence-capable superclass for a Persistable class.

Parameters:

pcClass - the Persistable class.

Returns:

The Persistable superclass for this class, or null if there isn't one.

newInstance

public Persistable newInstance(Class pcClass,
                               StateManager sm)

Create a new instance of the class and assign its StateManager. The new instance has its dnFlags set to LOAD_REQUIRED.

Parameters:

pcClass - the Persistable class.

sm - the StateManager which will own the new instance.

Returns:

the new instance, or null if the class is not registered.

See Also:

Persistable.dnNewInstance(StateManager sm)

newInstance

public Persistable newInstance(Class pcClass,
                               StateManager sm,
                               Object oid)

Create a new instance of the class and assign its StateManager and key values from the ObjectId. If the oid parameter is null, no key values are copied. The new instance has its dnFlags set to LOAD_REQUIRED.

Parameters:

pcClass - the Persistable 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:

Persistable.dnNewInstance(StateManager sm, Object oid)

newObjectIdInstance

public Object newObjectIdInstance(Class pcClass)

Create a new instance of the ObjectId class of this Persistable 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 Persistable 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:

obj - the Object form of the object id

pcClass - the Persistable class.

Returns:

the new ObjectId instance, or null if the class is not registered.

copyKeyFieldsToObjectId

public void copyKeyFieldsToObjectId(Class pcClass,
                                    Persistable.ObjectIdFieldSupplier fm,
                                    Object oid)

Copy fields from an outside source to the key fields in the ObjectId. This method is generated in the Persistable 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 dnCopyKeyFieldsToObjectId (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 Persistable Class.

oid - the ObjectId target of the copy.

fm - the field manager that supplies the field values.

copyKeyFieldsFromObjectId

public void copyKeyFieldsFromObjectId(Class pcClass,
                                      Persistable.ObjectIdFieldConsumer fm,
                                      Object oid)

Copy fields to an outside source from the key fields in the ObjectId. This method is generated in the Persistable 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 dnCopyKeyFieldsFromObjectId(Persistable 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 Persistable class

oid - the ObjectId source of the copy.

fm - the field manager that receives the field values.

registerClass

public static void registerClass(Class pcClass,
                                 String[] fieldNames,
                                 Class[] fieldTypes,
                                 byte[] fieldFlags,
                                 Class persistableSuperclass,
                                 Persistable pc)

Register metadata by class. The registration will be done in the class named EnhancementHelper loaded by the same or an ancestor class loader as the Persistable class performing the registration.

Parameters:

pcClass - the Persistable 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

pc - an instance of the Persistable class

persistableSuperclass - the most immediate superclass that is Persistable

unregisterClasses

public void unregisterClasses(ClassLoader cl)

Unregister metadata by class loader. This method unregisters all registered Persistable 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.

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 Persistable class to be unregistered.

addRegisterClassListener

public void addRegisterClassListener(EnhancementHelper.RegisterClassListener crl)

Add the specified RegisterClassListener to the listener list.

Parameters:

crl - the listener to be added

removeRegisterClassListener

public void removeRegisterClassListener(EnhancementHelper.RegisterClassListener crl)

Remove the specified RegisterClassListener from the listener list.

Parameters:

crl - the listener to be removed

getRegisteredClasses

public Collection<Class> getRegisteredClasses()

Returns a collection of class objects of the registered persistable classes.

Returns:

registered persistable classes

registerAuthorizedStateManagerClass

public static void registerAuthorizedStateManagerClass(Class smClass)

Register a class authorized to replaceStateManager. During replaceStateManager, a persistable 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").

registerAuthorizedStateManagerClasses

public static void registerAuthorizedStateManagerClasses(Collection smClasses)

Register classes authorized to replaceStateManager. During replaceStateManager, a persistable 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

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 persistable 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.

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")

registerStringConstructor

public Object registerStringConstructor(Class cls,
                                        EnhancementHelper.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

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

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