tx
Product: xTier™/LWC 2.3 Whitepaper: n/a	support@fitechlabs.com  Download  Buy
Depends: log  Related: cache  grid  db
xTier™ Navigator: cache cluster config email i18n ioc info jmx jndi security log marshal objpool os fs tx uidgen workflow jobs db startup jms grid

Description
The transaction service provides "out-of-the-box" support for XA transaction functionality with 2PC protocol even if the hosting environment that xTier™ is running on does not provide it natively. 'tx' service provides a fully compliant JTA transaction manager for the Java runtime that enables non-J2EE applications such as JSP/Servlet engines or custom middleware to benefit from JTA functionality. Major features of xTier™ JTA transaction manager include:

• Fully JTA/JTS compliant.
• Configurable selection of either xTier™ or native transaction manager.
• XML-based transaction log configured with 'tx' service XML configuration.
• Paralleled commit, rollback and prepare implementation for maximum performance on multiple XA resources.

'tx' service provides a fully compliant JTA transaction manager for the Java runtime. For example, if user is running the application code within the Tomcat it can use xTier™ transaction manager because JSP engine does not provide JTA/JTS functionality. If however code is moved to WebLogic application server user can simply configure 'tx' service to use native transaction manager - and avoid any changes in application code.

 Top

Configuration
Configuration of 'tx' service is defined in xtier_tx.xml configuration file. This file follows standard xTier™ service configuration pattern that can be illustrated by the following complete example:

1		<tm-xtier>
2		<!-- Default transaction timeout. -->
3		<tx-default-timeout-secs>
4		30
5		</tx-default-timeout-secs>
6
7		<!--
8		Name of the thread pool for asynchronous
9		commit, prepare and rollback operations.
10		-->
11		<tx-thread-pool-name>
12		tx.thread.pool
13		</tx-thread-pool-name>
14
15		<!--
16		Optional absolute folder path where transaction
17		manager will store its transaction log.
18		By default, it wil be stored
19		at: ${XTIER_ROOT}/config/tlog
20		-->
21		<tm-log-folder>n:/test/tlog</tm-log-folder>
22
23		<!--
24		Optional prefix for transaction
25		log file name.
26		-->
27		<tm-log-file-prefix>jboss-tx</tm-log-file-prefix>
28
29		<!-- Maximum size of the tlog file in bytes. -->
30		<tm-max-log-file-size>50000</tm-max-log-file-size>
31		</tm-xtier>
32
33		<!-- Native transaction manager. -->
34		<!--
35		<native-tm>
36		<jndi-tm-name>
37		java:/TransactionManager
38		</jndi-tm-name>
39		</native-tm>
40		-->

Note: This example uses xTier™ transaction manager and native transaction manager is commented out.

Formal specification for 'tx' service configuration can be found at xtier_tx.dtd DTD file at ${XTIER_ROOT}/config/dtd folder. xTier™ transaction manager is defined using <tm-xtier> tag with the following nested elements:

tx-default-timeout-secs	This attribute defines default transaction timeout. The value must be >= 0.
tx-thread-pool-name	This attribute defines name of the thread pool for asynchronous commit, prepare and rollback operations. Note that thread pool with this name must be defined in 'objpool' service. See ObjectPoolService for more details.
tm-log-folder	This attribute defines absolute folder path where transaction manager will store its transaction log. Note: this attribute is optiona. By default, it wil be stored at ${XTIER_ROOT}/config/tlog.
tm-log-file-prefix	This attribute defines prefix for transaction log file name. Note: this attribute is optional. By default, file name will not have any prefix.
tm-max-log-file-size	This attribute defines maximum size of the tlog file in bytes. The value must be > 0.

Native transaction manager is defined within <native-tm> tag and can be specified via either JNDI name (jndi-tm-name element) or as IoC element:

jndi-tm-name	This element defines JNDI name for transation manager. Usually, it is java:/TransactionManager
jndi-tm-name	This IoC element defines how to create transaction manager. For more information on IoC configuration see IocService.

Note: If native transaction manager is defined in XML configuration it will be used as a working transaction manager.

 Top

Examples
Usage of 'tx' service follows the standard pattern of using xTier™ service: you need to obtain an instance of xTier™ kernel that serves as a service registry. Once you have xTier™ kernel you can get an instance of any service, in our case the 'tx' service:

1		// Get the instance of xTier kernel.
2		XtierKernel xtier = XtierKernel.getInstance();
3
4		// Get the instance of 'tx' service.
5		tx = xtier.tx();

Once service iterface is obtained 'tx' service can be used to acquire user transaction or access transaction manager directly (examples is simplified):

1		// Get user transaction associated with this thread.
2		UserTransaction userTx = tx.userTx();
3
4		// Begin transaction.
5		userTx.begin();
6
7		// Perform some SQL operations. Note that in J2EE environment
8		// all XA resources will be enlisted automatically.
9
10		...
11
12		// Commit transaction.
13		userTx.commit();

 Top