View Javadoc

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;
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 }