View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17
    18  /*
    19   * PersistenceManagerFactory.java
    20   *
    21   */
    22
    23  package javax.jdo;
    24
    25  import javax.jdo.datastore.DataStoreCache;
    26  import javax.jdo.listener.InstanceLifecycleListener;
    27  import javax.jdo.metadata.TypeMetadata;
    28  import javax.jdo.metadata.JDOMetadata;
    29  import javax.jdo.spi.JDOPermission; // for getFetchGroups javadoc
    30  import java.io.Serializable;
    31  import java.util.Collection;
    32  import java.util.Properties;
    33  import java.util.Set;
    34
    35  /** The <code>PersistenceManagerFactory</code> is the interface to use to obtain
    36   * <code>PersistenceManager</code> instances.
    37   * All <code>PersistenceManager</code> instances obtained from the same
    38   * <code>PersistenceManagerFactory</code> will have the same default properties.
    39   *
    40   * <P><code>PersistenceManagerFactory</code> instances may be configured and
    41   * serialized for later use.  They may be stored via JNDI and looked up
    42   * and used later.  Any properties configured will be saved and restored.
    43   *
    44   * <P>Once the first <code>PersistenceManager</code> is obtained from the
    45   * <code>PersistenceManagerFactory</code>, the factory can no longer be
    46   * configured.
    47   * <P>If the <code>ConnectionFactory</code> property is set
    48   * (non-<code>null</code>) then all other Connection properties including
    49   * <code>ConnectionFactoryName</code> are ignored;
    50   * otherwise, if <code>ConnectionFactoryName</code> is set
    51   * (non-<code>null</code>) then all other Connection properties are ignored.
    52   * Similarly, if the <code>ConnectionFactory2</code> property is set
    53   * (non-<code>null</code>) then <code>ConnectionFactory2Name</code> is ignored.
    54   * <P>Operational state (<code>PersistenceManager</code> pooling, connection
    55   * pooling, operational parameters) must not be serialized.
    56   *
    57   * @version 2.2
    58   */
    59
    60  public interface PersistenceManagerFactory extends Serializable {
    61
    62
    63      /** Close this PersistenceManagerFactory. Check for
    64       * JDOPermission("closePersistenceManagerFactory") and if not authorized,
    65       * throw SecurityException.
    66       * <P>If the authorization check succeeds, check to see that all
    67       * PersistenceManager instances obtained from this PersistenceManagerFactory
    68       * have no active transactions. If any PersistenceManager instances have
    69       * an active transaction, throw a JDOUserException, with one nested
    70       * JDOUserException for each PersistenceManager with an active Transaction.
    71       * <P>If there are no active transactions, then close all PersistenceManager
    72       * instances obtained from this PersistenceManagerFactory, mark this
    73       * PersistenceManagerFactory as closed, disallow getPersistenceManager
    74       * methods, and allow all other get methods. If a set method or
    75       * getPersistenceManager method is called after close, then
    76       * JDOUserException is thrown.
    77       * @since 1.0.1
    78       */
    79      void close();
    80
    81      /**
    82       * A <code>PersistenceManagerFactory</code> instance can be used
    83       * until it is closed.
    84       * @return <code>true</code> if this <code>PersistenceManagerFactory</code>
    85       * has been closed.
    86       * @see #close()
    87       * @since 2.0
    88       */
    89      boolean isClosed();
    90
    91      /** Get an instance of <code>PersistenceManager</code> from this factory.
    92       * The instance has default values for options.
    93       *
    94       * <P>After the first use of <code>getPersistenceManager</code>, no "set"
    95       * methods will succeed.
    96       *
    97       * @return a <code>PersistenceManager</code> instance with default options.
    98       */
    99      PersistenceManager getPersistenceManager();
    100
    101     /** Get a thread-safe instance of a proxy that dynamically binds
    102      * on each method call to an instance of <code>PersistenceManager</code>.
    103      * <P>When used with a <code>PersistenceManagerFactory</code>
    104      * that uses TransactionType JTA,
    105      * the proxy can be used in a server to dynamically bind to an instance
    106      * from this factory associated with the thread's current transaction.
    107      * In this case, the close method is ignored, as the
    108      * <code>PersistenceManager</code> is automatically closed when the
    109      * transaction completes.
    110      * <P>When used with a <code>PersistenceManagerFactory</code>
    111      * that uses TransactionType RESOURCE_LOCAL, the proxy uses an inheritable
    112      * ThreadLocal to bind to an instance of <code>PersistenceManager</code>
    113      * associated with the thread. In this case, the close method executed
    114      * on the proxy closes the <code>PersistenceManager</code> and then
    115      * clears the ThreadLocal.
    116      * Use of this method does not affect the configurability of the
    117      * <code>PersistenceManagerFactory</code>.
    118      *
    119      * @since 2.1
    120      * @return a <code>PersistenceManager</code> proxy.
    121      */
    122     PersistenceManager getPersistenceManagerProxy();
    123
    124     /** Get an instance of <code>PersistenceManager</code> from this factory.
    125      * The instance has default values for options.
    126      * The parameters <code>userid</code> and <code>password</code> are used
    127      * when obtaining datastore connections from the connection pool.
    128      *
    129      * <P>After the first use of <code>getPersistenceManager</code>, no "set"
    130      * methods will succeed.
    131      *
    132      * @return a <code>PersistenceManager</code> instance with default options.
    133      * @param userid the userid for the connection
    134      * @param password the password for the connection
    135      */
    136     PersistenceManager getPersistenceManager(String userid, String password);
    137
    138     /** Set the user name for the data store connection.
    139      * @param userName the user name for the data store connection.
    140      */
    141     void setConnectionUserName(String userName);
    142
    143     /** Get the user name for the data store connection.
    144      * @return the user name for the data store connection.
    145      */
    146     String getConnectionUserName ();
    147
    148     /** Set the password for the data store connection.
    149      * @param password the password for the data store connection.
    150      */
    151     void setConnectionPassword (String password);
    152
    153     /** Set the URL for the data store connection.
    154      * @param url the URL for the data store connection.
    155      */
    156     void setConnectionURL (String url);
    157
    158     /** Get the URL for the data store connection.
    159      * @return the URL for the data store connection.
    160      */
    161     String getConnectionURL ();
    162
    163     /** Set the driver name for the data store connection.
    164      * @param driverName the driver name for the data store connection.
    165      */
    166     void setConnectionDriverName  (String driverName);
    167
    168     /** Get the driver name for the data store connection.
    169      * @return the driver name for the data store connection.
    170      */
    171     String getConnectionDriverName ();
    172
    173     /** Set the name for the data store connection factory.
    174      * @param connectionFactoryName the name of the data store connection
    175      * factory.
    176      */
    177     void setConnectionFactoryName (String connectionFactoryName);
    178
    179     /** Get the name for the data store connection factory.
    180      * @return the name of the data store connection factory.
    181      */
    182     String getConnectionFactoryName ();
    183
    184     /** Set the data store connection factory.  JDO implementations
    185      * will support specific connection factories.  The connection
    186      * factory interfaces are not part of the JDO specification.
    187      * @param connectionFactory the data store connection factory.
    188      */
    189     void setConnectionFactory (Object connectionFactory);
    190
    191     /** Get the data store connection factory.
    192      * @return the data store connection factory.
    193      */
    194     Object getConnectionFactory ();
    195
    196     /** Set the name for the second data store connection factory.  This is
    197      * needed for managed environments to get nontransactional connections for
    198      * optimistic transactions.
    199      * @param connectionFactoryName the name of the data store connection
    200      * factory.
    201      */
    202     void setConnectionFactory2Name (String connectionFactoryName);
    203
    204     /** Get the name for the second data store connection factory.  This is
    205      * needed for managed environments to get nontransactional connections for
    206      * optimistic transactions.
    207      * @return the name of the data store connection factory.
    208      */
    209     String getConnectionFactory2Name ();
    210
    211     /** Set the second data store connection factory.  This is
    212      * needed for managed environments to get nontransactional connections for
    213      * optimistic transactions.  JDO implementations
    214      * will support specific connection factories.  The connection
    215      * factory interfaces are not part of the JDO specification.
    216      * @param connectionFactory the data store connection factory.
    217      */
    218     void setConnectionFactory2 (Object connectionFactory);
    219
    220     /** Get the second data store connection factory.  This is
    221      * needed for managed environments to get nontransactional connections for
    222      * optimistic transactions.
    223      * @return the data store connection factory.
    224      */
    225     Object getConnectionFactory2 ();
    226
    227     /** Set the default Multithreaded setting for all
    228      * <code>PersistenceManager</code> instances obtained from this factory.
    229      *
    230      * @param flag the default Multithreaded setting.
    231      */
    232     void setMultithreaded (boolean flag);
    233
    234     /** Get the default Multithreaded setting for all
    235      * <code>PersistenceManager</code> instances obtained from this factory.
    236      *
    237      * @return the default Multithreaded setting.
    238      */
    239     boolean getMultithreaded();
    240
    241     /** Set the Mapping setting for this factory. This is used to find the
    242      * object-datastore mapping file(s).
    243      *
    244      * @param mapping the Mapping setting.
    245      */
    246     void setMapping (String mapping);
    247
    248     /** Get the Mapping setting for this factory.  This is used to find the
    249      * object-datastore mapping file(s).
    250      *
    251      * @return the Mapping setting.
    252      */
    253     String getMapping ();
    254
    255     /** Set the default Optimistic setting for all
    256      * <code>PersistenceManager</code> instances obtained from this factory.
    257      *
    258      * @param flag the default Optimistic setting.
    259      */
    260     void setOptimistic (boolean flag);
    261
    262     /** Get the default Optimistic setting for all
    263      * <code>PersistenceManager</code> instances obtained from this factory.
    264      *
    265      * @return the default Optimistic setting.
    266      */
    267     boolean getOptimistic();
    268
    269     /** Set the default RetainValues setting for all
    270      * <code>PersistenceManager</code> instances obtained from this factory.
    271      *
    272      * @param flag the default RetainValues setting.
    273      */
    274     void setRetainValues (boolean flag);
    275
    276    /** Get the default RetainValues setting for all
    277     * <code>PersistenceManager</code> instances obtained from this factory.
    278      *
    279      * @return the default RetainValues setting.
    280      */
    281     boolean getRetainValues ();
    282
    283     /** Set the default value for the RestoreValues property.
    284      * If <code>true</code>, at rollback, fields of newly persistent instances
    285      * are restored to
    286      * their values as of the beginning of the transaction, and the instances
    287      * revert to transient.  Additionally, fields of modified
    288      * instances of primitive types and immutable reference types
    289      * are restored to their values as of the beginning of the
    290      * transaction.
    291      * <P>If <code>false</code>, at rollback, the values of fields of
    292      * newly persistent instances are unchanged and the instances revert to
    293      * transient.  Additionally, dirty instances transition to hollow.
    294      * If an implementation does not support this option, a
    295      * <code>JDOUnsupportedOptionException</code> is thrown.
    296      * @param restoreValues the value of the restoreValues property
    297      */
    298     void setRestoreValues(boolean restoreValues);
    299
    300     /** Get the default value for the RestoreValues property.
    301      * @return the value of the restoreValues property
    302      */
    303     boolean getRestoreValues();
    304
    305     /** Set the default NontransactionalRead setting for all
    306      * <code>PersistenceManager</code> instances obtained from this factory.
    307      *
    308      * @param flag the default NontransactionalRead setting.
    309      */
    310     void setNontransactionalRead (boolean flag);
    311
    312     /** Get the default NontransactionalRead setting for all
    313      * <code>PersistenceManager</code> instances obtained from this factory.
    314      *
    315      * @return the default NontransactionalRead setting.
    316      */
    317     boolean getNontransactionalRead ();
    318
    319     /** Set the default NontransactionalWrite setting for all
    320      * <code>PersistenceManager</code> instances obtained from this factory.
    321      *
    322      * @param flag the default NontransactionalWrite setting.
    323      */
    324     void setNontransactionalWrite (boolean flag);
    325
    326     /** Get the default NontransactionalWrite setting for all
    327      * <code>PersistenceManager</code> instances obtained from this factory.
    328      *
    329      * @return the default NontransactionalWrite setting.
    330      */
    331     boolean getNontransactionalWrite ();
    332
    333     /** Set the default IgnoreCache setting for all
    334      * <code>PersistenceManager</code> instances obtained from this factory.
    335      *
    336      * @param flag the default IgnoreCache setting.
    337      */
    338     void setIgnoreCache (boolean flag);
    339
    340     /** Get the default IgnoreCache setting for all
    341      * <code>PersistenceManager</code> instances obtained from this factory.
    342      *
    343      * @return the default IngoreCache setting.
    344      */
    345     boolean getIgnoreCache ();
    346
    347     /** Gets the detachAllOnCommit setting.
    348      * @see #setDetachAllOnCommit(boolean)
    349      * @since 2.0
    350      * @return the default detachAllOnCommit setting.
    351      */
    352     boolean getDetachAllOnCommit();
    353
    354     /** Sets the default detachAllOnCommit setting for all
    355      * <code>PersistenceManager</code> instances obtained from this
    356      * factory.
    357      * @see #getDetachAllOnCommit()
    358      * @since 2.0
    359      * @param flag the default DetachAllOnCommit setting
    360      */
    361     void setDetachAllOnCommit(boolean flag);
    362
    363    /** Gets the default copyOnAttach setting for all
    364     * <code>PersistenceManager</code> instances obtained from this
    365     * factory.
    366     * @see #setCopyOnAttach(boolean)
    367     * @since 2.1
    368     * @return the copyOnAttach setting.
    369     */
    370    boolean getCopyOnAttach();
    371
    372    /** Sets the default copyOnAttach setting for all
    373     * <code>PersistenceManager</code> instances obtained from this
    374     * factory.
    375     *
    376     * <P>CopyOnAttach set to <code>true</code> specifies that during
    377     * makePersistent, copies are made of detached parameter instances.
    378     * With this flag set to <code>false</code>, detached parameter
    379     * instances are attached directly and change their state from
    380     * detached-clean to persistent-clean or from detached-dirty to
    381     * persistent-dirty.
    382     *
    383     * @see #getCopyOnAttach()
    384     * @since 2.1
    385     */
    386    void setCopyOnAttach(boolean flag);
    387
    388     /**
    389      * Sets the name of this PersistenceManagerFactory.
    390      * @since 2.1
    391      * @param name the name of this PMF
    392      */
    393     void setName(String name);
    394
    395     /**
    396      * Gets the name of this PersistenceManagerFactory.
    397      * @since 2.1
    398      * @return the name of this PMF
    399      */
    400     String getName();
    401
    402     /**
    403      * Sets the PersistenceUnitName for this PersistenceManagerFactory.
    404      * This has the same semantics as the same-named property in
    405      * JSR-220 PersistenceUnitInfo.
    406      * @see #getPersistenceUnitName()
    407      * @since 2.1
    408      * @param name the PersistenceUnitName
    409      */
    410     void setPersistenceUnitName(String name);
    411
    412     /**
    413      * Gets the PersistenceUnitName for this PersistenceManagerFactory.
    414      * @see #setPersistenceUnitName(String)
    415      * @since 2.1
    416      * @return the PersistenceUnitName
    417      */
    418     String getPersistenceUnitName();
    419
    420     /**
    421      * Sets the TimeZone ID of the server associated with this
    422      * PersistenceManagerFactory. The parameter is a String
    423      * suitable for use with TimeZone.getTimeZone(). The String
    424      * must match an ID returned by TimeZone.getAvailableIDs().
    425      * If the ServerTimeZoneID is not set, or set to the null String,
    426      * assume that the server has the same TimeZone ID as the client.
    427      * If incorrectly set, the result of PersistenceManager.getServerDate()
    428      * might be incorrect.
    429      * @see #getServerTimeZoneID()
    430      * @see java.util.TimeZone#getTimeZone(String)
    431      * @see java.util.TimeZone#getAvailableIDs()
    432      * @see PersistenceManager#getServerDate()
    433      * @since 2.1
    434      * @param timezoneid the TimeZone ID of the server
    435      * @throws JDOUserException if the parameter does not match
    436      * an ID from TimeZone.getAvailableIDs()
    437      */
    438     void setServerTimeZoneID(String timezoneid);
    439
    440     /**
    441      * Gets the TimeZone ID of the server associated with this
    442      * PersistenceManagerFactory. If not set, assume that
    443      * the server has the same TimeZone ID as the client.
    444      * @see #setServerTimeZoneID(String)
    445      * @since 2.1
    446      * @return the TimeZone of the server
    447      */
    448     String getServerTimeZoneID();
    449
    450     /**
    451      * Sets the TransactionType for this PersistenceManagerFactory.
    452      * Permitted values are "JTA" and "RESOURCE_LOCAL".
    453      * This has the same semantics as the same-named property in
    454      * JSR-220 EntityManagerFactory.
    455      * @see #getTransactionType()
    456      * @see Constants#JTA
    457      * @see Constants#RESOURCE_LOCAL
    458      * @since 2.1
    459      * @param name the TransactionType
    460      * @throws JDOUserException if the parameter is not a permitted value
    461      */
    462     void setTransactionType(String name);
    463
    464     /**
    465      * Gets the TransactionType for this PersistenceManagerFactory.
    466      * @see #setTransactionType(String)
    467      * @since 2.1
    468      * @return the TransactionType
    469      */
    470     String getTransactionType();
    471
    472     /** Gets the value for read-only for this PMF.
    473      * Indicates whether the datastore is read-only or writable.
    474      * @see #setReadOnly(boolean)
    475      * @since 2.2
    476      * @return the readOnly setting.
    477      */
    478     boolean getReadOnly();
    479
    480     /** Sets the value for whether the datastore is to be considered
    481      * read-only.
    482      *
    483      * <P>ReadOnly set to <code>false</code> specifies that no updates
    484      * can be performed to the datastore, and if updates are attempted
    485      * a JDOReadOnlyException is thrown.
    486      *
    487      * @see #getReadOnly()
    488      * @since 2.2
    489      */
    490     void setReadOnly(boolean flag);
    491
    492     /** Get the value for transaction isolation level for this PMF.
    493      * @return the transaction isolation level
    494      * @see #setTransactionIsolationLevel(String)
    495      * @since 2.2
    496      */
    497     String getTransactionIsolationLevel();
    498
    499     /** Set the value for transaction isolation level for this PMF.
    500      * Transaction isolation levels are defined in javax.jdo.Constants.
    501      * If the requested level is not available, but a higher level is
    502      * available, the higher level is silently used.
    503      * If the requested level is not available, and no higher level is
    504      * available, then JDOUnsupportedOptionException is thrown.
    505      * Standard values in order from low to high are:
    506      * <ul><li>read-uncommitted
    507      * </li><li>read-committed
    508      * </li><li>repeatable-read
    509      * </li><li>snapshot
    510      * </li><li>serializable
    511      * </li></ul>
    512      * @param level the transaction isolation level
    513      * @see #getTransactionIsolationLevel()
    514      * @see Constants#TX_READ_UNCOMMITTED
    515      * @see Constants#TX_READ_COMMITTED
    516      * @see Constants#TX_REPEATABLE_READ
    517      * @see Constants#TX_SNAPSHOT
    518      * @see Constants#TX_SERIALIZABLE
    519      * @since 2.2
    520      */
    521     void setTransactionIsolationLevel(String level);
    522
    523     /**
    524      * Specify a default timeout interval (milliseconds) for any read
    525      * operations for persistence managers obtained from this persistence
    526      * manager factory. To unset the explicit timeout, specify null.
    527      * For no timeout, specify 0.
    528      * If the datastore and JDO implementation support timeouts, then
    529      * javax.jdo.option.DatastoreTimeout is returned by supportedOptions().
    530      * If timeouts are not supported,this method will throw
    531      * JDOUnsupportedOptionException.
    532      * @since 3.0
    533      * @param interval the timeout interval (milliseconds)
    534      */
    535     void setDatastoreReadTimeoutMillis(Integer interval);
    536
    537     /** Get the default timeout setting for read operations.
    538      * If timeouts are not supported,this method will return null.
    539      * @see #setDatastoreReadTimeoutMillis(Integer)
    540      * @return the default timeout setting (milliseconds).
    541      * @since 3.0
    542      */
    543     Integer getDatastoreReadTimeoutMillis();
    544
    545     /**
    546      * Specify a default timeout interval (milliseconds) for any write
    547      * operations for persistence managers obtained from this persistence
    548      * manager factory. To unset the explicit timeout, specify null.
    549      * For no timeout, specify 0.
    550      * If the datastore and JDO implementation support timeouts, then
    551      * javax.jdo.option.DatastoreTimeout is returned by supportedOptions().
    552      * If timeouts are not supported,this method will throw
    553      * JDOUnsupportedOptionException.
    554      * @since 3.0
    555      * @param interval the timeout interval (milliseconds)
    556      */
    557     void setDatastoreWriteTimeoutMillis(Integer interval);
    558
    559     /** Get the default timeout setting for write operations.
    560      * If timeouts are not supported,this method will return null.
    561      * @see #setDatastoreWriteTimeoutMillis(Integer)
    562      * @return the default timeout setting (milliseconds).
    563      * @since 3.0
    564      */
    565     Integer getDatastoreWriteTimeoutMillis();
    566
    567     /** Return non-configurable properties of this
    568      * <code>PersistenceManagerFactory</code>.
    569      * Properties with keys <code>VendorName</code> and
    570      * <code>VersionNumber</code> are required.  Other keys are optional.
    571      * @return the non-configurable properties of this
    572      * <code>PersistenceManagerFactory</code>.
    573      */
    574     Properties getProperties();
    575
    576     /** The application can determine from the results of this
    577      * method which optional features, and which query languages
    578      * are supported by the JDO implementation.
    579      * <P>Each supported JDO feature is represented by a
    580      * <code>String</code> with one of the following values:
    581      *
    582      * <P><code>javax.jdo.option.TransientTransactional
    583      * <BR>javax.jdo.option.NontransactionalRead
    584      * <BR>javax.jdo.option.NontransactionalWrite
    585      * <BR>javax.jdo.option.RetainValues
    586      * <BR>javax.jdo.option.Optimistic
    587      * <BR>javax.jdo.option.ApplicationIdentity
    588      * <BR>javax.jdo.option.DatastoreIdentity
    589      * <BR>javax.jdo.option.NonDurableIdentity
    590      * <BR>javax.jdo.option.ArrayList
    591      * <BR>javax.jdo.option.HashMap
    592      * <BR>javax.jdo.option.Hashtable
    593      * <BR>javax.jdo.option.LinkedList
    594      * <BR>javax.jdo.option.TreeMap
    595      * <BR>javax.jdo.option.TreeSet
    596      * <BR>javax.jdo.option.Vector
    597      * <BR>javax.jdo.option.Map
    598      * <BR>javax.jdo.option.List
    599      * <BR>javax.jdo.option.Array
    600      * <BR>javax.jdo.option.NullCollection
    601      * <BR>javax.jdo.option.ChangeApplicationIdentity
    602      * <BR>javax.jdo.option.BinaryCompatibility
    603      * <BR>javax.jdo.option.GetDataStoreConnection
    604      * <BR>javax.jdo.option.UnconstrainedQueryVariables
    605      * <BR>javax.jdo.option.TransactionIsolationLevel.read-uncommitted
    606      * <BR>javax.jdo.option.TransactionIsolationLevel.read-committed
    607      * <BR>javax.jdo.option.TransactionIsolationLevel.repeatable-read
    608      * <BR>javax.jdo.option.TransactionIsolationLevel.snapshot
    609      * <BR>javax.jdo.option.TransactionIsolationLevel.serializable
    610      * <BR>javax.jdo.option.QueryCancel
    611      * <BR>javax.jdo.option.DatastoreTimeout
    612      * <BR>javax.jdo.query.SQL
    613      * <BR>javax.jdo.query.JDOQL
    614      * </code>
    615      *
    616      *<P>The standard JDO query language is represented by a
    617      * <code>String</code>:
    618      *<P><code>javax.jdo.query.JDOQL</code>
    619      * @return the <code>Collection</code> of <code>String</code>s representing
    620      * the supported options.
    621      */
    622     Collection<String> supportedOptions();
    623
    624     /**
    625      * Return the {@link DataStoreCache} that this factory uses for
    626      * controlling a second-level cache. If this factory does not use
    627      * a second-level cache, the returned instance does nothing. This
    628      * method never returns <code>null</code>.
    629      * @since 2.0
    630      * @return the DataStoreCache
    631      */
    632     DataStoreCache getDataStoreCache ();
    633
    634     /**
    635      * Add the parameter listener to the list of
    636      * instance lifecycle event listeners set as the initial listeners
    637      * for each PersistenceManager created by this PersistenceManagerFactory.
    638      * The <code>addInstanceLifecycleListener</code> and
    639      * <code>removeInstanceLifecycleListener</code>
    640      * methods are considered to be configuration methods and
    641      * can only be called when the PersistenceManagerFactory
    642      * is configurable (before the first time {@link #getPersistenceManager}
    643      * is called).
    644      * <p>The <code>classes</code> parameter identifies all
    645      * of the classes of interest. If the <code>classes</code>
    646      * parameter is specified as <code>null</code>, events for all
    647      * persistent classes and interfaces will be sent to the listener.</p>
    648      * <p>The listener will be called for each event for which it
    649      * implements the corresponding {@link InstanceLifecycleListener}
    650      * interface.</p>
    651      * @param listener the lifecycle listener
    652      * @param classes the classes of interest to the listener
    653      * @since 2.0
    654      */
    655     void addInstanceLifecycleListener (InstanceLifecycleListener listener,
    656         Class[] classes);
    657
    658     /**
    659      * Remove the parameter listener instance from the list of
    660      * instance lifecycle event listeners set as the initial listeners
    661      * for each PersistenceManager created by this PersistenceManagerFactory.
    662      * The <code>addInstanceLifecycleListener</code> and
    663      * <code>removeInstanceLifecycleListener</code>
    664      * methods are considered to be configuration methods and
    665      * can only be called when the PersistenceManagerFactory
    666      * is configurable (before the first time {@link #getPersistenceManager}
    667      * is called).
    668      * @param listener the listener instance to be removed
    669      * @since 2.0
    670      */
    671     void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
    672
    673     /**
    674      * Add the <code>FetchGroup</code>s to the set of active fetch groups.
    675      * <code>FetchGroup</code>s are made unmodifiable before being added.
    676      * <code>FetchGroup</code>s that match existing <code>FetchGroup</code>s
    677      * replace the corresponding <code>FetchGroup</code>s.
    678      * The replaced <code>FetchGroup</code>s become unscoped.
    679      * Match is based on identical class and equal name.
    680      * The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
    681      * {@link #getFetchGroups}, and {@link #removeAllFetchGroups}
    682      * are internally serialized.
    683      * @param groups an array of FetchGroups
    684      * @throws SecurityException if the caller is not authorized for
    685      * {@link JDOPermission} ("manageMetadata")
    686      * @since 2.2
    687      */
    688     void addFetchGroups(FetchGroup... groups);
    689
    690     /**
    691      * Remove the <code>FetchGroup</code>s from the set of active
    692      * <code>FetchGroup</code>s. Existing <code>FetchGroup</code>s that match
    693      * parameter <code>FetchGroup</code>s are removed. Parameter
    694      * <code>FetchGroup</code>s that do not match any existing
    695      * <code>FetchGroup</code> are ignored.
    696      * Removed <code>FetchGroup</code>s become unscoped.
    697      * Match is based on identical class and equal name.
    698      * The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
    699      * {@link #getFetchGroups}, and {@link #removeAllFetchGroups}
    700      * are internally serialized.
    701      * @param groups an array of FetchGroups
    702      * @throws SecurityException if the caller is not authorized for
    703      * {@link JDOPermission} ("manageMetadata")
    704      * @since 2.2
    705      */
    706     void removeFetchGroups(FetchGroup... groups);
    707
    708     /**
    709      * Remove all <code>FetchGroup</code>s from the set of active
    710      * <code>FetchGroup</code>s.
    711      * All removed <code>FetchGroup</code>s become unscoped.
    712      * The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
    713      * {@link #getFetchGroups}, and {@link #removeAllFetchGroups}
    714      * are internally serialized.
    715      * @throws SecurityException if the caller is not authorized for
    716      * {@link JDOPermission} ("manageMetadata")
    717      * @since 2.2
    718      */
    719     void removeAllFetchGroups();
    720
    721     /**
    722      * Create an unscoped, modifiable <code>FetchGroup</code> for the Class and
    723      * name. If a corresponding <code>FetchGroup</code> already exists in
    724      * <code>PersistenceManagerFactory</code> scope, copy its definition
    725      * to a new <code>FetchGroup</code>.
    726      * If the <code>FetchGroup</code> does not already exist, create it
    727      * with no members. The <code>FetchGroup</code> does not become
    728      * in scope until it is added to the current set via
    729      * {@link #addFetchGroups}.
    730      * @param cls the class or interface for the FetchGroup
    731      * @param name the name of the fetch group
    732      * @return the FetchGroup
    733      * @throws JDOUserException if the class is not a persistence-capable
    734      * class or interface
    735      * @since 2.2
    736      */
    737     FetchGroup getFetchGroup(Class cls, String name);
    738
    739     /**
    740      * Get a modifiable Set containing a mutable copy of all currently active
    741      * (in scope) fetch groups.
    742      * The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
    743      * {@link #getFetchGroups}, and {@link #removeAllFetchGroups}
    744      * are internally serialized.
    745      * @return a copy of all currently active fetch groups
    746      * @throws SecurityException if the caller is not authorized for
    747      * {@link JDOPermission} ("getMetadata")
    748      * @since 2.2
    749      */
    750     Set getFetchGroups();
    751
    752     /**
    753      * Method to register metadata with the persistence process managed by this
    754      * <code>PersistenceManagerFactory</code>.
    755      * Metadata can be created using the method {@link #newMetadata}.
    756      * If there is already metadata registered for a class contained in this metadata
    757      * object then a JDOUserException will be thrown.
    758      * @param metadata The Metadata to register.
    759      * @since 3.0
    760      */
    761     void registerMetadata(JDOMetadata metadata);
    762
    763     /**
    764      * Method to return a new metadata object that can be subsequently modified
    765      * and registered with the persistence process using the method {@link #registerMetadata}.
    766      * @return The metadata
    767      * @since 3.0
    768      */
    769     JDOMetadata newMetadata();
    770
    771     /**
    772      * Method to return the metadata object for the specified class/interface, if there is
    773      * metadata defined for that class/interface.
    774      * If there is no metadata for the specified class/interface, or the parameter is null,
    775      * then null will be returned.
    776      * @return The metadata
    777      * @since 3.0
    778      */
    779     TypeMetadata getMetadata(String className);
    780 }