javax.jdo

Interface PersistenceManagerFactory

All Superinterfaces:
java.io.Serializable

public interface PersistenceManagerFactory
extends java.io.Serializable

The PersistenceManagerFactory is the interface to use to obtain PersistenceManager instances. All PersistenceManager instances obtained from the same PersistenceManagerFactory will have the same default properties.

PersistenceManagerFactory instances may be configured and serialized for later use. They may be stored via JNDI and looked up and used later. Any properties configured will be saved and restored.

Once the first PersistenceManager is obtained from the PersistenceManagerFactory, the factory can no longer be configured.

If the ConnectionFactory property is set (non-null) then all other Connection properties including ConnectionFactoryName are ignored; otherwise, if ConnectionFactoryName is set (non-null) then all other Connection properties are ignored. Similarly, if the ConnectionFactory2 property is set (non-null) then ConnectionFactory2Name is ignored.

Operational state (PersistenceManager pooling, connection pooling, operational parameters) must not be serialized.

Version:
2.0

Method Summary

void
addInstanceLifecycleListener(InstanceLifecycleListener listener, Class[] classes)
Add the parameter listener to the list of instance lifecycle event listeners set as the initial listeners for each PersistenceManager created by this PersistenceManagerFactory.
void
close()
Close this PersistenceManagerFactory.
String
getConnectionDriverName()
Get the driver name for the data store connection.
Object
getConnectionFactory()
Get the data store connection factory.
Object
getConnectionFactory2()
Get the second data store connection factory.
String
getConnectionFactory2Name()
Get the name for the second data store connection factory.
String
getConnectionFactoryName()
Get the name for the data store connection factory.
String
getConnectionURL()
Get the URL for the data store connection.
String
getConnectionUserName()
Get the user name for the data store connection.
DataStoreCache
getDataStoreCache()
Return the DataStoreCache that this factory uses for controlling a second-level cache.
boolean
getDetachAllOnCommit()
Gets the detachAllOnCommit setting.
boolean
getIgnoreCache()
Get the default IgnoreCache setting for all PersistenceManager instances obtained from this factory.
String
getMapping()
Get the Mapping setting for this factory.
boolean
getMultithreaded()
Get the default Multithreaded setting for all PersistenceManager instances obtained from this factory.
boolean
getNontransactionalRead()
Get the default NontransactionalRead setting for all PersistenceManager instances obtained from this factory.
boolean
getNontransactionalWrite()
Get the default NontransactionalWrite setting for all PersistenceManager instances obtained from this factory.
boolean
getOptimistic()
Get the default Optimistic setting for all PersistenceManager instances obtained from this factory.
PersistenceManager
getPersistenceManager()
Get an instance of PersistenceManager from this factory.
PersistenceManager
getPersistenceManager(String userid, String password)
Get an instance of PersistenceManager from this factory.
Properties
getProperties()
Return non-configurable properties of this PersistenceManagerFactory.
boolean
getRestoreValues()
Get the default value for the RestoreValues property.
boolean
getRetainValues()
Get the default RetainValues setting for all PersistenceManager instances obtained from this factory.
boolean
isClosed()
A PersistenceManagerFactory instance can be used until it is closed.
void
removeInstanceLifecycleListener(InstanceLifecycleListener listener)
Remove the parameter listener instance from the list of instance lifecycle event listeners set as the initial listeners for each PersistenceManager created by this PersistenceManagerFactory.
void
setConnectionDriverName(String driverName)
Set the driver name for the data store connection.
void
setConnectionFactory(Object connectionFactory)
Set the data store connection factory.
void
setConnectionFactory2(Object connectionFactory)
Set the second data store connection factory.
void
setConnectionFactory2Name(String connectionFactoryName)
Set the name for the second data store connection factory.
void
setConnectionFactoryName(String connectionFactoryName)
Set the name for the data store connection factory.
void
setConnectionPassword(String password)
Set the password for the data store connection.
void
setConnectionURL(String url)
Set the URL for the data store connection.
void
setConnectionUserName(String userName)
Set the user name for the data store connection.
void
setDetachAllOnCommit(boolean flag)
Sets the default detachAllOnCommit setting for all PersistenceManager instances obtained from this factory.
void
setIgnoreCache(boolean flag)
Set the default IgnoreCache setting for all PersistenceManager instances obtained from this factory.
void
setMapping(String mapping)
Set the Mapping setting for this factory.
void
setMultithreaded(boolean flag)
Set the default Multithreaded setting for all PersistenceManager instances obtained from this factory.
void
setNontransactionalRead(boolean flag)
Set the default NontransactionalRead setting for all PersistenceManager instances obtained from this factory.
void
setNontransactionalWrite(boolean flag)
Set the default NontransactionalWrite setting for all PersistenceManager instances obtained from this factory.
void
setOptimistic(boolean flag)
Set the default Optimistic setting for all PersistenceManager instances obtained from this factory.
void
setRestoreValues(boolean restoreValues)
Set the default value for the RestoreValues property.
void
setRetainValues(boolean flag)
Set the default RetainValues setting for all PersistenceManager instances obtained from this factory.
Collection
supportedOptions()
The application can determine from the results of this method which optional features, and which query languages are supported by the JDO implementation.

