CosTransactions
Interface Coordinator

        
interface Coordinator

The Coordinator class enables explicit control of a factory-created transaction; the factory creates a transaction and returns a Control instance associated with the transaction. Control::get_coordinator() returns the Coordinator object used to manage the transaction.

The operations defined by the Coordinator class can be used by the participants in a transaction to determine the status of the transaction, determine the relationship of the transaction to other transactions, mark the transaction for rollback, and create subtransactions.

The Coordinator class also defines operations for registering resources as participants in a transaction and registering subtransaction-aware resources with a subtransaction.

package org.omg.CosTransactions;

public interface Coordinator
    extends CoordinatorOperations,
    org.omg.CORBA.Object,
    org.omg.CORBA.portable.IDLEntity
{
}

The Coordinator class extends CoordinatorOperations:

public interface CoordinatorOperations

{
     org.omg.CosTransactions.Status get_status();

     org.omg.CosTransactions.Status get_parent_status();

     org.omg.CosTransactions.Status get_top_level_status();

     boolean is_same_transaction(
        org.omg.CosTransactions.Coordinator tc
    );

     boolean is_related_transaction(
        org.omg.CosTransactions.Coordinator tc
    );

     boolean is_ancestor_transaction(
        org.omg.CosTransactions.Coordinator tc
    );

     boolean is_descendant_transaction(
        org.omg.CosTransactions.Coordinator tc
    );

     boolean is_top_level_transaction();

     int hash_transaction();

     int hash_top_level_tran();

     org.omg.CosTransactions.RecoveryCoordinator register_resource(
        org.omg.CosTransactions.Resource r
    ) throws org.omg.CosTransactions.Inactive;

     void register_synchronization(
        org.omg.CosTransactions.Synchronization sync
    ) throws org.omg.CosTransactions.Inactive, org.omg.CosTransactions.SynchronizationUnavailable;

     void register_subtran_aware(
        org.omg.CosTransactions.SubtransactionAwareResource r
    ) throws org.omg.CosTransactions.Inactive, org.omg.CosTransactions.NotSubtransaction;

     void rollback_only() throws org.omg.CosTransactions.Inactive;

     java.lang.String get_transaction_name();

     org.omg.CosTransactions.Control create_subtransaction() throws org.omg.CosTransactions.SubtransactionsUnavailable, org.omg.CosTransactions.Inactive;

     org.omg.CosTransactions.PropagationContext get_txcontext() throws org.omg.CosTransactions.Unavailable;

}

See also:

CosTransactions::Control

CosTransactions::Control::get_coordinator()
CosTransactions::Terminator

get_status

CosTransactions::Status get_status()

// Java
public org.omg.CosTransactions.Status get_status(
)
throws org.omg.CORBA.SystemException                

get_status() returns the status of the transaction associated with the Coordinator object. The status returned indicates which phase of processing the transaction is in. See the reference page for the Status type for information about the possible status values.

See also:

CosTransactions::Coordinator::get_parent_status() 

CosTransactions::Coordinator::get_top_level_status() 
CosTransactions::Status

get_parent_status

CosTransactions::Status get_parent_status()

// Java
public org.omg.CosTransactions.Status get_parent_status(
)
throws org.omg.CORBA.SystemException                

get_parent_status() returns the status of the parent of the transaction associated with the Coordinator object. For more information, see create_subtransaction().

The status returned indicates which phase of processing the transaction is in. See the reference page for the Status type for information about the possible status values. If the transaction associated with the Coordinator object is a subtransaction, the status of its parent transaction is returned. If there is no parent transaction, the status of the transaction associated with the Coordinator object itself is returned.

See also:

CosTransactions::Coordinator::create_subtransaction() 

CosTransactions::Coordinator::get_status() 
CosTransactions::Coordinator::get_top_level_status() 
CosTransactions::Status  

get_top_level_status

CosTransactions::Status get_top_level_status()

// Java
public org.omg.CosTransactions.Status get_top_level_status(
)
throws org.omg.CORBA.SystemException                

get_top_level_status() returns the status of the top-level ancestor of the transaction associated with the Coordinator object. See Coordinator::create_subtransaction() for more information.

The status returned indicates which phase of processing the transaction is in. See the reference page for the Status type for information about the possible status values. If the transaction associated with the Coordinator object is the top-level transaction, its status is returned.

See also:

CosTransactions::Coordinator::create_subtransaction() 

CosTransactions::Coordinator::get_status() 
CosTransactions::Coordinator::get_parent_status() 
CosTransactions::Status  

is_same_transaction

boolean is_same_transaction(
    in CosTransactions::Coordinator tc
)

// Java
public boolean is_same_transaction(
         org.omg.CosTransactions.Coordinator tc
)
throws org.omg.CORBA.SystemException                

is_same_transaction() returns true if the transactions associated with the two Coordinator objects are the same transaction; otherwise, the method returns false.

tc	Specifies the coordinator of another transaction to compare with the Coordinator object.

is_same_transaction() determines whether the transaction associated with the Coordinator object and the transaction associated with the coordinator specified in the tc parameter are the same transaction.

