org.omg.CosTransactions
Interface Current

All Known Subinterfaces:

TransactionCurrent

public interface Current

extends org.omg.CORBA.Object, org.omg.CORBA.portable.IDLEntity

The Current interface defines methods that allow a client of the Transaction Service to explicitly manage the association between threads and transactions. This interface also defines methods that simplify the use of the Transaction Service for most applications. These methods can be used to demarcate transactions, to suspend/resume transactions, and to obtain information about the current transaction.

Method Summary

void	begin() Creates a new transaction.
void	commit(boolean report_heuristics) Completes the current transaction.
Control	get_control() If the client is associated with a transaction, a Control object is returned that represents the transaction context currently associated with the client thread.
Status	get_status() If there is a transaction associated with the client thread, this method returns the status of the transaction associated with the client thread.
java.lang.String	get_transaction_name() If there is a transaction associated with the client thread, this method returns a printable string describing the transaction (specifically the XID as specified by the Open Group).
void	resume(Control which) If the parameter is a valid object reference in the current execution environment, the client thread becomes associated with that transaction (in place of any previous transaction).
void	rollback_only() If there is a transaction associated with the client thread, it is modified so that the only possible outcome is to roll back the transaction.
void	rollback() Rolls back the current transaction.
void	set_timeout(int seconds) This method modifies a state variable associated with the target object that affects the time-out period associated with transactions created by subsequent invocations of the begin method.
Control	suspend() If in a proper context with a transaction not marked ROLLEDBACK, an object is returned that represents the transaction context currently associated with the client thread.

Methods inherited from interface org.omg.CORBA.Object

_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Method Detail

begin

public void begin()
           throws SubtransactionsUnavailable

Creates a new transaction. The transaction context of the client thread is modified so that the thread is associated with the new transaction.

If the client thread is currently associated with a transaction, the SubtransactionsUnavailable exception is raised.

If the client thread cannot be placed in transaction mode due to an error while starting the transaction, the org.omg.CORBA.INVALID_TRANSACTION standard system exception is raised.

If the call was made in an improper context, the org.omg.CORBA.BAD_INV_ORDER standard system exception is raised.

commit

public void commit(boolean report_heuristics)
            throws NoTransaction,
                   HeuristicMixed,
                   HeuristicHazard

Completes the current transaction. If the operation completes normally, the thread's transaction context is set to null. If there is no transaction associated with the client thread, the org.omg.CosTransactions.NoTransaction exception is raised.

If the call was made in an improper context, the standard system exception org.omg.CORBA.BAD_INV_ORDER is raised.

If the system decides to roll back the transaction, the standard system exception org.omg.CORBA.TRANSACTION_ROLLEDBACK is raised and the thread's transaction context is set to null.

An org.omg.CosTransactions.HeuristicMixed exception is raised to report that a heuristic decision was made and that some relevant updates have been committed and others have been rolled back. A HeuristicHazard exception is raised to report that a heuristic decision was made, and the disposition of all relevant updates is not known. For those updates whose disposition is known, either all have been committed or all have been rolled back. The HeuristicMixed exception takes priority over the HeuristicHazard exception. If a heuristic exception is raised or the operation completes normally, the thread's transaction context is set to null.

rollback

public void rollback()
              throws NoTransaction

Rolls back the current transaction. A return from the rollback method on the Current object is asynchronous. A consequence of this is that the objects that were infected by the rolled back transaction get their states cleared by the M3 TP Framework a little later. This implies that no other client can infect these objects with a different transaction until the M3 TP Framework clears the states of these objects. This race condition exists for a very short amount of time and is typically not noticeable in a full-fledged application. A simple workaround for this race condition is to try the appropriate operation after a short (typically a 1-second) delay.

If there is no transaction associated with the client thread, the org.omg.CosTransactions.NoTransaction exception is raised.

If the call was made in an improper context, the standard system exception org.omg.CORBA.BAD_INV_ORDER is raised.

If the operation completes normally, the thread's transaction context is set to null.

rollback_only

public void rollback_only()
                   throws NoTransaction

If there is a transaction associated with the client thread, it is modified so that the only possible outcome is to roll back the transaction. Otherwise, the NoTransaction exception is raised.

get_status

public Status get_status()

If there is a transaction associated with the client thread, this method returns the status of the transaction associated with the client thread. Otherwise, the StatusNoTransaction value is returned.

get_transaction_name

public java.lang.String get_transaction_name()

If there is a transaction associated with the client thread, this method returns a printable string describing the transaction (specifically the XID as specified by the Open Group). Otherwise, an empty string is returned. The returned string is intended to support debugging.

set_timeout

public void set_timeout(int seconds)

This method modifies a state variable associated with the target object that affects the time-out period associated with transactions created by subsequent invocations of the begin method. If the parameter has a nonzero value n, transactions created by subsequent invocation of begin will be subject to being rolled back if they do not complete before n seconds after their creation. If the parameter is zero, no application-specified time-out is established.

If the time-out period is not defined, the M3 system uses a default value, which is specified in the UBBCONFIG file. For more information, see the description of the TIMEOUT parameter in the Administration Guide.

Note: The initial transaction timeout value is 300 seconds. If a transaction is started via AUTOTRAN instead of via the begin method, the timeout value is determined by the TRANTIME value in the M3 configuration file. For more information, refer to Chapter 7 of the Administration Guide.

get_control

public Control get_control()

If the client is associated with a transaction, a Control object is returned that represents the transaction context currently associated with the client thread. This object may be given to the resume method to reestablish this context. If the client is not associated with a transaction, a null object reference is returned.

suspend

public Control suspend()

If in a proper context with a transaction not marked ROLLEDBACK, an object is returned that represents the transaction context currently associated with the client thread. The same client can subsequently give this object to the resume method to reestablish this context. In addition, the client thread becomes associated with no transaction. If the client thread is not associated with a transaction, a null object reference is returned.

If the associated transaction is in a state such that the only possible outcome of the transaction is to be rolled back, the org.omg.CORBA.TRANSACTION_ROLLEDBACK standard system exception is raised and the client thread becomes associated with no transaction.

If the call was made in an improper context, the standard system exception org.omg.CORBA.BAD_INV_ORDER is raised. The caller's state with respect to the transaction is not changed.

Note: As defined in The Common Object Request Broker: Architecture and Specification, Revision 2.2, February 1998, the org.omg.CORBA.TRANSACTION_ROLLEDBACK standard system exception indicates that the transaction associated with the request has already been rolled back or has been marked to roll back. Thus, the requested method either could not be performed or was not performed because further computation on behalf of the transaction would be fruitless.

resume

public void resume(Control which)
            throws InvalidControl

If the parameter is a valid object reference in the current execution environment, the client thread becomes associated with that transaction (in place of any previous transaction). If the client thread is already associated with a transaction that is in a state such that the only possible outcome of the transaction is to be rolled back, the org.omg.CORBA.TRANSACTION_ROLLEDBACK standard system exception is raised and the client thread becomes associated with no transaction. If the parameter is not valid, the org.omg.CosTransactions.InvalidControl exception is raised.

If the call was made in an improper context, the standard system exception org.omg.CORBA.BAD_INV_ORDER is raised.

If the system is unable to resume the global transaction because the caller is currently participating in work outside any global transaction with one or more resource managers, the org.omg.CORBA.INVALID_TRANSACTION standard system exception is raised.

Note: See suspend for a definition of the org.omg.CORBA.TRANSACTION_ROLLEDBACK standard system exception.