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.
addRegisterClassListener
public void addRegisterClassListener(RegisterClassListener crl)
Add the specified RegisterClassListener
to the listener
list.
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").
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.
smClass
- a Class to be checked for JDOPermission("setStateManager")
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.
className
- the name of the classkeyString
- the String parameter for the constructor
- 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.
pcClass
- the PersistenceCapable
classfm
- 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.
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.
pcClass
- the PersistenceCapable
class.
- 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).
pcClass
- the PersistenceCapable
class.
- 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.
pcClass
- the PersistenceCapable
class.
- 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
.
- an instance of
JDOImplHelper
.
getPersistenceCapableSuperclass
public Class getPersistenceCapableSuperclass(Class pcClass)
Get the persistence-capable superclass for a
PersistenceCapable
class.
pcClass
- the PersistenceCapable
class.
- 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.
- 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
.
pcClass
- the PersistenceCapable
class.sm
- the StateManager
which will own the new instance.
- the new instance, or
null
if the class is not
registered.
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
.
pcClass
- the PersistenceCapable
class.sm
- the StateManager
which will own the new instance.oid
- the ObjectId instance from which to copy key field values.
- the new instance, or
null
if the class is not
registered.
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.
pcClass
- the PersistenceCapable
class.
- 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
pcClass
- the PersistenceCapable
class.obj
- the Object
form of the object id
- the new ObjectId instance, or
null
if the class is not registered.
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.
smClass
- a Class that is authorized for
JDOPermission("setStateManager").
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.
smClasses
- a Collection of Classes that are authorized for
JDOPermission("setStateManager").
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.
pcClass
- the PersistenceCapable
class
used as the key for lookup.fieldNames
- an array of String
field names for
persistent and transactional fieldsfieldTypes
- an array of Class
field typesfieldFlags
- the Field Flags for persistent and transactional fieldspersistenceCapableSuperclass
- 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.
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.
cls
- the class to register a StringConstructor forsc
- the StringConstructor instance
- the previous StringConstructor registered for this class
removeRegisterClassListener
public void removeRegisterClassListener(RegisterClassListener crl)
Remove the specified RegisterClassListener
from the listener
list.
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
.
pcClass
- the PersistenceCapable
class to be
unregistered.
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
.