<?xml version="1.0"?>
<!--
  JBoss, Home of Professional Open Source
  Copyright 2006, Red Hat Middleware LLC, and individual contributors
  as indicated by the @author tags.
  See the copyright.txt in the distribution for a full listing
  of individual contributors.
  This copyrighted material is made available to anyone wishing to use,
  modify, copy, or redistribute it subject to the terms and conditions
  of the GNU Lesser General Public License, v. 2.1.
  This program is distributed in the hope that it will be useful, but WITHOUT A
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
  PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
  You should have received a copy of the GNU Lesser General Public License,
  v.2.1 along with this distribution; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  MA  02110-1301, USA.


  (C) 2005-2006,
  @author JBoss Inc.
-->
<page title="JBossTS Trail map: The OMG OTS" rootpath="../..">
	<header>         Trail map: OMG Object Request Broker   </header>
	<content>
		<navigation>
			<links include="includes/www_arjuna_com_navigation.xml"/>
			<links include="includes/trailmap_navigation.xml"/>
			<links title="Navigation">
				<link ref="index.html">Home</link>
			</links>
			<links include="includes/trailmap_additional.xml"/>
		</navigation>
		<area title="Overview of the OMG Object Transaction Service">
			<html>
	Object Transaction Service (OTS) is a distributed transaction processing
service specified by the Object Management Group (OMG). This specification
extends the CORBA model and defines a set of interfaces to perform transaction
processing across multiple CORBA objects.
<br>OTS is based on the Open Group's DTP model and is designed so that
it can be implemented using a common kernel for both the OTS and Open Group
APIs. In addition to the functions defined by DTP, OTS contains enhancements
specifically designed to support the object environment. Nested transactions
and explicit propagation are two examples.</br>
				<br>The CORBA model also makes some of the functions in DTP unnecessary
so these have been consciously omitted. Static registration and the communications
resource manager are unnecessary in the CORBA environment.</br>
				<br>A key feature of OTS is its ability to share a common transaction with
XA compliant resource managers. This permits the incremental addition of
objects into an environment of existing procedural applications.</br>
				<p>
					<img SRC="includes/OTS.GIF"/>
				</p>
				<p>Figure 1 - OTS Architecture</p>
				<p>The OTS architecture, shown in Figure 1, consists of the following components:</p>
				<ul>
					<li>
						<b>Transaction Client:</b> A program or object that invokes operations
on transactional objects.</li>
					<li>
						<b>Transactional Object</b>: A CORBA object that encapsulates or refers
to persistent data, and whose behavior depends on whether or not its operations
are invoked during a transaction.</li>
					<li>
						<b>Recoverable Object</b>: A transactional object that directly maintains
persistent data, and participates in transaction protocols.</li>
					<li>
						<b>Transactional Server</b>: A collection of one or more transactional
objects.</li>
					<li>
						<b>Recoverable Server:</b> A collection of objects, of which at least one
of which is recoverable.</li>
					<li>
						<b>Resource Object</b>: A resource object is an object in the transaction
service that is registered for participation in the two-phase commit and
recovery protocol.</li>
				</ul>
In addition to the usual transactional semantics, the CORBA OTS provides
for the following features:
<ul>
					<li>
						<b>Nested Transactions</b>: This allows an application to create a transaction
that is embedded in an existing transaction. In this model, multiple subtransactions
can be embedded recursively in a transaction. Subtransactions can be committed
or rolled back without committing or rolling back the parent transaction.
However, the results of a commit operation are contingent upon the commitment
of all the transaction's ancestors. The main advantage of this model is
that transactional operations can be controlled at a finer granularity.
The application will have an opportunity to correct or compensate for failures
at the subtransaction level, without actually attempting to commit the
complete parent transaction.</li>
					<li>
						<b>Application Synchronization</b>: Using the OTS synchronization protocol,
certain objects can be registered with the transaction service for notification
before the start of and the completion of the two-phase commit process.
This enables such application objects to synchronize transient state and
data stored in persistent storage.</li>
				</ul>
				<h4>
					<a name="program_models"/>Application programming models</h4>