Method Details

addInstanceLifecycleListener

public void addInstanceLifecycleListener(InstanceLifecycleListener listener,
                                         Class[] classes)
Add the parameter listener to the list of instance lifecycle event listeners set as the initial listeners for each PersistenceManager created by this PersistenceManagerFactory. The addInstanceLifecycleListener and removeInstanceLifecycleListener methods are considered to be configuration methods and can only be called when the PersistenceManagerFactory is configurable (before the first time getPersistenceManager is called).

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 the listener.

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

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

close

public void close()
Close this PersistenceManagerFactory. Check for JDOPermission("closePersistenceManagerFactory") and if not authorized, throw SecurityException.

If the authorization check succeeds, check to see that all PersistenceManager instances obtained from this PersistenceManagerFactory have no active transactions. If any PersistenceManager instances have an active transaction, throw a JDOUserException, with one nested JDOUserException for each PersistenceManager with an active Transaction.

If there are no active transactions, then close all PersistenceManager instances obtained from this PersistenceManagerFactory, mark this PersistenceManagerFactory as closed, disallow getPersistenceManager methods, and allow all other get methods. If a set method or getPersistenceManager method is called after close, then JDOUserException is thrown.

Since:
1.0.1

getConnectionDriverName

public String getConnectionDriverName()
Get the driver name for the data store connection.
Returns:
the driver name for the data store connection.

getConnectionFactory

public Object getConnectionFactory()
Get the data store connection factory.
Returns:
the data store connection factory.

getConnectionFactory2

public Object getConnectionFactory2()
Get the second data store connection factory. This is needed for managed environments to get nontransactional connections for optimistic transactions.
Returns:
the data store connection factory.

getConnectionFactory2Name

public String getConnectionFactory2Name()
Get the name for the second data store connection factory. This is needed for managed environments to get nontransactional connections for optimistic transactions.
Returns:
the name of the data store connection factory.

getConnectionFactoryName

public String getConnectionFactoryName()
Get the name for the data store connection factory.
Returns:
the name of the data store connection factory.

getConnectionURL

public String getConnectionURL()
Get the URL for the data store connection.
Returns:
the URL for the data store connection.

getConnectionUserName

public String getConnectionUserName()
Get the user name for the data store connection.
Returns:
the user name for the data store connection.

getDataStoreCache

public DataStoreCache getDataStoreCache()
Return the DataStoreCache that this factory uses for controlling a second-level cache. If this factory does not use a second-level cache, the returned instance does nothing. This method never returns null.
Since:
2.0

getDetachAllOnCommit

public boolean getDetachAllOnCommit()
Gets the detachAllOnCommit setting.
Returns:
the default detachAllOnCommit setting.
Since:
2.0

getIgnoreCache

