ozone API

org.ozoneDB
Class ExternalTransaction

java.lang.Object
  |
  +--org.ozoneDB.AbstractTransaction
        |
        +--org.ozoneDB.ExternalTransaction
All Implemented Interfaces:
javax.naming.Referenceable

public final class ExternalTransaction
extends AbstractTransaction
implements javax.naming.Referenceable

ExternalTransaction allows an application to explicitly manage transaction boundaries.

When programming ozone applications explicite transaction demarcation is needed under rare circumstances only (for example: processing of binary large objects - BLOBs). In fact, in most cases explicite transactions are not really needed while implicite transactions are cleaner and faster. So, every time you are going to use explicite transactions, you should ask yourself if an implicite transaction is maybe a better choice.

In case of a deadlock the ordinary behaviour of ozone is to abort one of the locked transactions and restart until all transactions are successfully commited. This is not possible when explicite transactions are used! In case of deadlock an exceptions is thrown and the client has to decide what to do.

Note: If an operation that runs under control of this transaction fails, the transaction is set to rollback only.

Version:
$Revision: 1.1 $Date: 2001/12/18 10:31:30 $
Author:
SMB

Field Summary
static int STATUS_ACTIVE
          Status of a transaction: transaction has been started.
static int STATUS_COMMITED
          Status of a transaction: transaction has been successfully committed.
static int STATUS_COMMITING
          Status of a transaction: transaction is about to commit.
static int STATUS_NONE
          Status of a transaction: transaction is not active.
static int STATUS_PREPARED
          Status of a transaction: transaction has been successfully prepared.
static int STATUS_PREPARING
          Status of a transaction: transaction is about to prepare.
static int STATUS_ROLLEDBACK
          Status of a transaction: transaction has been aborted.
static int STATUS_ROLLINGBACK
          Status of a transaction: transaction is about to abort.
 
Constructor Summary
ExternalTransaction(ExternalDatabase _database)
           
 
Method Summary
 void begin()
          Start work on behalf of this transaction and associate it with the current thread.
 void checkpoint()
          Checkpoint this transaction.
 void commit()
          Complete this transaction.
 void commit(boolean onePhase)
          Complete this transaction.
static ExternalTransaction getInstance()
           
 java.lang.Object getObjectInstance(java.lang.Object refObj, javax.naming.Name name, javax.naming.Context nameCtx, java.util.Hashtable env)
           
 javax.naming.Reference getReference()
          Retrieves the JNDI Reference of this object.
 int getStatus()
          Obtain the status of the transaction associated with the current thread.
 void join()
          Attach the caller's thread to this transaction and detach the thread from any former Transaction the thread may have been associated with.
 void leave()
          Detach the caller's thread from this Transaction, but do not attach the thread to another Transaction.
 void prepare()
          Prepares this transaction.
 void rollback()
          Rollback the transaction associated with the current thread.
 void setRollbackOnly()
          Modify the transaction associated with the current thread such that the only possible outcome of the transaction is to roll back the transaction.
 void setTransactionTimeout(int seconds)
          Modify the value of the timeout value that is associated with the transactions started by the current thread with the begin method.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

STATUS_NONE

public static final int STATUS_NONE
Status of a transaction: transaction is not active.

See Also:
Constant Field Values

STATUS_ACTIVE

public static final int STATUS_ACTIVE
Status of a transaction: transaction has been started.

See Also:
Constant Field Values

STATUS_PREPARING

public static final int STATUS_PREPARING
Status of a transaction: transaction is about to prepare.

See Also:
Constant Field Values

STATUS_PREPARED

public static final int STATUS_PREPARED
Status of a transaction: transaction has been successfully prepared.

See Also:
Constant Field Values

STATUS_COMMITING

public static final int STATUS_COMMITING
Status of a transaction: transaction is about to commit.

See Also:
Constant Field Values

STATUS_COMMITED

public static final int STATUS_COMMITED
Status of a transaction: transaction has been successfully committed.

See Also:
Constant Field Values

STATUS_ROLLINGBACK

public static final int STATUS_ROLLINGBACK
Status of a transaction: transaction is about to abort.

See Also:
Constant Field Values

STATUS_ROLLEDBACK

public static final int STATUS_ROLLEDBACK
Status of a transaction: transaction has been aborted.

See Also:
Constant Field Values
Constructor Detail

ExternalTransaction

public ExternalTransaction(ExternalDatabase _database)
Method Detail

begin

public void begin()
           throws TransactionExc,
                  java.io.IOException
Start work on behalf of this transaction and associate it with the current thread.

Throws:
TransactionExc - If the thread is already associated with a transaction.
java.io.IOException - If the server is not reachable.

join

public void join()
          throws TransactionExc,
                 java.io.IOException
Attach the caller's thread to this transaction and detach the thread from any former Transaction the thread may have been associated with.

TransactionExc
java.io.IOException

leave

public void leave()
           throws TransactionExc,
                  java.io.IOException
Detach the caller's thread from this Transaction, but do not attach the thread to another Transaction.

TransactionExc
java.io.IOException

prepare

public void prepare()
             throws TransactionExc,
                    java.io.IOException
Prepares this transaction. This method is intended to be used by transactional applications that need two-phase commit.

TransactionExc
java.io.IOException

commit

public void commit()
            throws TransactionExc,
                   java.io.IOException
Complete this transaction. When this method completes, the thread becomes associated with no transaction. This method can be called by a non-joined thread.

TransactionExc
java.io.IOException

commit

public void commit(boolean onePhase)
            throws TransactionExc,
                   java.io.IOException
Complete this transaction. When this method completes, the thread becomes associated with no transaction. This method is intended to be used by transactional applications that need two-phase commit.

TransactionExc
java.io.IOException

checkpoint

public void checkpoint()
                throws TransactionExc,
                       java.io.IOException
Checkpoint this transaction. This method can also be called by a non-joined thread.

TransactionExc
java.io.IOException

rollback

public void rollback()
              throws TransactionExc,
                     java.io.IOException
Rollback the transaction associated with the current thread. When this method completes, the thread becomes associated with no transaction. Calling this method when the transaction is not opened doe not throw an exception.

This method can be called by any threads.

TransactionExc
java.io.IOException

setRollbackOnly

public void setRollbackOnly()
                     throws TransactionExc,
                            java.io.IOException
Modify the transaction associated with the current thread such that the only possible outcome of the transaction is to roll back the transaction.

TransactionExc
java.io.IOException

getStatus

public int getStatus()
              throws TransactionExc,
                     java.io.IOException
Obtain the status of the transaction associated with the current thread.

TransactionExc
java.io.IOException

setTransactionTimeout

public void setTransactionTimeout(int seconds)
                           throws TransactionExc,
                                  java.io.IOException
Modify the value of the timeout value that is associated with the transactions started by the current thread with the begin method. If an application has not called this method, the transaction service uses some default value for the transaction timeout.

Parameters:
seconds - The value of the timeout in seconds. If the value is zero, the transaction service restores the default value
TransactionExc
java.io.IOException

getReference

public javax.naming.Reference getReference()
                                    throws javax.naming.NamingException
Retrieves the JNDI Reference of this object.

Specified by:
getReference in interface javax.naming.Referenceable
Returns:
The non-null Reference of this object.
javax.naming.NamingException

getObjectInstance

public java.lang.Object getObjectInstance(java.lang.Object refObj,
                                          javax.naming.Name name,
                                          javax.naming.Context nameCtx,
                                          java.util.Hashtable env)

getInstance

public static ExternalTransaction getInstance()

ozone API

Copyright (C) The Ozone Database Project - www.ozone-db.org. All rights reserved.