PersistenceManager (Payara Project 5.184 API)

All Known Subinterfaces:

PersistenceManager

All Known Implementing Classes:

PersistenceManagerImpl, PersistenceManagerWrapper
```
public interface PersistenceManager
```
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:

0.1

Author:

Craig Russell

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`close()` A PersistenceManager instance can be used until it is closed.
`Transaction`	`currentTransaction()` There is exactly one Transaction associated with a PersistenceManager.
`void`	`deletePersistent(Collection pcs)` Delete a Collection of instances from the data store.
`void`	`deletePersistent(Object pc)` Delete the persistent instance from the data store.
`void`	`deletePersistent(Object[] pcs)` Delete an array of instances from the data store.
`Collection`	`getExtent(Class persistenceCapableClass, boolean subclasses)` The PersistenceManager may manage a collection of instances in the data store based on the class of the instances.
`Object`	`getObjectById(Object oid)` This method locates a persistent instance in the cache of instances managed by this PersistenceManager.
`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)` In order for the application to construct instance of the ObjectId class it needs to know the class being used by the JDO implementation.
`PersistenceManagerFactory`	`getPersistenceManagerFactory()` This method returns the PersistenceManagerFactory used to create this PersistenceManager.
`Properties`	`getProperties()` The JDO vendor might store certain non-operational properties and make those properties available to applications (for troubleshooting).
`boolean`	`getRequireCopyObjectId()` Returns the boolean value of the requireCopyObjectId flag for this PersistenceManager.
`boolean`	`getRequireTrackedSCO()` Returns the boolean value of the requireTrackedSCO flag for this PersistenceManager.
`boolean`	`getSupersedeDeletedInstance()` Returns the boolean value of the supersedeDeletedInstance flag for this PersistenceManager.
`Object`	`getTransactionalInstance(Object pc)` This method is used to get a PersistenceCapable instance representing the same data store object as the parameter, that is valid for this PersistenceManager.
`Object`	`getUserObject()` The application can manage the PersistenceManager instances more easily by having an application object associated with each PersistenceManager instance.
`boolean`	`isClosed()` A PersistenceManager instance can be used until it is closed.
`void`	`makePersistent(Collection pcs)` Make a Collection of instances persistent.
`void`	`makePersistent(Object pc)` Make the transient instance persistent in this PersistenceManager.
`void`	`makePersistent(Object[] pcs)` Make an array of instances persistent.
`Object`	`newCollectionInstance(Class type, Object owner, String fieldName, Class elementType, boolean allowNulls, int initialSize)` Returns a new Collection instance of the type specified, with the owner and field name to notify upon changes to the value of any of its fields.
`Query`	`newQuery()` Create a new Query with no elements.
`Query`	`newQuery(Class cls)` Create a new Query specifying the Class of the candidate instances.
`Query`	`newQuery(Class cls, Collection cln)` Create a new Query with the Class of the candidate instances and candidate Collection.
`Query`	`newQuery(Class cls, Collection cln, String filter)` Create a new Query with the Class of the candidate instances, candidate Collection, and Filter.
`Query`	`newQuery(Class cls, String filter)` Create a new Query with the Class of the candidate instances and Filter.
`Query`	`newQuery(Object compiled)` Create a new Query using elements from another Query.
`Object`	`newSCOInstance(Class type, Object owner, String fieldName)` Returns a new Second Class Object instance of the type specified, with the owner and field name to notify upon changes to the value of any of its fields.
`void`	`setRequireCopyObjectId(boolean flag)` Sets the requireCopyObjectId flag for this PersistenceManager.
`void`	`setRequireTrackedSCO(boolean flag)` Sets the requireTrackedSCO flag for this PersistenceManager.
`void`	`setSupersedeDeletedInstance(boolean flag)` Sets the supersedeDeletedInstance flag for this PersistenceManager.
`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:
    
    if this PersistenceManager has been closed
    
    See Also:
    
    close()
  - close
```
void close()
```
    A PersistenceManager instance can be used until it is closed.
    This method closes the PersistenceManager, which if pooled, releases it to the pool of available PersistenceManagers.
  - currentTransaction
```
Transaction currentTransaction()
```
    There is exactly one Transaction associated with a PersistenceManager.
    
    Returns:
    
    the Transaction associated with this PersistenceManager.
  - newQuery
```
Query newQuery()
```
    Create a new Query with no elements.
    
    Returns:
    
    a new Query instance with no elements.
  - 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.
    
    Parameters:
    
    compiled - another Query from the same JDO implementation
    
    Returns:
    
    the new Query
  - newQuery
```
Query newQuery(Class cls)
```
    Create a new Query specifying the Class of the candidate instances.
    
    Parameters:
    
    cls - the Class of the candidate instances
    
    Returns:
    
    the new Query
  - newQuery
```
Query newQuery(Class cls,
               Collection cln)
