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 }