/* * Copyright 2005 The Apache Software Foundation. * * Licensed 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 java.util.Properties; import java.util.Collection; import javax.jdo.datastore.DataStoreCache; import javax.jdo.listener.InstanceLifecycleListener; /** 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 */ public interface PersistenceManagerFactory extends java.io.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 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 */ void setDetachAllOnCommit(boolean flag); /** 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 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 * @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 */ 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); }