```
    Create a new Query with the Class of the candidate instances and candidate Collection. specified.
    
    Parameters:
    
    cls - the Class of the candidate instances
    
    cln - the Collection of candidate instances
    
    Returns:
    
    the new Query
  - newQuery
```
Query newQuery(Class cls,
               String filter)
```
    Create a new Query with the Class of the candidate instances and Filter. specified.
    
    Parameters:
    
    cls - the Class of the candidate instances
    
    filter - the Filter for candidate instances
    
    Returns:
    
    the new Query
  - newQuery
```
Query newQuery(Class cls,
               Collection cln,
               String filter)
```
    Create a new Query with the Class of the candidate instances, candidate Collection, and Filter.
    
    Parameters:
    
    cls - the Class of the candidate instances
    
    cln - the Collection of candidate instances
    
    filter - the Filter for candidate instances
    
    Returns:
    
    the new Query
  - getExtent
```
Collection getExtent(Class persistenceCapableClass,
                     boolean subclasses)
```
    The PersistenceManager may manage a collection of instances in the data store based on the class of the instances. This method returns a Collection of instances in the data store that might be iterated or given to a Query as the Collection of candidate instances.
    
    Parameters:
    
    persistenceCapableClass - Class of instances
    
    subclasses - whether to include instances of subclasses
    
    Returns:
    
    a Collection of instances
    
    See Also:
    
    Query
  - getObjectById
```
Object getObjectById(Object oid)
```
    This method locates a persistent instance in the cache of instances managed by this PersistenceManager. If an instance with the same ObjectId is found it is returned. Otherwise, a new instance is created and associated with the ObjectId.
    If the instance does not exist in the data store, then this method will not fail. However, a request to access fields of the instance will throw an exception.
    
    Parameters:
    
    oid - an ObjectId
    
    Returns:
    
    the PersistenceCapable instance with the specified ObjectId
  - 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.
    
    Parameters:
    
    pc - the PersistenceCapable instance
    
    Returns:
    
    the ObjectId of the instance
  - getTransactionalInstance
```
Object getTransactionalInstance(Object pc)
```
    This method is used to get a PersistenceCapable instance representing the same data store object as the parameter, that is valid for this PersistenceManager.
    
    Parameters:
    
    pc - a PersistenceCapable instance
    
    Returns:
    
    the PersistenceCapable instance representing the same data store object
  - makePersistent
```
void makePersistent(Object pc)
```
    Make the transient instance persistent in this PersistenceManager. This method must be called in an active transaction. The PersistenceManager assigns an ObjectId to the instance and transitions it to persistent-new. The instance will be managed in the Extent associated with its Class. The instance will be put into the data store at commit.
    
    Parameters:
    
    pc - a transient instance of a Class that implements PersistenceCapable
  - makePersistent
```
void makePersistent(Object[] pcs)
```
    Make an array of instances persistent.
    
    Parameters:
    
    pcs - an array of transient instances
    
    See Also:
    
    makePersistent(Object pc)
  - makePersistent
```
void makePersistent(Collection pcs)
```
    Make a Collection of instances persistent.
    
    Parameters:
    
    pcs - a Collection of transient instances
    
    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 an exception if the instance is transient or is managed by another PersistenceManager.
    
    Parameters:
    
    pc - a persistent instance
  - deletePersistent
```
void deletePersistent(Object[] pcs)
```
    Delete an array of instances from the data store.
    
    Parameters:
    
    pcs - a Collection of persistent instances
    
    See Also:
    
    deletePersistent(Object pc)
  - deletePersistent
```
void deletePersistent(Collection pcs)
```
    Delete a Collection of instances from the data store.
    
    Parameters:
    
    pcs - a Collection of persistent instances
    
    See Also:
    
    deletePersistent(Object pc)
  - getPersistenceManagerFactory
```
PersistenceManagerFactory getPersistenceManagerFactory()
```
    This method returns the PersistenceManagerFactory used to create this PersistenceManager. It returns null if this instance was created via a constructor.
    
    Returns:
    
    the PersistenceManagerFactory that created this PersistenceManager
  - 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)
  - getProperties
```
Properties getProperties()
```
    The JDO vendor might store certain non-operational properties and make those properties available to applications (for troubleshooting).
    Standard properties include:
  - VendorName
  - VersionNumber

Returns:: the Properties of this PersistenceManager

getObjectIdClass
```
Class getObjectIdClass(Class cls)
```
In order for the application to construct 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

newSCOInstance
```
Object newSCOInstance(Class type,
                      Object owner,
                      String fieldName)