See also:

CosTransactions::Coordinator::is_descendant_transaction() 

CosTransactions::Coordinator::is_related_transaction() 
CosTransactions::Coordinator::is_ancestor_transaction() 
CosTransactions::Coordinator::is_top_level_transaction() 

is_related_transaction

boolean is_related_transaction(
    in CosTransactions::Coordinator tc
)

// Java
public boolean is_related_transaction(
         org.omg.CosTransactions.Coordinator tc
)
throws org.omg.CORBA.SystemException                

is_related_transaction() returns true if both transactions are descendants of the same transaction; otherwise, the method returns false.

tc	Specifies the coordinator of another transaction to compare with the Coordinator object.

is_related_transaction() determines whether the transaction associated with the Coordinator object and the transaction associated with the coordinator specified in the tc parameter have a common ancestor. See create_subtransaction() for more information.

See also:

CosTransactions::Coordinator::is_descendant_transaction() 

CosTransactions::Coordinator::is_ancestor_transaction() 
CosTransactions::Coordinator::is_same_transaction() 
CosTransactions::Coordinator::is_top_level_transaction() 
CosTransactions::Coordinator::create_subtransaction() 

is_ancestor_transaction

boolean is_ancestor_transaction(
    in CosTransactions::Coordinator tc
)

// Java
public boolean is_ancestor_transaction(
         org.omg.CosTransactions.Coordinator tc
)
throws org.omg.CORBA.SystemException                

is_ancestor_transaction() returns true if the transaction is an ancestor or if the two transactions are the same; otherwise, the method returns false.

tc	Specifies the coordinator of another transaction to compare with the Coordinator object.

is_ancestor_transaction() determines whether the transaction associated with the Coordinator object is an ancestor of the transaction associated with the coordinator specified in the tc parameter. See create_subtransaction() for more information.

See also:

CosTransactions::Coordinator::is_descendant_transaction() 

CosTransactions::Coordinator::is_related_transaction() 
CosTransactions::Coordinator::is_same_transaction() 
CosTransactions::Coordinator::create_subtransaction() 

is_descendant_transaction

boolean is_descendant_transaction(
    in CosTransactions::Coordinator tc
)

// Java
public boolean is_descendant_transaction(
         org.omg.CosTransactions.Coordinator tc
)
throws org.omg.CORBA.SystemException                

is_descendant_transaction() returns true if the transaction is a descendant or if the two transactions are the same; otherwise, the method returns false.

tc	Specifies the coordinator of another transaction to compare with the Coordinator object.

is_descendant_transaction() determines whether the transaction associated with the Coordinator object is a descendant of the transaction associated with the coordinator specified in the tc parameter. See Coordinator::create_subtransaction() for more information.

See also:

CosTransactions::Coordinator::is_descendant_transaction() 

CosTransactions::Coordinator::is_related_transaction() 
CosTransactions::Coordinator::is_same_transaction() 
CosTransactions::Coordinator::is_top_level_transaction() 
CosTransactions::Coordinator::create_subtransaction() 

is_top_level_transaction

boolean is_top_level_transaction()

// Java
public boolean is_top_level_transaction(
)
throws org.omg.CORBA.SystemException                

is_top_level_transaction() returns true if the transaction is a top-level transaction; otherwise, the method returns false. is_top_level_transaction() determines whether the transaction associated with a Coordinator object is a top-level transaction. See create_subtransaction() for more information.

See also:

CosTransactions::Coordinator::is_descendant_transaction() 

CosTransactions::Coordinator::is_related_transaction() 
CosTransactions::Coordinator::is_same_transaction() 
CosTransactions::Coordinator::is_ancestor_transaction() 
CosTransactions::Coordinator::create_subtransaction() 

hash_transaction

unsigned long hash_transaction()

// Java
public int hash_transaction(
)
throws org.omg.CORBA.SystemException                

hash_transaction() returns a hash code for the transaction associated with the Coordinator object.

See also:

CosTransactions::Coordinator::hash_top_level_tran() 

hash_top_level_tran

unsigned long hash_top_level_tran()

// Java
public int hash_top_level_tran(
)
throws org.omg.CORBA.SystemException                

hash_top_level_tran() returns a hash code for the top-level ancestor of the transaction associated with the Coordinator object. If the transaction associated with the Coordinator object is the top-level transaction, its hash code is returned. See create_subtransaction() for more information. The returned hash code is typically used as an index into a table of Coordinator objects. The low-order bits of the hash code can be used to hash into a table with a size that is a power of two.

See also:

CosTransactions::Coordinator::create_subtransaction() 

CosTransactions::Coordinator::hash_transaction() 

register_resource

CosTransactions::RecoveryCoordinator register_resource(
    in CosTransactions::Resource r
)
raises(
    CosTransactions::Inactive
)

// Java
public org.omg.CosTransactions.RecoveryCoordinator register_resource(
         org.omg.CosTransactions.Resource r
)
throws org.omg.CORBA.SystemException,
 org.omg.CosTransactions.Inactive                

