/*
 * 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 <code>PersistenceManagerFactory</code> is the interface to use to obtain
 * <code>PersistenceManager</code> instances.  All <code>PersistenceManager</code> instances obtained
 * from the same <code>PersistenceManagerFactory</code> will have the same default
 * properties.
 *
 * <P><code>PersistenceManagerFactory</code> 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.
 *
 * <P>Once the first <code>PersistenceManager</code> is obtained from the 
 * <code>PersistenceManagerFactory</code>, the factory can no longer be configured.
 * <P>If the <code>ConnectionFactory</code> property is set (non-<code>null</code>) then 
 * all other Connection properties including <code>ConnectionFactoryName</code> are ignored;
 * otherwise, if <code>ConnectionFactoryName</code> is set (non-<code>null</code>) then
 * all other Connection properties are ignored.
 * Similarly, if the <code>ConnectionFactory2</code> property is set (non-<code>null</code>) then 
 * <code>ConnectionFactory2Name</code> is ignored.
 * <P>Operational state (<code>PersistenceManager</code> 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. 
     * <P>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. 
     * <P>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 <code>PersistenceManagerFactory</code> instance can be used 
     * until it is closed.
     * @return <code>true</code> if this <code>PersistenceManagerFactory</code>
     * has been closed.
     * @see #close()
     * @since 2.0
     */
    boolean isClosed();
    
    /** Get an instance of <code>PersistenceManager</code> from this factory.  The instance has
     * default values for options.
     *
     * <P>After the first use of <code>getPersistenceManager</code>, no "set" methods will
     * succeed.
     *
     * @return a <code>PersistenceManager</code> instance with default options.
     */
    PersistenceManager getPersistenceManager();

    /** Get an instance of <code>PersistenceManager</code> from this factory.  The instance has
     * default values for options.  The parameters <code>userid</code> and <code>password</code> are used
     * when obtaining datastore connections from the connection pool.
     *
     * <P>After the first use of <code>getPersistenceManager</code>, no "set" methods will
     * succeed.
     *
     * @return a <code>PersistenceManager</code> 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 <code>PersistenceManager</code> instances
     * obtained from this factory.
     *
     * @param flag the default Multithreaded setting.
     */
    void setMultithreaded (boolean flag);
  
    /** Get the default Multithreaded setting for all <code>PersistenceManager</code> 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 <code>PersistenceManager</code> instances
     * obtained from this factory.  
     *
     * @param flag the default Optimistic setting.
     */
    void setOptimistic (boolean flag);
  
    /** Get the default Optimistic setting for all <code>PersistenceManager</code> instances
     * obtained from this factory.  
     *
     * @return the default Optimistic setting.
     */
    boolean getOptimistic();
    
    /** Set the default RetainValues setting for all <code>PersistenceManager</code> instances
     * obtained from this factory.
     *
     * @param flag the default RetainValues setting.
     */
    void setRetainValues (boolean flag);
  
   /** Get the default RetainValues setting for all <code>PersistenceManager</code> instances
     * obtained from this factory.
     *
     * @return the default RetainValues setting.
     */
    boolean getRetainValues ();
    
    /** Set the default value for the RestoreValues property.  
     * If <code>true</code>, 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.
     * <P>If <code>false</code>, 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 
     * <code>JDOUnsupportedOptionException</code> 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 <code>PersistenceManager</code> instances
     * obtained from this factory.  
     *
     * @param flag the default NontransactionalRead setting.
     */
    void setNontransactionalRead (boolean flag);
  
    /** Get the default NontransactionalRead setting for all <code>PersistenceManager</code> instances
     * obtained from this factory.
     *
     * @return the default NontransactionalRead setting.
     */
    boolean getNontransactionalRead ();
    
    /** Set the default NontransactionalWrite setting for all <code>PersistenceManager</code> instances
     * obtained from this factory.  
     *
     * @param flag the default NontransactionalWrite setting.
     */
    void setNontransactionalWrite (boolean flag);
  
    /** Get the default NontransactionalWrite setting for all <code>PersistenceManager</code> instances
     * obtained from this factory.
     *
     * @return the default NontransactionalWrite setting.
     */
    boolean getNontransactionalWrite ();
    
    /** Set the default IgnoreCache setting for all <code>PersistenceManager</code> instances
     * obtained from this factory.
     *
     * @param flag the default IgnoreCache setting.
     */
    void setIgnoreCache (boolean flag);
  
    /** Get the default IgnoreCache setting for all <code>PersistenceManager</code> 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
    * <code>PersistenceManager</code> instances obtained from this
    * factory.
    * @see #getDetachAllOnCommit()
    * @since 2.0
    */
   void setDetachAllOnCommit(boolean flag);

   /** Return non-configurable properties of this <code>PersistenceManagerFactory</code>.
     * Properties with keys <code>VendorName</code> and <code>VersionNumber</code> are required.  Other
     * keys are optional.
     * @return the non-configurable properties of this
     * <code>PersistenceManagerFactory</code>.
     */
    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.
     * <P>Each supported JDO optional feature is represented by a
     * <code>String</code> with one of the following values:
     *
     * <P><code>javax.jdo.option.TransientTransactional
     * <BR>javax.jdo.option.NontransactionalRead
     * <BR>javax.jdo.option.NontransactionalWrite
     * <BR>javax.jdo.option.RetainValues
     * <BR>javax.jdo.option.Optimistic
     * <BR>javax.jdo.option.ApplicationIdentity
     * <BR>javax.jdo.option.DatastoreIdentity
     * <BR>javax.jdo.option.NonDatastoreIdentity
     * <BR>javax.jdo.option.ArrayList
     * <BR>javax.jdo.option.HashMap
     * <BR>javax.jdo.option.Hashtable
     * <BR>javax.jdo.option.LinkedList
     * <BR>javax.jdo.option.TreeMap
     * <BR>javax.jdo.option.TreeSet
     * <BR>javax.jdo.option.Vector
     * <BR>javax.jdo.option.Map
     * <BR>javax.jdo.option.List
     * <BR>javax.jdo.option.Array  
     * <BR>javax.jdo.option.NullCollection
     * <BR>javax.jdo.option.ChangeApplicationIdentity
     * <BR>javax.jdo.option.BinaryCompatibility
     * <BR>javax.jdo.option.GetDataStoreConnection
     * <BR>javax.jdo.option.UnconstrainedQueryVariables
     * <BR>javax.jdo.query.SQL
     * <BR>javax.jdo.query.JDOQL
     * </code>
     *
     *<P>The standard JDO query language is represented by a <code>String</code>:
     *<P><code>javax.jdo.query.JDOQL</code>
     * @return the <code>Collection</code> of <code>String</code>s 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 <code>null</code>.
     * @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 <code>addInstanceLifecycleListener</code> and 
     * <code>removeInstanceLifecycleListener</code>
     * 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).
     * <p>The <code>classes</code> parameter identifies all
     * of the classes of interest. If the <code>classes</code>
     * parameter is specified as <code>null</code>, events for all
     * persistent classes and interfaces will be sent to the listener.</p>
     * <p>The listener will be called for each event for which it
     * implements the corresponding {@link InstanceLifecycleListener}
     * interface.</p>
     * @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 <code>addInstanceLifecycleListener</code> and 
     * <code>removeInstanceLifecycleListener</code>
     * 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);

}