javax.jdo.spi

## Class JDOImplHelper

- java.lang.Object
- - javax.jdo.spi.JDOImplHelper

-     public class JDOImplHelper
      extends 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:
    2.1

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `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.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Set<String>` | `USER_CONFIGURABLE_STANDARD_PROPERTIES` JDO standard properties that the user can configure.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRegisterClassListener(RegisterClassListener crl)` Add the specified `RegisterClassListener` to the listener list.
    `void` | `addStateInterrogation(StateInterrogation si)` Add a StateInterrogation to the list.
    `static void` | `assertOnlyKnownStandardProperties(Map<?,?> properties)` Examines the given map for keys beginning with the JDO standard prefix, `Constants.JAVAX_JDO_PREFIX`.
    `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<Class>` | `getRegisteredClasses()` Returns a collection of class objects of the registered persistence-capable classes.
    `static DocumentBuilderFactory` | `getRegisteredDocumentBuilderFactory()` Return the registered instance of DocumentBuilderFactory.
    `static ErrorHandler` | `getRegisteredErrorHandler()` Return the registered instance of ErrorHandler.
    `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.
    `void` | `registerDocumentBuilderFactory(DocumentBuilderFactory factory)` Register a DocumentBuilderFactory instance for use in parsing the resource(s) META-INF/jdoconfig.xml.
    `void` | `registerErrorHandler(ErrorHandler handler)` Register an ErrorHandler instance for use in parsing the resource(s) META-INF/jdoconfig.xml.
    `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.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### USER_CONFIGURABLE_STANDARD_PROPERTIES

          public static final Set<String> USER_CONFIGURABLE_STANDARD_PROPERTIES

      JDO standard properties that the user can configure.

  - ### Method Detail

    - #### 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`.
      Throws:
        `SecurityException` - if the caller is not authorized for JDOPermission("getMetadata").

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

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

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

    - #### 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:
        `obj` - the `Object` form of the object id
        `pcClass` - the `PersistenceCapable` class.
      Returns:
        the new ObjectId instance, or `null` if the class is not registered.
      Since:
        2.0

    - #### 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`.
        `oid` - the ObjectId target of the copy.
        `fm` - the field manager that supplies the field values.

    - #### 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
        `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 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
        `pc` - an instance of the `PersistenceCapable` class
        `persistenceCapableSuperclass` - the most immediate superclass that is `PersistenceCapable`

    - #### 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

    - #### 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

    - #### addRegisterClassListener

          public void addRegisterClassListener(RegisterClassListener crl)

      Add the specified `RegisterClassListener` to the listener list.
      Parameters:
        `crl` - the listener to be added

    - #### removeRegisterClassListener

          public void removeRegisterClassListener(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 persistence-capable classes.
      Returns:
        registered persistence-capable classes

    - #### 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").
      Throws:
        `SecurityException` - if the caller is not 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").
      Throws:
        `SecurityException` - if the caller is not authorized for JDOPermission("setStateManager").
      Since:
        1.0.1

    - #### registerDocumentBuilderFactory

          public void registerDocumentBuilderFactory(DocumentBuilderFactory factory)

      Register a DocumentBuilderFactory instance for use in parsing the resource(s) META-INF/jdoconfig.xml. The default is governed by the semantics of DocumentBuilderFactory.newInstance().
      Parameters:
        `factory` - the DocumentBuilderFactory instance to use
      Since:
        2.1

    - #### getRegisteredDocumentBuilderFactory

          public static DocumentBuilderFactory getRegisteredDocumentBuilderFactory()

      Return the registered instance of DocumentBuilderFactory.
      Returns:
        the DocumentBuilderFactory if registered; null otherwise
      Since:
        2.1

    - #### registerErrorHandler

          public void registerErrorHandler(ErrorHandler handler)

      Register an ErrorHandler instance for use in parsing the resource(s) META-INF/jdoconfig.xml. The default is an ErrorHandler that throws on error or fatalError and ignores warnings.
      Parameters:
        `handler` - the ErrorHandler instance to use
      Since:
        2.1

    - #### getRegisteredErrorHandler

          public static ErrorHandler getRegisteredErrorHandler()

      Return the registered instance of ErrorHandler.
      Returns:
        the registered ErrorHandler if registered; null otherwise
      Since:
        2.1

    - #### 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

    - #### 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

    - #### 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
      Since:
        2.0

    - #### 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.
      Parameters:
        `si` - the StateInterrogation to add

    - #### 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.
      Parameters:
        `si` - the StateInterrogation to remove

    - #### 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.
      Parameters:
        `pc` - the instance to mark dirty
        `fieldName` - the field to mark dirty

    - #### 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.
      Parameters:
        `pc` - the instance to be checked
        `sibr` - the method object that delegates to the non-binary-compatible implementation
      Returns:
        Boolean.TRUE if the instance satisfies the state interrogation; Boolean.FALSE if the instance does not satisfy the interrogation; or null if the implementation does not manage the class of the instance

    - #### 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.
      Parameters:
        `pc` - the instance whose associated object is needed
        `sibr` - the method object that delegates to the non-binary-compatible implementation
      Returns:
        the associated object or null if the implementation does not manage the class of the instance

    - #### assertOnlyKnownStandardProperties

          public static void assertOnlyKnownStandardProperties(Map<?,?> properties)

      Examines the given map for keys beginning with the JDO standard prefix, `Constants.JAVAX_JDO_PREFIX`. If any property keys are found with that prefix but are unknown to this version of the JDO standard, a JDOUserException is thrown with a message indicating the unknown property. Keys that are not strings are ignored, as are string keys beginning with `Constants.PROPERTY_PREFIX_INSTANCE_LIFECYCLE_LISTENER` or not beginning with `Constants.JAVAX_JDO_PREFIX`.
      Parameters:
        `properties` - The properties to examine.
      Since:
        3.1
      See Also:
        `Constants.JAVAX_JDO_PREFIX`

Copyright © 2005–2022 The Apache Software Foundation. All rights reserved.