/*
 * 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 <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.2
 */

public interface PersistenceManagerFactory extends 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 a thread-safe instance of a proxy that dynamically binds
     * on each method call to an instance of <code>PersistenceManager</code>.
     * <P>When used with a <code>PersistenceManagerFactory</code>
     * 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
     * <code>PersistenceManager</code> is automatically closed when the
     * transaction completes.
     * <P>When used with a <code>PersistenceManagerFactory</code>
     * that uses TransactionType RESOURCE_LOCAL, the proxy uses an inheritable
     * ThreadLocal to bind to an instance of <code>PersistenceManager</code>
     * associated with the thread. In this case, the close method executed
     * on the proxy closes the <code>PersistenceManager</code> and then
     * clears the ThreadLocal.
     * Use of this method does not affect the configurability of the
     * <code>PersistenceManagerFactory</code>.
     *
     * @since 2.1
     * @return a <code>PersistenceManager</code> proxy.
     */
    PersistenceManager getPersistenceManagerProxy();

    /** 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.
     * This property might be ignored by the JDO implementation
     * because the JDBC DriverManager handles the driver name.
     * @param driverName the driver name for the data store connection.
     */
    void setConnectionDriverName  (String driverName);

    /** Get the driver name for the data store connection.
     * This property might be ignored by the JDO implementation
     * because the JDBC DriverManager handles the driver name.
     * @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
     * @param flag the default DetachAllOnCommit setting
     */
    void setDetachAllOnCommit(boolean flag);

   /** Gets the default copyOnAttach setting for all
    * <code>PersistenceManager</code> instances obtained from this
    * factory.
    * @see #setCopyOnAttach(boolean)
    * @since 2.1
    * @return the copyOnAttach setting.
    */
   boolean getCopyOnAttach();

   /** Sets the default copyOnAttach setting for all
    * <code>PersistenceManager</code> instances obtained from this
    * factory.
    *
    * <P>CopyOnAttach set to <code>true</code> specifies that during
    * makePersistent, copies are made of detached parameter instances.
    * With this flag set to <code>false</code>, detached parameter
    * instances are attached directly and change their state from
    * detached-clean to persistent-clean or from detached-dirty to
    * persistent-dirty.
    * @param flag Whether we should copy on attach
    * @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.
     *
     * <P>ReadOnly set to <code>false</code> specifies that no updates
     * can be performed to the datastore, and if updates are attempted
     * a JDOReadOnlyException is thrown.
     * @param flag whether we should consider this datastore read-only
     * @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:
     * <ul><li>read-uncommitted
     * </li><li>read-committed
     * </li><li>repeatable-read
     * </li><li>snapshot
     * </li><li>serializable
     * </li></ul>
     * @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
     * <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 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.NonDurableIdentity
     * <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.option.TransactionIsolationLevel.read-uncommitted
     * <BR>javax.jdo.option.TransactionIsolationLevel.read-committed
     * <BR>javax.jdo.option.TransactionIsolationLevel.repeatable-read
     * <BR>javax.jdo.option.TransactionIsolationLevel.snapshot
     * <BR>javax.jdo.option.TransactionIsolationLevel.serializable
     * <BR>javax.jdo.option.QueryCancel
     * <BR>javax.jdo.option.DatastoreTimeout
     * <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<String> 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
     * @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 <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);

    /**
     * Add the <code>FetchGroup</code>s to the set of active fetch groups.
     * <code>FetchGroup</code>s are made unmodifiable before being added.
     * <code>FetchGroup</code>s that match existing <code>FetchGroup</code>s
     * replace the corresponding <code>FetchGroup</code>s.
     * The replaced <code>FetchGroup</code>s 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 <code>FetchGroup</code>s from the set of active
     * <code>FetchGroup</code>s. Existing <code>FetchGroup</code>s that match
     * parameter <code>FetchGroup</code>s are removed. Parameter
     * <code>FetchGroup</code>s that do not match any existing
     * <code>FetchGroup</code> are ignored.
     * Removed <code>FetchGroup</code>s 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 <code>FetchGroup</code>s from the set of active
     * <code>FetchGroup</code>s.
     * All removed <code>FetchGroup</code>s 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 <code>FetchGroup</code> for the Class and
     * name. If a corresponding <code>FetchGroup</code> already exists in
     * <code>PersistenceManagerFactory</code> scope, copy its definition
     * to a new <code>FetchGroup</code>.
     * If the <code>FetchGroup</code> does not already exist, create it
     * with no members. The <code>FetchGroup</code> 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
     * <code>PersistenceManagerFactory</code>.
     * 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.
     * @param className Name of the class to get metadata for
     * @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<Class> getManagedClasses();
}
