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   * Transaction.java
20   *
21   */
22   
23  package javax.jdo;
24  import javax.transaction.Synchronization;
25  
26  /** The JDO <code>Transaction</code> interface provides for initiation and 
27   * completion of transactions under user control.
28   * It is a sub-interface of the {@link PersistenceManager}
29   * that deals with options and transaction demarcation. 
30   * <P>Transaction options include whether optimistic concurrency
31   * control should be used for the current transaction, whether instances
32   * may hold values in the cache outside transactions, and whether
33   * values should be retained in the cache after transaction completion.  These
34   * options are valid for both managed and non-managed transactions.
35   *
36   * <P>Transaction initiation and completion methods have similar semantics to
37   * <code>javax.transaction.UserTransaction</code> when used outside a managed
38   * environment. When used in a managed environment, transaction initiation 
39   * and completion methods may only be used with bean-managed transaction 
40   * semantics.
41   * @version 3.0
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>JDOFatalDataStoreException<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     /** Get the value for transaction isolation level for this transaction.
169      * @return the transaction isolation level
170      * @see #setIsolationLevel(String)
171      * @since 2.2
172      */
173     String getIsolationLevel();
174 
175     /** Set the value for transaction isolation level for this transaction.
176      * Transaction isolation levels are defined in javax.jdo.Constants.
177      * If the requested level is not available, but a higher level is
178      * available, the higher level is silently used. 
179      * If the requested level is not available, and no higher level is
180      * available, then JDOUnsupportedOptionException is thrown.
181      * Five standard isolation levels are defined. Other isolation levels
182      * might be supported by an implementation but are not standard.
183      * <p>Standard values in order of low to high are:
184      * <ul><li>read-uncommitted
185      * </li><li>read-committed
186      * </li><li>repeatable-read
187      * </li><li>snapshot
188      * </li><li>serializable
189      * </li></ul>
190      * @param level the transaction isolation level
191      * @see #getIsolationLevel()
192      * @see Constants#TX_READ_UNCOMMITTED
193      * @see Constants#TX_READ_COMMITTED
194      * @see Constants#TX_REPEATABLE_READ
195      * @see Constants#TX_SNAPSHOT
196      * @see Constants#TX_SERIALIZABLE
197      * @since 2.2
198      */
199     void setIsolationLevel(String level);
200 
201     /** The user can specify a <code>Synchronization</code> instance to be 
202      * notified on transaction completions.  The <code>beforeCompletion</code> 
203      * method is called prior to flushing instances to the data store.
204      *
205      * <P>The <code>afterCompletion</code> method is called after performing 
206      * state transitions of persistent and transactional instances, following 
207      * the data store commit or rollback operation.
208      * <P>Only one <code>Synchronization</code> instance can be registered with 
209      * the  <code>Transaction</code>. If the application requires more than one 
210      * instance to receive synchronization callbacks, then the single 
211      * application instance is responsible for managing them, and forwarding 
212      * callbacks to them.
213      * @param sync the <code>Synchronization</code> instance to be notified; 
214      * <code>null</code> for none
215      */
216     void setSynchronization(Synchronization sync);
217     
218     /** The user-specified <code>Synchronization</code> instance for this 
219      * <code>Transaction</code> instance.    
220      * @return the user-specified <code>Synchronization</code> instance.
221      */
222     Synchronization getSynchronization();
223 
224     /** The <code>Transaction</code> instance is always associated with exactly 
225      * one <code>PersistenceManager</code>.
226      *
227      * @return the <code>PersistenceManager</code> for this 
228      * <code>Transaction</code> instance
229      */
230     PersistenceManager getPersistenceManager();
231 
232     /**
233      * If <code>true</code>, a lock will be applied to all objects read in this
234      * transaction.
235      * <P>If <code>false</code> then retrieved objects will not be locked.
236      * If null will fallback to the value for metadata for the class in question.
237      * @param serialize the value of the serializeRead property
238      * @since 3.0
239      */
240     void setSerializeRead(Boolean serialize);
241 
242     /**
243      * Return the current value of the serializeRead property.
244      * @return the value of the serializeRead property
245      * @since 3.0
246      */
247     Boolean getSerializeRead();
248 }