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