```
Returns a new Second Class Object instance of the type specified, with the owner and field name to notify upon changes to the value of any of its fields. If a collection class is created, then the class does not restrict the element types, and allows nulls to be added as elements.

Parameters:

type - Class of the new SCO instance

owner - the owner to notify upon changes

fieldName - the field to notify upon changes

Returns:

the object of the class type

newCollectionInstance
```
Object newCollectionInstance(Class type,
                             Object owner,
                             String fieldName,
                             Class elementType,
                             boolean allowNulls,
                             int initialSize)
```
Returns a new Collection instance of the type specified, with the owner and field name to notify upon changes to the value of any of its fields. The collection class restricts the element types allowed to the elementType or instances assignable to the elementType, and allows nulls to be added as elements based on the setting of allowNulls. The Collection has an initial size as specified by the initialSize parameter.

Parameters:

type - Class of the new SCO instance

owner - the owner to notify upon changes

fieldName - the field to notify upon changes

elementType - the element types allowed

allowNulls - true if allowed

initialSize - initial size of the Collection

Returns:

the object of the class type

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 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 JDODataStoreException. But a subsequent access of the fields of the instance will throw a JDODataStoreException 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 JDODataStoreException 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), getObjectById(Object oid)

getSupersedeDeletedInstance
```
boolean getSupersedeDeletedInstance()
```
Returns the boolean value of the supersedeDeletedInstance flag for this PersistenceManager. If set to true, deleted instances are allowed to be replaced with persistent-new instances with the equal Object Id.

Returns:

boolean supersedeDeletedInstance flag

setSupersedeDeletedInstance
```
void setSupersedeDeletedInstance(boolean flag)
```
Sets the supersedeDeletedInstance flag for this PersistenceManager.

Parameters:

flag - boolean supersedeDeletedInstance flag

getRequireCopyObjectId
```
boolean getRequireCopyObjectId()
```
Returns the boolean value of the requireCopyObjectId flag for this PersistenceManager. If set to false, the PersistenceManager does not create a copy of an ObjectId for PersistenceManager.getObjectId(Object pc) and PersistenceManager.getObjectById(Object oid) requests.

Returns:

boolean requireCopyObjectId flag

See Also:

getObjectId(Object pc), getObjectById(Object oid)

setRequireCopyObjectId
```
void setRequireCopyObjectId(boolean flag)
```
Sets the requireCopyObjectId flag for this PersistenceManager. If set to false, the PersistenceManager will not create a copy of an ObjectId for PersistenceManager.getObjectId(Object pc) and PersistenceManager.getObjectById(Object oid) requests.

Parameters:

flag - boolean requireCopyObjectId flag

See Also:

getObjectId(Object pc), getObjectById(Object oid)

getRequireTrackedSCO
```
boolean getRequireTrackedSCO()
```
Returns the boolean value of the requireTrackedSCO flag for this PersistenceManager. If set to false, the PersistenceManager will not create tracked SCO instances for new persistent instances at commit with retainValues set to true and while retrieving data from a datastore.

Returns:

boolean requireTrackedSCO flag

setRequireTrackedSCO
```
void setRequireTrackedSCO(boolean flag)
```
Sets the requireTrackedSCO flag for this PersistenceManager. If set to false, the PersistenceManager will not create tracked SCO instances for new persistent instances at commit with retainValues set to true and while retrieving data from a datastore.

Parameters:

flag - boolean requireTrackedSCO flag

Interface PersistenceManager

Method Summary

Method Detail

isClosed

close

currentTransaction

newQuery

newQuery

newQuery

newQuery

newQuery

newQuery

getExtent

getObjectById

getObjectId

getTransactionalInstance

makePersistent

makePersistent

makePersistent

deletePersistent

deletePersistent

deletePersistent

getPersistenceManagerFactory

setUserObject

getUserObject

getProperties

getObjectIdClass

newSCOInstance

newCollectionInstance

getObjectById

getSupersedeDeletedInstance

setSupersedeDeletedInstance

getRequireCopyObjectId

setRequireCopyObjectId

getRequireTrackedSCO

setRequireTrackedSCO