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