JBoss.orgCommunity Documentation

Narayana JTS Quick Start Guide

by Mark Little, Jonathan Halliday, Andrew Dinn, and Kevin Connor

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example:

The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context.

Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example:

The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously).

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

It is important that Narayana JTS is correctly initialized prior to any application object being created. In order to guarantee this, the programmer must use the initORB and initBOA/initPOA methods of the ORBInterface class described in the ORB Portability Manual. Using the ORB_init and BOA_init/create_POA methods provided by the underlying ORB will not be sufficient, and may lead to incorrectly operating applications. For example:

The ORBInterface class has operations orb() and boa()/poa()/rootPoa() for returning references to the orb and boa/child POA/root POA respectively after initialization has been performed. If the ORB being used does not support the BOA (e.g., Sun’s JDK 1.2) then boa() does not appear in the class definition, and initBOA will do nothing.

In addition, it is necessary to use shutdownOA and shutdownORB (in that order) prior to terminating an application to allow Narayana JTS to perform necessary cleanup routines. shutdownOA routine will either shutdown the BOA or the POA depending upon the ORB being used.

No further CORBA objects should be used once shutdown has been called. It will be necessary to re-initialise the BOA/POA and ORB in such an event.


In the rest of this document we shall use the term Object Adapter to mean either the Basic Object Adapter (BOA) or the Portable Object Adapter (POA). In addition, where possible we shall use the ORB Portability classes which attempt to mask the differences between POA and BOA.

Transactions can be created within one domain (e.g., process) and used within another. Therefore, information about a transaction (the transaction context) needs to be propagated between these domains. This can be accomplished in two ways:

OTS objects supporting the Control interface are standard CORBA objects. When the interface is passed as a parameter in some operation call to a remote server only an object reference is passed. This ensures that any operations that the remote object performs on the interface (such as registering resources as participants within the transaction) are performed on the real object. However, this can have substantial penalties for the application if it frequently uses these interfaces due to the overheads of remote invocation. To avoid this overhead Narayana JTS supports interposition, whereby the server creates a local object which acts as a proxy for the remote transaction and fields all requests that would normally have been passed back to the originator. This surrogate registers itself with the original transaction coordinator to enable it to correctly participate in the termination of the transaction. Interposed coordinators effectively form a tree structure with their parent coordinators. This is shown in the figure below.


implicit transaction propagation does not imply interposition will be used at the server, but (typically) interposition requires implicit propagation.

If implicit context propagation and interposition are required, then the programmer must ensure that Narayana JTS is correctly initialised prior to objects being created; obviously it is necessary for both client and server to agree on which, if any, protocol (implicit or interposition) is being used. Implicit context propagation is only possible on those ORBs which either support filters/interceptors, or the CosTSPortability interface. Currently this is JacORB and the JDK miniORB. Depending upon which type of functionality is required, the programmer must perform the following:

  • Implicit context propagation:

    set the JTSEnvironmentBean.contextPropMode property variable to CONTEXT.

  • Interposition:

    set the JTSEnvironmentBean.contextPropMode property variable to INTERPOSITION.

If using the Narayana JTS advanced API then interposition is required .

By default, Narayana JTS does not use a separate transaction manager when creating transactions through the Current interface. Each transactional client essentially has its own transaction manager (TransactionFactory) which is co-located with it. By setting the com.arjuna.ats.jts.transactionManager property variable to YES this can be overridden at runtime. The transaction factory is located in the bin directory of the Narayana JTS distribution, and should be started by executing the start-transaction-service script located in <ats_root>/bin.

Typically Current locates the factory using the CosServices.cfg file. This file is similar to resolve_initial_references, and is automatically updated (or created) when the transaction factory is started on a particular machine. This file must be copied to the installation of all machines which require to share the same transaction factory. CosServices.cfg is located at runtime by the OrbPortabilityEnvironmentBean properties initialReferencesRoot (a directory, defaulting to the current working directory) and initialReferencesFile (a name relative to the directory,'CosServices.cfg' by default).

It is possible to override the default location mechanism by using the OrbPortabilityEnvironmentBean.resolveService property variable. This can have one of the following values:

If OrbPortabilityEnvironmentBean.resolveService is specified when the transaction factory is run, then the factory will register itself with the specified resolution mechanism.

Revision History
Revision 1Wed Apr 13 2010Tom Jenkinson
Taken from installation guide
Revision 2Thu Jan 16 2014Gytis Trikleris
Update to Wildfly and Narayana