A client application program may use direct or indirect context management to
manage a transaction. With indirect context management, an application uses the
pseudo object called Current, provided by the Transaction Service , to associate
the transaction context with the application thread of control. In direct context
management, an application manipulates the Control object and the other objects
associated with the transaction. <br>
An object may require transactions to be either explicitly or implicitly
propagated to its operations.</br>
				<ul>
					<li>
Explicit propagation means that an application propagates a transaction
context by passing objects defined by the Transaction Service as explicit
parameters. This should typically be the PropagationContext structure.</li>
					<li>
Implicit propagation means that requests are implicitly associated with
the client's transaction; they share the client's transaction context.
It is transmitted implicitly to the objects, without direct client intervention.
Implicit propagation depends on indirect context management, since it propagates
the transaction context associated with the Current pseudo object. An object
that supports implicit propagation would not typically expect to receive
any Transaction Service object as an explicit parameter.</li>
				</ul>
A client may use one or both forms of context management, and may communicate
with objects that use either method of transaction propagation. (Details
of how to enable implicit propagation were described in Section Chapter
0 and Section 0). This results in four ways in which client applications
may communicate with transactional objects:
<ul>
					<li>
Direct Context Management/Explicit Propagation: the client application
directly accesses the Control object, and the other objects which describe
the state of the transaction. To propagate the transaction to an object,
the client must include the appropriate Transaction Service object as an
explicit parameter of an operation; typically this should be the PropagationContext
structure.</li>
					<li>
Indirect Context Management/Implicit Propagation: the client application
uses operations on the Current pseudo object to create and control its
transactions. When it issues requests on transactional objects, the transaction
context associated with the current thread is implicitly propagated to
the object.</li>
					<li>
Indirect Context Management/Explicit Propagation: for an implicit model
application to use explicit propagation, it can get access to the Control
using the get_control operation on the Current pseudo object. It can then
use a Transaction Service object as an explicit parameter to a transactional
object; for efficiency reasons this should be the PropagationContext structure,
obtained by calling get_txcontext on the appropriate Coordinator reference.
This is explicit propagation.</li>
					<li>
Direct Context Management/Implicit Propagation: a client that accesses
the Transaction Service objects directly can use the resume pseudo object
operation to set the implicit transaction context associated with its thread.
This allows the client to invoke operations of an object that requires
implicit propagation of the transaction context.</li>
				</ul>
				<h5>Examples</h5>
				<ul>
					<li>Indirect and Implicit
    <p>In the code fragments below, a transaction originator uses indirect context
      management and implicit transaction propagation; txn_crt is an example of
      an object supporting the Current interface. The client uses the begin operation
      to start the transaction whichbecomes implicitly associated with the originator's
      thread of control.</p>

<pre>...
txn_crt.begin();
// should test the exceptions that might be raised
...
// the client issues requests, some of which involve
// transactional objects;
BankAccount.makeDeposit(deposit);
...
txn_crt.commit(false)
</pre>

						<p> The program commits the transaction associated with the client thread.
      The report_heuristics argument is set to false so no report will be made
      by the Transaction Service about possible heuristic decisions.</p>
					</li>
					<li>Direct and Explicit
    <p>In the following example, a transaction originator uses direct context
      management and explicit transaction propagation. The client uses a factory
      object supporting the CosTransactions::TransactionFactory interface to create
      a new transaction and uses the returned Control object to retrieve the Ter
      mi nat or and Coordinator objects.</p>

<pre>...
CosTransactions::Control ctrl;
CosTransactions::Terminator ter;
CosTransactions::Coordinator coo;
coo = TFactory.create(0);
ter = ctrl.get_terminator();
...
transactional_object.do_operation(arg, c);
...
t.commit(false);
</pre>

						<p> The client issues requests, some of which involve transactional objects,
      in this case explicit propagation of the context is used. The Control object
      reference is passed as an explicit parameter of the request; it is declared
      in the OMG IDL of the interface. The transaction originator uses the Terminator
      object to commit the transaction; the report_heuristics argument is set
      to false: so no report will be made by the Transaction Service about possible
      heuristic decisions.</p>
					</li>
				</ul>
				<p>The main difference between direct and indirect context management is the effect
  on the invoking thread's transaction context. If using indirect (i.e., invoking
  operations through the Current pseudo object), then the thread's transaction
  context will be modified automatically by the OTS, e.g., if begin is called
  then the thread's notion of the current transaction will be modified to the
  newly created transaction; when that is terminated, the transaction previously
  associated with the thread (if any) will be restored as the thread's context
  (assuming subtransactions are supported by the OTS implementation). However,
  if using direct management, no changes to the threads transaction context are
  performed by the OTS: the application programmer assumes responsibility for
  this. </p>
				<h4>
