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