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  ;
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     /** 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   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   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  [] 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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags