KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jdo > PersistenceManagerFactory


1 /*
2  * Copyright 2005 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16
17 /*
18  * PersistenceManagerFactory.java
19  *
20  */

21  
22 package javax.jdo;
23
24 import java.util.Properties JavaDoc;
25 import java.util.Collection JavaDoc;
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 JavaDoc {
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 JavaDoc userid, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc URL);
126
127     /** Get the URL for the data store connection.
128      * @return the URL for the data store connection.
129      */

130     String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc connectionFactory);
158   
159     /** Get the data store connection factory.
160      * @return the data store connection factory.
161      */

162     Object JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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     /** Return non-configurable properties of this <code>PersistenceManagerFactory</code>.
315      * Properties with keys <code>VendorName</code> and <code>VersionNumber</code> are required. Other
316      * keys are optional.
317      * @return the non-configurable properties of this
318      * <code>PersistenceManagerFactory</code>.
319      */

320     Properties JavaDoc getProperties();
321   
322     /** The application can determine from the results of this
323      * method which optional features, and which query languages
324      * are supported by the JDO implementation.
325      * <P>Each supported JDO optional feature is represented by a
326      * <code>String</code> with one of the following values:
327      *
328      * <P><code>javax.jdo.option.TransientTransactional
329      * <BR>javax.jdo.option.NontransactionalRead
330      * <BR>javax.jdo.option.NontransactionalWrite
331      * <BR>javax.jdo.option.RetainValues
332      * <BR>javax.jdo.option.Optimistic
333      * <BR>javax.jdo.option.ApplicationIdentity
334      * <BR>javax.jdo.option.DatastoreIdentity
335      * <BR>javax.jdo.option.NonDatastoreIdentity
336      * <BR>javax.jdo.option.ArrayList
337      * <BR>javax.jdo.option.HashMap
338      * <BR>javax.jdo.option.Hashtable
339      * <BR>javax.jdo.option.LinkedList
340      * <BR>javax.jdo.option.TreeMap
341      * <BR>javax.jdo.option.TreeSet
342      * <BR>javax.jdo.option.Vector
343      * <BR>javax.jdo.option.Map
344      * <BR>javax.jdo.option.List
345      * <BR>javax.jdo.option.Array
346      * <BR>javax.jdo.option.NullCollection
347      * <BR>javax.jdo.option.ChangeApplicationIdentity
348      * <BR>javax.jdo.option.BinaryCompatibility
349      * <BR>javax.jdo.option.GetDataStoreConnection
350      * <BR>javax.jdo.option.UnconstrainedQueryVariables
351      * <BR>javax.jdo.query.SQL
352      * <BR>javax.jdo.query.JDOQL
353      * </code>
354      *
355      *<P>The standard JDO query language is represented by a <code>String</code>:
356      *<P><code>javax.jdo.query.JDOQL</code>
357      * @return the <code>Collection</code> of <code>String</code>s representing the supported options.
358      */

359     Collection JavaDoc supportedOptions();
360    
361     /**
362      * Return the {@link DataStoreCache} that this factory uses for
363      * controlling a second-level cache. If this factory does not use
364      * a second-level cache, the returned instance does nothing. This
365      * method never returns <code>null</code>.
366      * @since 2.0
367      */

368     DataStoreCache getDataStoreCache ();
369
370     /**
371      * Add the parameter listener to the list of
372      * instance lifecycle event listeners set as the initial listeners
373      * for each PersistenceManager created by this PersistenceManagerFactory.
374      * The <code>addInstanceLifecycleListener</code> and
375      * <code>removeInstanceLifecycleListener</code>
376      * methods are considered to be configuration methods and
377      * can only be called when the PersistenceManagerFactory
378      * is configurable (before the first time {@link #getPersistenceManager}
379      * is called).
380      * <p>The <code>classes</code> parameter identifies all
381      * of the classes of interest. If the <code>classes</code>
382      * parameter is specified as <code>null</code>, events for all
383      * persistent classes and interfaces will be sent to the listener.</p>
384      * <p>The listener will be called for each event for which it
385      * implements the corresponding {@link InstanceLifecycleListener}
386      * interface.</p>
387      * @param listener the lifecycle listener
388      * @param classes the classes of interest to the listener
389      * @since 2.0
390      */

391     void addInstanceLifecycleListener (InstanceLifecycleListener listener,
392         Class JavaDoc[] classes);
393
394     /**
395      * Remove the parameter listener instance from the list of
396      * instance lifecycle event listeners set as the initial listeners
397      * for each PersistenceManager created by this PersistenceManagerFactory.
398      * The <code>addInstanceLifecycleListener</code> and
399      * <code>removeInstanceLifecycleListener</code>
400      * methods are considered to be configuration methods and
401      * can only be called when the PersistenceManagerFactory
402      * is configurable (before the first time {@link #getPersistenceManager}
403      * is called).
404      * @param listener the listener instance to be removed
405      * @since 2.0
406      */

407     void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
408
409 }
410
Popular Tags