JBoss Transaction Internals

The JBoss application server is written to be independent of the actual transaction manager used. JBoss uses the JTA javax.transaction.TransactionManager interface as its view of the server transaction manager. Thus, JBoss may use any transaction manager which implements the JTA TRansactionManager interface. Whenever a transaction manager is used, it is obtained from the well-known JNDI location, java:/TransactionManager. This is the globally available access point for the server transaction manager.

If transaction contexts are to be propagated with RMI/JRMP calls, the transaction manager must also implement two simple interfaces for the import and export of transaction propagation contexts (TPCs). The interfaces are transactionPropagationContextImporter and TRansactionPropagationContextFactory, both in the org.jboss.tm package.

Being independent of the actual transaction manager used also means JBoss does not specify the format or type of the transaction propagation context used. In JBoss, a TPC is of type Object, and the only requirement is that the TPC must implement the java.io.Serializable interface.

When using the RMI/JRMP protocol for remote calls, the TPC is carried as a field in the org.jboss.ejb.plugins.jrmp.client.RemoteMethodInvocation class used to forward remote method invocation requests.

Adapting a Transaction Manager to JBoss

A transaction manager has to implement the JTA to be easily integrated with JBoss. Like almost everything in JBoss, the transaction manager is managed as an MBean. Like all JBoss services, it should implement org.jboss.system.ServiceMBean to ensure proper lifecycle management.

The primary requirement of the transaction manager service on startup is that it binds its implementation of the three required interfaces into JNDI. These interfaces and their JNDI locations are as follows:

• The javax.transaction.TransactionManager interface is used by the application server to manage transactions on behalf of the transactional objects that use container managed transactions. It must be bound under the JNDI name java:/TransactionManager.

• The TRansactionPropagationContextFactory interface is called by JBoss whenever a transaction propagation context is needed for transporting a transaction with a remote method call. It must be bound under the JNDI name java:/TransactionPropagationContextImporter.

• The TRansactionPropagationContextImporter interface is called by JBoss whenever a transaction propagation context from an incoming remote method invocation has to be converted to a transaction that can be used within the receiving JBoss server VM.

Establishing these JNDI bindings is all the transaction manager service needs to do to install its implementation as the JBoss server transaction manager.

The Default Transaction Manager

JBoss is by default configured to use the fast in-VM transaction manager. This transaction manager is very fast, but does have two limitations:

• It does not do transactional logging, and is thus incapable of automated recovery after a server crash.

• Although it does support propagating transaction contexts with remote calls, it does not support propagating transaction contexts to other virtual machines, so all transactional work must be done in the same virtual machine as the JBoss server.

The corresponding default transaction manager MBean service is the org.jboss.tm.TransactionManagerService MBean. It has four configurable attributes:

• TransactionTimeout The default transaction timeout in seconds. The default value is 300 seconds (five minutes).

• InterruptThreads Indicates whether the transaction manager should interrupt threads when the transaction times out. The default value is false.

• GlobalIdsEnabled Indicates whether the transaction manager should use global transaction IDs. This should be set to true for transaction demarcation over IIOP. The default value is true.

• XidFactory The JMX ObjectName of the MBean service that provides the org.jboss.tm.XidFactoryMBean implementation. The XidFactoryMBean interface is used to create javax.transaction.xa.Xid instances. This is a workaround for XA JDBC drivers that only work with their own Xid implementation. Examples of such drivers are the older Oracle XA drivers. The default factory is jboss:service=XidFactory.

org.jboss.tm.XidFactory

The XidFactory MBean is a factory for javax.transaction.xa.Xid instances in the form of org.jboss.tm.XidImpl. The XidFactory allows for customization of the XidImpl that it constructs through the following attributes:

• BaseGlobalId This is used for building globally unique transaction identifiers. This must be set individually if multiple JBoss instances are running on the same machine. The default value is the hostname of the JBoss server, followed by a slash.

• GlobalIdNumber A long value used as initial transaction ID. The default is zero.

• Pad The pad value determines whether the byte returned by the Xid getGlobalTransactionId and getBranchQualifier methods should be equal to the maximum 64-byte length or a variable value less than or equal to 64 bytes. Some resource managers (Oracle, for example) require IDs that are the maximum length in size.

UserTransaction Support

The JTA javax.transaction.UserTransaction interface allows applications to explicitly control transactions. For enterprise session beans that manage transaction themselves (Bean Managed Transactions or BMT), a UserTransaction can be obtained by calling the getUserTransaction method on the bean context object, javax.ejb.SessionContext.

The ClientUserTransactionService MBean publishes a UserTransaction implementation under the JNDI name UserTransaction. When the UserTransaction is obtained with a JNDI lookup from an external client, a very simple UserTransaction suitable for thin clients is returned. This UserTransaction implementation only controls the transactions on the server the UserTransaction object was obtained from. Local transactional work done in the client is not done within the transactions started by this UserTransaction object.

When a UserTransaction object is obtained by looking up the JNDI name UserTransaction in the same virtual machine as JBoss, a simple interface to the JTA TRansactionManager is returned. This is suitable for web components running in web containers embedded in JBoss. When components are deployed in an embedded web server, the deployer makes a JNDI link from the standard java:comp/UserTransaction Environment Naming Context (ENC) name to the global UserTransaction binding so the web components can look up the UserTransaction instance under the JNDI name as specified by the J2EE.

Note

For BMT beans, do not obtain the UserTransaction interface using a JNDI lookup. Doing this violates the EJB specification, and the returned UserTransaction object does not have the hooks the EJB container needs to make important checks.