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