OTS Interfaces</h4>
Figure 2 describes the principal interfaces in the CORBA OTS specification,
with their interaction, while the Table 1 below provides more details for
each interface.
<p>
					<img SRC="includes/OTS_Interfaces.GIF"/>
				</p>
				<p>Figure 2 - OTS interfaces and their interactions</p>
				<p/>Table 1 - OTS Interfaces and their role.<table BORDER="" WIDTH="100%">
					<tr BGCOLOR="#66FFFF">
						<td align="center">
							<b>Interface</b>
						</td>
						<td align="center">
							<b>Role and operations</b>
						</td>
					</tr>
					<tr>
						<td>
							<a name="Current"/>Current</td>
						<td>
							<ul>
								<li>
Transaction demarcation (<i>begin, commit, rollback, rollback_only, set_time_out</i>)</li>
								<li>
Status of the transaction (<i>get_status</i>)</li>
								<li>
Name of the transaction (g<i>et_transaction_name</i>)</li>
								<li>
Transaction context (<i>get_control</i>)</li>
							</ul>
						</td>
					</tr>
					<tr>
						<td>
							<a name="TransactionFactory"/>TransactionFactory</td>
						<td>Explicit transaction creation
<ul>
								<li>
create a transaction with its associated cooridinator (<i>create</i>)</li>
								<li>
create an interposed coordinator as a subrodinator in the transaction tree
(<i>recreate</i>)</li>
							</ul>
						</td>
					</tr>
					<tr>
						<td>
							<a name="Control"/>Control</td>
						<td>Explicit transaction context management
<ul>
								<li>
access to the transaction coordinator (<i>get_coordinator</i>)</li>
								<li>
access to the transactions terminator (<i>get_terminator</i>)</li>
							</ul>
						</td>
					</tr>
					<tr>
						<td>
							<a name="Terminator"/>Terminator</td>
						<td>Commit (commit) or rollback (rollback) a transaction in a direct transaction
management mode</td>
					</tr>
					<tr>
						<td>
							<a name="Coordinator"/>Coordinator</td>
						<td>
							<ul>
								<li>
Status of the transaction (<i>get_status, get_parent_status, get_top_level_status</i>)</li>
								<li>
Transaction information (<i>is_same_transaction, is_related_transaction,
is_ancestor_transaction, is_descendant_transaction, is_top_level_transaction,
hash_transaciton, hash_top_level_transaction, get_transaction_name, get_txcontext</i>)</li>
								<li>
Resource enlistment (<i>register_resource, register_subtrans_aware</i>)</li>
								<li>
Registration of synchronization objects (<i>register_synchronization</i>)</li>
								<li>
Set the transaction for rollback (<i>rollback_only</i>)</li>
								<li>
Create subtransactions (<i>create_subtransaction</i>)</li>
							</ul>
						</td>
					</tr>
					<tr>
						<td>
							<a name="RecoveryCoordinator"/>RecoveryCoordinator</td>
						<td>Allows to coordinate recovery in case of failure (<i>replay_completion</i>)</td>
					</tr>
					<tr>
						<td>
							<a name="Resource"/>Resource</td>
						<td>Participation in two-phase commit and recovery protocol (<i>prepare,
rollback, commit, commit_one_phase, forget</i>)</td>
					</tr>
					<tr>
						<td>Synchronization</td>
						<td>Application synchronization before beginning and after completion of
two-phase commit (<i>before_completion, after_completion</i>)</td>
					</tr>
					<tr>
						<td>SubtransactionAwareResource</td>
						<td>Commit or rollback a subtransaction (<i>commit_subtransaction, rollback_subtransaction)</i>
						</td>
					</tr>
					<tr>
						<td>
							<a name="TransactionalObject"/>TransactionalObject</td>
						<td>A marker interface to be implemented by all transactional objects (no
operation defined)</td>
					</tr>
				</table>
			</html>
		</area>
	</content>
	<footer/>
</page>
