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   * PersistenceManager.java
    20   *
    21   */
    22
    23  package javax.jdo;
    24
    25  import java.util.Collection;
    26  import java.util.Date;
    27  import java.util.EnumSet;
    28  import java.util.Set;
    29
    30  import javax.jdo.datastore.JDOConnection;
    31  import javax.jdo.datastore.Sequence;
    32
    33  import javax.jdo.listener.InstanceLifecycleListener;
    34
    35  /** <code>PersistenceManager</code> is the primary interface for JDO-aware
    36   * application components.  It is the factory for <code>Query</code> and
    37   * <code>Transaction</code> instances, and contains methods to manage the
    38   * life cycle of <code>PersistenceCapable</code> instances.
    39   *
    40   * <P>A <code>PersistenceManager</code> is obtained from the
    41   * {@link PersistenceManagerFactory}
    42   * (recommended) or by construction.
    43   * @version 2.1
    44   */
    45
    46  public interface PersistenceManager {
    47      /**
    48       * A <code>PersistenceManager</code> instance can be used until it is
    49       * closed.
    50       * @return <code>true</code> if this <code>PersistenceManager</code> has
    51       * been closed.
    52       * @see #close()
    53       */
    54      boolean isClosed ();
    55
    56      /** Close this <code>PersistenceManager</code> so that no further requests
    57       * may be made on it.  A <code>PersistenceManager</code> instance can be
    58       * used only until it is closed.
    59       *
    60       * <P>Closing a <code>PersistenceManager</code> might release it to the pool
    61       * of available <code>PersistenceManager</code>s, or might be garbage
    62       * collected, at the option of the JDO implementation.  Before being used
    63       * again to satisfy a <code>getPersistenceManager()</code> request, the
    64       * default values for options will be restored to their values as specified
    65       * in the <code>PersistenceManagerFactory</code>.
    66       *
    67       * <P>This method closes the <code>PersistenceManager</code>.
    68       */
    69      void close ();
    70
    71      /** Return the <code>Transaction</code> instance associated with a
    72       * <code>PersistenceManager</code>. There is one <code>Transaction</code>
    73       * instance associated with each <code>PersistenceManager</code> instance.
    74       * The <code>Transaction</code> instance supports options as well as
    75       * transaction completion requests.
    76       * @return the <code>Transaction</code> associated with this
    77       * <code>PersistenceManager</code>.
    78       */
    79      Transaction currentTransaction();
    80
    81      /** Mark an instance as no longer needed in the cache.  Eviction is normally
    82       * done automatically by the <code>PersistenceManager</code> at transaction
    83       * completion.  This method allows the application to explicitly provide a
    84       * hint to the <code>PersistenceManager</code> that the  instance is no
    85       * longer needed in the cache.
    86       * @param pc the instance to evict from the cache.
    87       */
    88      void evict (Object pc);
    89
    90      /** Mark an array of instances as no longer needed in the cache.
    91       * @see #evict(Object pc)
    92       * @param pcs the array of instances to evict from the cache.
    93       */
    94      void evictAll (Object... pcs);
    95
    96      /** Mark a <code>Collection</code> of instances as no longer needed in the
    97       * cache.
    98       * @see #evict(Object pc)
    99       * @param pcs the <code>Collection</code> of instances to evict from the
    100      * cache.
    101      */
    102     void evictAll (Collection pcs);
    103
    104     /** Mark the parameter instances as no longer needed in the cache.
    105      * @param pcClass the class of instances to evict
    106      * @param subclasses if true, mark instances of subclasses also
    107      * @since 2.1
    108      */
    109     void evictAll (boolean subclasses, Class pcClass);
    110
    111     /** Mark all persistent-nontransactional instances as no longer needed
    112      * in the cache.  It transitions
    113      * all persistent-nontransactional instances to hollow.  Transactional
    114      * instances are subject to eviction based on the RetainValues setting.
    115      * @see #evict(Object pc)
    116      */
    117     void evictAll ();
    118
    119     /** Refresh the state of the instance from the data store.
    120      *
    121      * <P>In an optimistic transaction, the state of instances in the cache
    122      * might not match the state in the data store.  This method is used to
    123      * reload the state of the instance from the data store so that a subsequent
    124      * commit is more likely to succeed.
    125      * <P>Outside a transaction, this method will refresh nontransactional
    126      * state.
    127      * @param pc the instance to refresh.
    128      */
    129     void refresh (Object pc);
    130
    131     /** Refresh the state of an array of instances from the data store.
    132      *
    133      * @see #refresh(Object pc)
    134      * @param pcs the array of instances to refresh.
    135      */
    136     void refreshAll (Object... pcs);
    137
    138     /** Refresh the state of a <code>Collection</code> of instances from the
    139      * data store.
    140      *
    141      * @see #refresh(Object pc)
    142      * @param pcs the <code>Collection</code> of instances to refresh.
    143      */
    144     void refreshAll (Collection pcs);
    145
    146     /** Refresh the state of all applicable instances from the data store.
    147      * <P>If called with an active transaction, all transactional instances
    148      * will be refreshed.  If called outside an active transaction, all
    149      * nontransactional instances will be refreshed.
    150      * @see #refresh(Object pc)
    151      */
    152     void refreshAll ();
    153
    154     /**
    155      * Refreshes all instances in the exception that failed verification.
    156      *
    157      * @since 2.0
    158      */
    159     void refreshAll (JDOException jdoe);
    160
    161     /** Create a new <code>Query</code> with no elements.
    162      * @return the new <code>Query</code>.
    163      */
    164     Query newQuery ();
    165
    166     /** Create a new <code>Query</code> using elements from another
    167      * <code>Query</code>. The other <code>Query</code> must have been created
    168      * by the same JDO implementation. It might be active in a different
    169      * <code>PersistenceManager</code> or might have been serialized and
    170      * restored.
    171      * <P>All of the settings of the other <code>Query</code> are copied to this
    172      * <code>Query</code>, except for the candidate <code>Collection</code> or
    173      * <code>Extent</code>.
    174      * @return the new <code>Query</code>
    175      * @param compiled another <code>Query</code> from the same JDO
    176      * implementation
    177      */
    178     Query newQuery (Object compiled);
    179
    180     /** Create a Construct a new query instance using the specified String
    181      * as the single-string representation of the query.
    182      * @param query the single-string query
    183      * @return the new <code>Query</code>
    184      * @since 2.0
    185      */
    186     Query newQuery (String query);
    187
    188     /** Create a new <code>Query</code> using the specified language.
    189      * @param language the language of the query parameter
    190      * @param query the query, which is of a form determined by the language
    191      * @return the new <code>Query</code>
    192      */
    193     Query newQuery (String language, Object query);
    194
    195     /** Create a new <code>Query</code> specifying the <code>Class</code> of the
    196      * candidate instances.
    197      * @param cls the <code>Class</code> of the candidate instances
    198      * @return the new <code>Query</code>
    199      */
    200     Query newQuery (Class cls);
    201
    202     /** Create a new <code>Query</code> with the <code>Class</code> of the
    203      * candidate instances and candidate <code>Extent</code>.
    204      * @param cln the <code>Extent</code> of candidate instances
    205      * @return the new <code>Query</code>
    206      */
    207     Query newQuery (Extent cln);
    208
    209     /** Create a new <code>Query</code> with the candidate <code>Class</code>
    210      * and <code>Collection</code>.
    211      * @param cls the <code>Class</code> of results
    212      * @param cln the <code>Collection</code> of candidate instances
    213      * @return the new <code>Query</code>
    214      */
    215     Query newQuery (Class cls, Collection cln);
    216
    217     /** Create a new <code>Query</code> with the <code>Class</code> of the
    218      * candidate instances and filter.
    219      * @param cls the <code>Class</code> of results
    220      * @param filter the filter for candidate instances
    221      * @return the new <code>Query</code>
    222      */
    223     Query newQuery (Class cls, String filter);
    224
    225     /** Create a new <code>Query</code> with the <code>Class</code> of the
    226      * candidate instances,
    227      * candidate <code>Collection</code>, and filter.
    228      * @param cls the <code>Class</code> of candidate instances
    229      * @param cln the <code>Collection</code> of candidate instances
    230      * @param filter the filter for candidate instances
    231      * @return the new <code>Query</code>
    232      */
    233     Query newQuery (Class cls, Collection cln, String filter);
    234
    235     /** Create a new <code>Query</code> with the
    236      * candidate <code>Extent</code> and filter; the class
    237      * is taken from the <code>Extent</code>.
    238      * @param cln the <code>Extent</code> of candidate instances
    239      * @param filter the filter for candidate instances
    240      * @return the new <code>Query</code>
    241      */
    242     Query newQuery (Extent cln, String filter);
    243
    244     /**
    245      * Create a new <code>Query</code> with the given candidate class
    246      * from a named query. The query name given must be the name of a
    247      * query defined in metadata.
    248      * @param cls the <code>Class</code> of candidate instances
    249      * @param queryName the name of the query to look up in metadata
    250      * @return the new <code>Query</code>
    251      */
    252     Query newNamedQuery (Class cls, String queryName);
    253
    254     /** The <code>PersistenceManager</code> manages a collection of instances in
    255      * the data store based on the class of the instances.  This method returns
    256      * an <code>Extent</code> of instances in the data store that might be
    257      * iterated or given to a <code>Query</code>.  The <code>Extent</code>
    258      * itself might not reference any instances, but only hold the class name
    259      * and an indicator as to whether subclasses are included in the
    260      * <code>Extent</code>.
    261      * <P>Note that the <code>Extent</code> might be very large.
    262      * @param persistenceCapableClass <code>Class</code> of instances
    263      * @param subclasses whether to include instances of subclasses
    264      * @return an <code>Extent</code> of the specified <code>Class</code>
    265      * @see Query
    266      */
    267     <T> Extent<T> getExtent (Class<T> persistenceCapableClass, boolean subclasses);
    268
    269     /**
    270      * Equivalent to <code>getExtent (persistenceCapableClass,
    271      * true)</code>.
    272      * @see #getExtent(Class,boolean)
    273      * @since 2.0
    274      */
    275     <T> Extent<T> getExtent (Class<T> persistenceCapableClass);
    276
    277     /** This method locates a persistent instance in the cache of instances
    278      * managed by this <code>PersistenceManager</code>.
    279      * The <code>getObjectById</code> method attempts
    280      * to find an instance in the cache with the specified JDO identity.
    281      * The <code>oid</code> parameter object might have been returned by an
    282      * earlier call to <code>getObjectId</code> or
    283      * <code>getTransactionalObjectId</code>, or might have been constructed by
    284      * the application.
    285      * <P>If the <code>PersistenceManager</code> is unable to resolve the
    286      * <code>oid</code> parameter to an ObjectId instance, then it throws a
    287      * <code>JDOUserException</code>.
    288      * <P>If the <code>validate</code> flag is <code>false</code>, and there is
    289      * already an instance in the cache with the same JDO identity as the
    290      * <code>oid</code> parameter, then this method returns it. There is no
    291      * change made to the state of the returned instance.
    292      * <P>If there is not an instance already in the cache with the same JDO
    293      * identity as the <code>oid</code> parameter, then this method creates an
    294      * instance with the specified JDO identity and returns it. If there is no
    295      * transaction in progress, the returned instance will be hollow or
    296      * persistent-nontransactional, at the choice of the implementation.
    297      * <P>If there is a transaction in progress, the returned instance will
    298      * be hollow, persistent-nontransactional, or persistent-clean, at the
    299      * choice of the implementation.
    300      * <P>It is an implementation decision whether to access the data store,
    301      * if required to determine the exact class. This will be the case of
    302      * inheritance, where multiple <code>PersistenceCapable</code> classes share
    303      * the same ObjectId class.
    304      * <P>If the validate flag is <code>false</code>, and the instance does not
    305      * exist in the data store, then this method might not fail. It is an
    306      * implementation choice whether to fail immediately with a
    307      * <code>JDOObjectNotFoundException</code>. But a subsequent access
    308      * of the fields of the
    309      * instance will throw a <code>JDOObjectNotFoundException</code>
    310      * if the instance does not
    311      * exist at that time. Further, if a relationship is established to this
    312      * instance, then the transaction in which the association was made will
    313      * fail.
    314      * <P>If the <code>validate</code> flag is <code>true</code>, and there is
    315      * already a transactional instance in the cache with the same JDO identity
    316      * as the <code>oid</code> parameter, then this method returns it. There is
    317      * no change made to the state of the returned instance.
    318      * <P>If there is an instance already in the cache with the same JDO
    319      * identity as the <code>oid</code> parameter, but the instance is not
    320      * transactional, then it must be verified in the data store. If the
    321      * instance does not exist in the datastore, then a
    322      * <code>JDOObjectNotFoundException</code> is thrown.
    323      * <P>If there is not an instance already in the cache with the same JDO
    324      * identity as the <code>oid</code> parameter, then this method creates an
    325      * instance with the specified JDO identity, verifies that it exists in the
    326      * data store, and returns it. If there is no transaction in progress, the
    327      * returned instance will be hollow or persistent-nontransactional,
    328      * at the choice of the implementation.
    329      * <P>If there is a data store transaction in progress, the returned
    330      * instance will be persistent-clean.
    331      * If there is an optimistic transaction in progress, the returned
    332      * instance will be persistent-nontransactional.
    333      * @see #getObjectId(Object pc)
    334      * @see #getTransactionalObjectId(Object pc)
    335      * @return the <code>PersistenceCapable</code> instance with the specified
    336      * ObjectId
    337      * @param oid an ObjectId
    338      * @param validate if the existence of the instance is to be validated
    339      */
    340     Object getObjectById (Object oid, boolean validate);
    341
    342     /**
    343      * Looks up the instance of the given type with the given key.
    344      * @param cls The type of object to load
    345      * @param key either the string representation of the object id, or
    346      * an object representation of a single field identity key
    347      * @return the corresponding persistent instance
    348      * @since 2.0
    349      */
    350     <T> T getObjectById (Class<T> cls, Object key);
    351
    352     /**
    353      * Looks up the instance corresponding to the specified oid. This is
    354      * equivalent to <code>getObjectById(oid, true);
    355      * @param oid The object id of the object to load
    356      * @return the corresponding persistent instance
    357      */
    358     Object getObjectById (Object oid);
    359
    360     /** The ObjectId returned by this method represents the JDO identity of
    361      * the instance.  The ObjectId is a copy (clone) of the internal state
    362      * of the instance, and changing it does not affect the JDO identity of
    363      * the instance.
    364      * <P>The <code>getObjectId</code> method returns an ObjectId instance that
    365      * represents the object identity of the specified JDO instance. The
    366      * identity is guaranteed to be unique only in the context of the JDO
    367      * <code>PersistenceManager</code> that created the identity, and only for
    368      * two types of JDO Identity: those that are managed by the application, and
    369      * those that are managed by the data store.
    370      * <P>If the object identity is being changed in the transaction, by the
    371      * application modifying one or more of the application key fields,
    372      * then this method returns the identity as of the beginning of the
    373      * transaction. The value returned by <code>getObjectId</code> will be
    374      * different following <code>afterCompletion</code> processing for
    375      * successful transactions. <P>Within a transaction, the ObjectId returned
    376      * will compare equal to the ObjectId returned by only one among all JDO
    377      * instances associated with the <code>PersistenceManager</code> regardless
    378      * of the type of ObjectId.
    379      * <P>The ObjectId does not necessarily contain any internal state of the
    380      * instance, nor is it necessarily an instance of the class used to
    381      * manage identity internally. Therefore, if the application makes a
    382      * change to the ObjectId instance returned by this method, there is
    383      * no effect on the instance from which the ObjectId was obtained.
    384      * <P>The <code>getObjectById</code> method can be used between instances of
    385      * <code>PersistenceManager</code> of different JDO vendors only for
    386      * instances of persistence capable classes using application-managed
    387      * (primary key) JDO identity. If it is used for instances of classes using
    388      * datastore identity, the method might succeed, but there are no guarantees
    389      * that the parameter and return instances are related in any way.
    390      * @see #getTransactionalObjectId(Object pc)
    391      * @see #getObjectById(Object oid, boolean validate)
    392      * @param pc the <code>PersistenceCapable</code> instance
    393      * @return the ObjectId of the instance
    394      */
    395     Object getObjectId (Object pc);
    396
    397     /** The ObjectId returned by this method represents the JDO identity of
    398      * the instance.  The ObjectId is a copy (clone) of the internal state
    399      * of the instance, and changing it does not affect the JDO identity of
    400      * the instance.
    401      * <P>If the object identity is being changed in the transaction, by the
    402      * application modifying one or more of the application key fields,
    403      * then this method returns the current identity in the transaction.
    404      * <P>If there is no transaction in progress, or if none of the key fields
    405      * is being modified, then this method will return the same value as
    406      * <code>getObjectId</code>.
    407      * @see #getObjectId(Object pc)
    408      * @see #getObjectById(Object oid, boolean validate)
    409      * @param pc a <code>PersistenceCapable</code> instance
    410      * @return the ObjectId of the instance
    411      */
    412     Object getTransactionalObjectId (Object pc);
    413
    414     /**
    415      * This method returns an object id instance corresponding to the pcClass
    416      * and key arguments.
    417      * @param pcClass the <code>Class</code> of the persistence-capable instance
    418      * @param key for single-field identity, the parameter for the
    419      * constructor; for non-single-field application identity, the result
    420      * of toString() on the object id instance.
    421      * @return an instance of the object identity class
    422      */
    423     Object newObjectIdInstance (Class pcClass, Object key);
    424
    425     /**
    426      * Return the objects with the given oids.
    427      * @param oids the oids of the objects to return
    428      * @param validate if true, the existance of the objects in
    429      *     the datastore will be validated.
    430      * @return the objects that were looked up, in the
    431      *     same order as the oids parameter.
    432      * @see #getObjectById(Object,boolean)
    433      * @since 2.0
    434      */
    435     Collection getObjectsById (Collection oids, boolean validate);
    436
    437     /**
    438      * Return the objects with the given oids. This method is equivalent
    439      * to calling {@link #getObjectsById(Collection, boolean)}
    440      * with the validate flag true.
    441      * @param oids the oids of the objects to return
    442      * @return the objects that were looked up, in the
    443      *     same order as the oids parameter.
    444      * @see #getObjectsById(Collection,boolean)
    445      * @since 2.0
    446      */
    447     Collection getObjectsById (Collection oids);
    448
    449     /**
    450      * Return the objects with the given oids.
    451      * @param oids the oids of the objects to return
    452      * @param validate if true, the existance of the objects in
    453      *     the datastore will be validated.
    454      * @return the objects that were looked up, in the
    455      *     same order as the oids parameter.
    456      * @see #getObjectById(Object,boolean)
    457      * @see #getObjectsById(boolean,Object...)
    458      * @deprecated
    459      * @since 2.0
    460      */
    461     Object[] getObjectsById (Object[] oids, boolean validate);
    462
    463     /**
    464      * Return the objects with the given oids.
    465      * @param oids the oids of the objects to return
    466      * @param validate if true, the existance of the objects in
    467      *     the datastore will be validated.
    468      * @return the objects that were looked up, in the
    469      *     same order as the oids parameter.
    470      * @see #getObjectById(Object,boolean)
    471      * @since 2.1
    472      */
    473     Object[] getObjectsById (boolean validate, Object... oids);
    474
    475     /**
    476      * Return the objects with the given oids. This method is equivalent
    477      * to calling {@link #getObjectsById(boolean,Object...)}
    478      * with the validate flag true.
    479      * @param oids the oids of the objects to return
    480      * @return the objects that were looked up, in the
    481      *     same order as the oids parameter.
    482      * @see #getObjectsById(boolean,Object...)
    483      * @since 2.0
    484      */
    485     Object[] getObjectsById (Object... oids);
    486
    487     /** Make the parameter instance persistent in this
    488      * <code>PersistenceManager</code>.
    489      * This method makes transient instances persistent and applies detached
    490      * instance changes to the cache. It must be called in the context of
    491      * an active transaction, or a JDOUserException is thrown. For a transient
    492      * instance, it assigns an object identity to the instance and transitions
    493      * it to persistent-new. Any transient instances reachable from this
    494      * instance via persistent fields of this instance become provisionally
    495      * persistent, transitively. That is, they behave as persistent-new
    496      * instances (return true to isPersistent, isNew, and isDirty).
    497      * But at commit time, the reachability algorithm is run again,
    498      * and instances made provisionally persistent that are not then
    499      * reachable from persistent instances will revert to transient.
    500      * <P>During makePersistent of transient instances, the create life cycle
    501      * listener is called.
    502      * <P>For detached instances, it locates or instantiates a persistent
    503      * instance with the same JDO identity as the detached instance,
    504      * and merges the persistent state of the detached instance into the
    505      * persistent instance. Only the state of persistent fields is merged.
    506      * If non-persistent state needs to be copied, the application should
    507      * use the jdoPostAttach callback or the postAttach lifecycle event
    508      * listener. Any references to the detached instances from instances
    509      * in the closure of the parameter instances are modified to refer to
    510      * the corresponding persistent instance instead of to the
    511      * detached instance.
    512      * <P>During attachment of detached instances, the attach callbacks
    513      * and attach life cycle listeners are called.
    514      * <P>During application of changes of the detached state, if the JDO
    515      * implementation can determine that there were no changes made during
    516      * detachment, then the implementation is not required to mark the
    517      * corresponding instance dirty. If it cannot determine if changes
    518      * were made, then it must mark the instance dirty.
    519      * No consistency checking is done during makePersistent of detached
    520      * instances. If consistency checking is required by the application,
    521      * then flush or checkConsistency should be called after attaching the
    522      * instances.
    523      * <P>These methods have no effect on parameter persistent instances
    524      * already managed by this PersistenceManager. They will throw a
    525      * JDOUserException if the parameter instance is managed by a
    526      * different PersistenceManager.
    527      * If an instance is of a class whose identity type (application,
    528      * datastore, or none) is not supported by the JDO implementation,
    529      * then a JDOUserException will be thrown for that instance.
    530      * The return value for parameter instances in the transient or persistent
    531      * states is the same as the parameter value. The return value for
    532      * parameter instances in the detached state is the persistent instance
    533      * corresponding to the detached instance.
    534      * The return values for makePersistentAll methods correspond by position
    535      * to the parameter instances.
    536      * @param pc an instance of a <code>Class</code> that is persistent
    537      * capable.
    538      * @return the parameter instance for parameters in the transient or
    539      * persistent state, or the corresponding persistent instance
    540      * for detached parameter instances
    541      */
    542     <T> T makePersistent (T pc);
    543
    544     /** Make an array of instances persistent.
    545      * @param pcs an array of instances
    546      * @return the parameter instances for parameters in the transient or
    547      * persistent state, or the corresponding persistent instance
    548      * for detached parameter instances, in the same order as in the
    549      * parameter array
    550      * @see #makePersistent(Object pc)
    551      */
    552     <T> T[] makePersistentAll (T... pcs);
    553
    554     /** Make a <code>Collection</code> of instances persistent.
    555      * @param pcs a <code>Collection</code> of instances
    556      * @return the parameter instance for parameters in the transient or
    557      * persistent state, or the corresponding persistent instance
    558      * for detached parameter instances, with an iteration in the same order
    559      * as in the parameter Collection
    560      * @see #makePersistent(Object pc)
    561      */
    562     <T> Collection<T> makePersistentAll (Collection<T> pcs);
    563
    564     /** Delete the persistent instance from the data store.
    565      * This method must be called in an active transaction.
    566      * The data store object will be removed at commit.
    567      * Unlike <code>makePersistent</code>, which makes the closure of the
    568      * instance persistent, the closure of the instance is not deleted from the
    569      * data store.  This method has no effect if the instance is already deleted
    570      * in the current transaction.
    571      * This method throws <code>JDOUserException</code> if the instance is
    572      * transient or is managed by another <code>PersistenceManager</code>.
    573      *
    574      * @param pc a persistent instance
    575      */
    576     void deletePersistent (Object pc);
    577
    578     /** Delete an array of instances from the data store.
    579      * @param pcs a <code>Collection</code> of persistent instances
    580      * @see #deletePersistent(Object pc)
    581      */
    582     void deletePersistentAll (Object... pcs);
    583
    584     /** Delete a <code>Collection</code> of instances from the data store.
    585      * @param pcs a <code>Collection</code> of persistent instances
    586      * @see #deletePersistent(Object pc)
    587      */
    588     void deletePersistentAll (Collection pcs);
    589
    590     /** Make an instance transient, removing it from management by this
    591      * <code>PersistenceManager</code>.
    592      *
    593      * <P>The instance loses its JDO identity and it is no longer associated
    594      * with any <code>PersistenceManager</code>.  The state of fields is
    595      * preserved unchanged.
    596      * @param pc the instance to make transient.
    597      */
    598     void makeTransient (Object pc);
    599
    600     /** Make an array of instances transient, removing them from management by
    601      * this <code>PersistenceManager</code>.
    602      *
    603      * <P>The instances lose their JDO identity and they are no longer
    604      * associated with any <code>PersistenceManager</code>.  The state of fields
    605      * is preserved unchanged.
    606      * @param pcs the instances to make transient.
    607      */
    608     void makeTransientAll (Object... pcs);
    609
    610     /** Make a <code>Collection</code> of instances transient, removing them
    611      * from management by this <code>PersistenceManager</code>.
    612      *
    613      * <P>The instances lose their JDO identity and they are no longer
    614      * associated with any <code>PersistenceManager</code>.  The state of fields
    615      * is preserved unchanged.
    616      * @param pcs the instances to make transient.
    617      */
    618     void makeTransientAll (Collection pcs);
    619
    620     /** Make an instance transient, removing it from management by this
    621      * <code>PersistenceManager</code>. If the useFetchPlan parameter is
    622      * false, this method behaves exactly as makeTransient(Object pc).
    623      * <P>The affected instance(s) lose their JDO identity and are no longer
    624      * associated with any <code>PersistenceManager</code>.  The state
    625      * of fields is unchanged.
    626      * <P>If the useFetchPlan parameter is true, then the current FetchPlan
    627      * is applied to the pc parameter, as if detachCopy(Object) had been
    628      * called. After the graph of instances is loaded, the instances
    629      * reachable via loaded fields is made transient. The state of fields
    630      * in the affected instances is as specified by the FetchPlan.
    631      * <P>Unlike detachCopy, the instances are not detached; there is no
    632      * detachment information in the instances.
    633      * <P>The instances to be made transient do not need to
    634      * implement the javax.jdo.spi.Detachable interface.
    635      * @param pc the root instance to make transient.
    636      * @param useFetchPlan whether to use the current fetch plan to determine
    637      * which fields to load and which instances to make transient
    638      * @since 2.0
    639      */
    640     void makeTransient (Object pc, boolean useFetchPlan);
    641
    642     /** Make instances transient, removing them from management
    643      * by this <code>PersistenceManager</code>. If the useFetchPlan parameter
    644      * is false, this method behaves exactly as makeTransientAll(Object[] pcs).
    645      * <P>The affected instance(s) lose their JDO identity and are no longer
    646      * associated with any <code>PersistenceManager</code>.  The state
    647      * of fields is unchanged.
    648      * <P>If the useFetchPlan parameter is true, then the current FetchPlan
    649      * is applied to the pcs parameters and the entire graph of instances
    650      * reachable via loaded fields is made transient. The state of fields
    651      * in the affected instances is as specified by the FetchPlan.
    652      * <P>Unlike detachCopy, the instances are not detached; there is no
    653      * detachment information in the instances.
    654      * <P>The instances to be made transient do not need to
    655      * implement the javax.jdo.spi.Detachable interface.
    656      * @param pcs the root instances to make transient.
    657      * @param useFetchPlan whether to use the current fetch plan to determine
    658      * which fields to load and which instances to make transient
    659      * @see #makeTransientAll(boolean,Object...)
    660      * @deprecated
    661      * @since 2.0
    662      */
    663     void makeTransientAll (Object[] pcs, boolean useFetchPlan);
    664
    665     /** Make instances transient, removing them from management
    666      * by this <code>PersistenceManager</code>. If the useFetchPlan parameter
    667      * is false, this method behaves exactly as makeTransientAll(Object[] pcs).
    668      * <P>The affected instance(s) lose their JDO identity and are no longer
    669      * associated with any <code>PersistenceManager</code>.  The state
    670      * of fields is unchanged.
    671      * <P>If the useFetchPlan parameter is true, then the current FetchPlan
    672      * is applied to the pcs parameters and the entire graph of instances
    673      * reachable via loaded fields is made transient. The state of fields
    674      * in the affected instances is as specified by the FetchPlan.
    675      * <P>Unlike detachCopy, the instances are not detached; there is no
    676      * detachment information in the instances.
    677      * <P>The instances to be made transient do not need to
    678      * implement the javax.jdo.spi.Detachable interface.
    679      * @param pcs the root instances to make transient.
    680      * @param useFetchPlan whether to use the current fetch plan to determine
    681      * which fields to load and which instances to make transient
    682      * @since 2.1
    683      */
    684     void makeTransientAll (boolean useFetchPlan, Object... pcs);
    685
    686     /** Make instances transient, removing them from management
    687      * by this <code>PersistenceManager</code>. If the useFetchPlan parameter
    688      * is false, this method behaves exactly as
    689      * makeTransientAll(Collection pcs).
    690      * <P>The affected instance(s) lose their JDO identity and are no longer
    691      * associated with any <code>PersistenceManager</code>.  The state
    692      * of fields is unchanged.
    693      * <P>If the useFetchPlan parameter is true, then the current FetchPlan
    694      * is applied to the pcs parameters and the entire graph of instances
    695      * reachable via loaded fields is made transient. The state of fields
    696      * in the affected instances is as specified by the FetchPlan.
    697      * <P>Unlike detachCopy, the instances are not detached; there is no
    698      * detachment information in the instances.
    699      * <P>The instances to be made transient do not need to
    700      * implement the javax.jdo.spi.Detachable interface.
    701      * @param pcs the root instances to make transient.
    702      * @param useFetchPlan whether to use the current fetch plan to determine
    703      * which fields to load and which instances to make transient
    704      * @since 2.0
    705      */
    706     void makeTransientAll (Collection pcs, boolean useFetchPlan);
    707
    708     /** Make an instance subject to transactional boundaries.
    709      *
    710      * <P>Transient instances normally do not observe transaction boundaries.
    711      * This method makes transient instances sensitive to transaction
    712      * completion.  If an instance is modified in a transaction, and the
    713      * transaction rolls back, the state of the instance is restored to the
    714      * state before the first change in the transaction.
    715      *
    716      * <P>For persistent instances read in optimistic transactions, this method
    717      * allows the application to make the state of the instance part of the
    718      * transactional state.  At transaction commit, the state of the instance in
    719      * the cache is compared to the state of the instance in the data store.  If
    720      * they are not the same, then an exception is thrown.
    721      * @param pc the instance to make transactional.
    722      */
    723     void makeTransactional (Object pc);
    724
    725     /** Make an array of instances subject to transactional boundaries.
    726      * @param pcs the array of instances to make transactional.
    727      * @see #makeTransactional(Object pc)
    728      */
    729     void makeTransactionalAll (Object... pcs);
    730
    731     /** Make a <code>Collection</code> of instances subject to transactional
    732      * boundaries.
    733      * @param pcs the <code>Collection</code> of instances to make
    734      * transactional.
    735      * @see #makeTransactional(Object pc)
    736      */
    737     void makeTransactionalAll (Collection pcs);
    738
    739     /** Make an instance non-transactional after commit.
    740      *
    741      * <P>Normally, at transaction completion, instances are evicted from the
    742      * cache.  This method allows an application to identify an instance as
    743      * not being evicted from the cache at transaction completion.  Instead,
    744      * the instance remains in the cache with nontransactional state.
    745      *
    746      * @param pc the instance to make nontransactional.
    747      */
    748     void makeNontransactional (Object pc);
    749
    750     /** Make an array of instances non-transactional after commit.
    751      *
    752      * @param pcs the array of instances to make nontransactional.
    753      * @see #makeNontransactional(Object pc)
    754      */
    755     void makeNontransactionalAll (Object... pcs);
    756
    757     /** Make a <code>Collection</code> of instances non-transactional after
    758      * commit.
    759      *
    760      * @param pcs the <code>Collection</code> of instances to make
    761      * nontransactional.
    762      * @see #makeNontransactional(Object pc)
    763      */
    764     void makeNontransactionalAll (Collection pcs);
    765
    766     /** Retrieve field values of an instance from the store.  This tells
    767      * the <code>PersistenceManager</code> that the application intends to use
    768      * the instance, and its field values must be retrieved.
    769      * <P>The <code>PersistenceManager</code> might use policy information about
    770      * the class to retrieve associated instances.
    771      * @param pc the instance
    772      */
    773     void retrieve (Object pc);
    774
    775     /** Retrieve field values of an instance from the store.  This tells
    776      * the <code>PersistenceManager</code> that the application intends to use
    777      * the instance, and its field values must be retrieved.
    778      * <P>If the useFetchPlan parameter is false, this method behaves exactly
    779      * as the corresponding method without the useFetchPlan parameter.
    780      * If the useFetchPlan parameter is true, and the fetch plan has not been
    781      * modified from its default setting, all fields in the current fetch plan
    782      * are fetched, and other fields might be fetched lazily by the
    783      * implementation. If the useFetchPlan parameter is true, and the fetch
    784      * plan has been changed from its default setting, then the fields
    785      * specified by the fetch plan are loaded, along with related instances
    786      * specified by the fetch plan.
    787      * @param pc the instance
    788      * @param useFetchPlan whether to use the current fetch plan to determine
    789      * which fields to load and which instances to retrieve.
    790      * @since 2.0
    791      */
    792     void retrieve (Object pc, boolean useFetchPlan);
    793
    794     /** Retrieve field values of instances from the store.  This tells
    795      * the <code>PersistenceManager</code> that the application intends to use
    796      * the instances, and all field values must be retrieved.
    797      * <P>The <code>PersistenceManager</code> might use policy information about
    798      * the class to retrieve associated instances.
    799      * @param pcs the instances
    800      */
    801     void retrieveAll (Collection pcs);
    802
    803     /** Retrieve field values of instances from the store.  This tells
    804      * the <code>PersistenceManager</code> that the application intends to use
    805      * the instances, and their field values should be retrieved.  The fields
    806      * in the current fetch group must be retrieved, and the implementation
    807      * might retrieve more fields than the current fetch group.
    808      * <P>If the useFetchPlan parameter is false, this method behaves exactly
    809      * as the corresponding method without the useFetchPlan parameter.
    810      * If the useFetchPlan parameter is true, and the fetch plan has not been
    811      * modified from its default setting, all fields in the current fetch plan
    812      * are fetched, and other fields might be fetched lazily by the
    813      * implementation. If the useFetchPlan parameter is true, and the fetch
    814      * plan has been changed from its default setting, then the fields
    815      * specified by the fetch plan are loaded, along with related instances
    816      * specified by the fetch plan.
    817      * @param pcs the instances
    818      * @param useFetchPlan whether to use the current fetch plan to determine
    819      * which fields to load and which instances to retrieve.
    820      * @since 1.0.1
    821      */
    822     void retrieveAll (Collection pcs, boolean useFetchPlan);
    823
    824     /** Retrieve field values of instances from the store.  This tells
    825      * the <code>PersistenceManager</code> that the application intends to use
    826      * the instances, and all field values must be retrieved.
    827      * <P>The <code>PersistenceManager</code> might use policy information about
    828      * the class to retrieve associated instances.
    829      * @param pcs the instances
    830      */
    831     void retrieveAll (Object... pcs);
    832
    833     /** Retrieve field values of instances from the store.  This tells
    834      * the <code>PersistenceManager</code> that the application intends to use
    835      * the instances, and their field values should be retrieved.  The fields
    836      * in the current fetch group must be retrieved, and the implementation
    837      * might retrieve more fields than the current fetch group.
    838      * <P>If the useFetchPlan parameter is false, this method behaves exactly
    839      * as the corresponding method without the useFetchPlan parameter.
    840      * If the useFetchPlan parameter is true, and the fetch plan has not been
    841      * modified from its default setting, all fields in the current fetch plan
    842      * are fetched, and other fields might be fetched lazily by the
    843      * implementation. If the useFetchPlan parameter is true, and the fetch
    844      * plan has been changed from its default setting, then the fields
    845      * specified by the fetch plan are loaded, along with related instances
    846      * specified by the fetch plan.
    847      * @param pcs the instances
    848      * @param useFetchPlan whether to use the current fetch plan to determine
    849      * which fields to load and which instances to retrieve.
    850      * @deprecated
    851      * @see #retrieveAll(boolean,Object...)
    852      * @since 1.0.1
    853      */
    854     void retrieveAll (Object[] pcs, boolean useFetchPlan);
    855
    856     /** Retrieve field values of instances from the store.  This tells
    857      * the <code>PersistenceManager</code> that the application intends to use
    858      * the instances, and their field values should be retrieved.  The fields
    859      * in the current fetch group must be retrieved, and the implementation
    860      * might retrieve more fields than the current fetch group.
    861      * <P>If the useFetchPlan parameter is false, this method behaves exactly
    862      * as the corresponding method without the useFetchPlan parameter.
    863      * If the useFetchPlan parameter is true, and the fetch plan has not been
    864      * modified from its default setting, all fields in the current fetch plan
    865      * are fetched, and other fields might be fetched lazily by the
    866      * implementation. If the useFetchPlan parameter is true, and the fetch
    867      * plan has been changed from its default setting, then the fields
    868      * specified by the fetch plan are loaded, along with related instances
    869      * specified by the fetch plan.
    870      * @param pcs the instances
    871      * @param useFetchPlan whether to use the current fetch plan to determine
    872      * which fields to load and which instances to retrieve.
    873      * @since 2.1
    874      */
    875     void retrieveAll (boolean useFetchPlan, Object... pcs);
    876
    877     /** The application can manage the <code>PersistenceManager</code> instances
    878      * more easily by having an application object associated with each
    879      * <code>PersistenceManager</code> instance.
    880      * @param o the user instance to be remembered by the
    881      * <code>PersistenceManager</code>
    882      * @see #getUserObject
    883      */
    884     void setUserObject (Object o);
    885
    886     /** The application can manage the <code>PersistenceManager</code> instances
    887      * more easily by having an application object associated with each
    888      * <code>PersistenceManager</code> instance.
    889      * @return the user object associated with this
    890      * <code>PersistenceManager</code>
    891      * @see #setUserObject
    892      */
    893     Object getUserObject ();
    894
    895     /** This method returns the <code>PersistenceManagerFactory</code> used to
    896      * create this <code>PersistenceManager</code>.
    897      * @return the <code>PersistenceManagerFactory</code> that created
    898      * this <code>PersistenceManager</code>
    899      */
    900     PersistenceManagerFactory getPersistenceManagerFactory();
    901
    902     /** Return the <code>Class</code> that implements the JDO Identity for the
    903      * specified <code>PersistenceCapable</code> class.  The application can use
    904      * the returned <code>Class</code> to construct a JDO Identity instance for
    905      * application identity <code>PersistenceCapable</code> classes.  This JDO
    906      * Identity instance can then be used to get an instance of the
    907      * <code>PersistenceCapable</code> class for use in the application.
    908      *
    909      * <P>In order for the application to construct an instance of the ObjectId
    910      * class it needs to know the class being used by the JDO implementation.
    911      * @param cls the <code>PersistenceCapable Class</code>
    912      * @return the <code>Class</code> of the ObjectId of the parameter
    913      * @see #getObjectById
    914      */
    915     Class getObjectIdClass(Class cls);
    916
    917     /** Set the Multithreaded flag for this <code>PersistenceManager</code>.
    918      * Applications that use multiple threads to invoke methods or access fields
    919      * from instances managed by this <code>PersistenceManager</code> must set
    920      * this flag to <code>true</code>.
    921      * Instances managed by this <code>PersistenceManager</code> include
    922      * persistent or transactional instances of <code>PersistenceCapable</code>
    923      * classes, as well as helper instances such as <code>Query</code>,
    924      * <code>Transaction</code>, or <code>Extent</code>.
    925      * @param flag the Multithreaded setting.
    926      */
    927     void setMultithreaded (boolean flag);
    928
    929     /** Get the current Multithreaded flag for this
    930      * <code>PersistenceManager</code>.
    931      * @see #setMultithreaded
    932      * @return the Multithreaded setting.
    933      */
    934     boolean getMultithreaded();
    935
    936     /** Set the ignoreCache parameter for queries.
    937      *
    938      * <P>IgnoreCache set to <code>true</code> specifies that for all
    939      * <code>Query</code> instances created by this
    940      * <code>PersistenceManager</code>, the default is the cache should be
    941      * ignored for queries.
    942      * @param flag the ignoreCache setting.
    943      */
    944     void setIgnoreCache(boolean flag);
    945
    946     /** Get the ignoreCache setting for queries.
    947      *
    948      * <P>IgnoreCache set to <code>true</code> specifies that for all
    949      * <code>Query</code> instances created by this
    950      * <code>PersistenceManager</code>, the default is the cache should be
    951      * ignored for queries.
    952      * @return the ignoreCache setting.
    953      */
    954    boolean getIgnoreCache();
    955
    956    /**
    957     * Specify a timeout interval (milliseconds) for any datastore read
    958     * operations associated with this persistence manager. To unset
    959     * the explicit timeout, specify null. For no timeout, specify 0.
    960     * Read operations include, for example, those associated with query,
    961     * getObjectById, refresh, retrieve, and extent iteration operations.
    962     * If the datastore granularity is larger than milliseconds, the
    963     * timeout value will be rounded up to the nearest supported datastore
    964     * value.
    965     * If a read operation hasn't completed within this interval, the operation
    966     * will throw a JDODatastoreException.
    967     * If multiple datastore operations are required to complete the query,
    968     * the timeout value applies to each of them individually.
    969     * If the datastore and JDO implementation support timeouts, then
    970     * javax.jdo.option.DatastoreTimeout is returned by
    971     * PersistenceManagerFactory.supportedOptions().
    972     * If timeouts are not supported,this method will throw
    973     * JDOUnsupportedOptionException.
    974     * @since 3.0
    975     * @param interval the timeout interval (milliseconds)
    976     */
    977    void setDatastoreReadTimeoutMillis(Integer interval);
    978
    979    /** Get the effective timeout setting for datastore read operations
    980     * associated with this persistence manager.
    981     * If the timeout has not been set on this persistence manager explicitly,
    982     * the default read timeout value from the persistence manager factory
    983     * is returned.
    984     * @see #setDatastoreReadTimeoutMillis(Integer)
    985     * @see PersistenceManagerFactory#setDatastoreReadTimeoutMillis(Integer)
    986     * @return the effective timeout setting (milliseconds).
    987     * @since 3.0
    988     */
    989    Integer getDatastoreReadTimeoutMillis();
    990
    991    /**
    992     * Specify a timeout interval (milliseconds) for any write operations
    993     * associated with this persistence manager. To unset the explicit timeout,
    994     * specify null. For no timeout, specify 0.
    995     * Datastore write operations include, for example, operations associated
    996     * with flush, commit, and delete by query.
    997     * If the datastore granularity is larger than milliseconds, the
    998     * timeout value will be rounded up to the nearest supported datastore
    999     * value.
    1000     * If a write operation hasn't completed within this interval, methods
    1001     * will throw a JDODatastoreException.
    1002     * If multiple datastore operations are required to complete the method,
    1003     * the timeout value applies to each of them individually.
    1004     * If the datastore and JDO implementation support timeouts, then
    1005     * javax.jdo.option.DatastoreTimeout is returned by
    1006     * PersistenceManagerFactory.supportedOptions().
    1007     * If timeouts are not supported,this method will throw
    1008     * JDOUnsupportedOptionException.
    1009     * @since 3.0
    1010     * @param interval the timeout interval (milliseconds)
    1011     */
    1012    void setDatastoreWriteTimeoutMillis(Integer interval);
    1013
    1014    /** Get the effective timeout setting for write operations.
    1015     * If the timeout has not been set on this persistence manager explicitly,
    1016     * the default datastore write timeout value from the persistence manager
    1017     * factory is returned.
    1018     * @see #setDatastoreWriteTimeoutMillis(Integer)
    1019     * @see PersistenceManagerFactory#setDatastoreWriteTimeoutMillis(Integer)
    1020     * @return the effective timeout setting (milliseconds).
    1021     * @since 3.0
    1022     */
    1023    Integer getDatastoreWriteTimeoutMillis();
    1024
    1025    /** Gets the detachAllOnCommit setting.
    1026     * @see #setDetachAllOnCommit(boolean)
    1027     * @since 2.0
    1028     * @return the detachAllOnCommit setting.
    1029     */
    1030    boolean getDetachAllOnCommit();
    1031
    1032    /** Sets the detachAllOnCommit setting.
    1033     *
    1034     * <P>DetachAllOnCommit set to <code>false</code> specifies that the
    1035     * state of persistent instances in the cache after commit is defined
    1036     * by the <code>retainValues</code> flag. With this flag set to true,
    1037     * during beforeCompletion all cached instances are prepared for
    1038     * detachment according to the fetch plan in effect at commit. Loading
    1039     * fields and unloading fields required by the fetch plan is done after
    1040     * calling the user's <code>beforeCompletion</code> callback. During
    1041     * <code>afterCompletion</code>, before calling the user's
    1042     * <code>afterCompletion</code> callback, all detachable persistent
    1043     * instances in the cache transition to detached; non-detachable
    1044     * persistent instances transition to transient; and detachable
    1045     * instances can be serialized as detached instances. Transient
    1046     * transactional instances are unaffected by this flag.
    1047     *
    1048     * @see #getDetachAllOnCommit()
    1049     * @since 2.0
    1050     */
    1051    void setDetachAllOnCommit(boolean flag);
    1052
    1053    /** Gets the copyOnAttach setting.
    1054     * @see #setCopyOnAttach(boolean)
    1055     * @since 2.1
    1056     * @return the copyOnAttach setting.
    1057     */
    1058    boolean getCopyOnAttach();
    1059
    1060    /** Sets the copyOnAttach setting.
    1061     *
    1062     * <P>CopyOnAttach set to <code>true</code> specifies that during
    1063     * makePersistent, copies are made of detached parameter instances.
    1064     * With this flag set to <code>false</code>, detached parameter
    1065     * instances are attached directly and change their state from
    1066     * detached-clean to persistent-clean or from detached-dirty to
    1067     * persistent-dirty.
    1068     *
    1069     * @see #getCopyOnAttach()
    1070     * @since 2.1
    1071     */
    1072    void setCopyOnAttach(boolean flag);
    1073
    1074     /**
    1075      * Detach the specified instance from the <code>PersistenceManager</code>.
    1076      * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
    1077      * and the active fetch groups determine the scope of fetching for the
    1078      * graph of instances reachable from the pc parameter. The state of fields
    1079      * in the affected instances is as specified by the FetchPlan.
    1080      * @param pc the instance to detach
    1081      * @return the detached instance
    1082      * @see #detachCopyAll(Object[])
    1083      * @since 2.0
    1084      */
    1085     <T> T detachCopy (T pc);
    1086
    1087     /**
    1088      * Detach the specified instances from the <code>PersistenceManager</code>.
    1089      * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
    1090      * and the active fetch groups determine the scope of fetching for the
    1091      * graph of instances reachable from the pcs parameter. The state of fields
    1092      * in the affected instances is as specified by the FetchPlan.
    1093      * @param pcs the instances to detach
    1094      * @return the detached instances
    1095      * @see #detachCopyAll(Object[])
    1096      * @since 2.0
    1097      */
    1098     <T> Collection<T> detachCopyAll (Collection<T> pcs);
    1099
    1100     /**
    1101      * Detach the specified instances from the <code>PersistenceManager</code>.
    1102      * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
    1103      * and the active fetch groups determine the scope of fetching for the
    1104      * graph of instances reachable from the pcs parameter. The state of fields
    1105      * in the affected instances is as specified by the FetchPlan.
    1106      * The objects returned can be manipulated and re-attached with
    1107      * {@link #makePersistentAll(Object[])}.
    1108      * The detached instances will be
    1109      * unmanaged copies of the specified parameters, and are suitable
    1110      * for serialization and manipulation outside of a JDO
    1111      * environment. When detaching instances, only fields in the
    1112      * current {@link FetchPlan} will be traversed. Thus, to detach a
    1113      * graph of objects, relations to other persistent instances must
    1114      * either be in the <code>default-fetch-group</code>, or in the
    1115      * current custom {@link FetchPlan}.
    1116      * @param pcs the instances to detach
    1117      * @return the detached instances
    1118      * @throws JDOUserException if any of the instances to be detached do not
    1119      * implement the javax.jdo.spi.Detachable interface.
    1120      * @see #makePersistentAll(Object[])
    1121      * @see #getFetchPlan
    1122      * @since 2.0
    1123      */
    1124     <T> T[] detachCopyAll (T... pcs);
    1125
    1126     /**
    1127      * Put the specified key-value pair into the map of user objects.
    1128      * @since 2.0
    1129      */
    1130     Object putUserObject (Object key, Object val);
    1131
    1132     /**
    1133      * Get the value for the specified key from the map of user objects.
    1134      * @param key the key of the object to be returned
    1135      * @return the object
    1136      * @since 2.0
    1137      */
    1138     Object getUserObject (Object key);
    1139
    1140     /**
    1141      * Remove the specified key and its value from the map of user objects.
    1142      * @param key the key of the object to be removed
    1143      * @since 2.0
    1144      */
    1145     Object removeUserObject (Object key);
    1146
    1147     /**
    1148      * Flushes all dirty, new, and deleted instances to the data
    1149      * store. It has no effect if a transaction is not active.
    1150      * <p>If a datastore transaction is active, this method
    1151      * synchronizes the cache with the datastore and reports any
    1152      * exceptions.</p>
    1153      * <p>If an optimistic transaction is active, this method obtains
    1154      * a datastore connection, synchronizes the cache with the
    1155      * datastore using this connection and reports any
    1156      * exceptions. The connection obtained by this method is held
    1157      * until the end of the transaction.</p>
    1158      * <p>If exceptions occur during flush, the implementation will
    1159      * set the current transaction's <code>RollbackOnly</code> flag
    1160      * (see {@link Transaction#setRollbackOnly}).</p>
    1161      * @since	2.0
    1162      */
    1163     void flush ();
    1164
    1165     /**
    1166      * Validates the <code>PersistenceManager</code> cache with the
    1167      * datastore. This method has no effect if a transaction is not
    1168      * active.
    1169      * <p>If a datastore transaction is active, this method verifies
    1170      * the consistency of instances in the cache against the
    1171      * datastore. An implementation might flush instances as if
    1172      * {@link #flush} were called, but it is not required to do
    1173      * so.</p>
    1174      * <p>If an optimistic transaction is active, this method obtains
    1175      * a datastore connection and verifies the consistency of the
    1176      * instances in the cache against the datastore. If any
    1177      * inconsistencies are detected, a {@link
    1178      * JDOOptimisticVerificationException} is thrown. This exception
    1179      * contains a nested {@link JDOOptimisticVerificationException}
    1180      * for each object that failed the consistency check. No
    1181      * datastore resources acquired during the execution of this
    1182      * method are held beyond the scope of this method.</p>
    1183      * @since 2.0
    1184      */
    1185     void checkConsistency ();
    1186
    1187     /**
    1188      * Returns the <code>FetchPlan</code> used by this
    1189      * <code>PersistenceManager</code>.
    1190      * @return the FetchPlan
    1191      * @since 2.0
    1192      */
    1193     FetchPlan getFetchPlan ();
    1194
    1195     /**
    1196      * Creates an instance of a persistence-capable interface,
    1197      * or of a concrete or abstract class.
    1198      * The returned instance is transient.
    1199      * @param pcClass Must be a persistence-capable interface,
    1200      * or a concrete or abstract class that is declared in the metadata.
    1201      * @return the created instance
    1202      * @since 2.0
    1203      */
    1204     <T> T newInstance (Class<T> pcClass);
    1205
    1206     /**
    1207      * Returns the sequence identified by <code>name</code>.
    1208      * @param name the name of the Sequence
    1209      * @return the Sequence
    1210      * @since 2.0
    1211      */
    1212     Sequence getSequence (String name);
    1213
    1214     /**
    1215      * If this method is called while a datastore transaction is
    1216      * active, the object returned will be enlisted in the current
    1217      * transaction. If called in an optimistic transaction or outside
    1218      * an active transaction, the object returned will not be
    1219      * enlisted in any transaction.
    1220      * @return the JDOConnection instance
    1221      * @since 2.0
    1222      */
    1223     JDOConnection getDataStoreConnection ();
    1224
    1225     /**
    1226      * Adds the listener instance to the list of lifecycle event
    1227      * listeners. The <code>classes</code> parameter identifies all
    1228      * of the classes of interest. If the <code>classes</code>
    1229      * parameter is specified as <code>null</code>, events for all
    1230      * persistent classes and interfaces will be sent to
    1231      * <code>listenerInstance</code>.
    1232      * <p>The listenerInstance will be called for each event for which it
    1233      * implements the corresponding listenerInstance interface.</p>
    1234      * @param listener the lifecycle listener
    1235      * @param classes the classes of interest to the listener
    1236      * @since 2.0
    1237      */
    1238     void addInstanceLifecycleListener (InstanceLifecycleListener listener,
    1239         Class... classes);
    1240
    1241     /**
    1242      * Removes the listener instance from the list of lifecycle event listeners.
    1243      * @param listener the listener instance to be removed
    1244      * @since 2.0
    1245      */
    1246     void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
    1247
    1248     /**
    1249      * Get the Date as seen by the server.
    1250      * Clients using this method can order their operations according to
    1251      * a single time source. Implementations use the setting of the
    1252      * server time zone to prepare a Date instance that represents
    1253      * UTC time on the server.
    1254      * @return a Date instance corresponding to the UTC Date
    1255      * as seen by the server
    1256      * @since 2.1
    1257      */
    1258     Date getServerDate();
    1259
    1260     /**
    1261      * Get the objects managed by this persistence manager.
    1262      * @return the objects
    1263      * @since 2.1
    1264      */
    1265     Set getManagedObjects();
    1266
    1267     /**
    1268      * Get the objects managed by this persistence manager having the
    1269      * specified object states.
    1270      * @param states The states of objects that we are interested in
    1271      * @return the objects
    1272      * @since 2.1
    1273      */
    1274     Set getManagedObjects(EnumSet<ObjectState> states);
    1275
    1276     /**
    1277      * Get the objects managed by this persistence manager being instances of
    1278      * the specified classes.
    1279      * @param classes The classes of objects that we are interested in
    1280      * @return the objects
    1281      * @since 2.1
    1282      */
    1283     Set getManagedObjects(Class... classes);
    1284
    1285     /**
    1286      * Get the objects managed by this persistence manager having the
    1287      * specified object states and being instances of the specified classes.
    1288      * @param states The states of objects that we are interested in
    1289      * @param classes The classes of objects that we are interested in
    1290      * @return the objects
    1291      * @since 2.1
    1292      */
    1293     Set getManagedObjects(EnumSet<ObjectState> states, Class... classes);
    1294
    1295     /**
    1296      * Get a modifiable <code>FetchGroup</code> for the Class and name.
    1297      * If a modifiable <code>FetchGroup</code> already exists in the
    1298      * <code>PersistenceManager</code> scope, return it.
    1299      * If not, create and populate a new <code>FetchGroup</code> from the
    1300      * existing definition in the {@link PersistenceManager} or
    1301      * {@link PersistenceManagerFactory}. If the definition for the
    1302      * <code>FetchGroup</code> is not in scope in either the
    1303      * <code>PersistenceManager</code> or
    1304      * <code>PersistenceManagerFactory</code>, create it with no members.
    1305      * The <code>FetchGroup</code> immediately
    1306      * becomes active and in scope of the PersistenceManager, and hides
    1307      * the corresponding fetch group in the PersistenceManagerFactory.
    1308      * @param cls the class or interface for the <code>FetchGroup</code>
    1309      * @param name the name of the fetch group
    1310      * @return the FetchGroup
    1311      * @throws JDOUserException if the class is not a persistence-capable
    1312      * class or interface
    1313      * @since 2.2
    1314      */
    1315     FetchGroup getFetchGroup(Class cls, String name);
    1316 }