/* * 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: *

* @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(); }