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.metadata.ComponentMetadata;
28 import javax.jdo.metadata.JDOMetadata;
29 import javax.jdo.spi.JDOPermission;
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 }