public boolean getIgnoreCache()
Get the default IgnoreCache setting for all PersistenceManager instances obtained from this factory.
Returns:
the default IngoreCache setting.

getMapping

public String getMapping()
Get the Mapping setting for this factory. This is used to find the object-datastore mapping file(s).
Returns:
the Mapping setting.

getMultithreaded

public boolean getMultithreaded()
Get the default Multithreaded setting for all PersistenceManager instances obtained from this factory.
Returns:
the default Multithreaded setting.

getNontransactionalRead

public boolean getNontransactionalRead()
Get the default NontransactionalRead setting for all PersistenceManager instances obtained from this factory.
Returns:
the default NontransactionalRead setting.

getNontransactionalWrite

public boolean getNontransactionalWrite()
Get the default NontransactionalWrite setting for all PersistenceManager instances obtained from this factory.
Returns:
the default NontransactionalWrite setting.

getOptimistic

public boolean getOptimistic()
Get the default Optimistic setting for all PersistenceManager instances obtained from this factory.
Returns:
the default Optimistic setting.

getPersistenceManager

public PersistenceManager getPersistenceManager()
Get an instance of PersistenceManager from this factory. The instance has default values for options.

After the first use of getPersistenceManager, no "set" methods will succeed.

Returns:
a PersistenceManager instance with default options.

getPersistenceManager

public PersistenceManager getPersistenceManager(String userid,
                                                String password)
Get an instance of PersistenceManager from this factory. The instance has default values for options. The parameters userid and password are used when obtaining datastore connections from the connection pool.

After the first use of getPersistenceManager, no "set" methods will succeed.

Parameters:
userid - the userid for the connection
password - the password for the connection
Returns:
a PersistenceManager instance with default options.

getProperties

public Properties getProperties()
Return non-configurable properties of this PersistenceManagerFactory. Properties with keys VendorName and VersionNumber are required. Other keys are optional.
Returns:
the non-configurable properties of this PersistenceManagerFactory.

getRestoreValues

public boolean getRestoreValues()
Get the default value for the RestoreValues property.
Returns:
the value of the restoreValues property

getRetainValues

public boolean getRetainValues()
Get the default RetainValues setting for all PersistenceManager instances obtained from this factory.
Returns:
the default RetainValues setting.

isClosed

public boolean isClosed()
A PersistenceManagerFactory instance can be used until it is closed.
Returns:
true if this PersistenceManagerFactory has been closed.
Since:
2.0

removeInstanceLifecycleListener

public void removeInstanceLifecycleListener(InstanceLifecycleListener listener)
Remove the parameter listener instance from the list of instance lifecycle event listeners set as the initial listeners for each PersistenceManager created by this PersistenceManagerFactory. The addInstanceLifecycleListener and removeInstanceLifecycleListener methods are considered to be configuration methods and can only be called when the PersistenceManagerFactory is configurable (before the first time getPersistenceManager is called).
Parameters:
listener - the listener instance to be removed
Since:
2.0

setConnectionDriverName

public void setConnectionDriverName(String driverName)
Set the driver name for the data store connection.
Parameters:
driverName - the driver name for the data store connection.

setConnectionFactory

public void setConnectionFactory(Object connectionFactory)
Set the data store connection factory. JDO implementations will support specific connection factories. The connection factory interfaces are not part of the JDO specification.
Parameters:
connectionFactory - the data store connection factory.

setConnectionFactory2

public void setConnectionFactory2(Object connectionFactory)
Set the second data store connection factory. This is needed for managed environments to get nontransactional connections for optimistic transactions. JDO implementations will support specific connection factories. The connection factory interfaces are not part of the JDO specification.
Parameters:
connectionFactory - the data store connection factory.

setConnectionFactory2Name

public void setConnectionFactory2Name(String connectionFactoryName)
Set the name for the second data store connection factory. This is needed for managed environments to get nontransactional connections for optimistic transactions.
Parameters:
connectionFactoryName - the name of the data store connection factory.

setConnectionFactoryName

public void setConnectionFactoryName(String connectionFactoryName)
Set the name for the data store connection factory.
Parameters:
connectionFactoryName - the name of the data store connection factory.

