This section introduces the CosTransactions and
VisTransactions modules, and describes the data types, structures, and exceptions for the
CosTransactions module.
The CosTransactions module is the Transaction Service IDL that conforms to the final OMG Transaction Service document. This is the module to use to restrict yourself strictly to CORBA-compliant methods. The IDL for this module is contained in the file
CosTransactions.idl.
You might also consider using the VISTransactions module, which contains the IDL for some VisiBroker VisiTransact extensions to the standard. The IDL for the
VISTransactions module is contained in the file
VISTransactions.idl. You can use
VISTransactions.idl in your code to obtain both the
CosTransactions and
VISTransactions modules. For more information, see
“Looking at the VISTransactions module” on page 154.
The CosTransactions module defines the data types
enum Status and
enum Vote.
The definition for the enum Status data type is:
The enum Vote data type is used only by implementations of the
CosTransactions::Resource interface. It is used to indicate the result of a Resource's attempt to prepare a transaction.
The definition for the enum Vote data type is:
|
•
|
VoteCommit. The Resource is able to write (or has already written) all the data needed to commit the transaction to stable storage, as well as an indication that it has prepared the transaction.
|
|
•
|
VoteRollback. For any reason, the Resource could not vote to commit the transaction. This includes not having any knowledge about the transaction (which might happen after a crash).
|
|
•
|
VoteReadOnly. No persistent data associated with the Resource has been modified by the transaction.
|
The CosTransactions module defines these structures, which are used to save the transaction context.
|
•
|
otid_t contains an object transaction ID (or otid), which is a globally unique ID for a transaction. The otid_t structure is a more efficient OMG IDL version of the X/Open-defined transaction identifier (XID). The otid_t can be transformed to an X/Open XID and vice versa.
|
|
•
|
TransIdentity contains certain key information for a transaction: its Coordinator, its Terminator (optionally), and its otid.
|
|
•
|
PropagationContext contains a transaction's TransIdentity and its time-out. In addition, it contains a TransIdentity for the parent and each ancestor transaction, up to the top-level transaction, formatted as a sequence (or array). Because nested transactions are not implemented in VisiTransact, every transaction is a top-level transaction, and the parents sequence will always be empty.
|
When the transaction context is passed from one object to another object, usually a TransactionalObject, it is commonly passed as a
PropagationContext. The
implementation_specific_data field is reserved for the VisiTransact Transaction Service.
Another method that obtains information from these structures is the VISTransactions::Current::get_otid() method, which extracts the
otid from the
PropagationContext.
|
|
|
|
|
|
|
|
The Control parameter passed to resume is not valid in the current execution environment.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Interfaces in the VISTransactions module inherit from and extend the
CosTransactions interfaces. The
VISTransactions module defines no new data types, structures, or exceptions over those in
CosTransactions. For example, the
Current interface includes VisiBroker VisiTransact methods that make certain programming operations shorter and more convenient. The IDL for this module is contained in the file
VISTransactions.idl.
The Current interface defines methods to:
|
•
|
CosTransactions.idl contains the Transaction Service IDL that conforms to the final OMG Transaction Service document.
|
|
•
|
VISTransactions.idl provides both the CosTransactions interface and the VISTransactions interface, which inherits and extends the CosTransactions::Current interface. This interface includes VisiBroker VisiTransact extensions such as begin_with_name(), register_resource(), and others.
|
The following example shows the CosTransactions interface for
Current.
...
interface Current
{
void begin()
raises(SubtransactionsUnavailable);
void
commit(in boolean report_heuristics)
raises (NoTransaction,
HeuristicMixed,
HeuristicHazard);
void
rollback()
raises(NoTransaction);
void
rollback_only()
raises(NoTransaction);
Status
get_status();
string
get_transaction_name();
void
set_timeout(in unsigned long seconds);
Control
get_control();
Control
suspend();
void
resume(in Control which)
raises(InvalidControl);
};
...
The next example shows the VISTransactions interface for
Current.
interface Current : CosTransactions::Current
{
void begin_with_name(in string user_transaction_name)
raises(CosTransactions::SubtransactionsUnavailable);
CosTransactions::RecoveryCoordinator
register_resource(in CosTransactions::Resource resource)
raises(CosTransactions::Inactive);
void
register_synchronization(in CosTransactions::Synchronization synch)
raises(CosTransactions::NoTransaction,
CosTransactions::Inactive,
CosTransactions::SynchronizationUnavailable
CosTransactions::Unavailable);
CosTransactions::otid_t get_otid();
raises(CosTransactions::NoTransaction,
CosTransactions::Unavailable);
CosTransactions::PropagationContext get_txcontext()
raises(CosTransactions::Unavailable,
CosTransactions::NoTransaction);
attribute string
ots_name;
attribute string
ots_host;
attribute string
ots_factory;
};
The example below shows how a reference to the Current object is obtained using the resolve_initial_references() method, and then how the object returned by that method is narrowed to a
CosTransactions::Current object.
VisiBroker VisiTransact offers extensions to the Current interface to simplify certain operations. To take advantage of these extensions, narrow to a
VISTransactions::Current object.
|
•
|
For VISTransactions, use #include <VISTransactions_c.hh>.
|
|
•
|
For CosTransactions, use #include <CosTransactions_c.hh>.
|
You can issue begin() or
begin_with_name() to determine if the instance of your VisiTransact Transaction Service is available. The method will raise
CORBA:NO_IMPLEMENT exception if the instance is not available.
Calling get_status() when there is no available instance of the VisiTransact Transaction Service will return the current transaction state, and cannot be used to determine if the instance of the VisiTransact Transaction Service is available.
Checked behavior is supported by the VisiTransact Transaction Service to provide an extra level of transaction integrity. Specifically, checked behavior is supported for transactions originated with Current::begin(). The purpose of the checks is to ensure that all transactional requests made by the application have completed their processing before the transaction is committed. This guarantees that a commit will not succeed unless all transactional objects involved in the transaction have completed the processing of their transactional requests. For checks that are part of the commit process, see
“commit()” on page 158. For more information about checked behavior, see the VisiBroker
VisiTransact Guide.
void begin()
raises SubtransactionsUnavailable;
This method creates a new transaction. Because nested transactions are not supported in VisiBroker VisiTransact, this is always a top-level transaction.
Included in the Current interface in
CosTransactions.idl
For more information, see the VisiBroker VisiTransact Guide.
void begin_with_name(in string user_transaction_name)
raises(CosTransactions::SubtransactionsUnavailable);
This VisiBroker VisiTransact method is a begin() method that enables its caller to pass a user-defined informational transaction name. For example, this helps with diagnostics because the user-defined transaction name is included in the value returned by the
get_transaction_name() method. The name also helps with administration, because the Console will report the name in the detailed information about an outstanding transaction.
Included in the Current interface in
VISTransactions.idl
void commit(in boolean report_heuristics)
raises(NoTransaction,
HeuristicMixed,
HeuristicHazard
);
If this transaction has been marked for rollback, or any Resource votes for rollback, this call raises CORBA::TRANSACTION_ROLLEDBACK. If there is no current transaction, a
CosTransactions::NoTransaction exception is raised. If the caller is not the transaction originator,
commit() raises the exception
CORBA::NO_PERMISSION.
On return from this method, the client thread is no longer associated with a transaction. Any attempt to use Current, as if there were a transaction, will raise an exception, such as
NoTransaction or
CORBA::TRANSACTION_REQUIRED, or will return a null object reference.
Included in the Current interface in
CosTransactions.idl
|
|
|
|
|
|
|
|
A heuristic decision was made and report_heuristics is true. Some relevant updates have been committed and others have been rolled back.
|
|
|
A heuristic decision may have been made and report_heuristics is true. 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. If the known updates are a mixture of commits and rollbacks, then the HeuristicMixed exception is raised.
|
|
|
|
|
|
|
|
|
|
See the VisiBroker VisiTransact Guide for details on checked behavior and the implications of using this method.
Included in the Current interface in
CosTransactions.idl.
This VISTransactions::Current method provides the object transaction ID (
otid) through the
Current interface as a convenience. This avoids going to the Coordinator and looking through a
PropagationContext. The
otid is used to identify a transaction to a recoverable object. This method raises
CosTransactions::NoTransaction if no transaction is associated with the client thread.
Included in the Current interface in
VISTransactions.idl.
This method returns an enumerated value (enum Status) that represents the status of the transaction associated with the client thread.
Calling this method is equivalent to calling the get_status() method on the corresponding Coordinator object. If there is no transaction associated with the current thread, then the method returns
CosTransactions::StatusNoTransaction.
Included in the Current interface in
CosTransactions.idl.
Some implications of the enum Status values are:
|
•
|
StatusActive: A transaction is associated with the target object and it is in the active state. The VisiTransact Transaction Service returns this status after a transaction has been started and prior to a Coordinator issuing any prepare statements, unless the transaction has been marked for rollback or timed out.
|
|
•
|
StatusMarkedRollback: A transaction is associated with the target object and has been marked for rollback, perhaps as the result of the rollback_only() method.
|
|
•
|
StatusPrepared: A transaction is associated with the target object and has been prepared.
|
|
•
|
StatusCommitted: A transaction is associated with the target object and has been committed. It is likely that heuristics exist, otherwise the transaction would have been quickly destroyed and StatusNoTransaction returned.
|
|
•
|
StatusRolledBack: A transaction is associated with the target object and the outcome has been determined as rollback. It is likely that heuristics exist, otherwise the transaction would have been quickly destroyed and StatusNoTransaction returned.
|
|
•
|
StatusUnknown: A transaction is associated with the target object, but the VisiTransact Transaction Service cannot determine its current status. This is a transient condition, and a subsequent invocation will ultimately return a different status.
|
|
•
|
StatusNoTransaction: No transaction is currently associated with the target object. This will occur after a transaction has completed.
|
|
•
|
StatusPreparing: A transaction is associated with the target object and it is in the process of preparing. The VisiTransact Transaction Service returns this status if the transaction has started preparing, but has not yet completed the process, perhaps because it is waiting for responses to prepare from one or more Resources.
|
|
•
|
StatusCommitting: A transaction is associated with the target object and is in the process of committing. The VisiTransact Transaction Service returns this status if the transaction has begun to commit, but has not yet completed the process, perhaps because it is waiting for responses from one or more Resources.
|
|
•
|
StatusRollingBack: A transaction is associated with the target object and it is in the process of rolling back. The VisiTransact Transaction Service returns this status if the transaction is being rolled back, but has not yet completed the process, perhaps because it is waiting for responses from one or more Resources.
|
string get_transaction_name();
The effect of this method is equivalent to calling the get_transaction_name() method on the corresponding Coordinator object. If there is no transaction associated with the client thread, an empty string is returned.
Included in the Current interface in
CosTransactions.idl.
This VISTransactions::Current method returns a
PropagationContext, which can be used by one VisiTransact Transaction Service domain to export a transaction to a new VisiTransact Transaction Service domain.
Included in the Current interface in
VISTransactions.idl.
If you are using VISTransactions.idl, you can control the instance of the VisiTransact Transaction Service used to create a transaction by setting this attribute before you call
VISTransactions::Current::begin(). Subsequent calls to the
begin() method create transactions on the specified VisiTransact Transaction Service. This attribute applies to all the threads in your program. When the attribute is set, it retains its value until set again.
This attribute specifies the VisiTransact Transaction Service instance by IOR. VisiTransact uses the specified IOR (CosTransactions::TransactionFactory) to locate the desired instance of a VisiTransact Transaction Service instance on the network. This argument enables VisiTransact to operate without the use of a Smart Agent (
osagent).
Included in the Current interface in
VISTransactions.idl.
If you are using VISTransactions.idl, you can control the instance of the VisiTransact Transaction Service used to create a transaction by setting this attribute before you call
VISTransactions::Current::begin(). Subsequent calls to the
begin() method create transactions on the specified VisiTransact Transaction Service. This attribute applies to all the threads in your program. When the attribute is set, it retains its value until set again. To return this attribute to the default VisiTransact instance, set it to an empty or null string.
Included in the Current interface in
VISTransactions.idl.
If you are using VISTransactions.idl, you can control the instance of the VisiTransact Transaction Service used to create a transaction by setting this attribute before you call
VISTransactions::Current::begin(). Subsequent calls to the
begin() method create transactions on the specified VisiTransact Transaction Service. This attribute applies to all the threads in your program. When the attribute is set, it retains its value until set again. To return this attribute to the default VisiTransact instance, set it to an empty or null string.
Included in the Current interface in
VISTransactions.idl.
This VISTransactions::Current method registers a Resource for a recoverable object. This method is a shortcut for using the Control and Coordinator objects to register a Resource for a recoverable object. It returns a Recovery Coordinator object that can be used to help coordinate recovery. If this method is invoked when there is no transaction associated with the client thread, the
CORBA::TRANSACTION_REQUIRED exception is thrown.
Included in the Current interface in
VISTransactions.idl.
void register_synchronization(in CosTransactions::Synchronization synch)
raises(CosTransactions::NoTransaction,
CosTransactions::Inactive,
CosTransactions::SynchronizationUnavailable
CosTransactions::Unavailable);
This VISTransactions::Current method registers a Synchronization object. This method is a short-cut for using the Control and Coordinator object to register a Synchronization object. To use this method, narrow the object returned from
resolve_initial_references() to
VISTransactions::Current. For more information, see
“Obtaining a Current object reference” on page 156.
Included in the Current interface in
VISTransactions.idl.
void resume(in Control which)
raises(InvalidControl);
Any transaction context you set via resume() is propagated back to the invoking object.
Included in the Current interface in
CosTransactions.idl.
|
|
|
|
|
The Control parameter passed to resume is not valid in the current execution environment.
|
void rollback()
raises(NoTransaction);
Rolls back the transaction associated with the client thread. This is equivalent to calling the rollback() method on the corresponding Terminator object. This method does not return until the transaction is complete, and all related Synchronization objects have been notified. On return from this method, the client thread is no longer associated with a transaction. Any attempt to use Current, as if there were a transaction, will raise an exception, such as
CosTransactions::NoTransaction or
CORBA::TRANSACTION_REQUIRED, or return a null object reference. If a heuristic occurs, this method will not throw a heuristic-related exception.
If the caller is not the transaction originator, rollback() raises the exception
CORBA::NO_PERMISSION.
Included in the Current interface in
CosTransactions.idl.
For more information, see the VisiBroker VisiTransact Guide.
void rollback_only()
raises(NoTransaction);
Included in the Current interface in
CosTransactions.idl.
void set_timeout(in unsigned long seconds);
|
•
|
= 0 Sets any subsequent transaction that is begun to the default transaction timeout for the VisiTransact Transaction Service instance that it uses.
|
|
•
|
> 0 Sets the new timeout to the specified number of seconds. If the seconds parameter exceeds the maximum timeout valid for a VisiTransact Transaction Service instance being used, then the new timeout is set to that maximum, to bring it in range.
|
When a transaction, created by a subsequent call to begin() in any thread in the process, takes longer to start transaction completion than the established timeout, it will be rolled back. If the timeout occurs before the transaction enters the completion stage (begins two-phase or one-phase processing) the transaction will be rolled back. Otherwise, the timeout is ignored.
Included in the Current interface in
CosTransactions.idl.
For more information see the description of set_timeout() in the VisiBroker
VisiTransact Guide.
The Control object can be passed to the resume() method to reestablish this context in the same thread or a different thread.
After the call to suspend(), no transaction is associated with the client thread. Any attempt to use Current, as if there were a transaction, will raise an exception, such as
CosTransactions::NoTransaction or
CORBA::TRANSACTION_REQUIRED, or return a null object reference.
Included in the Current interface in
CosTransactions.idl.
The TransactionalObject interface provides for the automatic propagation of transaction context on method calls of transactional objects. The
TransactionalObject interface defines no methods.
|
•
|
Explicit propagation. A method receives and passes the transaction context as a Terminator, Control, Coordinator, or PropagationContext structure. For further information, see the VisiBroker VisiTransact Guide.
|
|
•
|
Implicit propagation. The transaction context is passed automatically (and implicitly) on method calls. For further information, see the VisiBroker VisiTransact Guide.
|
An instance of TransactionalObject can participate in implicit propagation. Implicit propagation is where the transaction context associated with the client thread is automatically propagated to
TransactionalObject instances through method calls.
To use VisiTransact-managed transactions, all of your transactional objects must inherit from TransactionalObject. By using VisiTransact-managed transactions, you benefit from checked behavior.
The following example shows the TransactionalObject interface in the
CosTransactions.idl file.
The transaction context is always passed implicitly to an object that inherits from CosTransactions::TransactionalObject. In addition, a program may be passed a transaction context explicitly, as a parameter.
As described in “Current interface” on page 154, the
Current interface enables a program to initiate VisiTransact-managed transactions. This section, by contrast, describes the
TransactionFactory interface, which defines methods that enable a program to initiate non-VisiTransact-managed transactions. The
TransactionFactory interface gives programs direct control over the propagation of transaction context.
In the CosTransactions module, the
TransactionFactory interface provides three methods:
|
•
|
create_with_name() Available if you are using the VISTransactions IDL interface (with the VisiBroker VisiTransact extensions).
|
|
•
|
recreate() Creates a new representation of a transaction.
|
The following example shows the CosTransactions IDL for
TransactionFactory.
The next example shows the VISTransactions IDL for
TransactionFactory.
This method accepts a timeout parameter (time_out) and creates a new transaction. It returns a Control object. The Control object can be used to manage or to control participation in the new transaction. The Control object can be used by any thread and passed around explicitly, just like any other CORBA object.
Included in the TransactionFactory interface in
CosTransactions.idl.
|
•
|
= 0 Sets any subsequent transaction that is begun to the default transaction timeout for the VisiTransact Transaction Service instance that it uses.
|
|
•
|
> 0 Sets the new timeout to the specified number of seconds. If the seconds parameter exceeds the maximum timeout valid for a VisiTransact Transaction Service instance being used, then the new timeout is set to that maximum.
|
See the description of set_timeout() in the VisiBroker VisiTransact Guide.
This VISTransactions method extends the
CosTransactions::
TransactionFactory::create() method by enabling you to create a new transaction and assign it an informational transaction name that can be used for debugging and error reporting. The user-defined transaction name is included in the value returned by
get_transaction_name().
Included in the TransactionFactory interface in
VISTransactions.idl.
|
•
|
= 0 Sets any subsequent transaction that is begun to the default transaction timeout for the VisiTransact Transaction Service instance that it uses.
|
|
•
|
> 0 Sets the new timeout to the specified number of seconds. If the seconds parameter exceeds the maximum timeout valid for VisiTransact Transaction Service instance being used, then the new timeout is set to that maximum.
|
See the description of set_timeout() in the VisiBroker
VisiTransact Guide.
Control recreate(in PropagationContext context);
This method creates a new Control object using its PropagationContext parameter. The Control object can be used to manage or to control participation in the transaction.
To get a transaction's PropagationContext, invoke the
get_txcontext() method on the transaction's Coordinator object.
Included in the TransactionFactory interface in
CosTransactions.idl.
The following example shows the way get_txcontext() and
recreate() work together to recreate a transaction.
The Control interface enables a program to explicitly manage or propagate a transaction context. A Control object is implicitly associated with one specific transaction.
The Control interface defines two methods:
The get_coordinator() method returns a Coordinator object, which supports methods used by participants in the transaction. The
get_terminator() method returns a Terminator object, which supports methods to complete the transaction. The Terminator and Coordinator objects support methods that are typically performed by different parties. Providing two objects enables each set of methods to be made available only to the parties that require those methods.
The example below contains the IDL for the Control interface, an excerpt from the
CosTransactions.idl file.
You can obtain a Control object by using one of the methods of the TransactionFactory. See
“TransactionFactory interface” on page 168. You can also obtain a Control object for the current transaction (associated with a thread) through methods of the Current object.
Included in the Control interface in
CosTransactions.idl.
For more information, see “Coordinator interface” on page 175 for details on methods you can use once you obtain the Coordinator object.
This method returns a Terminator object. The Terminator can be used to rollback or commit the transaction associated with the Control. The Unavailable exception is raised if the Control cannot provide the requested object due to the inability of the Terminator object to be transmitted to or be used in other execution environments.
Included in the Control interface in
CosTransactions.idl.
For more information, see the VisiBroker VisiTransact Guide.
The Terminator interface supports methods to commit or rollback a transaction. Typically, these methods are used by the transaction originator, but any program that has access to a Terminator object for that transaction can commit or rollback the transaction.
The following example contains the IDL for the Terminator interface, an excerpt from the
CosTransactions.idl file.
void commit(in boolean report_heuristics)
raises(HeuristicMixed,
HeuristicHazard);
If the report_heuristics parameter is true, the VisiTransact Transaction Service will report inconsistent or possibly inconsistent outcomes using the
CosTransactions::HeuristicMixed and
CosTransactions::HeuristicHazard exceptions when appropriate. Information about the Resources involved in a heuristic outcome will be written to a heuristic log file corresponding to the instance of the VisiTransact Transaction Service. For more information on heuristics, see the VisiBroker
VisiTransact Guide.
Included in the Terminator interface in
CosTransactions.idl.
|
|
|
|
|
true: Requests that the HeuristicMixed or HeuristicHazard exceptions be raised, when appropriate. false: Requests that the heuristic information is not returned to the program.
|
The example below shows how to use the commit() method with and without heuristics.
// Using commit() without heuristics.
try
{
terminator->commit(0);
}
catch(CORBA::TRANSACTION_ROLLEDBACK&)
{
cerr << "Transaction failed" << endl;
}
...
// Using commit() with heuristics.
try
{
terminator->commit(1);
}
catch(CORBA::TRANSACTION_ROLLEDBACK&)
{
cerr << "Transaction failed" << endl;
}
catch(CosTransactions::HeuristicMixed&)
{
cerr << "HeuristicMixed exception was raised" << endl;
}
catch(CosTransactions::HeuristicHazard&)
{
cerr << "HeuristicHazard exception was raised" << endl;
}
catch(CORBA::OBJECT_NOT_EXIST&)
{
cerr << "Transaction no longer exists" << endl;
}
Included in the Terminator interface in
CosTransactions.idl.
The Coordinator interface provides methods that are used by participants in a transaction. These participants are typically either recoverable objects or agents of recoverable objects. Each Coordinator is implicitly associated with a single transaction.
The following example shows the CosTransactions IDL for the
Coordinator interface.
...
interface Coordinator
{
Status get_status();
Status
get_parent_status();
Status
get_top_level_status();
boolean
is_same_transaction(in Coordinator coord);
boolean
is_related_transaction(in Coordinator coord);
boolean
is_ancestor_transaction(in Coordinator coord);
boolean
is_descendant_transaction(in Coordinator coord);
boolean
is_top_level_transaction();
unsigned long
hash_transaction();
unsigned long
hash_top_level_tran();
RecoveryCoordinator
register_resource(in Resource resource)
raises(Inactive);
void
register_synchronization(in Synchronization synch)
raises(Inactive, SynchronizationUnavailable);
void
register_subtran_aware(in SubtransactionAwareResource resource)
raises(Inactive, NotSubtransaction);
void
rollback_only()
raises(Inactive);
string
get_transaction_name();
Control
create_subtransaction()
raises(SubtransactionsUnavailable, Inactive);
PropagationContext
get_txcontext()
raises(Unavailable);
};
Because VisiTransact does not support nested transactions, several of the Coordinator methods have become equivalent--that is, they return the same result. More information is provided later in the section with the method descriptions.
Finally, without nested transactions, the create_subtransaction() method is not useful and is therefore excluded from this version of VisiTransact (and this documentation), although it is described in the OMG specification.
Because VisiTransact does not support nested transactions, every transaction is top-level, and get_parent_status() of a top-level transaction is equivalent to
get_status(), by OMG definition. For further information, see
“recreate()” on page 170.
Included in the Coordinator interface in
CosTransactions.idl.
This method returns the status of the transaction associated with the target object, as an enumerated value (enum Status). If there is no transaction associated with the target object, then the method returns the value
StatusNoTransaction.
Included in the Coordinator interface in
CosTransactions.idl.
For more information, see the VisiBroker VisiTransact Guide.
Status get_top_level_status();
Included in the Coordinator interface in
CosTransactions.idl.
string get_transaction_name();
This method returns a printable string that is a descriptive name for the transaction. This method is intended to assist with diagnostics and debugging. If the transaction was created by the VISTransactions::TransactionFactory::create_with_name() method, the return string is the user-defined descriptive transaction name rather than the VisiTransact Transaction Service-generated name. If there is no transaction associated with the client thread, an empty string is returned.
Included in the Coordinator interface in
CosTransactions.idl.
The get_txcontext() method returns a
PropagationContext, which can be used by one VisiTransact Transaction Service domain to export a transaction to a new VisiTransact Transaction Service domain.
Included in the Coordinator interface in
CosTransactions.idl.
Included in the Coordinator interface in
CosTransactions.idl.
For more information, see the VisiBroker VisiTransact Guide.
Included in the Coordinator interface in
CosTransactions.idl.
The example below shows a method that uses hash_transaction() to efficiently reject unequal Coordinators.
For more information, see the VisiBroker VisiTransact Guide.
boolean is_ancestor_transaction(in Coordinator coord);
Included in the Coordinator interface in
CosTransactions.idl.
boolean is_descendant_transaction(in Coordinator coord);
Included in the Coordinator interface in
CosTransactions.idl.
boolean is_related_transaction(in Coordinator coord);
Included in the Coordinator interface in
CosTransactions.idl.
boolean is_same_transaction(in Coordinator coord);
Included in the Coordinator interface in
CosTransactions.idl.
boolean is_top_level_transaction(in Coordinator coord);
Included in the Coordinator interface in
CosTransactions.idl.
Included in the Coordinator interface in
CosTransactions.idl.
void register_synchronization(in Synchronization synch)
raises(Inactive, SynchronizationUnavailable);
Included in the Coordinator interface in
CosTransactions.idl.
void register_subtran_aware(in SubtransactionAwareResource resource)
raises(Inactive, SubtransactionsUnavailable);
Included in the Coordinator interface in
CosTransactions.idl.
void rollback_only()
raises (Inactive);
Included in the Coordinator interface in
CosTransactions.idl.
For more information about invoking rollback_only(), see the VisiBroker
VisiTransact Guide.
The following example shows the RecoveryCoordinator interface in the
CosTransactions.idl file.
Status replay_completion(Resource resource)
raises(NotPrepared);
Included in the RecoveryCoordinator interface in
CosTransactions.idl.
The following example shows the Resource interface in the
CosTransactions.idl file.
...
interface Resource
{
Vote prepare()
raises(
HeuristicMixed,
HeuristicHazard
);
void
rollback()
raises(
HeuristicCommit,
HeuristicMixed,
HeuristicHazard
);
void
commit()
raises(
NotPrepared,
HeuristicRollback,
HeuristicMixed,
HeuristicHazard
);
void
commit_one_phase()
raises(
HeuristicHazard
);
void
forget();
};
...
void commit()
raises(NotPrepared
HeuristicRollback
HeuristicMixed
HeuristicHazard
);
This method attempts to commit all changes associated with the Resource. If a heuristic outcome exception is raised, the Resource must keep the heuristic decision in persistent storage until the forget() method is performed so that it can return the same outcome in case
commit() is invoked again during recovery. Otherwise, the Resource can immediately forget all knowledge of the transaction.
Included in the Resource interface in
CosTransactions.idl.
|
|
|
|
|
The commit() method was called before the prepare() method was called.
|
|
|
|
|
|
|
|
|
|
void commit_one_phase()
raises (HeuristicHazard);
The commit_one_phase() method requests the Resource to commit all changes made as part of the transaction. This method is an optimization for use when a transaction has only one participating Resource. The
commit_one_phase() method can be called on the Resource, instead of first calling
prepare() and then
commit() or
rollback().
If a heuristic outcome exception is raised, the Resource must keep the heuristic decision in persistent storage until the forget() method is performed. This enables the Resource to return the same outcome in case
commit_one_phase() is performed again during recovery. Otherwise, the Resource immediately forgets all knowledge of the transaction.
Included in the Resource interface in
CosTransactions.idl.
If a failure occurs during commit_one_phase(), it is called again when the failure is repaired. Since there is only a single Resource, the
HeuristicHazard exception is used to report heuristic decisions related to that Resource.
|
|
|
|
|
|
|
|
The commit_one_phase() method cannot commit all changes made as part of the transaction.
|
When VisiBroker VisiTransact receives a heuristic exception, it records the exception. The VisiTransact Transaction Service will ultimately call forget() on the Resource. This means that the Resource can discard all information about the transaction that raised the heuristic exception. This method is called only if a heuristic exception was raised from
rollback(),
commit(), or
commit_one_phase().
Included in the Resource interface in
CosTransactions.idl.
Vote prepare()
raises(HeuristicMixed
HeuristicHazard
);
|
•
|
VoteReadOnly--No persistent data associated with the Resource has been modified by the transaction.
|
|
•
|
VoteCommit--The following data has been saved to persistent storage:
|
|
•
|
VoteRollback--Some circumstance has caused the Resource to call for a rollback, such as inability to save the relevant data, inconsistent outcomes, or no knowledge of the transaction (which might happen after a crash).
|
Included in the Resource interface in
CosTransactions.idl.
For more information, see the VisiBroker VisiTransact Guide.
void rollback()
raises(HeuristicCommit
HeuristicMixed
HeuristicHazard
);
If a heuristic outcome exception is raised, the Resource must save the heuristic decision in persistent storage until the forget() method is invoked. This enables the Resource to return the same outcome in case
rollback() is called again during recovery. Otherwise, the Resource immediately forgets all knowledge of the transaction.
Included in the Resource interface in
CosTransactions.idl.
For more information, see the VisiBroker VisiTransact Guide.
The Synchronization interface defines methods that enable a transactional object to be notified before the start of the two and one-phase commit protocol, and after its completion, as described in the VisiBroker
VisiTransact Guide.
In the CosTransactions module, the
Synchronization interface provides two methods:
|
•
|
before_completion()--Ensures that before_completion() is invoked before starting to commit a transaction.
|
|
•
|
after_completion()--Ensures a transactional object is notified after the transaction has been completed. This applies to all transactions whether they were committed or rolled back.
|
In certain cases, after_completion() is called when
before_completion() was not called.
before_completion() is called only if a transaction is still continuing towards a commit at the outset of completion.
after_completion() is always called (unless the VisiTransact Transaction Service crashes before the transaction completes).
Although the signatures of these methods are fixed by the Synchronization interface, their implementations are user-defined. This enables an application to do custom processing at key points in a transaction--before and after transaction completion.
The following example shows the CosTransactions IDL for the
Synchronization interface.
void after_completion(in Status status);
The after_completion() method is always invoked during normal processing.
As shown above, IDL for the Synchronization interface inherits from the
TransactionalObject interface. As a programmer, you are responsible for writing the implementation of an
after_completion() method that conforms to the IDL.
If after_completion() is to be called in processing a particular transaction, the following actions must be taken:
The VisiTransact Transaction Service calls this method after the two-phase commit protocol completes. As an example of its use, after_completion() can be used by a transactional object to discover the outcome of the transaction. This is particularly useful for transactional objects that are not also recoverable objects, and so are not automatically notified of the outcome.
You can call get_status() to see whether or not the transaction has been marked for rollback.
Notice that because Synchronization inherits from
TransactionalObject, the transaction context will be available through the Current object.
Included in the Synchronization interface in
CosTransactions.idl.
|
|
|
|
|
A Status value passed by the Terminator to the Synchronization object once the outcome of the transaction has been determined.
|
void before_completion();
The before_completion() method is invoked after the application invokes
commit(), but before the VisiTransact Transaction Service begins transaction completion. The
before_completion() method is not invoked for a rollback request.
As shown in the beginning of this section the IDL for the Synchronization interface inherits from the
TransactionalObject interface. As a programmer, you are responsible for writing the implementation of a
before_completion() method that conforms to the IDL.
If before_completion() is to be called when processing a particular transaction, the Synchronization object must be registered using the
register_synchronization() method in the
Coordinator interface. Register the Synchronization object from your transactional object or recoverable server. Registration must be done after the transaction is created and before the start of the two-phase commit.
The VisiTransact Transaction Service calls this method after the transaction work has been done but before the two-phase commit protocol starts; that is, before prepare() is called on the participating Resource. VisiBroker VisiTransact calls
before_completion() only if a transaction is still continuing towards a commit at the outset of completion. This means that
Terminator->commit() was called and the transaction has not been marked for rollback. If
Terminator->rollback() was called, or the first of several Synchronization objects marked the transaction for rollback, or the transaction was already marked for rollback,
before_completion() calls will not be called again for this transaction.
Within this method, you can ensure the transaction will be rolled back by calling the rollback_only() method. You can also call
get_status() to see whether or not the transaction has been marked for rollback. At the time the method is called, however, you cannot rely upon the status to indicate whether or not the transaction will actually be committed.
Notice that because the Synchronization interface inherits from
TransactionalObject, the transaction context will be available through the Current object. This means that
before_completion() can use all objects on the Current object, such as
get_status() and
get_control().
Included in the Synchronization interface in
CosTransactions.idl.
For more information see the VisiBroker VisiTransact Guide.
The VISTransactionService class is provided to help you link an instance of the VisiTransact Transaction Service with your application process.
Its methods, in the visits.h file, include:
If you want to initialize the embedded instance of the VisiTransact Transaction Service, the init() method must be called. After
ORB_init() has been invoked, all the recognized VisiTransact arguments will be stripped from the original parameter list so that they will not interfere with any other argument processing that your client program requires.
Included in the VISTransactionService interface in
visits.h.
The argc and
argv parameters should be
argc and
argv from the
main function.
This method will cleanup all the instances of the VisiTransact Transaction Service that have been initialized by a call to init(). This method will not bring down your application process unless the command line option
OTSexit_on_shutdown is set to 1.
Included in the VISTransactionService interface in
visits.h.
For more information, see the VisiBroker VisiTransact Guide.
You can pass arguments to ORB_init() (or
ORB.init() for Java applications) which affect the VisiTransact Transaction Service and your application components. The following sections explain these options.
As a component of VisiBroker, command line arguments are passed to VisiTransact Transaction Manager components through the VisiBroker ORB initialization call ORB_init(). Therefore, in order for arguments specified on the command line to have effect on the VisiTransact operation in a given application process, applications must pass the original
argc and
argv arguments to
ORB_init() from the main program. For example:
The ORB_init() function will parse both ORB arguments and VisiTransact Transaction Manager arguments, removing them from the
argv vector before returning.
By default, the first time you start a transaction with Current::begin(), an instance of the VisiTransact Transaction Service is found using the Smart Agent. You can specify an instance of the VisiTransact Transaction Service to use, and the timeout value for transactions, by using the arguments described in this section.
The following table explains the arguments that can be passed to ORB_init() from the command line for applications that originate transactions.
For example, to start the billing C++ transactional server that uses the
Accounting VisiTransact Transaction Service, you would use the following command:
To start the Billing Java transactional server that uses the
Accounting VisiTransact Transaction Service, and has a timeout period of 2400 seconds, you would use this command:
To execute Java transactional objects, you must use the vbj command to invoke the virtual machine. The options beginning
-Dvbroker.orb.dynamicLibs are required to use ORB services. Be sure to use the correct capitalization of this option.
If you specify a combination of -Dvbroker.ots.currentHost and
-Dvbroker.ots.currentName, the Smart Agent will find the named VisiTransact Transaction Service instance on the named host. If you specify
-Dvbroker.ots.currentFactory with either
-Dvbroker.ots.currentHost or
-Dvbroker.ots.currentName, the Smart Agent will find the VisiTransact Transaction Service instance by IOR only. It ignores the other arguments.
The following table explains the arguments that can be passed to ORB_init() from the command line for applications that embed an instance of the VisiTransact Transaction Service.