javax.jdo.PersistenceManagerFactory Maven / Gradle / Ivy
Show all versions of jdo-api Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* PersistenceManagerFactory.java
*
*/
package javax.jdo;
import javax.jdo.datastore.DataStoreCache;
import javax.jdo.listener.InstanceLifecycleListener;
import javax.jdo.metadata.TypeMetadata;
import javax.jdo.metadata.JDOMetadata;
import javax.jdo.spi.JDOPermission; // for getFetchGroups javadoc
import java.io.Serializable;
import java.util.Collection;
import java.util.Properties;
import java.util.Set;
/** 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.2
*/
public interface PersistenceManagerFactory extends Serializable {
/** 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
*/
void close();
/**
* A PersistenceManagerFactory instance can be used
* until it is closed.
* @return true if this PersistenceManagerFactory
* has been closed.
* @see #close()
* @since 2.0
*/
boolean isClosed();
/** 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.
*
* @return a PersistenceManager instance with default options.
*/
PersistenceManager getPersistenceManager();
/** Get a thread-safe instance of a proxy that dynamically binds
* on each method call to an instance of PersistenceManager.
*
When used with a PersistenceManagerFactory
* that uses TransactionType JTA,
* the proxy can be used in a server to dynamically bind to an instance
* from this factory associated with the thread's current transaction.
* In this case, the close method is ignored, as the
* PersistenceManager is automatically closed when the
* transaction completes.
*
When used with a PersistenceManagerFactory
* that uses TransactionType RESOURCE_LOCAL, the proxy uses an inheritable
* ThreadLocal to bind to an instance of PersistenceManager
* associated with the thread. In this case, the close method executed
* on the proxy closes the PersistenceManager and then
* clears the ThreadLocal.
* Use of this method does not affect the configurability of the
* PersistenceManagerFactory.
*
* @since 2.1
* @return a PersistenceManager proxy.
*/
PersistenceManager getPersistenceManagerProxy();
/** 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.
*
* @return a PersistenceManager instance with default options.
* @param userid the userid for the connection
* @param password the password for the connection
*/
PersistenceManager getPersistenceManager(String userid, String password);
/** Set the user name for the data store connection.
* @param userName the user name for the data store connection.
*/
void setConnectionUserName(String userName);
/** Get the user name for the data store connection.
* @return the user name for the data store connection.
*/
String getConnectionUserName ();
/** Set the password for the data store connection.
* @param password the password for the data store connection.
*/
void setConnectionPassword (String password);
/** Set the URL for the data store connection.
* @param url the URL for the data store connection.
*/
void setConnectionURL (String url);
/** Get the URL for the data store connection.
* @return the URL for the data store connection.
*/
String getConnectionURL ();
/** Set the driver name for the data store connection.
* @param driverName the driver name for the data store connection.
*/
void setConnectionDriverName (String driverName);
/** Get the driver name for the data store connection.
* @return the driver name for the data store connection.
*/
String getConnectionDriverName ();
/** Set the name for the data store connection factory.
* @param connectionFactoryName the name of the data store connection
* factory.
*/
void setConnectionFactoryName (String connectionFactoryName);
/** Get the name for the data store connection factory.
* @return the name of the data store connection factory.
*/
String getConnectionFactoryName ();
/** Set the data store connection factory. JDO implementations
* will support specific connection factories. The connection
* factory interfaces are not part of the JDO specification.
* @param connectionFactory the data store connection factory.
*/
void setConnectionFactory (Object connectionFactory);
/** Get the data store connection factory.
* @return the data store connection factory.
*/
Object getConnectionFactory ();
/** Set the name for the second data store connection factory. This is
* needed for managed environments to get nontransactional connections for
* optimistic transactions.
* @param connectionFactoryName the name of the data store connection
* factory.
*/
void setConnectionFactory2Name (String connectionFactoryName);
/** Get the name for the second data store connection factory. This is
* needed for managed environments to get nontransactional connections for
* optimistic transactions.
* @return the name of the data store connection factory.
*/
String getConnectionFactory2Name ();
/** 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.
* @param connectionFactory the data store connection factory.
*/
void setConnectionFactory2 (Object connectionFactory);
/** Get the second data store connection factory. This is
* needed for managed environments to get nontransactional connections for
* optimistic transactions.
* @return the data store connection factory.
*/
Object getConnectionFactory2 ();
/** Set the default Multithreaded setting for all
* PersistenceManager instances obtained from this factory.
*
* @param flag the default Multithreaded setting.
*/
void setMultithreaded (boolean flag);
/** Get the default Multithreaded setting for all
* PersistenceManager instances obtained from this factory.
*
* @return the default Multithreaded setting.
*/
boolean getMultithreaded();
/** Set the Mapping setting for this factory. This is used to find the
* object-datastore mapping file(s).
*
* @param mapping the Mapping setting.
*/
void setMapping (String mapping);
/** Get the Mapping setting for this factory. This is used to find the
* object-datastore mapping file(s).
*
* @return the Mapping setting.
*/
String getMapping ();
/** Set the default Optimistic setting for all
* PersistenceManager instances obtained from this factory.
*
* @param flag the default Optimistic setting.
*/
void setOptimistic (boolean flag);
/** Get the default Optimistic setting for all
* PersistenceManager instances obtained from this factory.
*
* @return the default Optimistic setting.
*/
boolean getOptimistic();
/** Set the default RetainValues setting for all
* PersistenceManager instances obtained from this factory.
*
* @param flag the default RetainValues setting.
*/
void setRetainValues (boolean flag);
/** Get the default RetainValues setting for all
* PersistenceManager instances obtained from this factory.
*
* @return the default RetainValues setting.
*/
boolean getRetainValues ();
/** 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.
* @param restoreValues the value of the restoreValues property
*/
void setRestoreValues(boolean restoreValues);
/** Get the default value for the RestoreValues property.
* @return the value of the restoreValues property
*/
boolean getRestoreValues();
/** Set the default NontransactionalRead setting for all
* PersistenceManager instances obtained from this factory.
*
* @param flag the default NontransactionalRead setting.
*/
void setNontransactionalRead (boolean flag);
/** Get the default NontransactionalRead setting for all
* PersistenceManager instances obtained from this factory.
*
* @return the default NontransactionalRead setting.
*/
boolean getNontransactionalRead ();
/** Set the default NontransactionalWrite setting for all
* PersistenceManager instances obtained from this factory.
*
* @param flag the default NontransactionalWrite setting.
*/
void setNontransactionalWrite (boolean flag);
/** Get the default NontransactionalWrite setting for all
* PersistenceManager instances obtained from this factory.
*
* @return the default NontransactionalWrite setting.
*/
boolean getNontransactionalWrite ();
/** Set the default IgnoreCache setting for all
* PersistenceManager instances obtained from this factory.
*
* @param flag the default IgnoreCache setting.
*/
void setIgnoreCache (boolean flag);
/** Get the default IgnoreCache setting for all
* PersistenceManager instances obtained from this factory.
*
* @return the default IngoreCache setting.
*/
boolean getIgnoreCache ();
/** Gets the detachAllOnCommit setting.
* @see #setDetachAllOnCommit(boolean)
* @since 2.0
* @return the default detachAllOnCommit setting.
*/
boolean getDetachAllOnCommit();
/** Sets the default detachAllOnCommit setting for all
* PersistenceManager instances obtained from this
* factory.
* @see #getDetachAllOnCommit()
* @since 2.0
* @param flag the default DetachAllOnCommit setting
*/
void setDetachAllOnCommit(boolean flag);
/** Gets the default copyOnAttach setting for all
* PersistenceManager instances obtained from this
* factory.
* @see #setCopyOnAttach(boolean)
* @since 2.1
* @return the copyOnAttach setting.
*/
boolean getCopyOnAttach();
/** Sets the default copyOnAttach setting for all
* PersistenceManager instances obtained from this
* factory.
*
*
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.
*
* @see #getCopyOnAttach()
* @since 2.1
*/
void setCopyOnAttach(boolean flag);
/**
* Sets the name of this PersistenceManagerFactory.
* @since 2.1
* @param name the name of this PMF
*/
void setName(String name);
/**
* Gets the name of this PersistenceManagerFactory.
* @since 2.1
* @return the name of this PMF
*/
String getName();
/**
* Sets the PersistenceUnitName for this PersistenceManagerFactory.
* This has the same semantics as the same-named property in
* JSR-220 PersistenceUnitInfo.
* @see #getPersistenceUnitName()
* @since 2.1
* @param name the PersistenceUnitName
*/
void setPersistenceUnitName(String name);
/**
* Gets the PersistenceUnitName for this PersistenceManagerFactory.
* @see #setPersistenceUnitName(String)
* @since 2.1
* @return the PersistenceUnitName
*/
String getPersistenceUnitName();
/**
* Sets the TimeZone ID of the server associated with this
* PersistenceManagerFactory. The parameter is a String
* suitable for use with TimeZone.getTimeZone(). The String
* must match an ID returned by TimeZone.getAvailableIDs().
* If the ServerTimeZoneID is not set, or set to the null String,
* assume that the server has the same TimeZone ID as the client.
* If incorrectly set, the result of PersistenceManager.getServerDate()
* might be incorrect.
* @see #getServerTimeZoneID()
* @see java.util.TimeZone#getTimeZone(String)
* @see java.util.TimeZone#getAvailableIDs()
* @see PersistenceManager#getServerDate()
* @since 2.1
* @param timezoneid the TimeZone ID of the server
* @throws JDOUserException if the parameter does not match
* an ID from TimeZone.getAvailableIDs()
*/
void setServerTimeZoneID(String timezoneid);
/**
* Gets the TimeZone ID of the server associated with this
* PersistenceManagerFactory. If not set, assume that
* the server has the same TimeZone ID as the client.
* @see #setServerTimeZoneID(String)
* @since 2.1
* @return the TimeZone of the server
*/
String getServerTimeZoneID();
/**
* Sets the TransactionType for this PersistenceManagerFactory.
* Permitted values are "JTA" and "RESOURCE_LOCAL".
* This has the same semantics as the same-named property in
* JSR-220 EntityManagerFactory.
* @see #getTransactionType()
* @see Constants#JTA
* @see Constants#RESOURCE_LOCAL
* @since 2.1
* @param name the TransactionType
* @throws JDOUserException if the parameter is not a permitted value
*/
void setTransactionType(String name);
/**
* Gets the TransactionType for this PersistenceManagerFactory.
* @see #setTransactionType(String)
* @since 2.1
* @return the TransactionType
*/
String getTransactionType();
/** Gets the value for read-only for this PMF.
* Indicates whether the datastore is read-only or writable.
* @see #setReadOnly(boolean)
* @since 2.2
* @return the readOnly setting.
*/
boolean getReadOnly();
/** Sets the value for whether the datastore is to be considered
* read-only.
*
*
ReadOnly set to false specifies that no updates
* can be performed to the datastore, and if updates are attempted
* a JDOReadOnlyException is thrown.
*
* @see #getReadOnly()
* @since 2.2
*/
void setReadOnly(boolean flag);
/** Get the value for transaction isolation level for this PMF.
* @return the transaction isolation level
* @see #setTransactionIsolationLevel(String)
* @since 2.2
*/
String getTransactionIsolationLevel();
/** Set the value for transaction isolation level for this PMF.
* Transaction isolation levels are defined in javax.jdo.Constants.
* If the requested level is not available, but a higher level is
* available, the higher level is silently used.
* If the requested level is not available, and no higher level is
* available, then JDOUnsupportedOptionException is thrown.
* Standard values in order from low to high are:
*
- read-uncommitted
*
- read-committed
*
- repeatable-read
*
- snapshot
*
- serializable
*
* @param level the transaction isolation level
* @see #getTransactionIsolationLevel()
* @see Constants#TX_READ_UNCOMMITTED
* @see Constants#TX_READ_COMMITTED
* @see Constants#TX_REPEATABLE_READ
* @see Constants#TX_SNAPSHOT
* @see Constants#TX_SERIALIZABLE
* @since 2.2
*/
void setTransactionIsolationLevel(String level);
/**
* Specify a default timeout interval (milliseconds) for any read
* operations for persistence managers obtained from this persistence
* manager factory. To unset the explicit timeout, specify null.
* For no timeout, specify 0.
* If the datastore and JDO implementation support timeouts, then
* javax.jdo.option.DatastoreTimeout is returned by supportedOptions().
* If timeouts are not supported,this method will throw
* JDOUnsupportedOptionException.
* @since 3.0
* @param interval the timeout interval (milliseconds)
*/
void setDatastoreReadTimeoutMillis(Integer interval);
/** Get the default timeout setting for read operations.
* If timeouts are not supported,this method will return null.
* @see #setDatastoreReadTimeoutMillis(Integer)
* @return the default timeout setting (milliseconds).
* @since 3.0
*/
Integer getDatastoreReadTimeoutMillis();
/**
* Specify a default timeout interval (milliseconds) for any write
* operations for persistence managers obtained from this persistence
* manager factory. To unset the explicit timeout, specify null.
* For no timeout, specify 0.
* If the datastore and JDO implementation support timeouts, then
* javax.jdo.option.DatastoreTimeout is returned by supportedOptions().
* If timeouts are not supported,this method will throw
* JDOUnsupportedOptionException.
* @since 3.0
* @param interval the timeout interval (milliseconds)
*/
void setDatastoreWriteTimeoutMillis(Integer interval);
/** Get the default timeout setting for write operations.
* If timeouts are not supported,this method will return null.
* @see #setDatastoreWriteTimeoutMillis(Integer)
* @return the default timeout setting (milliseconds).
* @since 3.0
*/
Integer getDatastoreWriteTimeoutMillis();
/** Return non-configurable properties of this
* PersistenceManagerFactory.
* Properties with keys VendorName and
* VersionNumber are required. Other keys are optional.
* @return the non-configurable properties of this
* PersistenceManagerFactory.
*/
Properties getProperties();
/** 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 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.NonDurableIdentity
*
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.option.TransactionIsolationLevel.read-uncommitted
*
javax.jdo.option.TransactionIsolationLevel.read-committed
*
javax.jdo.option.TransactionIsolationLevel.repeatable-read
*
javax.jdo.option.TransactionIsolationLevel.snapshot
*
javax.jdo.option.TransactionIsolationLevel.serializable
*
javax.jdo.option.QueryCancel
*
javax.jdo.option.DatastoreTimeout
*
javax.jdo.query.SQL
*
javax.jdo.query.JDOQL
*
*
*
The standard JDO query language is represented by a
* String:
*
javax.jdo.query.JDOQL
* @return the Collection of Strings representing
* the supported options.
*/
Collection supportedOptions();
/**
* Return the {@link 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
* @return the DataStoreCache
*/
DataStoreCache getDataStoreCache ();
/**
* 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 {@link #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 {@link InstanceLifecycleListener}
* interface.
* @param listener the lifecycle listener
* @param classes the classes of interest to the listener
* @since 2.0
*/
void addInstanceLifecycleListener (InstanceLifecycleListener listener,
Class[] classes);
/**
* 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 {@link #getPersistenceManager}
* is called).
* @param listener the listener instance to be removed
* @since 2.0
*/
void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
/**
* Add the FetchGroups to the set of active fetch groups.
* FetchGroups are made unmodifiable before being added.
* FetchGroups that match existing FetchGroups
* replace the corresponding FetchGroups.
* The replaced FetchGroups become unscoped.
* Match is based on identical class and equal name.
* The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
* {@link #getFetchGroups}, and {@link #removeAllFetchGroups}
* are internally serialized.
* @param groups an array of FetchGroups
* @throws SecurityException if the caller is not authorized for
* {@link JDOPermission} ("manageMetadata")
* @since 2.2
*/
void addFetchGroups(FetchGroup... groups);
/**
* Remove the FetchGroups from the set of active
* FetchGroups. Existing FetchGroups that match
* parameter FetchGroups are removed. Parameter
* FetchGroups that do not match any existing
* FetchGroup are ignored.
* Removed FetchGroups become unscoped.
* Match is based on identical class and equal name.
* The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
* {@link #getFetchGroups}, and {@link #removeAllFetchGroups}
* are internally serialized.
* @param groups an array of FetchGroups
* @throws SecurityException if the caller is not authorized for
* {@link JDOPermission} ("manageMetadata")
* @since 2.2
*/
void removeFetchGroups(FetchGroup... groups);
/**
* Remove all FetchGroups from the set of active
* FetchGroups.
* All removed FetchGroups become unscoped.
* The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
* {@link #getFetchGroups}, and {@link #removeAllFetchGroups}
* are internally serialized.
* @throws SecurityException if the caller is not authorized for
* {@link JDOPermission} ("manageMetadata")
* @since 2.2
*/
void removeAllFetchGroups();
/**
* Create an unscoped, modifiable FetchGroup for the Class and
* name. If a corresponding FetchGroup already exists in
* PersistenceManagerFactory scope, copy its definition
* to a new FetchGroup.
* If the FetchGroup does not already exist, create it
* with no members. The FetchGroup does not become
* in scope until it is added to the current set via
* {@link #addFetchGroups}.
* @param cls the class or interface for the FetchGroup
* @param name the name of the fetch group
* @return the FetchGroup
* @throws JDOUserException if the class is not a persistence-capable
* class or interface
* @since 2.2
*/
FetchGroup getFetchGroup(Class cls, String name);
/**
* Get a modifiable Set containing a mutable copy of all currently active
* (in scope) fetch groups.
* The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
* {@link #getFetchGroups}, and {@link #removeAllFetchGroups}
* are internally serialized.
* @return a copy of all currently active fetch groups
* @throws SecurityException if the caller is not authorized for
* {@link JDOPermission} ("getMetadata")
* @since 2.2
*/
Set getFetchGroups();
/**
* Method to register metadata with the persistence process managed by this
* PersistenceManagerFactory.
* Metadata can be created using the method {@link #newMetadata}.
* If there is already metadata registered for a class contained in this metadata
* object then a JDOUserException will be thrown.
* @param metadata The Metadata to register.
* @since 3.0
*/
void registerMetadata(JDOMetadata metadata);
/**
* Method to return a new metadata object that can be subsequently modified
* and registered with the persistence process using the method {@link #registerMetadata}.
* @return The metadata
* @since 3.0
*/
JDOMetadata newMetadata();
/**
* Method to return the metadata object for the specified class/interface, if there is
* metadata defined for that class/interface.
* If there is no metadata for the specified class/interface, or the parameter is null,
* then null will be returned.
* @return The metadata
* @since 3.0
*/
TypeMetadata getMetadata(String className);
/**
* Method to return the currently managed classes for this factory.
* @return Collection of persistable classes that are managed by this factory
* @since 3.1
*/
Collection getManagedClasses();
}