1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 package javax.jdo;
23
24 import java.util.Properties;
25 import java.util.Collection;
26
27 import javax.jdo.datastore.DataStoreCache;
28
29 import javax.jdo.listener.InstanceLifecycleListener;
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.0
54 */
55
56 public interface PersistenceManagerFactory extends java.io.Serializable {
57
58 /*** Close this PersistenceManagerFactory. Check for
59 * JDOPermission("closePersistenceManagerFactory") and if not authorized,
60 * throw SecurityException.
61 * <P>If the authorization check succeeds, check to see that all
62 * PersistenceManager instances obtained from this PersistenceManagerFactory
63 * have no active transactions. If any PersistenceManager instances have
64 * an active transaction, throw a JDOUserException, with one nested
65 * JDOUserException for each PersistenceManager with an active Transaction.
66 * <P>If there are no active transactions, then close all PersistenceManager
67 * instances obtained from this PersistenceManagerFactory, mark this
68 * PersistenceManagerFactory as closed, disallow getPersistenceManager
69 * methods, and allow all other get methods. If a set method or
70 * getPersistenceManager method is called after close, then
71 * JDOUserException is thrown.
72 * @since 1.0.1
73 */
74 void close();
75
76 /***
77 * A <code>PersistenceManagerFactory</code> instance can be used
78 * until it is closed.
79 * @return <code>true</code> if this <code>PersistenceManagerFactory</code>
80 * has been closed.
81 * @see #close()
82 * @since 2.0
83 */
84 boolean isClosed();
85
86 /*** Get an instance of <code>PersistenceManager</code> from this factory.
87 * The instance has default values for options.
88 *
89 * <P>After the first use of <code>getPersistenceManager</code>, no "set"
90 * methods will succeed.
91 *
92 * @return a <code>PersistenceManager</code> instance with default options.
93 */
94 PersistenceManager getPersistenceManager();
95
96 /*** Get an instance of <code>PersistenceManager</code> from this factory.
97 * The instance has default values for options.
98 * The parameters <code>userid</code> and <code>password</code> are used
99 * when obtaining datastore connections from the connection pool.
100 *
101 * <P>After the first use of <code>getPersistenceManager</code>, no "set"
102 * methods will succeed.
103 *
104 * @return a <code>PersistenceManager</code> instance with default options.
105 * @param userid the userid for the connection
106 * @param password the password for the connection
107 */
108 PersistenceManager getPersistenceManager(String userid, String password);
109
110 /*** Set the user name for the data store connection.
111 * @param userName the user name for the data store connection.
112 */
113 void setConnectionUserName(String userName);
114
115 /*** Get the user name for the data store connection.
116 * @return the user name for the data store connection.
117 */
118 String getConnectionUserName ();
119
120 /*** Set the password for the data store connection.
121 * @param password the password for the data store connection.
122 */
123 void setConnectionPassword (String password);
124
125 /*** Set the URL for the data store connection.
126 * @param url the URL for the data store connection.
127 */
128 void setConnectionURL (String url);
129
130 /*** Get the URL for the data store connection.
131 * @return the URL for the data store connection.
132 */
133 String getConnectionURL ();
134
135 /*** Set the driver name for the data store connection.
136 * @param driverName the driver name for the data store connection.
137 */
138 void setConnectionDriverName (String driverName);
139
140 /*** Get the driver name for the data store connection.
141 * @return the driver name for the data store connection.
142 */
143 String getConnectionDriverName ();
144
145 /*** Set the name for the data store connection factory.
146 * @param connectionFactoryName the name of the data store connection
147 * factory.
148 */
149 void setConnectionFactoryName (String connectionFactoryName);
150
151 /*** Get the name for the data store connection factory.
152 * @return the name of the data store connection factory.
153 */
154 String getConnectionFactoryName ();
155
156 /*** Set the data store connection factory. JDO implementations
157 * will support specific connection factories. The connection
158 * factory interfaces are not part of the JDO specification.
159 * @param connectionFactory the data store connection factory.
160 */
161 void setConnectionFactory (Object connectionFactory);
162
163 /*** Get the data store connection factory.
164 * @return the data store connection factory.
165 */
166 Object getConnectionFactory ();
167
168 /*** Set the name for the second data store connection factory. This is
169 * needed for managed environments to get nontransactional connections for
170 * optimistic transactions.
171 * @param connectionFactoryName the name of the data store connection
172 * factory.
173 */
174 void setConnectionFactory2Name (String connectionFactoryName);
175
176 /*** Get the name for the second data store connection factory. This is
177 * needed for managed environments to get nontransactional connections for
178 * optimistic transactions.
179 * @return the name of the data store connection factory.
180 */
181 String getConnectionFactory2Name ();
182
183 /*** Set the second data store connection factory. This is
184 * needed for managed environments to get nontransactional connections for
185 * optimistic transactions. JDO implementations
186 * will support specific connection factories. The connection
187 * factory interfaces are not part of the JDO specification.
188 * @param connectionFactory the data store connection factory.
189 */
190 void setConnectionFactory2 (Object connectionFactory);
191
192 /*** Get the second data store connection factory. This is
193 * needed for managed environments to get nontransactional connections for
194 * optimistic transactions.
195 * @return the data store connection factory.
196 */
197 Object getConnectionFactory2 ();
198
199 /*** Set the default Multithreaded setting for all
200 * <code>PersistenceManager</code> instances obtained from this factory.
201 *
202 * @param flag the default Multithreaded setting.
203 */
204 void setMultithreaded (boolean flag);
205
206 /*** Get the default Multithreaded setting for all
207 * <code>PersistenceManager</code> instances obtained from this factory.
208 *
209 * @return the default Multithreaded setting.
210 */
211 boolean getMultithreaded();
212
213 /*** Set the Mapping setting for this factory. This is used to find the
214 * object-datastore mapping file(s).
215 *
216 * @param mapping the Mapping setting.
217 */
218 void setMapping (String mapping);
219
220 /*** Get the Mapping setting for this factory. This is used to find the
221 * object-datastore mapping file(s).
222 *
223 * @return the Mapping setting.
224 */
225 String getMapping ();
226
227 /*** Set the default Optimistic setting for all
228 * <code>PersistenceManager</code> instances obtained from this factory.
229 *
230 * @param flag the default Optimistic setting.
231 */
232 void setOptimistic (boolean flag);
233
234 /*** Get the default Optimistic setting for all
235 * <code>PersistenceManager</code> instances obtained from this factory.
236 *
237 * @return the default Optimistic setting.
238 */
239 boolean getOptimistic();
240
241 /*** Set the default RetainValues setting for all
242 * <code>PersistenceManager</code> instances obtained from this factory.
243 *
244 * @param flag the default RetainValues setting.
245 */
246 void setRetainValues (boolean flag);
247
248 /*** Get the default RetainValues setting for all
249 * <code>PersistenceManager</code> instances obtained from this factory.
250 *
251 * @return the default RetainValues setting.
252 */
253 boolean getRetainValues ();
254
255 /*** Set the default value for the RestoreValues property.
256 * If <code>true</code>, at rollback, fields of newly persistent instances
257 * are restored to
258 * their values as of the beginning of the transaction, and the instances
259 * revert to transient. Additionally, fields of modified
260 * instances of primitive types and immutable reference types
261 * are restored to their values as of the beginning of the
262 * transaction.
263 * <P>If <code>false</code>, at rollback, the values of fields of
264 * newly persistent instances are unchanged and the instances revert to
265 * transient. Additionally, dirty instances transition to hollow.
266 * If an implementation does not support this option, a
267 * <code>JDOUnsupportedOptionException</code> is thrown.
268 * @param restoreValues the value of the restoreValues property
269 */
270 void setRestoreValues(boolean restoreValues);
271
272 /*** Get the default value for the RestoreValues property.
273 * @return the value of the restoreValues property
274 */
275 boolean getRestoreValues();
276
277 /*** Set the default NontransactionalRead setting for all
278 * <code>PersistenceManager</code> instances obtained from this factory.
279 *
280 * @param flag the default NontransactionalRead setting.
281 */
282 void setNontransactionalRead (boolean flag);
283
284 /*** Get the default NontransactionalRead setting for all
285 * <code>PersistenceManager</code> instances obtained from this factory.
286 *
287 * @return the default NontransactionalRead setting.
288 */
289 boolean getNontransactionalRead ();
290
291 /*** Set the default NontransactionalWrite setting for all
292 * <code>PersistenceManager</code> instances obtained from this factory.
293 *
294 * @param flag the default NontransactionalWrite setting.
295 */
296 void setNontransactionalWrite (boolean flag);
297
298 /*** Get the default NontransactionalWrite setting for all
299 * <code>PersistenceManager</code> instances obtained from this factory.
300 *
301 * @return the default NontransactionalWrite setting.
302 */
303 boolean getNontransactionalWrite ();
304
305 /*** Set the default IgnoreCache setting for all
306 * <code>PersistenceManager</code> instances obtained from this factory.
307 *
308 * @param flag the default IgnoreCache setting.
309 */
310 void setIgnoreCache (boolean flag);
311
312 /*** Get the default IgnoreCache setting for all
313 * <code>PersistenceManager</code> instances obtained from this factory.
314 *
315 * @return the default IngoreCache setting.
316 */
317 boolean getIgnoreCache ();
318
319 /*** Gets the detachAllOnCommit setting.
320 * @see #setDetachAllOnCommit(boolean)
321 * @since 2.0
322 * @return the default detachAllOnCommit setting.
323 */
324 boolean getDetachAllOnCommit();
325
326 /*** Sets the default detachAllOnCommit setting for all
327 * <code>PersistenceManager</code> instances obtained from this
328 * factory.
329 * @see #getDetachAllOnCommit()
330 * @since 2.0
331 */
332 void setDetachAllOnCommit(boolean flag);
333
334 /*** Return non-configurable properties of this
335 * <code>PersistenceManagerFactory</code>.
336 * Properties with keys <code>VendorName</code> and
337 * <code>VersionNumber</code> are required. Other keys are optional.
338 * @return the non-configurable properties of this
339 * <code>PersistenceManagerFactory</code>.
340 */
341 Properties getProperties();
342
343 /*** The application can determine from the results of this
344 * method which optional features, and which query languages
345 * are supported by the JDO implementation.
346 * <P>Each supported JDO optional feature is represented by a
347 * <code>String</code> with one of the following values:
348 *
349 * <P><code>javax.jdo.option.TransientTransactional
350 * <BR>javax.jdo.option.NontransactionalRead
351 * <BR>javax.jdo.option.NontransactionalWrite
352 * <BR>javax.jdo.option.RetainValues
353 * <BR>javax.jdo.option.Optimistic
354 * <BR>javax.jdo.option.ApplicationIdentity
355 * <BR>javax.jdo.option.DatastoreIdentity
356 * <BR>javax.jdo.option.NonDatastoreIdentity
357 * <BR>javax.jdo.option.ArrayList
358 * <BR>javax.jdo.option.HashMap
359 * <BR>javax.jdo.option.Hashtable
360 * <BR>javax.jdo.option.LinkedList
361 * <BR>javax.jdo.option.TreeMap
362 * <BR>javax.jdo.option.TreeSet
363 * <BR>javax.jdo.option.Vector
364 * <BR>javax.jdo.option.Map
365 * <BR>javax.jdo.option.List
366 * <BR>javax.jdo.option.Array
367 * <BR>javax.jdo.option.NullCollection
368 * <BR>javax.jdo.option.ChangeApplicationIdentity
369 * <BR>javax.jdo.option.BinaryCompatibility
370 * <BR>javax.jdo.option.GetDataStoreConnection
371 * <BR>javax.jdo.option.UnconstrainedQueryVariables
372 * <BR>javax.jdo.query.SQL
373 * <BR>javax.jdo.query.JDOQL
374 * </code>
375 *
376 *<P>The standard JDO query language is represented by a
377 * <code>String</code>:
378 *<P><code>javax.jdo.query.JDOQL</code>
379 * @return the <code>Collection</code> of <code>String</code>s representing
380 * the supported options.
381 */
382 Collection supportedOptions();
383
384 /***
385 * Return the {@link DataStoreCache} that this factory uses for
386 * controlling a second-level cache. If this factory does not use
387 * a second-level cache, the returned instance does nothing. This
388 * method never returns <code>null</code>.
389 * @since 2.0
390 */
391 DataStoreCache getDataStoreCache ();
392
393 /***
394 * Add the parameter listener to the list of
395 * instance lifecycle event listeners set as the initial listeners
396 * for each PersistenceManager created by this PersistenceManagerFactory.
397 * The <code>addInstanceLifecycleListener</code> and
398 * <code>removeInstanceLifecycleListener</code>
399 * methods are considered to be configuration methods and
400 * can only be called when the PersistenceManagerFactory
401 * is configurable (before the first time {@link #getPersistenceManager}
402 * is called).
403 * <p>The <code>classes</code> parameter identifies all
404 * of the classes of interest. If the <code>classes</code>
405 * parameter is specified as <code>null</code>, events for all
406 * persistent classes and interfaces will be sent to the listener.</p>
407 * <p>The listener will be called for each event for which it
408 * implements the corresponding {@link InstanceLifecycleListener}
409 * interface.</p>
410 * @param listener the lifecycle listener
411 * @param classes the classes of interest to the listener
412 * @since 2.0
413 */
414 void addInstanceLifecycleListener (InstanceLifecycleListener listener,
415 Class[] classes);
416
417 /***
418 * Remove the parameter listener instance from the list of
419 * instance lifecycle event listeners set as the initial listeners
420 * for each PersistenceManager created by this PersistenceManagerFactory.
421 * The <code>addInstanceLifecycleListener</code> and
422 * <code>removeInstanceLifecycleListener</code>
423 * methods are considered to be configuration methods and
424 * can only be called when the PersistenceManagerFactory
425 * is configurable (before the first time {@link #getPersistenceManager}
426 * is called).
427 * @param listener the listener instance to be removed
428 * @since 2.0
429 */
430 void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
431
432 }