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   * Transaction.java
19   *
20   */
21   
22  package javax.jdo;
23  import javax.transaction.Synchronization;
24  
25  /*** The JDO <code>Transaction</code> interface provides for initiation and 
26   * completion of transactions under user control.
27   * It is a sub-interface of the {@link PersistenceManager}
28   * that deals with options and transaction demarcation. 
29   * <P>Transaction options include whether optimistic concurrency
30   * control should be used for the current transaction, whether instances
31   * may hold values in the cache outside transactions, and whether
32   * values should be retained in the cache after transaction completion.  These
33   * options are valid for both managed and non-managed transactions.
34   *
35   * <P>Transaction initiation and completion methods have similar semantics to
36   * <code>javax.transaction.UserTransaction</code> when used outside a managed
37   * environment. When used in a managed environment, transaction initiation 
38   * and completion methods may only be used with bean-managed transaction 
39   * semantics.
40   * @version 2.0
41   */
42  
43  public interface Transaction
44  {
45      /*** Begin a transaction.  The type of transaction is determined by the
46       * setting of the Optimistic flag.
47       * @see #setOptimistic
48       * @see #getOptimistic
49       * @throws JDOUserException if transactions are managed by a container
50       * in the managed environment, or if the transaction is already active.
51       */
52      void begin();
53      
54      /*** Commit the current transaction.
55       * @throws JDOUserException if transactions are managed by a container
56       * in the managed environment, or if the transaction is not active.
57       */
58      void commit();
59      
60      /*** Roll back the current transaction.
61       * @throws JDOUserException if transactions are managed by a container
62       * in the managed environment, or if the transaction is not active.
63       */
64      void rollback();
65  
66      /*** Returns whether there is a transaction currently active.
67       * @return <code>true</code> if the transaction is active.
68       */
69      boolean isActive();
70      
71      /***
72       * Returns the rollback-only status of the transaction. When
73       * begun, the rollback-only status is false. Either the 
74       * application or the JDO implementation may set this flag
75       * using setRollbackOnly.
76       * @return <code>true</code> if the transaction has been
77       * marked for rollback.
78       * @since 2.0
79       */
80      boolean getRollbackOnly();
81  
82      /***
83       * Sets the rollback-only status of the transaction to <code>true</code>.
84       * After this flag is set to <code>true</code>, the transaction 
85       * can no longer be committed, and any attempt to commit the 
86       * transaction will throw <code>JDOUserException<code>.
87       * @since 2.0
88       */
89      void setRollbackOnly();
90  
91      /*** If <code>true</code>, allow persistent instances to be read without
92       * a transaction active.
93       * If an implementation does not support this option, a 
94       * <code>JDOUnsupportedOptionException</code> is thrown.
95       * @param nontransactionalRead the value of the nontransactionalRead 
96       * property
97       */
98      void setNontransactionalRead (boolean nontransactionalRead);
99      
100     /*** If <code>true</code>, allows persistent instances to be read without
101      * a transaction active.
102      * @return the value of the nontransactionalRead property
103      */
104     boolean getNontransactionalRead ();
105     
106     /*** If <code>true</code>, allow persistent instances to be written without
107      * a transaction active.
108      * If an implementation does not support this option, a 
109      * <code>JDOUnsupportedOptionException</code> is thrown.
110      * @param nontransactionalWrite the value of the nontransactionalRead 
111      * property
112      */
113     void setNontransactionalWrite (boolean nontransactionalWrite);
114     
115     /*** If <code>true</code>, allows persistent instances to be written without
116      * a transaction active.
117      * @return the value of the nontransactionalWrite property
118      */
119     boolean getNontransactionalWrite ();
120     
121     /*** If <code>true</code>, at commit instances retain their values and the 
122      * instances transition to persistent-nontransactional.
123      * If an implementation does not support this option, a 
124      * <code>JDOUnsupportedOptionException</code> is thrown.
125      * @param retainValues the value of the retainValues property
126      */
127     void setRetainValues(boolean retainValues);
128     
129     /*** If <code>true</code>, at commit time instances retain their field 
130      * values.
131      * @return the value of the retainValues property
132      */
133     boolean getRetainValues();
134     
135     /*** If <code>true</code>, at rollback, fields of newly persistent instances 
136      * are restored to 
137      * their values as of the beginning of the transaction, and the instances
138      * revert to transient.  Additionally, fields of modified
139      * instances of primitive types and immutable reference types
140      * are restored to their values as of the beginning of the 
141      * transaction.
142      * <P>If <code>false</code>, at rollback, the values of fields of 
143      * newly persistent instances are unchanged and the instances revert to
144      * transient.  Additionally, dirty instances transition to hollow.
145      * If an implementation does not support this option, a 
146      * <code>JDOUnsupportedOptionException</code> is thrown.
147      * @param restoreValues the value of the restoreValues property
148      */
149     void setRestoreValues(boolean restoreValues);
150     
151     /*** Return the current value of the restoreValues property.
152      * @return the value of the restoreValues property
153      */
154     boolean getRestoreValues();
155     
156     /*** Optimistic transactions do not hold data store locks until commit time.
157      * If an implementation does not support this option, a 
158      * <code>JDOUnsupportedOptionException</code> is thrown.
159      * @param optimistic the value of the Optimistic flag.
160      */
161     void setOptimistic(boolean optimistic);
162     
163     /*** Optimistic transactions do not hold data store locks until commit time.
164      * @return the value of the Optimistic property.
165      */
166     boolean getOptimistic();
167     
168     /*** The user can specify a <code>Synchronization</code> instance to be 
169      * notified on transaction completions.  The <code>beforeCompletion</code> 
170      * method is called prior to flushing instances to the data store.
171      *
172      * <P>The <code>afterCompletion</code> method is called after performing 
173      * state transitions of persistent and transactional instances, following 
174      * the data store commit or rollback operation.
175      * <P>Only one <code>Synchronization</code> instance can be registered with 
176      * the  <code>Transaction</code>. If the application requires more than one 
177      * instance to receive synchronization callbacks, then the single 
178      * application instance is responsible for managing them, and forwarding 
179      * callbacks to them.
180      * @param sync the <code>Synchronization</code> instance to be notified; 
181      * <code>null</code> for none
182      */
183     void setSynchronization(Synchronization sync);
184     
185     /*** The user-specified <code>Synchronization</code> instance for this 
186      * <code>Transaction</code> instance.    
187      * @return the user-specified <code>Synchronization</code> instance.
188      */
189     Synchronization getSynchronization();
190 
191     /*** The <code>Transaction</code> instance is always associated with exactly 
192      * one <code>PersistenceManager</code>.
193      *
194      * @return the <code>PersistenceManager</code> for this 
195      * <code>Transaction</code> instance
196      */
197     PersistenceManager getPersistenceManager();
198 }