Transaction


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