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