javax.jdo

## Interface PersistenceManager

- All Superinterfaces:
    AutoCloseable

      public interface PersistenceManager
      extends AutoCloseable

  `PersistenceManager` is the primary interface for JDO-aware application components. It is the factory for `Query` and `Transaction` instances, and contains methods to manage the life cycle of `PersistenceCapable` instances.

  A `PersistenceManager` is obtained from the `PersistenceManagerFactory` (recommended) or by construction.

  Version:
    2.1

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addInstanceLifecycleListener(InstanceLifecycleListener listener, Class... classes)` Adds the listener instance to the list of lifecycle event listeners.
    `void` | `checkConsistency()` Validates the `PersistenceManager` cache with the datastore.
    `void` | `close()` Close this `PersistenceManager` so that no further requests may be made on it.
    `Transaction` | `currentTransaction()` Return the `Transaction` instance associated with a `PersistenceManager`.
    `void` | `deletePersistent(Object pc)` Delete the persistent instance from the data store.
    `void` | `deletePersistentAll(Collection pcs)` Delete a `Collection` of instances from the data store.
    `void` | `deletePersistentAll(Object... pcs)` Delete an array of instances from the data store.
    `<T> T` | `detachCopy(T pc)` Detach the specified instance from the `PersistenceManager`.
    `<T> Collection<T>` | `detachCopyAll(Collection<T> pcs)` Detach the specified instances from the `PersistenceManager`.
    `<T> T[]` | `detachCopyAll(T... pcs)` Detach the specified instances from the `PersistenceManager`.
    `void` | `evict(Object pc)` Mark an instance as no longer needed in the cache.
    `void` | `evictAll()` Mark all persistent-nontransactional instances as no longer needed in the cache.
    `void` | `evictAll(boolean subclasses, Class pcClass)` Mark the parameter instances as no longer needed in the cache.
    `void` | `evictAll(Collection pcs)` Mark a `Collection` of instances as no longer needed in the cache.
    `void` | `evictAll(Object... pcs)` Mark an array of instances as no longer needed in the cache.
    `void` | `flush()` Flushes all dirty, new, and deleted instances to the data store.
    `boolean` | `getCopyOnAttach()` Gets the copyOnAttach setting.
    `JDOConnection` | `getDataStoreConnection()` If this method is called while a datastore transaction is active, the object returned will be enlisted in the current transaction.
    `Integer` | `getDatastoreReadTimeoutMillis()` Get the effective timeout setting for datastore read operations associated with this persistence manager.
    `Integer` | `getDatastoreWriteTimeoutMillis()` Get the effective timeout setting for write operations.
    `boolean` | `getDetachAllOnCommit()` Gets the detachAllOnCommit setting.
    `<T> Extent<T>` | `getExtent(Class<T> persistenceCapableClass)` Equivalent to `getExtent (persistenceCapableClass, true)`.
    `<T> Extent<T>` | `getExtent(Class<T> persistenceCapableClass, boolean subclasses)` The `PersistenceManager` manages a collection of instances in the data store based on the class of the instances.
    `FetchGroup` | `getFetchGroup(Class cls, String name)` Get a modifiable `FetchGroup` for the Class and name.
    `FetchPlan` | `getFetchPlan()` Returns the `FetchPlan` used by this `PersistenceManager`.
    `boolean` | `getIgnoreCache()` Get the ignoreCache setting for queries.
    `Set` | `getManagedObjects()` Get the objects managed by this persistence manager.
    `Set` | `getManagedObjects(Class... classes)` Get the objects managed by this persistence manager being instances of the specified classes.
    `Set` | `getManagedObjects(EnumSet<ObjectState> states)` Get the objects managed by this persistence manager having the specified object states.
    `Set` | `getManagedObjects(EnumSet<ObjectState> states, Class... classes)` Get the objects managed by this persistence manager having the specified object states and being instances of the specified classes.
    `boolean` | `getMultithreaded()` Get the current Multithreaded flag for this `PersistenceManager`.
    `<T> T` | `getObjectById(Class<T> cls, Object key)` Looks up the instance of the given type with the given key.
    `Object` | `getObjectById(Object oid)` Looks up the instance corresponding to the specified oid.
    `Object` | `getObjectById(Object oid, boolean validate)` This method locates a persistent instance in the cache of instances managed by this `PersistenceManager`.
    `Object` | `getObjectId(Object pc)` The ObjectId returned by this method represents the JDO identity of the instance.
    `Class` | `getObjectIdClass(Class cls)` Return the `Class` that implements the JDO Identity for the specified `PersistenceCapable` class.
    `Object[]` | `getObjectsById(boolean validate, Object... oids)` Return the objects with the given oids.
    `Collection` | `getObjectsById(Collection oids)` Return the objects with the given oids.
    `Collection` | `getObjectsById(Collection oids, boolean validate)` Return the objects with the given oids.
    `Object[]` | `getObjectsById(Object... oids)` Return the objects with the given oids.
    `PersistenceManagerFactory` | `getPersistenceManagerFactory()` This method returns the `PersistenceManagerFactory` used to create this `PersistenceManager`.
    `Map<String,Object>` | `getProperties()` Get the properties and associated values currently in effect for the persistence manager.
    `Sequence` | `getSequence(String name)` Returns the sequence identified by `name`.
    `Date` | `getServerDate()` Get the Date as seen by the server.
    `Set<String>` | `getSupportedProperties()` Get the names of the properties that are supported for use with the persistence manager.
    `Object` | `getTransactionalObjectId(Object pc)` The ObjectId returned by this method represents the JDO identity of the instance.
    `Object` | `getUserObject()` The application can manage the `PersistenceManager` instances more easily by having an application object associated with each `PersistenceManager` instance.
    `Object` | `getUserObject(Object key)` Get the value for the specified key from the map of user objects.
    `boolean` | `isClosed()` A `PersistenceManager` instance can be used until it is closed.
    `void` | `makeNontransactional(Object pc)` Make an instance non-transactional after commit.
    `void` | `makeNontransactionalAll(Collection pcs)` Make a `Collection` of instances non-transactional after commit.
    `void` | `makeNontransactionalAll(Object... pcs)` Make an array of instances non-transactional after commit.
    `<T> T` | `makePersistent(T pc)` Make the parameter instance persistent in this `PersistenceManager`.
    `<T> Collection<T>` | `makePersistentAll(Collection<T> pcs)` Make a `Collection` of instances persistent.
    `<T> T[]` | `makePersistentAll(T... pcs)` Make an array of instances persistent.
    `void` | `makeTransactional(Object pc)` Make an instance subject to transactional boundaries.
    `void` | `makeTransactionalAll(Collection pcs)` Make a `Collection` of instances subject to transactional boundaries.
    `void` | `makeTransactionalAll(Object... pcs)` Make an array of instances subject to transactional boundaries.
    `void` | `makeTransient(Object pc)` Make an instance transient, removing it from management by this `PersistenceManager`.
    `void` | `makeTransient(Object pc, boolean useFetchPlan)` Make an instance transient, removing it from management by this `PersistenceManager`.
    `void` | `makeTransientAll(boolean useFetchPlan, Object... pcs)` Make instances transient, removing them from management by this `PersistenceManager`.
    `void` | `makeTransientAll(Collection pcs)` Make a `Collection` of instances transient, removing them from management by this `PersistenceManager`.
    `void` | `makeTransientAll(Collection pcs, boolean useFetchPlan)` Make instances transient, removing them from management by this `PersistenceManager`.
    `void` | `makeTransientAll(Object... pcs)` Make an array of instances transient, removing them from management by this `PersistenceManager`.
    `<T> T` | `newInstance(Class<T> pcClass)` Creates an instance of a persistence-capable interface, or of a concrete or abstract class.
    `<T> JDOQLTypedQuery<T>` | `newJDOQLTypedQuery(Class<T> cls)` Create a new `JDOQLTypedQuery` with the specified candidate class.
    `<T> Query<T>` | `newNamedQuery(Class<T> cls, String queryName)` Create a new `Query` with the given candidate class from a named query.
    `Object` | `newObjectIdInstance(Class pcClass, Object key)` This method returns an object id instance corresponding to the pcClass and key arguments.
    `Query` | `newQuery()` Create a new `Query` with no elements.
    `<T> Query<T>` | `newQuery(Class<T> cls)` Create a new `Query` specifying the `Class` of the candidate instances.
    `<T> Query<T>` | `newQuery(Class<T> cls, Collection<T> cln)` Create a new `Query` with the candidate `Class` and `Collection`.
    `<T> Query<T>` | `newQuery(Class<T> cls, Collection<T> cln, String filter)` Create a new `Query` with the `Class` of the candidate instances, candidate `Collection`, and filter.
    `<T> Query<T>` | `newQuery(Class<T> cls, String filter)` Create a new `Query` with the `Class` of the candidate instances and filter.
    `<T> Query<T>` | `newQuery(Extent<T> cln)` Create a new `Query` with the `Class` of the candidate instances and candidate `Extent`.
    `<T> Query<T>` | `newQuery(Extent<T> cln, String filter)` Create a new `Query` with the candidate `Extent` and filter; the class is taken from the `Extent`.
    `Query` | `newQuery(Object compiled)` Create a new `Query` using elements from another `Query`.
    `Query` | `newQuery(String query)` Create a Construct a new query instance using the specified String as the single-string representation of the query.
    `Query` | `newQuery(String language, Object query)` Create a new `Query` using the specified language.
    `Object` | `putUserObject(Object key, Object val)` Put the specified key-value pair into the map of user objects.
    `void` | `refresh(Object pc)` Refresh the state of the instance from the data store.
    `void` | `refreshAll()` Refresh the state of all applicable instances from the data store.
    `void` | `refreshAll(Collection pcs)` Refresh the state of a `Collection` of instances from the data store.
    `void` | `refreshAll(JDOException jdoe)` Refreshes all instances in the exception that failed verification.
    `void` | `refreshAll(Object... pcs)` Refresh the state of an array of instances from the data store.
    `void` | `removeInstanceLifecycleListener(InstanceLifecycleListener listener)` Removes the listener instance from the list of lifecycle event listeners.
    `Object` | `removeUserObject(Object key)` Remove the specified key and its value from the map of user objects.
    `void` | `retrieve(Object pc)` Retrieve field values of an instance from the store.
    `void` | `retrieve(Object pc, boolean useFetchPlan)` Retrieve field values of an instance from the store.
    `void` | `retrieveAll(boolean useFetchPlan, Object... pcs)` Retrieve field values of instances from the store.
    `void` | `retrieveAll(Collection pcs)` Retrieve field values of instances from the store.
    `void` | `retrieveAll(Collection pcs, boolean useFetchPlan)` Retrieve field values of instances from the store.
    `void` | `retrieveAll(Object... pcs)` Retrieve field values of instances from the store.
    `void` | `setCopyOnAttach(boolean flag)` Sets the copyOnAttach setting.
    `void` | `setDatastoreReadTimeoutMillis(Integer interval)` Specify a timeout interval (milliseconds) for any datastore read operations associated with this persistence manager.
    `void` | `setDatastoreWriteTimeoutMillis(Integer interval)` Specify a timeout interval (milliseconds) for any write operations associated with this persistence manager.
    `void` | `setDetachAllOnCommit(boolean flag)` Sets the detachAllOnCommit setting.
    `void` | `setIgnoreCache(boolean flag)` Set the ignoreCache parameter for queries.
    `void` | `setMultithreaded(boolean flag)` Set the Multithreaded flag for this `PersistenceManager`.
    `void` | `setProperty(String propertyName, Object value)` Set a persistence manager property.
    `void` | `setUserObject(Object o)` The application can manage the `PersistenceManager` instances more easily by having an application object associated with each `PersistenceManager` instance.

- - ### Method Detail

    - #### isClosed

          boolean isClosed()

      A `PersistenceManager` instance can be used until it is closed.
      Returns:
        `true` if this `PersistenceManager` has been closed.
      See Also:
        `close()`

    - #### close

          void close()

      Close this `PersistenceManager` so that no further requests may be made on it. A `PersistenceManager` instance can be used only until it is closed.

      Closing a `PersistenceManager` might release it to the pool of available `PersistenceManager`s, or might be garbage collected, at the option of the JDO implementation. Before being used again to satisfy a `getPersistenceManager()` request, the default values for options will be restored to their values as specified in the `PersistenceManagerFactory`.

      This method closes the `PersistenceManager`.

      Specified by:
        `close` in interface `AutoCloseable`

    - #### currentTransaction

          Transaction currentTransaction()

      Return the `Transaction` instance associated with a `PersistenceManager`. There is one `Transaction` instance associated with each `PersistenceManager` instance. The `Transaction` instance supports options as well as transaction completion requests.
      Returns:
        the `Transaction` associated with this `PersistenceManager`.

    - #### evict

          void evict(Object pc)

      Mark an instance as no longer needed in the cache. Eviction is normally done automatically by the `PersistenceManager` at transaction completion. This method allows the application to explicitly provide a hint to the `PersistenceManager` that the instance is no longer needed in the cache.
      Parameters:
        `pc` - the instance to evict from the cache.

    - #### evictAll

          void evictAll(Object... pcs)

      Mark an array of instances as no longer needed in the cache.
      Parameters:
        `pcs` - the array of instances to evict from the cache.
      See Also:
        `evict(Object pc)`

    - #### evictAll

          void evictAll(Collection pcs)

      Mark a `Collection` of instances as no longer needed in the cache.
      Parameters:
        `pcs` - the `Collection` of instances to evict from the cache.
      See Also:
        `evict(Object pc)`

    - #### evictAll

          void evictAll(boolean subclasses,
                        Class pcClass)

      Mark the parameter instances as no longer needed in the cache.
      Parameters:
        `pcClass` - the class of instances to evict
        `subclasses` - if true, mark instances of subclasses also
      Since:
        2.1

    - #### evictAll

          void evictAll()

      Mark all persistent-nontransactional instances as no longer needed in the cache. It transitions all persistent-nontransactional instances to hollow. Transactional instances are subject to eviction based on the RetainValues setting.
      See Also:
        `evict(Object pc)`

    - #### refresh

          void refresh(Object pc)

      Refresh the state of the instance from the data store.

      In an optimistic transaction, the state of instances in the cache might not match the state in the data store. This method is used to reload the state of the instance from the data store so that a subsequent commit is more likely to succeed.

      Outside a transaction, this method will refresh nontransactional state.

      Parameters:
        `pc` - the instance to refresh.

    - #### refreshAll

          void refreshAll(Object... pcs)

      Refresh the state of an array of instances from the data store.
      Parameters:
        `pcs` - the array of instances to refresh.
      See Also:
        `refresh(Object pc)`

    - #### refreshAll

          void refreshAll(Collection pcs)

      Refresh the state of a `Collection` of instances from the data store.
      Parameters:
        `pcs` - the `Collection` of instances to refresh.
      See Also:
        `refresh(Object pc)`

    - #### refreshAll

          void refreshAll()

      Refresh the state of all applicable instances from the data store.

      If called with an active transaction, all transactional instances will be refreshed. If called outside an active transaction, all nontransactional instances will be refreshed.

      See Also:
        `refresh(Object pc)`

    - #### refreshAll

          void refreshAll(JDOException jdoe)

      Refreshes all instances in the exception that failed verification.
      Parameters:
        `jdoe` - The exception defining object(s) to be refreshed
      Since:
        2.0

    - #### newQuery

          Query newQuery()

      Create a new `Query` with no elements.
      Returns:
        the new `Query`.

    - #### newQuery

          Query newQuery(Object compiled)

      Create a new `Query` using elements from another `Query`. The other `Query` must have been created by the same JDO implementation. It might be active in a different `PersistenceManager` or might have been serialized and restored.

      All of the settings of the other `Query` are copied to this `Query`, except for the candidate `Collection` or `Extent`.

      Parameters:
        `compiled` - another `Query` from the same JDO implementation
      Returns:
        the new `Query`

    - #### newQuery

          Query newQuery(String query)

      Create a Construct a new query instance using the specified String as the single-string representation of the query.
      Parameters:
        `query` - the single-string query
      Returns:
        the new `Query`
      Since:
        2.0

    - #### newQuery

          Query newQuery(String language,
                         Object query)

      Create a new `Query` using the specified language.
      Parameters:
        `language` - the language of the query parameter
        `query` - the query, which is of a form determined by the language
      Returns:
        the new `Query`

    - #### newQuery

          <T> Query<T> newQuery(Class<T> cls)

      Create a new `Query` specifying the `Class` of the candidate instances.
      Type Parameters:
        `T` - Candidate type for the query
      Parameters:
        `cls` - the `Class` of the candidate instances
      Returns:
        the new `Query`

    - #### newQuery

          <T> Query<T> newQuery(Extent<T> cln)

      Create a new `Query` with the `Class` of the candidate instances and candidate `Extent`.
      Type Parameters:
        `T` - Candidate type for the query
      Parameters:
        `cln` - the `Extent` of candidate instances
      Returns:
        the new `Query`

    - #### newQuery

          <T> Query<T> newQuery(Class<T> cls,
                                Collection<T> cln)

      Create a new `Query` with the candidate `Class` and `Collection`.
      Type Parameters:
        `T` - Candidate type for the query
      Parameters:
        `cls` - the `Class` of results
        `cln` - the `Collection` of candidate instances
      Returns:
        the new `Query`

    - #### newQuery

          <T> Query<T> newQuery(Class<T> cls,
                                String filter)

      Create a new `Query` with the `Class` of the candidate instances and filter.
      Type Parameters:
        `T` - Candidate type for the query
      Parameters:
        `cls` - the `Class` of results
        `filter` - the filter for candidate instances
      Returns:
        the new `Query`

    - #### newQuery

          <T> Query<T> newQuery(Class<T> cls,
                                Collection<T> cln,
                                String filter)

      Create a new `Query` with the `Class` of the candidate instances, candidate `Collection`, and filter.
      Type Parameters:
        `T` - Candidate type for the query
      Parameters:
        `cls` - the `Class` of candidate instances
        `cln` - the `Collection` of candidate instances
        `filter` - the filter for candidate instances
      Returns:
        the new `Query`

    - #### newQuery

          <T> Query<T> newQuery(Extent<T> cln,
                                String filter)

      Create a new `Query` with the candidate `Extent` and filter; the class is taken from the `Extent`.
      Type Parameters:
        `T` - Candidate type for the query
      Parameters:
        `cln` - the `Extent` of candidate instances
        `filter` - the filter for candidate instances
      Returns:
        the new `Query`

    - #### newJDOQLTypedQuery

          <T> JDOQLTypedQuery<T> newJDOQLTypedQuery(Class<T> cls)

      Create a new `JDOQLTypedQuery` with the specified candidate class.
      Type Parameters:
        `T` - Candidate type for the query
      Parameters:
        `cls` - Candidate class for the query
      Returns:
        The JDOQLTypedQuery
      Since:
        3.2

    - #### newNamedQuery

          <T> Query<T> newNamedQuery(Class<T> cls,
                                     String queryName)

      Create a new `Query` with the given candidate class from a named query. The query name given must be the name of a query defined in metadata.
      Type Parameters:
        `T` - Candidate type for the query
      Parameters:
        `cls` - the `Class` of candidate instances
        `queryName` - the name of the query to look up in metadata
      Returns:
        the new `Query`

    - #### getExtent

          <T> Extent<T> getExtent(Class<T> persistenceCapableClass,
                                  boolean subclasses)

      The `PersistenceManager` manages a collection of instances in the data store based on the class of the instances. This method returns an `Extent` of instances in the data store that might be iterated or given to a `Query`. The `Extent` itself might not reference any instances, but only hold the class name and an indicator as to whether subclasses are included in the `Extent`.

      Note that the `Extent` might be very large.

      Type Parameters:
        `T` - Type for the candidate of the Extent
      Parameters:
        `persistenceCapableClass` - `Class` of instances
        `subclasses` - whether to include instances of subclasses
      Returns:
        an `Extent` of the specified `Class`
      See Also:
        `Query`

    - #### getExtent

          <T> Extent<T> getExtent(Class<T> persistenceCapableClass)

      Equivalent to `getExtent (persistenceCapableClass, true)`.
      Type Parameters:
        `T` - Type for the candidate of the Extent
      Parameters:
        `persistenceCapableClass` - Candidate class for the extent
      Returns:
        an `Extent` of the specified `Class`
      Since:
        2.0
      See Also:
        `getExtent(Class,boolean)`

    - #### getObjectById

          Object getObjectById(Object oid,
                               boolean validate)

      This method locates a persistent instance in the cache of instances managed by this `PersistenceManager`. The `getObjectById` method attempts to find an instance in the cache with the specified JDO identity. The `oid` parameter object might have been returned by an earlier call to `getObjectId` or `getTransactionalObjectId`, or might have been constructed by the application.

      If the `PersistenceManager` is unable to resolve the `oid` parameter to an ObjectId instance, then it throws a `JDOUserException`.

      If the `validate` flag is `false`, and there is already an instance in the cache with the same JDO identity as the `oid` parameter, then this method returns it. There is no change made to the state of the returned instance.

      If there is not an instance already in the cache with the same JDO identity as the `oid` parameter, then this method creates an instance with the specified JDO identity and returns it. If there is no transaction in progress, the returned instance will be hollow or persistent-nontransactional, at the choice of the implementation.

      If there is a transaction in progress, the returned instance will be hollow, persistent-nontransactional, or persistent-clean, at the choice of the implementation.

      It is an implementation decision whether to access the data store, if required to determine the exact class. This will be the case of inheritance, where multiple `PersistenceCapable` classes share the same ObjectId class.

      If the validate flag is `false`, and the instance does not exist in the data store, then this method might not fail. It is an implementation choice whether to fail immediately with a `JDOObjectNotFoundException`. But a subsequent access of the fields of the instance will throw a `JDOObjectNotFoundException` if the instance does not exist at that time. Further, if a relationship is established to this instance, then the transaction in which the association was made will fail.

      If the `validate` flag is `true`, and there is already a transactional instance in the cache with the same JDO identity as the `oid` parameter, then this method returns it. There is no change made to the state of the returned instance.

      If there is an instance already in the cache with the same JDO identity as the `oid` parameter, but the instance is not transactional, then it must be verified in the data store. If the instance does not exist in the datastore, then a `JDOObjectNotFoundException` is thrown.

      If there is not an instance already in the cache with the same JDO identity as the `oid` parameter, then this method creates an instance with the specified JDO identity, verifies that it exists in the data store, and returns it. If there is no transaction in progress, the returned instance will be hollow or persistent-nontransactional, at the choice of the implementation.

      If there is a data store transaction in progress, the returned instance will be persistent-clean. If there is an optimistic transaction in progress, the returned instance will be persistent-nontransactional.

      Parameters:
        `oid` - an ObjectId
        `validate` - if the existence of the instance is to be validated
      Returns:
        the `PersistenceCapable` instance with the specified ObjectId
      See Also:
        `getObjectId(Object pc)`, `getTransactionalObjectId(Object pc)`

    - #### getObjectById

          <T> T getObjectById(Class<T> cls,
                              Object key)

      Looks up the instance of the given type with the given key.
      Type Parameters:
        `T` - Type of the persistable object being retrieved
      Parameters:
        `cls` - The type of object to load
        `key` - either the string representation of the object id, or an object representation of a single field identity key
      Returns:
        the corresponding persistent instance
      Since:
        2.0

    - #### getObjectById

          Object getObjectById(Object oid)

      Looks up the instance corresponding to the specified oid. This is equivalent to `getObjectById(oid, true);`
      Parameters:
        `oid` - The object id of the object to load
      Returns:
        the corresponding persistent instance

    - #### getObjectId

          Object getObjectId(Object pc)

      The ObjectId returned by this method represents the JDO identity of the instance. The ObjectId is a copy (clone) of the internal state of the instance, and changing it does not affect the JDO identity of the instance.

      The `getObjectId` method returns an ObjectId instance that represents the object identity of the specified JDO instance. The identity is guaranteed to be unique only in the context of the JDO `PersistenceManager` that created the identity, and only for two types of JDO Identity: those that are managed by the application, and those that are managed by the data store.

      If the object identity is being changed in the transaction, by the application modifying one or more of the application key fields, then this method returns the identity as of the beginning of the transaction. The value returned by `getObjectId` will be different following `afterCompletion` processing for successful transactions.

      Within a transaction, the ObjectId returned will compare equal to the ObjectId returned by only one among all JDO instances associated with the `PersistenceManager` regardless of the type of ObjectId.

      The ObjectId does not necessarily contain any internal state of the instance, nor is it necessarily an instance of the class used to manage identity internally. Therefore, if the application makes a change to the ObjectId instance returned by this method, there is no effect on the instance from which the ObjectId was obtained.

      The `getObjectById` method can be used between instances of `PersistenceManager` of different JDO vendors only for instances of persistence capable classes using application-managed (primary key) JDO identity. If it is used for instances of classes using datastore identity, the method might succeed, but there are no guarantees that the parameter and return instances are related in any way.

      Parameters:
        `pc` - the `PersistenceCapable` instance
      Returns:
        the ObjectId of the instance
      See Also:
        `getTransactionalObjectId(Object pc)`, `getObjectById(Object oid, boolean validate)`

    - #### getTransactionalObjectId

          Object getTransactionalObjectId(Object pc)

      The ObjectId returned by this method represents the JDO identity of the instance. The ObjectId is a copy (clone) of the internal state of the instance, and changing it does not affect the JDO identity of the instance.

      If the object identity is being changed in the transaction, by the application modifying one or more of the application key fields, then this method returns the current identity in the transaction.

      If there is no transaction in progress, or if none of the key fields is being modified, then this method will return the same value as `getObjectId`.

      Parameters:
        `pc` - a `PersistenceCapable` instance
      Returns:
        the ObjectId of the instance
      See Also:
        `getObjectId(Object pc)`, `getObjectById(Object oid, boolean validate)`

    - #### newObjectIdInstance

          Object newObjectIdInstance(Class pcClass,
                                     Object key)

      This method returns an object id instance corresponding to the pcClass and key arguments.
      Parameters:
        `pcClass` - the `Class` of the persistence-capable instance
        `key` - for single-field identity, the parameter for the constructor; for non-single-field application identity, the result of toString() on the object id instance.
      Returns:
        an instance of the object identity class

    - #### getObjectsById

          Collection getObjectsById(Collection oids,
                                    boolean validate)

      Return the objects with the given oids.
      Parameters:
        `oids` - the oids of the objects to return
        `validate` - if true, the existance of the objects in the datastore will be validated.
      Returns:
        the objects that were looked up, in the same order as the oids parameter.
      Since:
        2.0
      See Also:
        `getObjectById(Object,boolean)`

    - #### getObjectsById

          Collection getObjectsById(Collection oids)

      Return the objects with the given oids. This method is equivalent to calling `getObjectsById(Collection, boolean)` with the validate flag true.
      Parameters:
        `oids` - the oids of the objects to return
      Returns:
        the objects that were looked up, in the same order as the oids parameter.
      Since:
        2.0
      See Also:
        `getObjectsById(Collection,boolean)`

    - #### getObjectsById

          Object[] getObjectsById(boolean validate,
                                  Object... oids)

      Return the objects with the given oids.
      Parameters:
        `oids` - the oids of the objects to return
        `validate` - if true, the existance of the objects in the datastore will be validated.
      Returns:
        the objects that were looked up, in the same order as the oids parameter.
      Since:
        2.1
      See Also:
        `getObjectById(Object,boolean)`

    - #### getObjectsById

          Object[] getObjectsById(Object... oids)

      Return the objects with the given oids. This method is equivalent to calling `getObjectsById(boolean,Object...)` with the validate flag true.
      Parameters:
        `oids` - the oids of the objects to return
      Returns:
        the objects that were looked up, in the same order as the oids parameter.
      Since:
        2.0
      See Also:
        `getObjectsById(boolean,Object...)`

    - #### makePersistent

          <T> T makePersistent(T pc)

      Make the parameter instance persistent in this `PersistenceManager`. This method makes transient instances persistent and applies detached instance changes to the cache. It must be called in the context of an active transaction, or a JDOUserException is thrown. For a transient instance, it assigns an object identity to the instance and transitions it to persistent-new. Any transient instances reachable from this instance via persistent fields of this instance become provisionally persistent, transitively. That is, they behave as persistent-new instances (return true to isPersistent, isNew, and isDirty). But at commit time, the reachability algorithm is run again, and instances made provisionally persistent that are not then reachable from persistent instances will revert to transient.

      During makePersistent of transient instances, the create life cycle listener is called.

      For detached instances, it locates or instantiates a persistent instance with the same JDO identity as the detached instance, and merges the persistent state of the detached instance into the persistent instance. Only the state of persistent fields is merged. If non-persistent state needs to be copied, the application should use the jdoPostAttach callback or the postAttach lifecycle event listener. Any references to the detached instances from instances in the closure of the parameter instances are modified to refer to the corresponding persistent instance instead of to the detached instance.

      During attachment of detached instances, the attach callbacks and attach life cycle listeners are called.

      During application of changes of the detached state, if the JDO implementation can determine that there were no changes made during detachment, then the implementation is not required to mark the corresponding instance dirty. If it cannot determine if changes were made, then it must mark the instance dirty. No consistency checking is done during makePersistent of detached instances. If consistency checking is required by the application, then flush or checkConsistency should be called after attaching the instances.

      These methods have no effect on parameter persistent instances already managed by this PersistenceManager. They will throw a JDOUserException if the parameter instance is managed by a different PersistenceManager. If an instance is of a class whose identity type (application, datastore, or none) is not supported by the JDO implementation, then a JDOUserException will be thrown for that instance. The return value for parameter instances in the transient or persistent states is the same as the parameter value. The return value for parameter instances in the detached state is the persistent instance corresponding to the detached instance. The return values for makePersistentAll methods correspond by position to the parameter instances.

      Type Parameters:
        `T` - Type of the persistable object
      Parameters:
        `pc` - an instance of a `Class` that is persistent capable.
      Returns:
        the parameter instance for parameters in the transient or persistent state, or the corresponding persistent instance for detached parameter instances

    - #### makePersistentAll

          <T> T[] makePersistentAll(T... pcs)

      Make an array of instances persistent.
      Type Parameters:
        `T` - Type of the persistable object
      Parameters:
        `pcs` - an array of instances
      Returns:
        the parameter instances for parameters in the transient or persistent state, or the corresponding persistent instance for detached parameter instances, in the same order as in the parameter array
      See Also:
        `makePersistent(Object pc)`

    - #### makePersistentAll

          <T> Collection<T> makePersistentAll(Collection<T> pcs)

      Make a `Collection` of instances persistent.
      Type Parameters:
        `T` - Type of the persistable object
      Parameters:
        `pcs` - a `Collection` of instances
      Returns:
        the parameter instance for parameters in the transient or persistent state, or the corresponding persistent instance for detached parameter instances, with an iteration in the same order as in the parameter Collection
      See Also:
        `makePersistent(Object pc)`

    - #### deletePersistent

          void deletePersistent(Object pc)

      Delete the persistent instance from the data store. This method must be called in an active transaction. The data store object will be removed at commit. Unlike `makePersistent`, which makes the closure of the instance persistent, the closure of the instance is not deleted from the data store. This method has no effect if the instance is already deleted in the current transaction. This method throws `JDOUserException` if the instance is transient or is managed by another `PersistenceManager`.
      Parameters:
        `pc` - a persistent instance

    - #### deletePersistentAll

          void deletePersistentAll(Object... pcs)

      Delete an array of instances from the data store.
      Parameters:
        `pcs` - a `Collection` of persistent instances
      See Also:
        `deletePersistent(Object pc)`

    - #### deletePersistentAll

          void deletePersistentAll(Collection pcs)

      Delete a `Collection` of instances from the data store.
      Parameters:
        `pcs` - a `Collection` of persistent instances
      See Also:
        `deletePersistent(Object pc)`

    - #### makeTransient

          void makeTransient(Object pc)

      Make an instance transient, removing it from management by this `PersistenceManager`.

      The instance loses its JDO identity and it is no longer associated with any `PersistenceManager`. The state of fields is preserved unchanged.

      Parameters:
        `pc` - the instance to make transient.

    - #### makeTransientAll

          void makeTransientAll(Object... pcs)

      Make an array of instances transient, removing them from management by this `PersistenceManager`.

      The instances lose their JDO identity and they are no longer associated with any `PersistenceManager`. The state of fields is preserved unchanged.

      Parameters:
        `pcs` - the instances to make transient.

    - #### makeTransientAll

          void makeTransientAll(Collection pcs)

      Make a `Collection` of instances transient, removing them from management by this `PersistenceManager`.

      The instances lose their JDO identity and they are no longer associated with any `PersistenceManager`. The state of fields is preserved unchanged.

      Parameters:
        `pcs` - the instances to make transient.

    - #### makeTransient

          void makeTransient(Object pc,
                             boolean useFetchPlan)

      Make an instance transient, removing it from management by this `PersistenceManager`. If the useFetchPlan parameter is false, this method behaves exactly as makeTransient(Object pc).

      The affected instance(s) lose their JDO identity and are no longer associated with any `PersistenceManager`. The state of fields is unchanged.

      If the useFetchPlan parameter is true, then the current FetchPlan is applied to the pc parameter, as if detachCopy(Object) had been called. After the graph of instances is loaded, the instances reachable via loaded fields is made transient. The state of fields in the affected instances is as specified by the FetchPlan.

      Unlike detachCopy, the instances are not detached; there is no detachment information in the instances.

      The instances to be made transient do not need to implement the javax.jdo.spi.Detachable interface.

      Parameters:
        `pc` - the root instance to make transient.
        `useFetchPlan` - whether to use the current fetch plan to determine which fields to load and which instances to make transient
      Since:
        2.0

    - #### makeTransientAll

          void makeTransientAll(boolean useFetchPlan,
                                Object... pcs)

      Make instances transient, removing them from management by this `PersistenceManager`. If the useFetchPlan parameter is false, this method behaves exactly as makeTransientAll(Object[] pcs).

      The affected instance(s) lose their JDO identity and are no longer associated with any `PersistenceManager`. The state of fields is unchanged.

      If the useFetchPlan parameter is true, then the current FetchPlan is applied to the pcs parameters and the entire graph of instances reachable via loaded fields is made transient. The state of fields in the affected instances is as specified by the FetchPlan.

      Unlike detachCopy, the instances are not detached; there is no detachment information in the instances.

      The instances to be made transient do not need to implement the javax.jdo.spi.Detachable interface.

      Parameters:
        `pcs` - the root instances to make transient.
        `useFetchPlan` - whether to use the current fetch plan to determine which fields to load and which instances to make transient
      Since:
        2.1

    - #### makeTransientAll

          void makeTransientAll(Collection pcs,
                                boolean useFetchPlan)

      Make instances transient, removing them from management by this `PersistenceManager`. If the useFetchPlan parameter is false, this method behaves exactly as makeTransientAll(Collection pcs).

      The affected instance(s) lose their JDO identity and are no longer associated with any `PersistenceManager`. The state of fields is unchanged.

      If the useFetchPlan parameter is true, then the current FetchPlan is applied to the pcs parameters and the entire graph of instances reachable via loaded fields is made transient. The state of fields in the affected instances is as specified by the FetchPlan.

      Unlike detachCopy, the instances are not detached; there is no detachment information in the instances.

      The instances to be made transient do not need to implement the javax.jdo.spi.Detachable interface.

      Parameters:
        `pcs` - the root instances to make transient.
        `useFetchPlan` - whether to use the current fetch plan to determine which fields to load and which instances to make transient
      Since:
        2.0

    - #### makeTransactional

          void makeTransactional(Object pc)

      Make an instance subject to transactional boundaries.

      Transient instances normally do not observe transaction boundaries. This method makes transient instances sensitive to transaction completion. If an instance is modified in a transaction, and the transaction rolls back, the state of the instance is restored to the state before the first change in the transaction.

      For persistent instances read in optimistic transactions, this method allows the application to make the state of the instance part of the transactional state. At transaction commit, the state of the instance in the cache is compared to the state of the instance in the data store. If they are not the same, then an exception is thrown.

      Parameters:
        `pc` - the instance to make transactional.

    - #### makeTransactionalAll

          void makeTransactionalAll(Object... pcs)

      Make an array of instances subject to transactional boundaries.
      Parameters:
        `pcs` - the array of instances to make transactional.
      See Also:
        `makeTransactional(Object pc)`

    - #### makeTransactionalAll

          void makeTransactionalAll(Collection pcs)

      Make a `Collection` of instances subject to transactional boundaries.
      Parameters:
        `pcs` - the `Collection` of instances to make transactional.
      See Also:
        `makeTransactional(Object pc)`

    - #### makeNontransactional

          void makeNontransactional(Object pc)

      Make an instance non-transactional after commit.

      Normally, at transaction completion, instances are evicted from the cache. This method allows an application to identify an instance as not being evicted from the cache at transaction completion. Instead, the instance remains in the cache with nontransactional state.

      Parameters:
        `pc` - the instance to make nontransactional.

    - #### makeNontransactionalAll

          void makeNontransactionalAll(Object... pcs)

      Make an array of instances non-transactional after commit.
      Parameters:
        `pcs` - the array of instances to make nontransactional.
      See Also:
        `makeNontransactional(Object pc)`

    - #### makeNontransactionalAll

          void makeNontransactionalAll(Collection pcs)

      Make a `Collection` of instances non-transactional after commit.
      Parameters:
        `pcs` - the `Collection` of instances to make nontransactional.
      See Also:
        `makeNontransactional(Object pc)`

    - #### retrieve

          void retrieve(Object pc)

      Retrieve field values of an instance from the store. This tells the `PersistenceManager` that the application intends to use the instance, and its field values must be retrieved.

      The `PersistenceManager` might use policy information about the class to retrieve associated instances.

      Parameters:
        `pc` - the instance

    - #### retrieve

          void retrieve(Object pc,
                        boolean useFetchPlan)

      Retrieve field values of an instance from the store. This tells the `PersistenceManager` that the application intends to use the instance, and its field values must be retrieved.

      If the useFetchPlan parameter is false, this method behaves exactly as the corresponding method without the useFetchPlan parameter. If the useFetchPlan parameter is true, and the fetch plan has not been modified from its default setting, all fields in the current fetch plan are fetched, and other fields might be fetched lazily by the implementation. If the useFetchPlan parameter is true, and the fetch plan has been changed from its default setting, then the fields specified by the fetch plan are loaded, along with related instances specified by the fetch plan.

      Parameters:
        `pc` - the instance
        `useFetchPlan` - whether to use the current fetch plan to determine which fields to load and which instances to retrieve.
      Since:
        2.0

    - #### retrieveAll

          void retrieveAll(Collection pcs)

      Retrieve field values of instances from the store. This tells the `PersistenceManager` that the application intends to use the instances, and all field values must be retrieved.

      The `PersistenceManager` might use policy information about the class to retrieve associated instances.

      Parameters:
        `pcs` - the instances

    - #### retrieveAll

          void retrieveAll(Collection pcs,
                           boolean useFetchPlan)

      Retrieve field values of instances from the store. This tells the `PersistenceManager` that the application intends to use the instances, and their field values should be retrieved. The fields in the current fetch group must be retrieved, and the implementation might retrieve more fields than the current fetch group.

      If the useFetchPlan parameter is false, this method behaves exactly as the corresponding method without the useFetchPlan parameter. If the useFetchPlan parameter is true, and the fetch plan has not been modified from its default setting, all fields in the current fetch plan are fetched, and other fields might be fetched lazily by the implementation. If the useFetchPlan parameter is true, and the fetch plan has been changed from its default setting, then the fields specified by the fetch plan are loaded, along with related instances specified by the fetch plan.

      Parameters:
        `pcs` - the instances
        `useFetchPlan` - whether to use the current fetch plan to determine which fields to load and which instances to retrieve.
      Since:
        1.0.1

    - #### retrieveAll

          void retrieveAll(Object... pcs)

      Retrieve field values of instances from the store. This tells the `PersistenceManager` that the application intends to use the instances, and all field values must be retrieved.

      The `PersistenceManager` might use policy information about the class to retrieve associated instances.

      Parameters:
        `pcs` - the instances

    - #### retrieveAll

          void retrieveAll(boolean useFetchPlan,
                           Object... pcs)

      Retrieve field values of instances from the store. This tells the `PersistenceManager` that the application intends to use the instances, and their field values should be retrieved. The fields in the current fetch group must be retrieved, and the implementation might retrieve more fields than the current fetch group.

      If the useFetchPlan parameter is false, this method behaves exactly as the corresponding method without the useFetchPlan parameter. If the useFetchPlan parameter is true, and the fetch plan has not been modified from its default setting, all fields in the current fetch plan are fetched, and other fields might be fetched lazily by the implementation. If the useFetchPlan parameter is true, and the fetch plan has been changed from its default setting, then the fields specified by the fetch plan are loaded, along with related instances specified by the fetch plan.

      Parameters:
        `pcs` - the instances
        `useFetchPlan` - whether to use the current fetch plan to determine which fields to load and which instances to retrieve.
      Since:
        2.1

    - #### setUserObject

          void setUserObject(Object o)

      The application can manage the `PersistenceManager` instances more easily by having an application object associated with each `PersistenceManager` instance.
      Parameters:
        `o` - the user instance to be remembered by the `PersistenceManager`
      See Also:
        `getUserObject()`

    - #### getUserObject

          Object getUserObject()

      The application can manage the `PersistenceManager` instances more easily by having an application object associated with each `PersistenceManager` instance.
      Returns:
        the user object associated with this `PersistenceManager`
      See Also:
        `setUserObject(java.lang.Object)`

    - #### getPersistenceManagerFactory

          PersistenceManagerFactory getPersistenceManagerFactory()

      This method returns the `PersistenceManagerFactory` used to create this `PersistenceManager`.
      Returns:
        the `PersistenceManagerFactory` that created this `PersistenceManager`

    - #### getObjectIdClass

          Class getObjectIdClass(Class cls)

      Return the `Class` that implements the JDO Identity for the specified `PersistenceCapable` class. The application can use the returned `Class` to construct a JDO Identity instance for application identity `PersistenceCapable` classes. This JDO Identity instance can then be used to get an instance of the `PersistenceCapable` class for use in the application.

      In order for the application to construct an instance of the ObjectId class it needs to know the class being used by the JDO implementation.

      Parameters:
        `cls` - the `PersistenceCapable Class`
      Returns:
        the `Class` of the ObjectId of the parameter
      See Also:
        `getObjectById(java.lang.Object, boolean)`

    - #### setMultithreaded

          void setMultithreaded(boolean flag)

      Set the Multithreaded flag for this `PersistenceManager`. Applications that use multiple threads to invoke methods or access fields from instances managed by this `PersistenceManager` must set this flag to `true`. Instances managed by this `PersistenceManager` include persistent or transactional instances of `PersistenceCapable` classes, as well as helper instances such as `Query`, `Transaction`, or `Extent`.
      Parameters:
        `flag` - the Multithreaded setting.

    - #### getMultithreaded

          boolean getMultithreaded()

      Get the current Multithreaded flag for this `PersistenceManager`.
      Returns:
        the Multithreaded setting.
      See Also:
        `setMultithreaded(boolean)`

    - #### setIgnoreCache

          void setIgnoreCache(boolean flag)

      Set the ignoreCache parameter for queries.

      IgnoreCache set to `true` specifies that for all `Query` instances created by this `PersistenceManager`, the default is the cache should be ignored for queries.

      Parameters:
        `flag` - the ignoreCache setting.

    - #### getIgnoreCache

          boolean getIgnoreCache()

      Get the ignoreCache setting for queries.

      IgnoreCache set to `true` specifies that for all `Query` instances created by this `PersistenceManager`, the default is the cache should be ignored for queries.

      Returns:
        the ignoreCache setting.

    - #### setDatastoreReadTimeoutMillis

          void setDatastoreReadTimeoutMillis(Integer interval)

      Specify a timeout interval (milliseconds) for any datastore read operations associated with this persistence manager. To unset the explicit timeout, specify null. For no timeout, specify 0. Read operations include, for example, those associated with query, getObjectById, refresh, retrieve, and extent iteration operations. If the datastore granularity is larger than milliseconds, the timeout value will be rounded up to the nearest supported datastore value. If a read operation hasn't completed within this interval, the operation will throw a JDODatastoreException. If multiple datastore operations are required to complete the query, the timeout value applies to each of them individually. If the datastore and JDO implementation support timeouts, then javax.jdo.option.DatastoreTimeout is returned by PersistenceManagerFactory.supportedOptions(). If timeouts are not supported,this method will throw JDOUnsupportedOptionException.
      Parameters:
        `interval` - the timeout interval (milliseconds)
      Since:
        3.0

    - #### getDatastoreReadTimeoutMillis

          Integer getDatastoreReadTimeoutMillis()

      Get the effective timeout setting for datastore read operations associated with this persistence manager. If the timeout has not been set on this persistence manager explicitly, the default read timeout value from the persistence manager factory is returned.
      Returns:
        the effective timeout setting (milliseconds).
      Since:
        3.0
      See Also:
        `setDatastoreReadTimeoutMillis(Integer)`, `PersistenceManagerFactory.setDatastoreReadTimeoutMillis(Integer)`

    - #### setDatastoreWriteTimeoutMillis

          void setDatastoreWriteTimeoutMillis(Integer interval)

      Specify a timeout interval (milliseconds) for any write operations associated with this persistence manager. To unset the explicit timeout, specify null. For no timeout, specify 0. Datastore write operations include, for example, operations associated with flush, commit, and delete by query. If the datastore granularity is larger than milliseconds, the timeout value will be rounded up to the nearest supported datastore value. If a write operation hasn't completed within this interval, methods will throw a JDODatastoreException. If multiple datastore operations are required to complete the method, the timeout value applies to each of them individually. If the datastore and JDO implementation support timeouts, then javax.jdo.option.DatastoreTimeout is returned by PersistenceManagerFactory.supportedOptions(). If timeouts are not supported,this method will throw JDOUnsupportedOptionException.
      Parameters:
        `interval` - the timeout interval (milliseconds)
      Since:
        3.0

    - #### getDatastoreWriteTimeoutMillis

          Integer getDatastoreWriteTimeoutMillis()

      Get the effective timeout setting for write operations. If the timeout has not been set on this persistence manager explicitly, the default datastore write timeout value from the persistence manager factory is returned.
      Returns:
        the effective timeout setting (milliseconds).
      Since:
        3.0
      See Also:
        `setDatastoreWriteTimeoutMillis(Integer)`, `PersistenceManagerFactory.setDatastoreWriteTimeoutMillis(Integer)`

    - #### getDetachAllOnCommit

          boolean getDetachAllOnCommit()

      Gets the detachAllOnCommit setting.
      Returns:
        the detachAllOnCommit setting.
      Since:
        2.0
      See Also:
        `setDetachAllOnCommit(boolean)`

    - #### setDetachAllOnCommit

          void setDetachAllOnCommit(boolean flag)

      Sets the detachAllOnCommit setting.

      DetachAllOnCommit set to `false` specifies that the state of persistent instances in the cache after commit is defined by the `retainValues` flag. With this flag set to true, during beforeCompletion all cached instances are prepared for detachment according to the fetch plan in effect at commit. Loading fields and unloading fields required by the fetch plan is done after calling the user's `beforeCompletion` callback. During `afterCompletion`, before calling the user's `afterCompletion` callback, all detachable persistent instances in the cache transition to detached; non-detachable persistent instances transition to transient; and detachable instances can be serialized as detached instances. Transient transactional instances are unaffected by this flag.

      Parameters:
        `flag` - Flag for whether to detach all on commit
      Since:
        2.0
      See Also:
        `getDetachAllOnCommit()`

    - #### getCopyOnAttach

          boolean getCopyOnAttach()

      Gets the copyOnAttach setting.
      Returns:
        the copyOnAttach setting.
      Since:
        2.1
      See Also:
        `setCopyOnAttach(boolean)`

    - #### setCopyOnAttach

          void setCopyOnAttach(boolean flag)

      Sets the copyOnAttach setting.

      CopyOnAttach set to `true` specifies that during makePersistent, copies are made of detached parameter instances. With this flag set to `false`, detached parameter instances are attached directly and change their state from detached-clean to persistent-clean or from detached-dirty to persistent-dirty.

      Parameters:
        `flag` - Flag for whether to copy on attach
      Since:
        2.1
      See Also:
        `getCopyOnAttach()`

    - #### detachCopy

          <T> T detachCopy(T pc)

      Detach the specified instance from the `PersistenceManager`. The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS) and the active fetch groups determine the scope of fetching for the graph of instances reachable from the pc parameter. The state of fields in the affected instances is as specified by the FetchPlan.
      Type Parameters:
        `T` - Type of the persistable object
      Parameters:
        `pc` - the instance to detach
      Returns:
        the detached instance
      Since:
        2.0
      See Also:
        `detachCopyAll(Object[])`

    - #### detachCopyAll

          <T> Collection<T> detachCopyAll(Collection<T> pcs)

      Detach the specified instances from the `PersistenceManager`. The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS) and the active fetch groups determine the scope of fetching for the graph of instances reachable from the pcs parameter. The state of fields in the affected instances is as specified by the FetchPlan.
      Type Parameters:
        `T` - Type of the persistable objects
      Parameters:
        `pcs` - the instances to detach
      Returns:
        the detached instances
      Since:
        2.0
      See Also:
        `detachCopyAll(Object[])`

    - #### detachCopyAll

          <T> T[] detachCopyAll(T... pcs)

      Detach the specified instances from the `PersistenceManager`. The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS) and the active fetch groups determine the scope of fetching for the graph of instances reachable from the pcs parameter. The state of fields in the affected instances is as specified by the FetchPlan. The objects returned can be manipulated and re-attached with `makePersistentAll(Object[])`. The detached instances will be unmanaged copies of the specified parameters, and are suitable for serialization and manipulation outside of a JDO environment. When detaching instances, only fields in the current `FetchPlan` will be traversed. Thus, to detach a graph of objects, relations to other persistent instances must either be in the `default-fetch-group`, or in the current custom `FetchPlan`.
      Type Parameters:
        `T` - Type of the persistable object
      Parameters:
        `pcs` - the instances to detach
      Returns:
        the detached instances
      Throws:
        `JDOUserException` - if any of the instances to be detached do not implement the javax.jdo.spi.Detachable interface.
      Since:
        2.0
      See Also:
        `makePersistentAll(Object[])`, `getFetchPlan()`

    - #### putUserObject

          Object putUserObject(Object key,
                               Object val)

      Put the specified key-value pair into the map of user objects.
      Parameters:
        `key` - Key to store the user object under
        `val` - User object to store
      Returns:
        The previous object under this key
      Since:
        2.0

    - #### getUserObject

          Object getUserObject(Object key)

      Get the value for the specified key from the map of user objects.
      Parameters:
        `key` - the key of the object to be returned
      Returns:
        the object
      Since:
        2.0

    - #### removeUserObject

          Object removeUserObject(Object key)

      Remove the specified key and its value from the map of user objects.
      Parameters:
        `key` - the key of the object to be removed
      Returns:
        The user object that was removed
      Since:
        2.0

    - #### flush

          void flush()

      Flushes all dirty, new, and deleted instances to the data store. It has no effect if a transaction is not active.

      If a datastore transaction is active, this method synchronizes the cache with the datastore and reports any exceptions.

      If an optimistic transaction is active, this method obtains a datastore connection, synchronizes the cache with the datastore using this connection and reports any exceptions. The connection obtained by this method is held until the end of the transaction.

      If exceptions occur during flush, the implementation will set the current transaction's `RollbackOnly` flag (see `Transaction.setRollbackOnly()`).

      Since:
        2.0

    - #### checkConsistency

          void checkConsistency()

      Validates the `PersistenceManager` cache with the datastore. This method has no effect if a transaction is not active.

      If a datastore transaction is active, this method verifies the consistency of instances in the cache against the datastore. An implementation might flush instances as if `flush()` were called, but it is not required to do so.

      If an optimistic transaction is active, this method obtains a datastore connection and verifies the consistency of the instances in the cache against the datastore. If any inconsistencies are detected, a `JDOOptimisticVerificationException` is thrown. This exception contains a nested `JDOOptimisticVerificationException` for each object that failed the consistency check. No datastore resources acquired during the execution of this method are held beyond the scope of this method.

      Since:
        2.0

    - #### getFetchPlan

          FetchPlan getFetchPlan()

      Returns the `FetchPlan` used by this `PersistenceManager`.
      Returns:
        the FetchPlan
      Since:
        2.0

    - #### newInstance

          <T> T newInstance(Class<T> pcClass)

      Creates an instance of a persistence-capable interface, or of a concrete or abstract class. The returned instance is transient.
      Type Parameters:
        `T` - Type of the persistable object
      Parameters:
        `pcClass` - Must be a persistence-capable interface, or a concrete or abstract class that is declared in the metadata.
      Returns:
        the created instance
      Since:
        2.0

    - #### getSequence

          Sequence getSequence(String name)

      Returns the sequence identified by `name`.
      Parameters:
        `name` - the name of the Sequence
      Returns:
        the Sequence
      Since:
        2.0

    - #### getDataStoreConnection

          JDOConnection getDataStoreConnection()

      If this method is called while a datastore transaction is active, the object returned will be enlisted in the current transaction. If called in an optimistic transaction or outside an active transaction, the object returned will not be enlisted in any transaction.
      Returns:
        the JDOConnection instance
      Since:
        2.0

    - #### addInstanceLifecycleListener

          void addInstanceLifecycleListener(InstanceLifecycleListener listener,
                                            Class... classes)

      Adds the listener instance to the list of lifecycle event listeners. The `classes` parameter identifies all of the classes of interest. If the `classes` parameter is specified as `null`, events for all persistent classes and interfaces will be sent to `listenerInstance`.

      The listenerInstance will be called for each event for which it implements the corresponding listenerInstance interface.

      Parameters:
        `listener` - the lifecycle listener
        `classes` - the classes of interest to the listener
      Since:
        2.0

    - #### removeInstanceLifecycleListener

          void removeInstanceLifecycleListener(InstanceLifecycleListener listener)

      Removes the listener instance from the list of lifecycle event listeners.
      Parameters:
        `listener` - the listener instance to be removed
      Since:
        2.0

    - #### getServerDate

          Date getServerDate()

      Get the Date as seen by the server. Clients using this method can order their operations according to a single time source. Implementations use the setting of the server time zone to prepare a Date instance that represents UTC time on the server.
      Returns:
        a Date instance corresponding to the UTC Date as seen by the server
      Since:
        2.1

    - #### getManagedObjects

          Set getManagedObjects()

      Get the objects managed by this persistence manager.
      Returns:
        the objects
      Since:
        2.1

    - #### getManagedObjects

          Set getManagedObjects(EnumSet<ObjectState> states)

      Get the objects managed by this persistence manager having the specified object states.
      Parameters:
        `states` - The states of objects that we are interested in
      Returns:
        the objects
      Since:
        2.1

    - #### getManagedObjects

          Set getManagedObjects(Class... classes)

      Get the objects managed by this persistence manager being instances of the specified classes.
      Parameters:
        `classes` - The classes of objects that we are interested in
      Returns:
        the objects
      Since:
        2.1

    - #### getManagedObjects

          Set getManagedObjects(EnumSet<ObjectState> states,
                                Class... classes)

      Get the objects managed by this persistence manager having the specified object states and being instances of the specified classes.
      Parameters:
        `states` - The states of objects that we are interested in
        `classes` - The classes of objects that we are interested in
      Returns:
        the objects
      Since:
        2.1

    - #### getFetchGroup

          FetchGroup getFetchGroup(Class cls,
                                   String name)

      Get a modifiable `FetchGroup` for the Class and name. If a modifiable `FetchGroup` already exists in the `PersistenceManager` scope, return it. If not, create and populate a new `FetchGroup` from the existing definition in the `PersistenceManager` or `PersistenceManagerFactory`. If the definition for the `FetchGroup` is not in scope in either the `PersistenceManager` or `PersistenceManagerFactory`, create it with no members. The `FetchGroup` immediately becomes active and in scope of the PersistenceManager, and hides the corresponding fetch group in the PersistenceManagerFactory.
      Parameters:
        `cls` - the class or interface for the `FetchGroup`
        `name` - the name of the fetch group
      Returns:
        the FetchGroup
      Throws:
        `JDOUserException` - if the class is not a persistence-capable class or interface
      Since:
        2.2

    - #### setProperty

          void setProperty(String propertyName,
                           Object value)

      Set a persistence manager property. This can be a standard property or a vendor-extension property. If a vendor-extension property is not recognized, it is silently ignored.
      Parameters:
        `propertyName` - name of property
        `value` - The value
      Throws:
        `JDOUserException` - if the value is not supported for the property
      Since:
        3.1

    - #### getProperties

          Map<String,Object> getProperties()

      Get the properties and associated values currently in effect for the persistence manager. Changing entries in the map will not have affect the configuration of the persistence manager.
      Returns:
        map of properties in effect
      Since:
        3.1

    - #### getSupportedProperties

          Set<String> getSupportedProperties()

      Get the names of the properties that are supported for use with the persistence manager. These can be standard JDO properties, or can be vendor-extension properties.
      Returns:
        property names Names of the properties accepted
      Since:
        3.1

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