View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software 
12   * distributed under the License is distributed on an "AS IS" BASIS, 
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
14   * See the License for the specific language governing permissions and 
15   * limitations under the License.
16   */
17  
18  /*
19   * PersistenceManagerFactory.java
20   *
21   */
22   
23  package javax.jdo;
24  
25  import javax.jdo.datastore.DataStoreCache;
26  import javax.jdo.listener.InstanceLifecycleListener;
27  import java.io.Serializable;
28  import java.util.Collection;
29  import java.util.Properties;
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.1
54   */
55  
56  public interface PersistenceManagerFactory extends Serializable {
57  
58      
59      /*** Close this PersistenceManagerFactory. Check for 
60       * JDOPermission("closePersistenceManagerFactory") and if not authorized, 
61       * throw SecurityException. 
62       * <P>If the authorization check succeeds, check to see that all 
63       * PersistenceManager instances obtained from this PersistenceManagerFactory 
64       * have no active transactions. If any PersistenceManager instances have 
65       * an active transaction, throw a JDOUserException, with one nested 
66       * JDOUserException for each PersistenceManager with an active Transaction. 
67       * <P>If there are no active transactions, then close all PersistenceManager 
68       * instances obtained from this PersistenceManagerFactory, mark this 
69       * PersistenceManagerFactory as closed, disallow getPersistenceManager 
70       * methods, and allow all other get methods. If a set method or 
71       * getPersistenceManager method is called after close, then 
72       * JDOUserException is thrown.
73       * @since 1.0.1
74       */
75      void close();
76      
77      /*** 
78       * A <code>PersistenceManagerFactory</code> instance can be used 
79       * until it is closed.
80       * @return <code>true</code> if this <code>PersistenceManagerFactory</code>
81       * has been closed.
82       * @see #close()
83       * @since 2.0
84       */
85      boolean isClosed();
86      
87      /*** Get an instance of <code>PersistenceManager</code> from this factory.  
88       * The instance has default values for options.
89       *
90       * <P>After the first use of <code>getPersistenceManager</code>, no "set" 
91       * methods will succeed.
92       *
93       * @return a <code>PersistenceManager</code> instance with default options.
94       */
95      PersistenceManager getPersistenceManager();
96  
97      /*** Get a thread-safe instance of a proxy that dynamically binds 
98       * on each method call to an instance of <code>PersistenceManager</code>.
99       * <P>When used with a <code>PersistenceManagerFactory</code>
100      * that uses TransactionType JTA,
101      * the proxy can be used in a server to dynamically bind to an instance 
102      * from this factory associated with the thread's current transaction.
103      * In this case, the close method is ignored, as the 
104      * <code>PersistenceManager</code> is automatically closed when the
105      * transaction completes.
106      * <P>When used with a <code>PersistenceManagerFactory</code>
107      * that uses TransactionType RESOURCE_LOCAL, the proxy uses an inheritable
108      * ThreadLocal to bind to an instance of <code>PersistenceManager</code>
109      * associated with the thread. In this case, the close method executed
110      * on the proxy closes the <code>PersistenceManager</code> and then
111      * clears the ThreadLocal.
112      * Use of this method does not affect the configurability of the
113      * <code>PersistenceManagerFactory</code>.
114      *
115      * @since 2.1
116      * @return a <code>PersistenceManager</code> proxy.
117      */
118     PersistenceManager getPersistenceManagerProxy();
119 
120     /*** Get an instance of <code>PersistenceManager</code> from this factory.  
121      * The instance has default values for options.  
122      * The parameters <code>userid</code> and <code>password</code> are used 
123      * when obtaining datastore connections from the connection pool.
124      *
125      * <P>After the first use of <code>getPersistenceManager</code>, no "set" 
126      * methods will succeed.
127      *
128      * @return a <code>PersistenceManager</code> instance with default options.
129      * @param userid the userid for the connection
130      * @param password the password for the connection
131      */
132     PersistenceManager getPersistenceManager(String userid, String password);
133 
134     /*** Set the user name for the data store connection.
135      * @param userName the user name for the data store connection.
136      */
137     void setConnectionUserName(String userName);
138 
139     /*** Get the user name for the data store connection.
140      * @return the user name for the data store connection.
141      */
142     String getConnectionUserName ();
143   
144     /*** Set the password for the data store connection.
145      * @param password the password for the data store connection.
146      */
147     void setConnectionPassword (String password);
148   
149     /*** Set the URL for the data store connection.
150      * @param url the URL for the data store connection.
151      */
152     void setConnectionURL (String url);
153 
154     /*** Get the URL for the data store connection.
155      * @return the URL for the data store connection.
156      */
157     String getConnectionURL ();
158   
159     /*** Set the driver name for the data store connection.
160      * @param driverName the driver name for the data store connection.
161      */
162     void setConnectionDriverName  (String driverName);
163 
164     /*** Get the driver name for the data store connection.
165      * @return the driver name for the data store connection.
166      */
167     String getConnectionDriverName ();
168     
169     /*** Set the name for the data store connection factory.
170      * @param connectionFactoryName the name of the data store connection 
171      * factory.
172      */
173     void setConnectionFactoryName (String connectionFactoryName);
174 
175     /*** Get the name for the data store connection factory.
176      * @return the name of the data store connection factory.
177      */
178     String getConnectionFactoryName ();
179   
180     /*** Set the data store connection factory.  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 setConnectionFactory (Object connectionFactory);
186   
187     /*** Get the data store connection factory.
188      * @return the data store connection factory.
189      */
190     Object getConnectionFactory ();
191   
192     /*** Set the name for the second data store connection factory.  This is
193      * needed for managed environments to get nontransactional connections for
194      * optimistic transactions.
195      * @param connectionFactoryName the name of the data store connection 
196      * factory.
197      */
198     void setConnectionFactory2Name (String connectionFactoryName);
199 
200     /*** Get the name for the second data store connection factory.  This is
201      * needed for managed environments to get nontransactional connections for
202      * optimistic transactions.
203      * @return the name of the data store connection factory.
204      */
205     String getConnectionFactory2Name ();
206   
207     /*** Set the second data store connection factory.  This is
208      * needed for managed environments to get nontransactional connections for
209      * optimistic transactions.  JDO implementations
210      * will support specific connection factories.  The connection
211      * factory interfaces are not part of the JDO specification.
212      * @param connectionFactory the data store connection factory.
213      */
214     void setConnectionFactory2 (Object connectionFactory);
215   
216     /*** Get the second data store connection factory.  This is
217      * needed for managed environments to get nontransactional connections for
218      * optimistic transactions.
219      * @return the data store connection factory.
220      */
221     Object getConnectionFactory2 ();
222   
223     /*** Set the default Multithreaded setting for all 
224      * <code>PersistenceManager</code> instances obtained from this factory.
225      *
226      * @param flag the default Multithreaded setting.
227      */
228     void setMultithreaded (boolean flag);
229   
230     /*** Get the default Multithreaded setting for all 
231      * <code>PersistenceManager</code> instances obtained from this factory.  
232      *
233      * @return the default Multithreaded setting.
234      */
235     boolean getMultithreaded();
236     
237     /*** Set the Mapping setting for this factory. This is used to find the 
238      * object-datastore mapping file(s).
239      *
240      * @param mapping the Mapping setting.
241      */
242     void setMapping (String mapping);
243   
244     /*** Get the Mapping setting for this factory.  This is used to find the 
245      * object-datastore mapping file(s).
246      *
247      * @return the Mapping setting.
248      */
249     String getMapping ();
250     
251     /*** Set the default Optimistic setting for all 
252      * <code>PersistenceManager</code> instances obtained from this factory.  
253      *
254      * @param flag the default Optimistic setting.
255      */
256     void setOptimistic (boolean flag);
257   
258     /*** Get the default Optimistic setting for all 
259      * <code>PersistenceManager</code> instances obtained from this factory.  
260      *
261      * @return the default Optimistic setting.
262      */
263     boolean getOptimistic();
264     
265     /*** Set the default RetainValues setting for all 
266      * <code>PersistenceManager</code> instances obtained from this factory.
267      *
268      * @param flag the default RetainValues setting.
269      */
270     void setRetainValues (boolean flag);
271   
272    /*** Get the default RetainValues setting for all 
273     * <code>PersistenceManager</code> instances obtained from this factory.
274      *
275      * @return the default RetainValues setting.
276      */
277     boolean getRetainValues ();
278     
279     /*** Set the default value for the RestoreValues property.  
280      * If <code>true</code>, at rollback, fields of newly persistent instances 
281      * are restored to 
282      * their values as of the beginning of the transaction, and the instances
283      * revert to transient.  Additionally, fields of modified
284      * instances of primitive types and immutable reference types
285      * are restored to their values as of the beginning of the 
286      * transaction.
287      * <P>If <code>false</code>, at rollback, the values of fields of 
288      * newly persistent instances are unchanged and the instances revert to
289      * transient.  Additionally, dirty instances transition to hollow.
290      * If an implementation does not support this option, a 
291      * <code>JDOUnsupportedOptionException</code> is thrown.
292      * @param restoreValues the value of the restoreValues property
293      */
294     void setRestoreValues(boolean restoreValues);
295     
296     /*** Get the default value for the RestoreValues property.  
297      * @return the value of the restoreValues property
298      */
299     boolean getRestoreValues();
300     
301     /*** Set the default NontransactionalRead setting for all 
302      * <code>PersistenceManager</code> instances obtained from this factory.  
303      *
304      * @param flag the default NontransactionalRead setting.
305      */
306     void setNontransactionalRead (boolean flag);
307   
308     /*** Get the default NontransactionalRead setting for all 
309      * <code>PersistenceManager</code> instances obtained from this factory.
310      *
311      * @return the default NontransactionalRead setting.
312      */
313     boolean getNontransactionalRead ();
314     
315     /*** Set the default NontransactionalWrite setting for all 
316      * <code>PersistenceManager</code> instances obtained from this factory.  
317      *
318      * @param flag the default NontransactionalWrite setting.
319      */
320     void setNontransactionalWrite (boolean flag);
321   
322     /*** Get the default NontransactionalWrite setting for all 
323      * <code>PersistenceManager</code> instances obtained from this factory.
324      *
325      * @return the default NontransactionalWrite setting.
326      */
327     boolean getNontransactionalWrite ();
328     
329     /*** Set the default IgnoreCache setting for all 
330      * <code>PersistenceManager</code> instances obtained from this factory.
331      *
332      * @param flag the default IgnoreCache setting.
333      */
334     void setIgnoreCache (boolean flag);
335   
336     /*** Get the default IgnoreCache setting for all 
337      * <code>PersistenceManager</code> instances obtained from this factory.
338      *
339      * @return the default IngoreCache setting.
340      */
341     boolean getIgnoreCache ();
342   
343     /*** Gets the detachAllOnCommit setting.
344      * @see #setDetachAllOnCommit(boolean)
345      * @since 2.0
346      * @return the default detachAllOnCommit setting.
347      */
348     boolean getDetachAllOnCommit();
349     
350     /*** Sets the default detachAllOnCommit setting for all
351      * <code>PersistenceManager</code> instances obtained from this
352      * factory.
353      * @see #getDetachAllOnCommit()
354      * @since 2.0
355      * @param flag the default DetachAllOnCommit setting
356      */
357     void setDetachAllOnCommit(boolean flag);
358 
359    /*** Gets the default copyOnAttach setting for all
360     * <code>PersistenceManager</code> instances obtained from this
361     * factory.
362     * @see #setCopyOnAttach(boolean)
363     * @since 2.1
364     * @return the copyOnAttach setting.
365     */
366    boolean getCopyOnAttach();
367 
368    /*** Sets the default copyOnAttach setting for all
369     * <code>PersistenceManager</code> instances obtained from this
370     * factory.
371     *
372     * <P>CopyOnAttach set to <code>true</code> specifies that during
373     * makePersistent, copies are made of detached parameter instances. 
374     * With this flag set to <code>false</code>, detached parameter
375     * instances are attached directly and change their state from
376     * detached-clean to persistent-clean or from detached-dirty to
377     * persistent-dirty.
378     *
379     * @see #getCopyOnAttach()
380     * @since 2.1
381     */
382    void setCopyOnAttach(boolean flag);
383    
384     /***
385      * Sets the name of this PersistenceManagerFactory.
386      * @since 2.1
387      * @param name the name of this PMF
388      */
389     void setName(String name);
390 
391     /***
392      * Gets the name of this PersistenceManagerFactory.
393      * @since 2.1
394      * @return the name of this PMF
395      */
396     String getName();
397 
398     /***
399      * Sets the PersistenceUnitName for this PersistenceManagerFactory.
400      * This has the same semantics as the same-named property in
401      * JSR-220 PersistenceUnitInfo.
402      * @see #getPersistenceUnitName()
403      * @since 2.1
404      * @param name the PersistenceUnitName
405      */
406     void setPersistenceUnitName(String name);
407 
408     /***
409      * Gets the PersistenceUnitName for this PersistenceManagerFactory.
410      * @see #setPersistenceUnitName(String)
411      * @since 2.1
412      * @return the PersistenceUnitName
413      */
414     String getPersistenceUnitName();
415 
416     /***
417      * Sets the TimeZone ID of the server associated with this
418      * PersistenceManagerFactory. The parameter is a String
419      * suitable for use with TimeZone.getTimeZone(). The String
420      * must match an ID returned by TimeZone.getAvailableIDs().
421      * If the ServerTimeZoneID is not set, or set to the null String,
422      * assume that the server has the same TimeZone ID as the client.
423      * If incorrectly set, the result of PersistenceManager.getServerDate()
424      * might be incorrect.
425      * @see #getServerTimeZoneID()
426      * @see java.util.TimeZone#getTimeZone(String)
427      * @see java.util.TimeZone#getAvailableIDs()
428      * @see PersistenceManager#getServerDate()
429      * @since 2.1
430      * @param timezoneid the TimeZone ID of the server
431      * @throws JDOUserException if the parameter does not match
432      * an ID from TimeZone.getAvailableIDs()
433      */
434     void setServerTimeZoneID(String timezoneid);
435 
436     /***
437      * Gets the TimeZone ID of the server associated with this
438      * PersistenceManagerFactory. If not set, assume that
439      * the server has the same TimeZone ID as the client.
440      * @see #setServerTimeZoneID(String)
441      * @since 2.1
442      * @return the TimeZone of the server
443      */
444     String getServerTimeZoneID();
445 
446     /***
447      * Sets the TransactionType for this PersistenceManagerFactory.
448      * Permitted values are "JTA" and "RESOURCE_LOCAL".
449      * This has the same semantics as the same-named property in
450      * JSR-220 EntityManagerFactory.
451      * @see #getTransactionType()
452      * @see Constants#JTA
453      * @see Constants#RESOURCE_LOCAL
454      * @since 2.1
455      * @param name the TransactionType
456      * @throws JDOUserException if the parameter is not a permitted value
457      */
458     void setTransactionType(String name);
459 
460     /***
461      * Gets the TransactionType for this PersistenceManagerFactory.
462      * @see #setTransactionType(String)
463      * @since 2.1
464      * @return the TransactionType
465      */
466     String getTransactionType();
467 
468     /*** Return non-configurable properties of this 
469      * <code>PersistenceManagerFactory</code>.
470      * Properties with keys <code>VendorName</code> and 
471      * <code>VersionNumber</code> are required.  Other keys are optional.
472      * @return the non-configurable properties of this
473      * <code>PersistenceManagerFactory</code>.
474      */
475     Properties getProperties();
476     
477     /*** The application can determine from the results of this
478      * method which optional features, and which query languages 
479      * are supported by the JDO implementation.
480      * <P>Each supported JDO optional feature is represented by a
481      * <code>String</code> with one of the following values:
482      *
483      * <P><code>javax.jdo.option.TransientTransactional
484      * <BR>javax.jdo.option.NontransactionalRead
485      * <BR>javax.jdo.option.NontransactionalWrite
486      * <BR>javax.jdo.option.RetainValues
487      * <BR>javax.jdo.option.Optimistic
488      * <BR>javax.jdo.option.ApplicationIdentity
489      * <BR>javax.jdo.option.DatastoreIdentity
490      * <BR>javax.jdo.option.NonDatastoreIdentity
491      * <BR>javax.jdo.option.ArrayList
492      * <BR>javax.jdo.option.HashMap
493      * <BR>javax.jdo.option.Hashtable
494      * <BR>javax.jdo.option.LinkedList
495      * <BR>javax.jdo.option.TreeMap
496      * <BR>javax.jdo.option.TreeSet
497      * <BR>javax.jdo.option.Vector
498      * <BR>javax.jdo.option.Map
499      * <BR>javax.jdo.option.List
500      * <BR>javax.jdo.option.Array  
501      * <BR>javax.jdo.option.NullCollection
502      * <BR>javax.jdo.option.ChangeApplicationIdentity
503      * <BR>javax.jdo.option.BinaryCompatibility
504      * <BR>javax.jdo.option.GetDataStoreConnection
505      * <BR>javax.jdo.option.UnconstrainedQueryVariables
506      * <BR>javax.jdo.query.SQL
507      * <BR>javax.jdo.query.JDOQL
508      * </code>
509      *
510      *<P>The standard JDO query language is represented by a 
511      * <code>String</code>:
512      *<P><code>javax.jdo.query.JDOQL</code>
513      * @return the <code>Collection</code> of <code>String</code>s representing 
514      * the supported options.
515      */    
516     Collection supportedOptions();
517    
518     /***
519      * Return the {@link DataStoreCache} that this factory uses for
520      * controlling a second-level cache. If this factory does not use
521      * a second-level cache, the returned instance does nothing. This
522      * method never returns <code>null</code>.
523      * @since 2.0
524      * @return the DataStoreCache
525      */
526     DataStoreCache getDataStoreCache ();
527 
528     /***
529      * Add the parameter listener to the list of
530      * instance lifecycle event listeners set as the initial listeners
531      * for each PersistenceManager created by this PersistenceManagerFactory. 
532      * The <code>addInstanceLifecycleListener</code> and 
533      * <code>removeInstanceLifecycleListener</code>
534      * methods are considered to be configuration methods and
535      * can only be called when the PersistenceManagerFactory
536      * is configurable (before the first time {@link #getPersistenceManager}
537      * is called).
538      * <p>The <code>classes</code> parameter identifies all
539      * of the classes of interest. If the <code>classes</code>
540      * parameter is specified as <code>null</code>, events for all
541      * persistent classes and interfaces will be sent to the listener.</p>
542      * <p>The listener will be called for each event for which it
543      * implements the corresponding {@link InstanceLifecycleListener}
544      * interface.</p>
545      * @param listener the lifecycle listener
546      * @param classes the classes of interest to the listener
547      * @since 2.0
548      */
549     void addInstanceLifecycleListener (InstanceLifecycleListener listener,
550         Class[] classes);
551 
552     /***
553      * Remove the parameter listener instance from the list of
554      * instance lifecycle event listeners set as the initial listeners
555      * for each PersistenceManager created by this PersistenceManagerFactory. 
556      * The <code>addInstanceLifecycleListener</code> and 
557      * <code>removeInstanceLifecycleListener</code>
558      * methods are considered to be configuration methods and
559      * can only be called when the PersistenceManagerFactory
560      * is configurable (before the first time {@link #getPersistenceManager}
561      * is called).
562      * @param listener the listener instance to be removed
563      * @since 2.0
564      */
565     void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
566 
567 }
568