register_resource() registers a specified resource as a participant in the transaction associated with a Coordinator object. When the transaction ends, the registered resource must commit or roll back changes made as part of the transaction. Only server applications can register resources. See Resource class for more information. register_resource() returns a RecoveryCoordinator object that the registered Resource object can use during recovery.

resource

The resource to register as a participant.

CORBA::TRANSACTION_ROLLEDBACK

The transaction is marked for rollback only.

See also:

CosTransactions::RecoveryCoordinator

CosTransactions::Resource

register_synchronization

void register_synchronization(
    in CosTransactions::Synchronization sync
)
raises(
    CosTransactions::Inactive,
    CosTransactions::SynchronizationUnavailable
)

// Java
public void register_synchronization(
         org.omg.CosTransactions.Synchronization sync
)
throws org.omg.CORBA.SystemException,
 org.omg.CosTransactions.Inactive,
 org.omg.CosTransactions.SynchronizationUnavailable                

register_synchronization() registers a specified synchronization object for the transaction associated with a Coordinator object. See the reference page for the Synchronization class for more information.

sync	The synchronization object to register.

Inactive	The transaction is already prepared.
CORBA::TRANSACTION_ROLLEDBACK	The transaction is marked for rollback only.

See also:

CosTransactions::RecoveryCoordinator  

CosTransactions::Synchronization  

register_subtran_aware

void register_subtran_aware(
    in CosTransactions::SubtransactionAwareResource r
)
raises(
    CosTransactions::Inactive,
    CosTransactions::NotSubtransaction
)

// Java
public void register_subtran_aware(
         org.omg.CosTransactions.SubtransactionAwareResource r
)
throws org.omg.CORBA.SystemException,
 org.omg.CosTransactions.Inactive,
 org.omg.CosTransactions.NotSubtransaction                

register_subtran_aware() registers a specified resource with the subtransaction associated with a Coordinator object. The resource is registered with the subtransaction only, not as a participant in the top-level transaction. (register_resource() can be used to register the resource as a participant in the top-level transaction.) Only server applications can register resources.

resource

The resource to register.

When the transaction ends, the registered resource must commit or roll back changes made as part of the subtransaction. See the reference page for the SubtransactionAwareResource class for more information.

NotSubtransaction	The transaction associated with the Coordinator object is not a subtransaction
Inactive	The subtransaction or any ancestor of the subtransaction has ended.
CORBA::TRANSACTION_ROLLEDBACK	The transaction is marked for rollback only.

See also:

CosTransactions::RecoveryCoordinator  

CosTransactions::SubtransactionAwareResource  

rollback_only

void rollback_only()
raises(
    CosTransactions::Inactive
)

// Java
public void rollback_only(
)
throws org.omg.CORBA.SystemException,
 org.omg.CosTransactions.Inactive                

rollback_only() marks the transaction associated with the Coordinator object so that the only possible outcome for the transaction is to roll back. The transaction is not rolled back until the participant that created the transaction either commits or aborts the transaction.

OTS allows Terminator::rollback() to be called instead of rollback_only(). Calling Terminator::rollback() rolls back the transaction immediately, preventing unnecessary work from being done between the time the transaction is marked for rollback and the time the transaction is actually rolled back.

Inactive

The transaction is already prepared.

See also:

CosTransactions::Terminator::rollback() 

get_transaction_name

string get_transaction_name()

// Java
public java.lang.String get_transaction_name(
)
throws org.omg.CORBA.SystemException                

get_transaction_name() returns the name of the transaction associated with the Coordinator object.

create_subtransaction

CosTransactions::Control create_subtransaction()
raises(
    CosTransactions::SubtransactionsUnavailable,
    CosTransactions::Inactive
)

// Java
public org.omg.CosTransactions.Control create_subtransaction(
)
throws org.omg.CORBA.SystemException,
 org.omg.CosTransactions.SubtransactionsUnavailable,
 org.omg.CosTransactions.Inactive                

create_subtransaction() returns the Control object associated with the new subtransaction.

create_subtransaction() creates a new subtransaction for the transaction associated with the Coordinator object. A subtransaction is one that is embedded within another transaction; the transaction within which the subtransaction is embedded is referred to as its parent. A transaction that has no parent is a top-level transaction. A subtransaction executes within the scope of its parent transaction and can be used to isolate failures; if a subtransaction fails, only the subtransaction is rolled back. If a subtransaction commits, the effects of the commit are not permanent until the parent transaction commits. If the parent transaction rolls back, the subtransaction is also rolled back.

SubtransactionsUnavailable	Subtransactions are not supported.
Inactive	The transaction is already prepared.

See also:

CosTransactions::Control 

get_txcontext

CosTransactions::PropagationContext get_txcontext()
raises(
    CosTransactions::Unavailable
)

// Java
public org.omg.CosTransactions.PropagationContext get_txcontext(
)
throws org.omg.CORBA.SystemException,
 org.omg.CosTransactions.Unavailable                

Returns the propagation context object which is used to export the current transaction to a new transaction service domain.

Unavailable

The propagation context is unavailable.

See also:

CosTransactions::TransactionFactory::recreate()