com.sun.jts.CosTransactions

Class TopCoordinator

java.lang.Object

org.omg.PortableServer.Servant

com.sun.jts.codegen.otsidl.JCoordinatorPOA

com.sun.jts.CosTransactions.TopCoordinator

All Implemented Interfaces:

JCoordinator, JCoordinatorOperations, Serializable, Object, IDLEntity, InvokeHandler, org.omg.CosTransactions.Coordinator, org.omg.CosTransactions.CoordinatorOperations

public class TopCoordinator
extends JCoordinatorPOA

The TopCoordinator interface is our implementation of the standard Coordinator interface that is used for top-level transactions. It allows Resources to be registered for participation in a top-level transaction. In addition the TopCoordinator recovery interface can be used if the connection to a superior Coordinator is lost after a transaction is prepared. As an instance of this class may be accessed from multiple threads within a process, serialisation for thread-safety is necessary in the implementation. The information managed should be reconstructible in the case of a failure.

Version:

0.02

Author:

Simon Holdsworth, IBM Corporation

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
Request	_create_request(Context ctx, String operation, NVList arg_list, NamedValue result)
Request	_create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts)
Object	_duplicate()
DomainManager[]	_get_domain_managers()
Object	_get_interface_def()
Policy	_get_policy(int policy_type)
int	_hash(int maximum)
boolean	_is_a(String repository_id)
boolean	_is_equivalent(Object that)
boolean	_non_existent()
void	_release()
Request	_request(String operation)
Object	_set_policy_override(Policy[] policies, SetOverrideType set_add)
org.omg.CosTransactions.Control	create_subtransaction() Creates a subtransaction and returns a Control object that represents the child transaction.
void	doFinalize() Cleans up the objects state.
boolean	equals(Object other) Determines equality of the object with the parameter.
org.omg.CosTransactions.Status	get_parent_status() Gets the local state of the transaction.
org.omg.CosTransactions.Status	get_status() Returns the local status of the target transaction.
org.omg.CosTransactions.Status	get_top_level_status() Gets the local state of the transaction.
String	get_transaction_name() Returns a printable string that represents the TopCoordinator.
org.omg.CosTransactions.PropagationContext	get_txcontext() Creates a PropagationContext which contains the information which would normally be passed implicitly via the CosTSPropagation interfaces.
org.omg.CosTransactions.TransIdentity[]	getAncestors() Returns the sequence of ancestors of the transaction.
GlobalTID	getGlobalTid()
org.omg.CosTransactions.otid_t	getGlobalTID() Returns a global identifier that represents the TopCoordinator's transaction.
long	getLocalTID() Returns the internal identifier for the transaction.
int	getParticipantCount()
int	hash_top_level_tran() Returns a hash value based on the top-level ancestor of the transaction associated with the target object.
int	hash_transaction() Returns a hash value based on the transaction associated with the target object.
int	hashCode() Returns a hash code for the object.
boolean	is_ancestor_transaction(org.omg.CosTransactions.Coordinator other) Determines whether the target TopCoordinator is an ancestor of the given Coordinator.
boolean	is_descendant_transaction(org.omg.CosTransactions.Coordinator other) Determines whether the target TopCoordinator is a descendant of the given Coordinator.
boolean	is_related_transaction(org.omg.CosTransactions.Coordinator other) Determines whether the target TopCoordinator is related to the given Coordinator (i.e.
boolean	is_root_transaction() Determines whether this TopCoordinator is the root TopCoordinator.
boolean	is_same_transaction(org.omg.CosTransactions.Coordinator other) Compares the given Coordinator object with the target, and returns TRUE if they represent the same transaction.
boolean	is_top_level_transaction() Determines whether the target TopCoordinator represents a top-level (non-nested) transaction.
boolean	isRollbackOnly() Checks whether the TopCoordinator is marked rollback-only.
org.omg.CosTransactions.RecoveryCoordinator	register_resource(org.omg.CosTransactions.Resource res) Enables a Resource to be registered as a participant in the completion of the top-level transaction represented by the TopCoordinator.
void	register_subtran_aware(org.omg.CosTransactions.SubtransactionAwareResource sares) Enables a SubtransactionAwareResource to be registered as a participant in the completion of a subtransaction.
void	register_synchronization(org.omg.CosTransactions.Synchronization sync) Informs the TopCoordinator that the given object requires synchronization before and after completion of the transaction.
void	rollback_only() Ensures that the transaction represented by the target TopCoordinator cannot be committed.

Methods inherited from class com.sun.jts.codegen.otsidl.JCoordinatorPOA

_all_interfaces, _invoke, _this, _this

Methods inherited from class org.omg.PortableServer.Servant

_default_POA, _get_delegate, _object_id, _orb, _poa, _set_delegate, _this_object, _this_object

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

doFinalize

public void doFinalize()

Cleans up the objects state.

Parameters:

-

get_status

public org.omg.CosTransactions.Status get_status()

Returns the local status of the target transaction.

Specified by:

get_status in interface org.omg.CosTransactions.CoordinatorOperations

Returns:

The status of the transaction.

get_parent_status

public org.omg.CosTransactions.Status get_parent_status()

Gets the local state of the transaction. For a top-level transaction this operation is equivalent to the get_status method. This operation references no instance variables and so can be implemented locally in the proxy class.

Specified by:

get_parent_status in interface org.omg.CosTransactions.CoordinatorOperations

Returns:

The status of the transaction.

get_top_level_status

public org.omg.CosTransactions.Status get_top_level_status()

Gets the local state of the transaction. For a top-level transaction this operation is equivalent to the get_status method. This operation references no instance variables and so can be implemented locally in a proxy class.

Specified by:

get_top_level_status in interface org.omg.CosTransactions.CoordinatorOperations

Returns:

The status of the transaction.

is_same_transaction

public boolean is_same_transaction(org.omg.CosTransactions.Coordinator other)
                            throws SystemException

Compares the given Coordinator object with the target, and returns TRUE if they represent the same transaction. This operation needs to be implemented in an efficient manner, without any cross-process calls. This could be achieved by including the global identifier in the Coordinator references and comparing them. This operation references no instance variables and so can be implemented locally in a proxy class.

Specified by:

is_same_transaction in interface org.omg.CosTransactions.CoordinatorOperations

Parameters:

other - The other Coordinator to be compared.

Returns:

Indicates equality of the transactions the objects represent.

Throws:

SystemException - The other Coordinator could not be reached.

is_related_transaction

public boolean is_related_transaction(org.omg.CosTransactions.Coordinator other)
                               throws SystemException

Determines whether the target TopCoordinator is related to the given Coordinator (i.e. is a member of the same transaction family). For a top-level transaction returns TRUE if and only if the transaction associated with the parameter object is a descendant of the transaction associated with the target object. This operation references no instance variables and so can be implemented locally in a proxy class.

Specified by:

is_related_transaction in interface org.omg.CosTransactions.CoordinatorOperations

Parameters:

other - The other Coordinator.

Returns:

Indicates the relationship.

Throws:

SystemException - The other Coordinator could not be reached.

is_root_transaction

public boolean is_root_transaction()

Determines whether this TopCoordinator is the root TopCoordinator. the given Coordinator (i.e. is a member of the same transaction family). For a root transaction, this method returns TRUE. Otherwise it returns FALSE.

Returns:

Indicates if this is the root TopCoordinator.

is_ancestor_transaction

public boolean is_ancestor_transaction(org.omg.CosTransactions.Coordinator other)
                                throws SystemException

Determines whether the target TopCoordinator is an ancestor of the given Coordinator. For a top-level transaction returns TRUE if and only if the transaction associated with the target object is an ancestor of the transaction associated with the parameter object. This operation references no instance variables and so can be implemented locally in a proxy class.

Specified by:

is_ancestor_transaction in interface org.omg.CosTransactions.CoordinatorOperations

Parameters:

other - The other Coordinator.

Returns:

Indicates the relationship.

Throws:

SystemException - The other Coordinator could not be reached.

is_descendant_transaction

public boolean is_descendant_transaction(org.omg.CosTransactions.Coordinator other)
                                  throws SystemException

Determines whether the target TopCoordinator is a descendant of the given Coordinator. For a top-level transaction returns TRUE if and only if the transaction associated with the target object is the same as the transaction associated with the parameter object. This operation references no instance variables and so can be implemented locally in a proxy class.

Specified by:

is_descendant_transaction in interface org.omg.CosTransactions.CoordinatorOperations

Parameters:

other - The other Coordinator.

Returns:

Indicates the relationship.

Throws:

SystemException - The other Coordinator could not be reached.

is_top_level_transaction

public boolean is_top_level_transaction()

Determines whether the target TopCoordinator represents a top-level (non-nested) transaction.

For a top-level transaction returns TRUE.

This operation references no instance variables and so can be implemented locally in a proxy class.

Specified by:

is_top_level_transaction in interface org.omg.CosTransactions.CoordinatorOperations

Returns:

Indicates this is a top-level transaction.

hash_transaction

public int hash_transaction()

Returns a hash value based on the transaction associated with the target object. This operation references only the global TID, and so can be implemented locally in a proxy class.

Specified by:

hash_transaction in interface org.omg.CosTransactions.CoordinatorOperations

Returns:

The hash value for the transaction.

hash_top_level_tran

public int hash_top_level_tran()

Returns a hash value based on the top-level ancestor of the transaction associated with the target object. This operation references only the global TID, and so can be implemented locally in a proxy class.

Specified by:

hash_top_level_tran in interface org.omg.CosTransactions.CoordinatorOperations

Returns:

The hash value for the transaction.

register_resource

public org.omg.CosTransactions.RecoveryCoordinator register_resource(org.omg.CosTransactions.Resource res)
                                                              throws org.omg.CosTransactions.Inactive,
                                                                     TRANSACTION_ROLLEDBACK

Enables a Resource to be registered as a participant in the completion of the top-level transaction represented by the TopCoordinator. If the TopCoordinator is a subordinate, and has not registered with its superior, it creates a CoordinatorResource and registers it. The RecoveryCoordinator that is returned is stored in the SuperiorInfo.

Specified by:

register_resource in interface org.omg.CosTransactions.CoordinatorOperations

Parameters:

res - The Resource to be registered.

Returns:

The RecoveryCoordinator object from the registration with the top-level ancestor.

Throws:

org.omg.CosTransactions.Inactive - The Coordinator is completing the transaction and cannot accept this registration.

TRANSACTION_ROLLEDBACK - The transaction which the Coordinator represents has already been rolled back, or has been marked rollback-only.

register_subtran_aware

public void register_subtran_aware(org.omg.CosTransactions.SubtransactionAwareResource sares)
                            throws org.omg.CosTransactions.NotSubtransaction

Enables a SubtransactionAwareResource to be registered as a participant in the completion of a subtransaction. For a top-level transaction this raises the NotSubtransaction exception.

Specified by:

register_subtran_aware in interface org.omg.CosTransactions.CoordinatorOperations

Parameters:

sares - The SubtransactionAwareResource to be registered.

Throws:

org.omg.CosTransactions.NotSubtransaction - The Coordinator represents a top-level transaction and cannot accept the registration.

rollback_only

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

Ensures that the transaction represented by the target TopCoordinator cannot be committed.

Specified by:

rollback_only in interface org.omg.CosTransactions.CoordinatorOperations

Throws:

org.omg.CosTransactions.Inactive - The Coordinator is already completing the transaction.

get_transaction_name

public String get_transaction_name()

Returns a printable string that represents the TopCoordinator. This operation references only the global TID, and so can be implemented locally in a proxy class.

Specified by:

get_transaction_name in interface org.omg.CosTransactions.CoordinatorOperations

Returns:

The transaction name.

create_subtransaction

public org.omg.CosTransactions.Control create_subtransaction()
                                                      throws org.omg.CosTransactions.Inactive

Creates a subtransaction and returns a Control object that represents the child transaction.

Specified by:

create_subtransaction in interface org.omg.CosTransactions.CoordinatorOperations

Returns:

The Control object for the new child transaction.

Throws:

org.omg.CosTransactions.Inactive - The Coordinator is completing the subtransaction and cannot create a new child.

getGlobalTID

public org.omg.CosTransactions.otid_t getGlobalTID()

Returns a global identifier that represents the TopCoordinator's transaction.

This operation references only the global identifier, and so can be implemented locally in a proxy class.

This method is currently not synchronized because that causes a deadlock in resync. I don't think this is a problem as the global identifier is allocated in the constructor and then never changes.

Specified by:

getGlobalTID in interface JCoordinatorOperations

Returns:

The global transaction identifier.

getGlobalTid

public GlobalTID getGlobalTid()

getParticipantCount

public int getParticipantCount()

getLocalTID

public long getLocalTID()

Returns the internal identifier for the transaction. This method is currently not synchronized because that causes a deadlock in resync.

Specified by:

getLocalTID in interface JCoordinatorOperations

Returns:

The local identifier.

isRollbackOnly

public boolean isRollbackOnly()

Checks whether the TopCoordinator is marked rollback-only.

Specified by:

isRollbackOnly in interface JCoordinatorOperations

Returns:

Indicates whether the transaction is rollback-only.

getAncestors

public org.omg.CosTransactions.TransIdentity[] getAncestors()

Returns the sequence of ancestors of the transaction.

Specified by:

getAncestors in interface JCoordinatorOperations

Returns:

The sequence of ancestors.

register_synchronization

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

Informs the TopCoordinator that the given object requires synchronization before and after completion of the transaction. If possible, a CoordinatorSync object is registered with the superior Coordinator. Otherwise this Coordinator becomes the root of a sub-tree for synchronization.

Specified by:

register_synchronization in interface org.omg.CosTransactions.CoordinatorOperations

Parameters:

sync - The Synchronization object to be registered.

Throws:

org.omg.CosTransactions.Inactive - The Coordinator is in the process of completing the transaction and cannot accept this registration.

org.omg.CosTransactions.SynchronizationUnavailable - The transaction service cannot support synchronization.

SystemException - The operation failed.

get_txcontext

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

Creates a PropagationContext which contains the information which would normally be passed implicitly via the CosTSPropagation interfaces.

Specified by:

get_txcontext in interface org.omg.CosTransactions.CoordinatorOperations

Returns:

The transaction context.

Throws:

org.omg.CosTransactions.Unavailable - The Coordinator is in the process of completing the transaction and cannot return the information.

hashCode

public int hashCode()

Returns a hash code for the object.

This very basic method is used by the trace facility and should not call any method which is traced.

Overrides:

hashCode in class Object

Returns:

The hash code for the object.

equals

public boolean equals(Object other)

Determines equality of the object with the parameter.

Overrides:

equals in class Object

Parameters:

other - The other object.

Returns:

Indicates equality.

_duplicate

public Object _duplicate()

Specified by:

_duplicate in interface Object

_release

public void _release()

Specified by:

_release in interface Object

_is_a

public boolean _is_a(String repository_id)

Specified by:

_is_a in interface Object

Overrides:

_is_a in class Servant

_is_equivalent

public boolean _is_equivalent(Object that)

Specified by:

_is_equivalent in interface Object

_non_existent

public boolean _non_existent()

Specified by:

_non_existent in interface Object

Overrides:

_non_existent in class Servant

_hash

public int _hash(int maximum)

Specified by:

_hash in interface Object

_request

public Request _request(String operation)

Specified by:

_request in interface Object

_create_request

public Request _create_request(Context ctx,
                               String operation,
                               NVList arg_list,
                               NamedValue result)

Specified by:

_create_request in interface Object

_create_request

public Request _create_request(Context ctx,
                               String operation,
                               NVList arg_list,
                               NamedValue result,
                               ExceptionList exceptions,
                               ContextList contexts)

Specified by:

_create_request in interface Object

_get_interface_def

public Object _get_interface_def()

Specified by:

_get_interface_def in interface Object

Overrides:

_get_interface_def in class Servant

_get_policy

public Policy _get_policy(int policy_type)

Specified by:

_get_policy in interface Object

_get_domain_managers

public DomainManager[] _get_domain_managers()

Specified by:

_get_domain_managers in interface Object

_set_policy_override

public Object _set_policy_override(Policy[] policies,
                                   SetOverrideType set_add)

Specified by:

_set_policy_override in interface Object