setConnectionPassword

public void setConnectionPassword(String password)
Set the password for the data store connection.
Parameters:
password - the password for the data store connection.

setConnectionURL

public void setConnectionURL(String url)
Set the URL for the data store connection.
Parameters:
url - the URL for the data store connection.

setConnectionUserName

public void setConnectionUserName(String userName)
Set the user name for the data store connection.
Parameters:
userName - the user name for the data store connection.

setDetachAllOnCommit

public void setDetachAllOnCommit(boolean flag)
Sets the default detachAllOnCommit setting for all PersistenceManager instances obtained from this factory.
Since:
2.0

setIgnoreCache

public void setIgnoreCache(boolean flag)
Set the default IgnoreCache setting for all PersistenceManager instances obtained from this factory.
Parameters:
flag - the default IgnoreCache setting.

setMapping

public void setMapping(String mapping)
Set the Mapping setting for this factory. This is used to find the object-datastore mapping file(s).
Parameters:
mapping - the Mapping setting.

setMultithreaded

public void setMultithreaded(boolean flag)
Set the default Multithreaded setting for all PersistenceManager instances obtained from this factory.
Parameters:
flag - the default Multithreaded setting.

setNontransactionalRead

public void setNontransactionalRead(boolean flag)
Set the default NontransactionalRead setting for all PersistenceManager instances obtained from this factory.
Parameters:
flag - the default NontransactionalRead setting.

setNontransactionalWrite

public void setNontransactionalWrite(boolean flag)
Set the default NontransactionalWrite setting for all PersistenceManager instances obtained from this factory.
Parameters:
flag - the default NontransactionalWrite setting.

setOptimistic

public void setOptimistic(boolean flag)
Set the default Optimistic setting for all PersistenceManager instances obtained from this factory.
Parameters:
flag - the default Optimistic setting.

setRestoreValues

public void setRestoreValues(boolean restoreValues)
Set the default value for the RestoreValues property. If true, at rollback, fields of newly persistent instances are restored to their values as of the beginning of the transaction, and the instances revert to transient. Additionally, fields of modified instances of primitive types and immutable reference types are restored to their values as of the beginning of the transaction.

If false, at rollback, the values of fields of newly persistent instances are unchanged and the instances revert to transient. Additionally, dirty instances transition to hollow. If an implementation does not support this option, a JDOUnsupportedOptionException is thrown.

Parameters:
restoreValues - the value of the restoreValues property

setRetainValues

public void setRetainValues(boolean flag)
Set the default RetainValues setting for all PersistenceManager instances obtained from this factory.
Parameters:
flag - the default RetainValues setting.

supportedOptions

public Collection supportedOptions()
The application can determine from the results of this method which optional features, and which query languages are supported by the JDO implementation.

Each supported JDO optional feature is represented by a String with one of the following values:

javax.jdo.option.TransientTransactional
javax.jdo.option.NontransactionalRead
javax.jdo.option.NontransactionalWrite
javax.jdo.option.RetainValues
javax.jdo.option.Optimistic
javax.jdo.option.ApplicationIdentity
javax.jdo.option.DatastoreIdentity
javax.jdo.option.NonDatastoreIdentity
javax.jdo.option.ArrayList
javax.jdo.option.HashMap
javax.jdo.option.Hashtable
javax.jdo.option.LinkedList
javax.jdo.option.TreeMap
javax.jdo.option.TreeSet
javax.jdo.option.Vector
javax.jdo.option.Map
javax.jdo.option.List
javax.jdo.option.Array
javax.jdo.option.NullCollection
javax.jdo.option.ChangeApplicationIdentity
javax.jdo.option.BinaryCompatibility
javax.jdo.option.GetDataStoreConnection
javax.jdo.option.UnconstrainedQueryVariables
javax.jdo.query.SQL
javax.jdo.query.JDOQL

The standard JDO query language is represented by a String:

javax.jdo.query.JDOQL

Returns:
the Collection of Strings representing the supported options.