Transactions Administrators Guide
for Use with JBoss Enterprise Application Platform 5
Chapter 1. Introduction
- JBoss Transaction Service does not provide a security layer. The objects stored in the JBoss Transactions Object Store are typically owned by the user running the application that created them. The Object Store and Object Manager facilities do not enforce ownership of objects. Ownership of objects is not checked or enforced by the Transaction Manager.
- Persistent objects created in the Object Store are never deleted unless the
StateManager.destroymethod is invoked on an object, or an application explicitly deletes them. This means that the Object Store gradually accumulates garbage, especially during application development and testing phases. JBoss Transaction Service provides no automated garbage collection facility. This lack of garbage collection can create dangling references. Here is an example of a dangling reference. A persistent object called ObjectA stores a Uid for ObjectB, which is also a persistent object, in its passive representation on disk. An application can delete ObjectB even though ObjectA still contains a reference to it. When ObjectA is next activated and attempts to access ObjectB, a run-time error occurs.
- JBoss Transaction Service includes no version control of objects or database reconfiguration in the event of class structure changes. If you change the definition of a class of persistent objects, you must ensure that existing instances of the object in the Object Store are converted to the new representation. The JBoss Transactions Service software cannot detect or correct references to old object state by new operation versions or vice versa.
- Object store management is critically important to the transaction service.
Chapter 2. ObjectStore Management
Chapter 3. OTS and J2EE Transaction Service management
3.1. Starting the Run-time System
com.arjuna.ats.jts.transactionManagerenvironment variable to
yes. The system locates the transaction manager using an ORB-specific mechanism. It might be registered with a name server, added to the ORB’s initial references, listed in a references file specific to JBoss Transaction Service, or located by the ORB’s specific location mechanism.
com.arjuna.orbportability.resolveServiceenvironment variable to one of the following values:
CONFIGURATION_FILE, the default value
- causes the system to use the
- JBoss Transaction Service attempts to use a name service to register the transaction factory. If this is not supported by the ORB, an exception will be thrown.
- JBoss Transaction Service uses the ORB-specific bind mechanism. If this is not supported by the ORB, an exception will be thrown.
- JBoss Transaction Service attempts to register the transaction service with the ORB's initial service references.
3.2. OTS Configuration File
RESOLVE_INITIAL_REFERENCESoption, JBoss Transaction Service supports an initial reference file where references for specific services can be stored and used at run-time. The file,
CosServices.cfg, consists of two columns: the
service name(which is always
TransactionServiceif you are using OTS server) and the IOR, separated by a single space.
CosServices.cfgnormally resides in the
etcdirectory of the JBoss Transaction Service installation, although the actual location is determined at run-time by searching the
CLASSPATHfor a copy of the file in an
etcdirectory or the location of the TransactionService properties file directory.
3.3. Name Service
3.5. Resolution service table
Table 3.1. Locating the OTS transaction manager server
|OTS configuration file||All available ORBs|
Chapter 4. XA specific management
com.arjuna.ats.arjuna.xa.nodeIdentifierproperty. This value must be unique across all your JBoss Transaction Service instances. If no value is given, JBoss Transaction Service will generate one and report the value via the logging infrastructure.
4.1. XA Recovery
com.arjuna.ats.jta.xaRecoveryNode. You can pass multiple values. A value of
*forces JBoss Transaction Service to recover (and possibly rollback) all transactions, regardless of their node identifier. Use this option with extreme caution.
Chapter 5. Web Service Transaction service management
- the application itself
- the Web services that the application consumes
- the Transaction Manager
- the transaction participants which support those Web services
5.1. The Transaction Manager
16:53:38,850 ERROR [STDERR] Message Listener Service: started, message listener jndi name activationcoordinator
5.1.1. Configuring the Transaction Manager
confdirectory and are used to configure the demo application and the standalone module.
C:/temp/ObjectStoreshould be changed to a value appropriate to your system. In a production environment, this directory should be located on fault-tolerant media, such as a RAID array.
5.1.2. Deploying the Transaction Manager
- Have JBoss Enterprise Application Platform 5 installed
- Install ant 1.4 or later.
build.xmlincluded with the coordinator, so that it points to the application server installation where the transaction coordinator will be deployed, and the location of the JBoss Transaction Service installation. The files
dd/directory of the coordinator are the deployment descriptors for the WS-C and WS-T WAR files. They contain templated URLs. During the build phase,
portvalues from the
build.xmlinto these files.
deploy-webmethods, to create and deploy a new coordinator into the correct application server installation.
5.1.3. Deployment descriptors
Table 5.1. Deployment descriptor values and properties
Chapter 6. JBoss Transaction Server Run-time Information
Infoclass. This class provides a
toStringmethod, which returns an XML dump of the configuration information for the module in question. See Example 6.1, “Using the
toStringMethod” for an example of the output.
Example 6.1. Using the
<module-info> <source-identifier>unknown</source-identifier> <build-information> Arjuna Technologies [mlittle] (Windows 2000 5.0) </build-information> <version>unknown</version> <date>2002/06/15 04:06 PM</date> <notes></notes> <configuration> <properties-file dir="null">arjuna.properties</properties-file> <object-store-root>null</object-store-root> </configuration> </module-info>
Chapter 7. Resource Recovery in JBoss Transaction Service
jbossts-properties.xmlfile, located in your server configuration's
confdirectory. For a server installed at JBOSS_HOME using the default configuration, the correct file path is:
7.3. Cluster Notes
<property name="com.arjuna.ats.arjuna.xa.nodeIdentifier" value="1"/>
<property name="com.arjuna.ats.jta.xaRecoveryNode" value="1"/>
7.4. Recovery Modules
jbossjta-properties.xml. Each recovery module must extend
com.arjuna.ats.jta.recovery.XAResourceRecovery. We provide implementations for JDBC and JMS XA resources.
7.4.1. JDBC Recovery
18.104.22.168. Vendor-Specific Database Information
- If Oracle is configured incorrectly, you will experience the following error in your log files:
WARN [com.arjuna.ats.jta.logging.loggerI18N] [com.arjuna.ats.internal.jta.recovery.xarecovery1] Local XARecoveryModule.xaRecovery got XA exception javax.transaction.xa.XAException, XAException.XAER_RMERRTo resolve this error, be sure that the Oracle user has access to the appropriate tables to accomplish the recovery:
GRANT SELECT ON sys.dba_pending_transactions TO user; GRANT SELECT ON sys.pending_trans$ TO user; GRANT SELECT ON sys.dba_2pc_pending TO user; GRANT EXECUTE ON sys.dbms_xa TO user;The above assumes that user is the user defined to connect from JBoss to Oracle. It also assumes that either Oracle 10g R2 (patched for bug 5945463) or 11g is in use. If an unpatched version prior to 11g is used then change the last GRANT EXECUTE to:
GRANT EXECUTE ON sys.dbms_system TO user;
- See the PostgreSQL documentation for instructions on enabling prepared (i.e. XA) transactions. Version 8.4-701 of PostgreSQL's JDBC driver has a bug in
org.postgresql.xa.PGXAConnectionwhich breaks recovery in certain situations. This is fixed in newer versions.
- Based on http://bugs.mysql.com/bug.php?id=12161, XA transaction recovery does not appear to be possible using MySQL. This is scheduled to be addressed in MySQL 6.1. See also JBPAPP-2576 in the release notes for JBoss Enterprise Application Platform 5.
- DB2 expects
XAResource.recovercalls only during designated resynchronization stage which occurs when application server is restarted after crash/failure. This is a design flaw in DB2, and out of the scope of this documentation.
7.4.2. JMS Recovery
7.5. JMS Clustering Notes
Could not find new XAResource to use for recovering non-serializable XAResource
<property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGINGREMOTE1" value="org.jboss.jms.server.recovery.MessagingXAResourceRecovery;java:/RemoteJMSProvider1"/> <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGINGREMOTE2" value="org.jboss.jms.server.recovery.MessagingXAResourceRecovery;java:/RemoteJMSProvider2"/>
<mbean code="org.jboss.jms.jndi.JMSProviderLoader" name="jboss.jms:service=JMSProviderLoader,name=RemoteJMSProvider"> <attribute name="ProviderName">MyRemoteJMSProvider</attribute> <attribute name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute> <attribute name="FactoryRef">XAConnectionFactory</attribute> <attribute name="QueueFactoryRef">XAConnectionFactory</attribute> <attribute name="TopicFactoryRef">XAConnectionFactory</attribute> <attribute name="Properties"> java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces java.naming.provider.url=192.168.1.172:1099 </attribute> </mbean>
Chapter 8. Selecting the JTA Implementation
- A local JTA, which only allows non-distributed JTA transactions to be executed. This is the only version available with the JBoss Transaction Service.
- A remote, CORBA-based JTA, which allows distributed JTA transactions to be executed. This version is only available with the ArjunaJTS product and requires a supported CORBA ORB.
- Set the
- Set the
Chapter 9. ORB specific configurations
For JacORB to function correctly, ensure there is a valid
.jacorb_properties file in one of the following places:
- The CLASSPATH.
- The home directory of the user running the JBoss Transaction Service. The home directory is retrieved using
System.getProperty( “user.home” );
- The current directory.
libdirectory of the JDK used to run your application. This is retrieved using
System.getProperty( “java.home” );
jacorb.propertiesfile can be found in the JacORB installation directory.
CosTransactions.idlfile. Unfortunately these are incompatible with the version shipped with JBoss Transaction Service. Therefore, the JBoss Transaction Service JAR files must appear in the
CLASSPATHbefore any JacORB JARs.
OAPortproperty provided by JacORB unless the recovery manager has its own
jacorb.propertiesfile or the port is provided on the command line when starting the recovery manager. If the recovery manager and other components of JBoss Transaction Service share the same
jacorb.propertiesfile, then you should use the
Chapter 10. Initializing JBoss Transaction Service applications
Chapter 11. Errors and Exceptions
Errors and Exceptions During Transactional Applications
- The application has run out of memory, and thrown an
OutOfMemoryErrorexception. JBoss Transactions has attempted to do some garbage collection before re-throwing the exception. This is sometimes a transient problem and retrying the invocation might succeed.
- The transaction system has encountered a fatal error and must shut down. Prior to this error, the transaction service ensures that all running transactions have rolled back. If caught, the application should tidy up and exit. If further work is attempted, application consistency may be violated.
- An attempt has been made to use the transaction service in a manner inconsistent with the current license. The transaction service will not allow further forward progress for existing or new transactions.
- An error occurred while the transaction service attempted to use the object store. Further forward progress is not possible.
- Object store warnings about access problems on states
- This error may occur during the normal execution of crash recovery, as the result of multiple concurrent attempts to perform recovery on the same transaction. It can be safely ignored.
Appendix A. Revision History
|Revision 5.2.0-100||Wed 23 Jan 2013|
|Revision 5.1.2-100||Thu 8 December 2011|