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.ComponentMetadata;
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     /** Set the default query timeout setting for all <code>PersistenceManager</code>
524      * instances obtained from this factory.
525      *
526      * @param interval The default timeout setting (millisecs).
527      * @since 2.3
528      */
529     void setQueryTimeoutMillis(Integer interval);
530 
531     /** Get the default query timeout setting for all 
532      * <code>PersistenceManager</code> instances obtained from this factory.
533      *
534      * @return the default query timeout setting.
535      * @since 2.3
536      */
537     Integer getQueryTimeoutMillis();
538 
539     /** Return non-configurable properties of this 
540      * <code>PersistenceManagerFactory</code>.
541      * Properties with keys <code>VendorName</code> and 
542      * <code>VersionNumber</code> are required.  Other keys are optional.
543      * @return the non-configurable properties of this
544      * <code>PersistenceManagerFactory</code>.
545      */
546     Properties getProperties();
547     
548     /** The application can determine from the results of this
549      * method which optional features, and which query languages 
550      * are supported by the JDO implementation.
551      * <P>Each supported JDO feature is represented by a
552      * <code>String</code> with one of the following values:
553      *
554      * <P><code>javax.jdo.option.TransientTransactional
555      * <BR>javax.jdo.option.NontransactionalRead
556      * <BR>javax.jdo.option.NontransactionalWrite
557      * <BR>javax.jdo.option.RetainValues
558      * <BR>javax.jdo.option.Optimistic
559      * <BR>javax.jdo.option.ApplicationIdentity
560      * <BR>javax.jdo.option.DatastoreIdentity
561      * <BR>javax.jdo.option.NonDurableIdentity
562      * <BR>javax.jdo.option.ArrayList
563      * <BR>javax.jdo.option.HashMap
564      * <BR>javax.jdo.option.Hashtable
565      * <BR>javax.jdo.option.LinkedList
566      * <BR>javax.jdo.option.TreeMap
567      * <BR>javax.jdo.option.TreeSet
568      * <BR>javax.jdo.option.Vector
569      * <BR>javax.jdo.option.Map
570      * <BR>javax.jdo.option.List
571      * <BR>javax.jdo.option.Array  
572      * <BR>javax.jdo.option.NullCollection
573      * <BR>javax.jdo.option.ChangeApplicationIdentity
574      * <BR>javax.jdo.option.BinaryCompatibility
575      * <BR>javax.jdo.option.GetDataStoreConnection
576      * <BR>javax.jdo.option.UnconstrainedQueryVariables
577      * <BR>javax.jdo.option.TransactionIsolationLevel.read-uncommitted
578      * <BR>javax.jdo.option.TransactionIsolationLevel.read-committed
579      * <BR>javax.jdo.option.TransactionIsolationLevel.repeatable-read
580      * <BR>javax.jdo.option.TransactionIsolationLevel.snapshot
581      * <BR>javax.jdo.option.TransactionIsolationLevel.serializable
582      * <BR>javax.jdo.option.QueryCancel
583      * <BR>javax.jdo.query.SQL
584      * <BR>javax.jdo.query.JDOQL
585      * </code>
586      *
587      *<P>The standard JDO query language is represented by a 
588      * <code>String</code>:
589      *<P><code>javax.jdo.query.JDOQL</code>
590      * @return the <code>Collection</code> of <code>String</code>s representing 
591      * the supported options.
592      */    
593     Collection<String> supportedOptions();
594    
595     /**
596      * Return the {@link DataStoreCache} that this factory uses for
597      * controlling a second-level cache. If this factory does not use
598      * a second-level cache, the returned instance does nothing. This
599      * method never returns <code>null</code>.
600      * @since 2.0
601      * @return the DataStoreCache
602      */
603     DataStoreCache getDataStoreCache ();
604 
605     /**
606      * Add the parameter listener to the list of
607      * instance lifecycle event listeners set as the initial listeners
608      * for each PersistenceManager created by this PersistenceManagerFactory. 
609      * The <code>addInstanceLifecycleListener</code> and 
610      * <code>removeInstanceLifecycleListener</code>
611      * methods are considered to be configuration methods and
612      * can only be called when the PersistenceManagerFactory
613      * is configurable (before the first time {@link #getPersistenceManager}
614      * is called).
615      * <p>The <code>classes</code> parameter identifies all
616      * of the classes of interest. If the <code>classes</code>
617      * parameter is specified as <code>null</code>, events for all
618      * persistent classes and interfaces will be sent to the listener.</p>
619      * <p>The listener will be called for each event for which it
620      * implements the corresponding {@link InstanceLifecycleListener}
621      * interface.</p>
622      * @param listener the lifecycle listener
623      * @param classes the classes of interest to the listener
624      * @since 2.0
625      */
626     void addInstanceLifecycleListener (InstanceLifecycleListener listener,
627         Class[] classes);
628 
629     /**
630      * Remove the parameter listener instance from the list of
631      * instance lifecycle event listeners set as the initial listeners
632      * for each PersistenceManager created by this PersistenceManagerFactory. 
633      * The <code>addInstanceLifecycleListener</code> and 
634      * <code>removeInstanceLifecycleListener</code>
635      * methods are considered to be configuration methods and
636      * can only be called when the PersistenceManagerFactory
637      * is configurable (before the first time {@link #getPersistenceManager}
638      * is called).
639      * @param listener the listener instance to be removed
640      * @since 2.0
641      */
642     void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
643 
644     /**
645      * Add the <code>FetchGroup</code>s to the set of active fetch groups. 
646      * <code>FetchGroup</code>s are made unmodifiable before being added. 
647      * <code>FetchGroup</code>s that match existing <code>FetchGroup</code>s
648      * replace the corresponding <code>FetchGroup</code>s.
649      * The replaced <code>FetchGroup</code>s become unscoped.
650      * Match is based on identical class and equal name.
651      * The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
652      * {@link #getFetchGroups}, and {@link #removeAllFetchGroups} 
653      * are internally serialized.
654      * @param groups an array of FetchGroups
655      * @throws SecurityException if the caller is not authorized for
656      * {@link JDOPermission} ("manageMetadata")
657      * @since 2.2
658      */
659     void addFetchGroups(FetchGroup... groups);
660 
661     /**
662      * Remove the <code>FetchGroup</code>s from the set of active 
663      * <code>FetchGroup</code>s. Existing <code>FetchGroup</code>s that match 
664      * parameter <code>FetchGroup</code>s are removed. Parameter 
665      * <code>FetchGroup</code>s that do not match any existing 
666      * <code>FetchGroup</code> are ignored.
667      * Removed <code>FetchGroup</code>s become unscoped.
668      * Match is based on identical class and equal name.
669      * The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
670      * {@link #getFetchGroups}, and {@link #removeAllFetchGroups} 
671      * are internally serialized.
672      * @param groups an array of FetchGroups
673      * @throws SecurityException if the caller is not authorized for
674      * {@link JDOPermission} ("manageMetadata")
675      * @since 2.2
676      */
677     void removeFetchGroups(FetchGroup... groups);
678 
679     /**
680      * Remove all <code>FetchGroup</code>s from the set of active 
681      * <code>FetchGroup</code>s.
682      * All removed <code>FetchGroup</code>s become unscoped.
683      * The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
684      * {@link #getFetchGroups}, and {@link #removeAllFetchGroups} 
685      * are internally serialized.
686      * @throws SecurityException if the caller is not authorized for
687      * {@link JDOPermission} ("manageMetadata")
688      * @since 2.2
689      */
690     void removeAllFetchGroups();
691 
692     /**
693      * Create an unscoped, modifiable <code>FetchGroup</code> for the Class and 
694      * name. If a corresponding <code>FetchGroup</code> already exists in 
695      * <code>PersistenceManagerFactory</code> scope, copy its definition
696      * to a new <code>FetchGroup</code>. 
697      * If the <code>FetchGroup</code> does not already exist, create it 
698      * with no members. The <code>FetchGroup</code> does not become 
699      * in scope until it is added to the current set via 
700      * {@link #addFetchGroups}.
701      * @param cls the class or interface for the FetchGroup
702      * @param name the name of the fetch group
703      * @return the FetchGroup
704      * @throws JDOUserException if the class is not a persistence-capable
705      * class or interface
706      * @since 2.2
707      */
708     FetchGroup getFetchGroup(Class cls, String name);
709 
710     /**
711      * Get a modifiable Set containing a mutable copy of all currently active
712      * (in scope) fetch groups.
713      * The methods {@link #addFetchGroups}, {@link #removeFetchGroups},
714      * {@link #getFetchGroups}, and {@link #removeAllFetchGroups} 
715      * are internally serialized.
716      * @return a copy of all currently active fetch groups
717      * @throws SecurityException if the caller is not authorized for
718      * {@link JDOPermission} ("getMetadata")
719      * @since 2.2
720      */
721     Set getFetchGroups();
722 
723     /**
724      * Method to register metadata with the persistence process managed by this
725      * <code>PersistenceManagerFactory</code>. 
726      * Metadata can be created using the method {@link #newMetadata}.
727      * If there is already metadata registered for a class contained in this metadata
728      * object then a JDOUserException will be thrown.
729      * @param metadata The Metadata to register.
730      * @since 2.3
731      */
732     void registerMetadata(JDOMetadata metadata);
733 
734     /**
735      * Method to return a new metadata object that can be subsequently modified
736      * and registered with the persistence process using the method {@link #registerMetadata}.
737      * @return The metadata
738      * @since 2.3
739      */
740     JDOMetadata newMetadata();
741 
742     /**
743      * Method to return the metadata object for the specified class/interface, if there is
744      * metadata defined for that class/interface.
745      * If there is no metadata for the specified class/interface then null will be returned.
746      * @return The metadata
747      * @since 2.3
748      */
749     ComponentMetadata getMetadata(String className);
750 }