1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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