ExternalTransaction


1   // You can redistribute this software and/or modify it under the terms of
2   // the Ozone Library License version 1 published by ozone-db.org.
3   //
4   // The original code and portions created by SMB are
5   // Copyright (C) 1997-@year@ by SMB GmbH. All rights reserved.
6   //
7   // $Id: ExternalTransaction.java,v 1.4 2002/12/29 11:15:55 per_nyfelt Exp $
8   
9   package org.ozoneDB;
10  
11  import org.ozoneDB.core.Transaction;
12  
13  import javax.naming.*;
14  import java.io.IOException  ;
15  import java.rmi.Remote  ;
16  import java.util.Hashtable  ;
17  
18  
19  /**
20   * ExternalTransaction allows an application to explicitly manage transaction
21   * boundaries.<p>
22   *
23   * When programming ozone applications explicite transaction demarcation is
24   * needed under rare circumstances only (for example: processing of binary large
25   * objects - BLOBs). In fact, in most cases explicite transactions are not
26   * really needed while implicite transactions are cleaner and faster. So, every
27   * time you are going to use explicite transactions, you should ask yourself if
28   * an implicite transaction is maybe a better choice.<p>
29   *
30   * In case of a deadlock the ordinary behaviour of ozone is to abort one of the
31   * locked transactions and restart until all transactions are successfully
32   * commited. This is not possible when explicite transactions are used! In case
33   * of deadlock an exceptions is thrown and the client has to decide what to do.
34   * <p>
35   *
36   * Note: If an operation that runs under control of this transaction fails, the
37   * transaction is set to rollback only.
38   *
39   *
40   * @author <a HREF="http://www.softwarebuero.de/">SMB</a>
41   * @version $Revision: 1.4 $Date: 2002/12/29 11:15:55 $
42   */
43  public final class ExternalTransaction
44          extends AbstractTransaction
45          implements Referenceable {
46  
47      // Constants
48  
49      /** Status of a transaction: transaction is not active. */
50      public final static int STATUS_NONE = 1;
51  
52      /** Status of a transaction: transaction has been started. */
53      public final static int STATUS_ACTIVE = 2;
54  
55      /** Status of a transaction: transaction is about to prepare. */
56      public final static int STATUS_PREPARING = 3;
57  
58      /** Status of a transaction: transaction has been successfully prepared. */
59      public final static int STATUS_PREPARED = 4;
60  
61      /** Status of a transaction: transaction is about to commit.*/
62      public final static int STATUS_COMMITING = 5;
63  
64      /** Status of a transaction: transaction has been successfully committed. */
65      public final static int STATUS_COMMITED = 6;
66  
67      /** Status of a transaction: transaction is about to abort. */
68      public final static int STATUS_ROLLINGBACK = 7;
69  
70      /** Status of a transaction: transaction has been aborted. */
71      public final static int STATUS_ROLLEDBACK = 8;
72  
73      // Fields
74  
75      protected boolean rollbackOnly = false;
76  
77  
78      public ExternalTransaction( ExternalDatabase _database ) {
79          super( _database );
80      }
81  
82  
83      /**
84       * Start work on behalf of this transaction and associate it with the current
85       * thread.
86       *
87       *
88       * @throws TransactionException If the thread is already associated with a
89       * transaction.
90       * @throws IOException If the server is not reachable.
91       */
92      public void begin() throws TransactionException, IOException   {
93          database.beginTX( this );
94      }
95  
96  
97      /**
98       * Attach the caller's thread to this transaction and detach the thread
99       * from any former Transaction the thread may have been associated with.
100      */
101     public void join() throws TransactionException, IOException   {
102         if (database instanceof LocalDatabase) {
103             // currently the client side threads are used for server internal work;
104             // that is, DbLocalClient just calls the appropriate server method; but
105             // the server can handle only one thread per transaction, therefore
106             // jointTX for local connections is not allowed -> one (Command)Thread per
107             // DbLocalClient
108             throw new RuntimeException  ( "Operation not supported: join() on LocalDatabase's." );
109             }
110         else {
111             database.leaveTX( this );
112             database.joinTX( this );
113         }
114     }
115 
116 
117     /**
118      * Detach the caller's thread from this <code>Transaction</code>, but do not attach
119      * the thread to another <code>Transaction</code>.
120      */
121     public void leave() throws TransactionException, IOException   {
122         database.leaveTX( this );
123     }
124 
125 
126     /**
127      * Prepares this transaction. This method is intended to be used by
128      * transactional applications that need two-phase commit.
129      */
130     public void prepare() throws TransactionException, IOException   {
131         if (rollbackOnly) {
132             database.rollbackTX( this );
133             throw new TransactionException( "Transaction was set to rollback only.", TransactionException.ROLLBACK );
134         } else {
135             // the server can also decide to rollback this transaction
136             database.prepareTX( this );
137         }
138     }
139 
140 
141     /**
142      * Complete this transaction. When this method completes, the thread
143      * becomes associated with no transaction. This method can be called by a
144      * non-joined thread.
145      */
146     public void commit() throws TransactionException, IOException   {
147         commit( true );
148     }
149 
150 
151     /**
152      * Complete this transaction. When this method completes, the thread
153      * becomes associated with no transaction. This method is intended to be
154      * used by transactional applications that need two-phase commit.
155      */
156     public void commit( boolean onePhase ) throws TransactionException, IOException   {
157         if (rollbackOnly) {
158             database.rollbackTX( this );
159             throw new TransactionException( "Transaction was set to rollback only.", TransactionException.ROLLBACK );
160         } else {
161             // the server can also decide to rollback this transaction
162             database.commitTX( this, onePhase );
163         }
164     }
165 
166 
167     /**
168      * Checkpoint this transaction. This method can also be called by a
169      * non-joined thread.
170      */
171     public void checkpoint() throws TransactionException, IOException   {
172         database.checkpointTX( this );
173     }
174 
175 
176     /**
177      * Rollback the transaction associated with the current thread. When this
178      * method completes, the thread becomes associated with no transaction.
179      * Calling this method when the transaction is not opened doe not throw
180      * an exception.
181      * <p>
182      * This method can be called by any threads.
183      */
184     public void rollback() throws TransactionException, IOException   {
185         database.rollbackTX( this );
186     }
187 
188 
189     /**
190      * Modify the transaction associated with the current thread such that the
191      * only possible outcome of the transaction is to roll back the transaction.
192      */
193     public synchronized void setRollbackOnly() throws TransactionException, IOException   {
194         rollbackOnly = true;
195     }
196 
197 
198     /**
199      * Obtain the status of the transaction associated with the current thread.
200      */
201     public int getStatus() throws TransactionException, IOException   {
202         int internal = database.getStatusTX( this );
203 
204         // explicitely map this to avoid conflicts when codes are changed in
205         // of the two classes
206         switch (internal) {
207         case Transaction.STATUS_NONE:
208             return STATUS_NONE;
209         case Transaction.STATUS_STARTED:
210             return STATUS_ACTIVE;
211         case Transaction.STATUS_PREPARING:
212             return STATUS_PREPARING;
213         case Transaction.STATUS_PREPARED:
214             return STATUS_PREPARED;
215         case Transaction.STATUS_COMMITING:
216             return STATUS_COMMITING;
217         case Transaction.STATUS_COMMITED:
218             return STATUS_COMMITED;
219         case Transaction.STATUS_ABORTING:
220             return STATUS_ROLLINGBACK;
221         case Transaction.STATUS_ABORTED:
222             return STATUS_ROLLEDBACK;
223         default:
224             throw new RuntimeException  ( "Unknown internal transaction status." );
225         }
226     }
227 
228 
229     /**
230      * Modify the value of the timeout value that is associated with the
231      * transactions started by the current thread with the begin method.
232      *
233      * If an application has not called this method, the transaction service
234      * uses some default value for the transaction timeout.
235      *
236      *
237      * @param seconds The value of the timeout in seconds. If the value is zero,
238      * the transaction service restores the default value
239      */
240     public void setTransactionTimeout( int seconds ) throws TransactionException, IOException   {
241         throw new RuntimeException  ( "setTransactionTimeout() is not yet implemented." );
242     }
243 
244 
245     // JNDI stuff *****************************************
246 
247 
248     /**
249      * Retrieves the JNDI Reference of this object.
250      * @return The non-null Reference of this object.
251      */
252     public Reference getReference() throws NamingException {
253         throw new RuntimeException  ( "getReference() is not yet implemented." );
254 
255     //        Reference ref;
256     //        Package   pkg;
257     //
258     //        // we use same object as factory.
259     //        ref = new Reference (getClass().getName(), getClass().getName(), null);
260     //
261     //        // No properties, the entire transaction manager is static.
262     //        pkg = ExternalTransaction.class.getPackage();
263     //        if (pkg != null) {
264     //            ref.add ( new StringRefAddr( "title", pkg.getImplementationTitle() ) );
265     //            ref.add ( new StringRefAddr( "vendor", pkg.getImplementationVendor() ) );
266     //            ref.add ( new StringRefAddr( "version", pkg.getImplementationVersion() ) );
267     //            }
268     //        return ref;
269     }
270 
271 
272     public Object   getObjectInstance( Object   refObj, Name name, Context nameCtx, Hashtable   env ) {
273 
274         // Can only reconstruct from a reference.
275         if (refObj instanceof Reference) {
276             return this;
277         } else if (refObj instanceof Remote  ) {
278             return refObj;
279         } else {
280             return null;
281         }
282     }
283 
284 
285     public static ExternalTransaction getInstance() {
286         throw new RuntimeException  ( "ExternalTransaction.getInstance() not implemented yet." );
287     // return new ExternalTransaction (database);
288     }
289 
290 }
291
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags