Transactions Development Quick Start Guide
for use with JBoss Enterprise Application Platform 5 Common Criteria Certification
Edition 5.1.0
Abstract
Chapter 1. Getting Started with JTA
1.1. Package Layout
Packages Relating to the JTA
- com.arjuna.ats.jts
- Contains the JBoss Transaction Service implementation of the JTS and JTA APIs (Application Programming Interfaces).
- com.arjuna.ats.jta
- Contains local and remote JTA implementation support.
- com.arjuna.ats.jdbc
- Contains transactional JDBC 2.0 support.
1.2. Setting Properties
$JBOSS_HOME/server/default/conf/jbossts-properties.xml
.
1.2.1. Specifying the Object Store Location
Example 1.1. Specifying the Object Store
java –Dcom.arjuna.ats.arjuna.objectstore.objectStoreDir=/location/of/objectstore myprogram
defaultStore
sub-directory of the object store root. You can change the sub-directory by setting the com.arjuna.ats.arjuna.objectstore.localOSRoot
property variable.
1.3. Demarcing Transactions
- A high-level application transaction demarcation interface
- A high-level transaction manager interface intended for application server
- and a standard Java mapping of the X/Open XA protocol intended for transactional resource manager
1.3.1. UserTransaction
UserTransaction
interface allows applications to control transaction boundaries.
UserTransaction
implementations via JNDI.
Example 1.2. Controlling Transactions
// Initialize the context and get UserTransaction InitialContext ic = new InitialContext(); UserTransaction utx = ic.lookup("java:comp/UserTransaction") // start transaction work.. utx.begin(); .. do work utx.commit();
1.3.2. TransactionManager
TransactionManager
interface allows the application server to control transaction boundaries on behalf of the application being managed.
TransactionManager
implementations via JNDI.
// Initialize the context and get the TransactionManager InitialContext ic = new InitialContext(); TransactinoManager utm = ic.lookup("java:/TransactionManager")
1.3.3. Transaction
Transaction
interface allows operations to be performed on the transaction associated with the target object. Every top-level transaction is associated with one Transaction
object when the transaction is created. The Transaction
object has several uses, as described in Transaction
Interface uses.
Transaction
Interface uses
- Enlists the transactional resources in use by the application.
- Register for transaction synchronization call backs.
- Commit or roll back the transaction.
- Obtain the status of the transaction.
Transaction
object by invoking the getTransaction
method of the TransactionManager
interface, as shown in Example 1.3, “Obtaining a Transaction”.
Example 1.3. Obtaining a Transaction
Transaction txObj = TransactionManager.getTransaction();
1.4. Local versus Distributed JTA Implementations
Procedure 1.1. Selecting the Local JTA Implementation
- Set the om.arjuna.ats.jta.jtaTMImplementation property to
com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple
. - Set the com.arjuna.ats.jta.jtaUTImplementation to
com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple
.
Procedure 1.2. Selecting the Distributed JTA Implementation
- Set the com.arjuna.ats.jta.jtaTMImplementation property to
com.arjuna.ats.internal.jta.transaction.jts.TransactionManagerImple
. - Set the com.arjuna.ats.jta.jtaUTImplementation property to
com.arjuna.ats.internal.jta.transaction.jts.UserTransactionImple
.
1.5. JDBC and Transactions
java.sql.Driver
interface.
java.sql.DriverManager.getConnection
method. After establishing the connection, JBossJTA monitors all operations. You can use such connections in the same way as any other JDBC driver connection.
close
method, all operations performed on the connection at the application level are only performed on this transaction-specific connection.
1.6. Configurable Options
Important Configurable Options
- com.arjuna.ats.jta.supportSubtransactions
Possible Values
- Yes (default)
- No
- com.arjuna.ats.jta.jtaTMImplementation
Possible Values
- com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple
- com.arjuna.ats.internal.jta.transaction.jts.TransactionManagerImple
- com.arjuna.ats.jta.jtaUTImplementation
Possible Values
- com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple
- com.arjuna.ats.internal.jta.transaction.jts.UserTransactionImple
- com.arjuna.ats.jta.xaBackoffPeriod
Possible Values
- Time in seconds
- com.arjuna.ats.jdbc.isolationLevel
Possible Values
- Any supported JDBC isolation level
Chapter 2. Getting Started with JTS / OTS
2.1. Package Layout
Package
|
Description
|
---|---|
com.arjuna.orbportability
|
this package contains the classes which constitute the ORB portability library and other useful utility classes.
|
org.omg.CosTransactions
|
this package contains the classes which make up the CosTransactions.idl module.
|
com.arjuna.ats.jts
|
this package contains the JBoss Transaction Service implementations of the JTS and JTA.
|
com.arjuna.ats.arjuna
|
this package contains further classes necessary for the JBoss Transaction Service implementation of the JTS.
|
com.arjuna.ats.jta
|
this package contains local and remote JTA implementation support.
|
com.arjuna.ats.jdbc
|
this package contains transactional JDBC 2.0 support.
|
2.2. Setting Properties
jbossts-properties.xml
, which may be in any of the locations mentioned, in search order, in Possible Locations of the jbossts-properties.xml
File. properties file.
Possible Locations of the jbossts-properties.xml
File
- The current working directory.
- The home directory of the executing user.
- The
CLASSPATH
, by means of thegetResource
method.
2.3. Starting and Stopping the ORB and BOA/POA
initORB
method, and either of the initBOA
or initPOA
methods of the ORBInterface
class, which is described in the ORB Portability Manual. Do not use the ORB_init
, BOA_init
, or create_POA
methods provided by the underlying ORB, because they may lead to incorrectly operating applications.
Example 2.1. ORB Initialization
public static void main (String[] args) { ORBInterface.initORB(args, null); ORBInterface.initOA(); . . . };
ORBInterface
Methods
orb
- Returns references to the ORB
boa
- Returns references to the BOA
poa
- Returns references to the POA
rootPoa
- Returns references to the root POA
shutdownOA
- Shut down the BOA. Run this before
shutdownORB
, and before terminating the application. shutdownORB
- Shut down the ORB. Use this after
shutdownOA
. Run this before terminating the application.
shutdownOA
and shutdownORB
methods, in sequence, before terminating an application. This allows JBoss Transaction Service to perform necessary cleanup routines. The shutdownOA
routine either shuts down the BOA or the POA, depending upon the ORB being used.
Example 2.2. Shutting Down the ORB
public static void main (String[] args) { . . . ORBInterface.shutdownOA(); ORBInterface.shutdownORB(); };
shutdown
. You need to reinitialize the BOA/POA and ORB before using more CORBA objects.
Note
2.4. Specifying the Object Store Location
objectStoreDir
property.
Example 2.3. Specifying the Object Store at Application Execution
java Dcom.arjuna.ats.arjuna.objectstore.objectStoreDir=/var/tmp/ObjectStore myprogram
defaultStore
. However, this sub-directory can be changed by setting the com.arjuna.ats.arjuna.objectstore.localOSRoot property variable.
2.5. Implicit Transaction Propagation and Interposition
Propagating the Transaction Context
- Explicit propagation
- An application passes context objects as explicit parameters. These objects are either instances of the
Control
interface or thePropagationContext
structure, and are defined by the Transaction Service. It is more efficient to use thePropagationContext
structure, rather than theControl
interface. - Implicit propagation
- Requests on objects are implicitly associated with the client’s transaction, and share the client’s transaction context. The context is transmitted implicitly to the objects, without direct client intervention.
Figure 2.1. Interposition
Note
CosTSPortability
interface. JacORB and the JDK miniORB both provide the required support.
Enabling Propagation
- Implicit context propagation
- Set the com.arjuna.ats.jts.contextPropMode property variable to
CONTEXT
. - Interposition
- Set the com.arjuna.ats.jts.contextPropMode property variable to
INTERPOSITION
.
Note
2.6. Obtaining Current
Current
pseudo-object from the com.arjuna.ats.jts.OTSManager
class by using its get_current
method.
2.7. Transaction Termination
Control
can access a terminated transaction is implementation-specific. In JBoss Transaction Service, if you are using the Current
pseudo-object, all information about a transaction is destroyed when it terminates. For this reason, you should not use any Control
references to the transaction after issuing the commit or rollback operation.
Terminator
interface, information about the transaction is only removed when all the outstanding references to it have been destroyed. You can signal that the transaction information is no longer required, by using the destroyControl
method of the OTS class, which is found in the com.arjuna.CosTransactions package. After the program indicates that the transaction information is no longer required, you should not use any Control
references to the transaction.
2.8. Transaction Factory
Current
interface. Each transactional client essentially has its own transaction manager, the TransactionFactory
, which is co-located with it. To override this behavior at run-time, set the com.arjuna.ats.jts.transactionManager property variable to YES
. To execute the Transaction Factory, execute the start-transaction-service
script, located in the ATS_ROOT/bin
directory.
Current
typically locates the factory using the CosServices.cfg
file located in the $JBOSS_HOME/etc
directory. This file is similar to the resolve_initial_references
file, and is automatically created or updated when the transaction factory is started on a particular machine. This file must be copied locally to each machine which needs to share the same transaction factory.
Note
CosServices.cfg
refers to the default name and location of the configuration file. To change the name of the file, use the com.arjuna.orbportability.initialReferencesFile variable. To change its location, set the com.arjuna.orbportability.initialReferencesRoot variable.
Example 2.4. Customizing the Initial References File
java –Dcom.arjuna.orbportability.initialReferencesFile=ref –Dcom.arjuna.orbportability.initialReferencesRoot=c:\\temp prog
ResolveService Parameters
- CONFIGURATION_FILE
- The system uses the
CosServices.cfg
file. This is the default behavior. - NAME_SERVICE
- JBoss Transaction Service attempts to use a name service to locate the transaction factory. If this is not supported, an exception is thrown.
- BIND_CONNECT
- JBoss Transaction Service uses the ORB-specific bind mechanism. If this is not supported, an exception is thrown.
2.9. Recovery Manager
start-recovery-manager
script in $ATS_ROOT/bin
.
Chapter 3. Getting Started with Web Services Transactions and XTS
3.1. Configuring the Web Services Component
Property
|
Possible Values
|
---|---|
com.arjuna.orbportability.initialReferencesFile
|
CosServices.cfg
|
com.arjuna.orbportability.initialReferencesRoot
|
The directory containing the file arjuna.properties.
|
ArjunaJTS_LicenceKey
|
System specific license.
|
com.arjuna.orbportability.resolveService
|
CONFIGURATION_FILE
NAME_SERVICE
BIND_CONNECT
|
com.arjuna.ats.arjuna.objectstore.objectStoreDir
|
Any location that the application can write to.
|
com.arjuna.ats.arjuna.objectstore.localOSRoot
|
defaultStore
|
PROPERTIES_FILE
|
arjuna.properties
|
com.arjuna.ats.arjuna.coordinator.asyncPrepare
|
YES/NO
|
com.arjuna.ats.arjuna.coordinator.asyncCommit
|
YES/NO
|
com.arjuna.ats.arjuna.coordinator.commitOnePhase
|
YES/NO
|
com.arjuna.ats.arjuna.coordinator.transactionSync
|
ON/OFF
|
com.arjuna.ats.arjuna.coordinator.enableStatistics
|
ON/OFF
|
com.arjuna.ats.jts.alwaysPropagateContext
|
YES/NO
|
com.arjuna.ats.jts.defaultTimeout
|
No timeout
|
com.arjuna.ats.jts.supportRollbackSync
|
YES/NO
|
com.arjuna.ats.jts.supportInterposedSynchronization
|
YES/NO
|
com.arjuna.ats.jts.supportSubtransactions
|
YES/NO
|
com.arjuna.ats.jts.checkedTransactions
|
YES/NO
|
com.arjuna.ats.jts.transactionManager
|
YES/NO
|
com.arjuna.ats.jts.needTranContext
|
YES/NO
|
com.arjuna.ats.arjuna.coordinator.txReaperTimeout
|
120000000 microseconds
|
com.arjuna.ats.arjuna.coordinator.txReaperMode
|
NORMAL
DYNAMIC
|
com.arjuna.ats.jts.contextPropMode
|
NONE
CONTEXT
INTERPOSITION
|
Index
C
- CLASSPATH, Getting Started with JTA, Getting Started with JTS / OTS
- configuration, Getting Started with Web Services Transactions and XTS
- Control interface, Getting Started with JTS / OTS
- CORBA, Getting Started with JTS / OTS
- Current pseudo-object, Getting Started with JTS / OTS
D
- distributed JTA, Getting Started with JTA
I
- implicit transaction propagation, Getting Started with JTS / OTS
- interposition, Getting Started with JTS / OTS
J
- javax.transaction package, Getting Started with JTA
- JDBC, Getting Started with JTA
- JDBC driver, Getting Started with JTA
- JTA
- Java Transactions API, Getting Started with JTA
L
- local JTA, Getting Started with JTA
O
- object store, Getting Started with JTA
- object store, location of, Getting Started with JTS / OTS
- ORB, Getting Started with JTS / OTS
- ORB, starting and stopping, Getting Started with JTS / OTS
P
- packages, Getting Started with JTS / OTS
- POA, Getting Started with JTS / OTS
- PropagationContext, Getting Started with JTS / OTS
- properties, Getting Started with JTA, Getting Started with JTS / OTS, Getting Started with Web Services Transactions and XTS
R
- Recovery Manager, starting and stopping, Getting Started with JTS / OTS
- ResolveService parameters, Getting Started with JTS / OTS
- run-time, Getting Started with JTA
T
- Transaction Factory, Getting Started with JTS / OTS
- TransactionManager, Getting Started with JTA
U
- UserTransaction, Getting Started with JTA
W
- Web Services, Getting Started with Web Services Transactions and XTS