Chapter 18. Transaction Subsystem
18.1. Transaction Subsystem Configuration
18.1.1. Transactions Configuration Overview
The following procedures show you how to configure the transactions subsystem of JBoss EAP 6.
18.1.2. Configure the Transaction Manager
default
, you may need to modify the steps and commands in the following ways.
Notes about the Example Commands
- For the Management Console, the
default
profile is the one which is selected when you first log into the console. If you need to modify the Transaction Manager's configuration in a different profile, select your profile instead ofdefault
, in each instruction.Similarly, substitute your profile for thedefault
profile in the example CLI commands. - If you use a Standalone Server, only one profile exists. Ignore any instructions to choose a specific profile. In CLI commands, remove the
/profile=default
portion of the sample commands.
Note
transactions
subsystem must be enabled. It is enabled by default, and required for many other subsystems to function properly, so it is very unlikely that it would be disabled.
To configure the TM using the web-based Management Console, select the Runtime tab from the list in the upper left side of the Management Console screen. If you use a managed domain, you have the choice of several profiles. Choose the correct one from the Profile selection box at the upper right of the Profiles screen. Expand the Container menu and select Transactions.
In the Management CLI, you can configure the TM using a series of commands. The commands all begin with /profile=default/subsystem=transactions/
for a managed domain with profile default
, or /subsystem=transactions
for a Standalone Server.
Table 18.1. TM Configuration Options
Option | Description | CLI Command |
---|---|---|
Enable Statistics
|
Whether to enable transaction statistics. These statistics can be viewed in the Management Console in the Subsystem Metrics section of the Runtime tab.
| /profile=default/subsystem=transactions/:write-attribute(name=enable-statistics,value=true)
|
Default Timeout
|
The default transaction timeout. This defaults to
300 seconds. You can override this programmatically, on a per-transaction basis.
| /profile=default/subsystem=transactions/:write-attribute(name=default-timeout,value=300)
|
Path
|
The relative or absolute filesystem path where the transaction manager core stores data. By default the value is a path relative to the value of the
relative-to attribute. The path is used to save the process ID when the process-id tag (or the process-id-uuid CLI attribute ) is used.
| /profile=default/subsystem=transactions/:write-attribute(name=path,value=var)
|
Relative To
|
References a global path configuration in the domain model. The default value is the data directory for JBoss EAP 6, which is the value of the property
jboss.server.data.dir , and defaults to EAP_HOME/domain/data/ for a Managed Domain, or EAP_HOME/standalone/data/ for a Standalone Server instance. The value of the path TM attribute is relative to this path.
| /profile=default/subsystem=transactions/:write-attribute(name=relative-to,value=jboss.server.data.dir)
|
Object Store Path
|
A relative or absolute filesystem path where the TM object store stores data. By default relative to the
object-store-relative-to parameter's value.
| /profile=default/subsystem=transactions/:write-attribute(name=object-store-path,value=tx-object-store)
|
Object Store Path Relative To
|
References a global path configuration in the domain model. The default value is the data directory for JBoss EAP 6, which is the value of the property
jboss.server.data.dir , and defaults to EAP_HOME/domain/data/ for a Managed Domain, or EAP_HOME/standalone/data/ for a Standalone Server instance. The value of the object store path TM attribute is relative to this path.
| /profile=default/subsystem=transactions/:write-attribute(name=object-store-relative-to,value=jboss.server.data.dir)
|
Socket Binding
|
Specifies the name of the socket binding used by the Transaction Manager for recovery and generating transaction identifiers, when the socket-based mechanism is used. Refer to
process-id-socket-max-ports for more information on unique identifier generation. Socket bindings are specified per server group in the Server tab of the Management Console.
| /profile=default/subsystem=transactions/:write-attribute(name=socket-binding,value=txn-recovery-environment)
|
Recovery Listener
|
Whether or not the Transaction Recovery process should listen on a network socket. Defaults to
false .
| /profile=default/subsystem=transactions/:write-attribute(name=recovery-listener,value=false)
|
Table 18.2. Advanced TM Configuration Options
Option | Description | CLI Command |
---|---|---|
jts
|
Whether to use Java Transaction Service (JTS) transactions. Defaults to
false , which uses JTA transactions only.
| /profile=default/subsystem=transactions/:write-attribute(name=jts,value=false)
|
node-identifier
|
The node identifier for the JTS service. This should be unique per JTS service, because the Transaction Manager uses this for recovery.
| /profile=default/subsystem=transactions/:write-attribute(name=node-identifier,value=1)
|
process-id-socket-max-ports
|
The Transaction Manager creates a unique identifier for each transaction log. Two different mechanisms are provided for generating unique identifiers: a socket-based mechanism and a mechanism based on the process identifier of the process.
In the case of the socket-based identifier, a socket is opened and its port number is used for the identifier. If the port is already in use, the next port is probed, until a free one is found. The
process-id-socket-max-ports represents the maximum number of sockets the TM will try before failing. The default value is 10 .
| /profile=default/subsystem=transactions/:write-attribute(name=process-id-socket-max-ports,value=10)
|
process-id-uuid
|
Set to
true to use the process identifier to create a unique identifier for each transaction. Otherwise, the socket-based mechanism is used. Defaults to true . Refer to process-id-socket-max-ports for more information.
| /profile=default/subsystem=transactions/:write-attribute(name=process-id-uuid,value=true)
|
use-hornetq-store
|
Use HornetQ's journaled storage mechanisms instead of file-based storage, for the transaction logs. This is disabled by default, but can improve I/O performance. It is not recommended for JTS transactions on separate Transaction Managers. .
| /profile=default/subsystem=transactions/:write-attribute(name=use-hornetq-store,value=false)
|
18.1.3. Configure Your Datasource to Use JTA Transactions
This task shows you how to enable Java Transactions API (JTA) on your datasource.
You must meet the following conditions before continuing with this task:
- Your database or other resource must support JTA. If in doubt, consult the documentation for your database or other resource.
- Create a datasource. Refer to Section 6.3.1, “Create a Non-XA Datasource with the Management Interfaces”.
- Stop JBoss EAP 6.
- Have access to edit the configuration files directly, in a text editor.
Procedure 18.1. Configure the Datasource to use JTA Transactions
Open the configuration file in a text editor.
Depending on whether you run JBoss EAP 6 in a managed domain or standalone server, your configuration file will be in a different location.Managed domain
The default configuration file for a managed domain is inEAP_HOME/domain/configuration/domain.xml
for Red Hat Enterprise Linux, andEAP_HOME\domain\configuration\domain.xml
for Microsoft Windows Server.Standalone server
The default configuration file for a standalone server is inEAP_HOME/standalone/configuration/standalone.xml
for Red Hat Enterprise Linux, andEAP_HOME\standalone\configuration\standalone.xml
for Microsoft Windows Server.
Locate the
<datasource>
tag that corresponds to your datasource.The datasource will have thejndi-name
attribute set to the one you specified when you created it. For example, the ExampleDS datasource looks like this:<datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="H2DS" enabled="true" jta="true" use-java-context="true" use-ccm="true">
Set the
jta
attribute totrue
.Add the following to the contents of your<datasource>
tag, as they appear in the previous step:jta="true"
Save the configuration file.
Save the configuration file and exit the text editor.Start JBoss EAP 6.
Relaunch the JBoss EAP 6 server.
JBoss EAP 6 starts, and your datasource is configured to use JTA transactions.
18.1.4. Configure an XA Datasource
In order to add an XA Datasource, you need to log into the Management Console. See Section 3.4.2, “Log in to the Management Console” for more information.
Add a new datasource.
Add a new datasource to JBoss EAP 6. Follow the instructions in Section 6.3.1, “Create a Non-XA Datasource with the Management Interfaces”, but click the XA Datasource tab at the top.Configure additional properties as appropriate.
All datasource parameters are listed in Section 6.6.1, “Datasource Parameters”.
Your XA Datasource is configured and ready to use.
18.1.5. About Transaction Log Messages
DEBUG
log level for the transaction logger. For detailed debugging, use the TRACE
log level. Refer to Section 18.1.6, “Configure Logging for the Transaction Subsystem” for information on configuring the transaction logger.
TRACE
log level. Following are some of the most commonly-seen messages. This list is not comprehensive, so you may see other messages than these.
Table 18.3. Transaction State Change
Transaction Begin |
When a transaction begins, the following code is executed:
com.arjuna.ats.arjuna.coordinator.BasicAction::Begin:1342 tsLogger.logger.trace("BasicAction::Begin() for action-id "+ get_uid()); |
Transaction Commit |
When a transaction commits, the following code is executed:
com.arjuna.ats.arjuna.coordinator.BasicAction::End:1342 tsLogger.logger.trace("BasicAction::End() for action-id "+ get_uid()); |
Transaction Rollback |
When a transaction rolls back, the following code is executed:
com.arjuna.ats.arjuna.coordinator.BasicAction::Abort:1575 tsLogger.logger.trace("BasicAction::Abort() for action-id "+ get_uid()); |
Transaction Timeout |
When a transaction times out, the following code is executed:
com.arjuna.ats.arjuna.coordinator.TransactionReaper::doCancellations:349 tsLogger.logger.trace("Reaper Worker " + Thread.currentThread() + " attempting to cancel " + e._control.get_uid());
You will then see the same thread rolling back the transaction as shown above.
|
18.1.6. Configure Logging for the Transaction Subsystem
Use this procedure to control the amount of information logged about transactions, independent of other logging settings in JBoss EAP 6. The main procedure shows how to do this in the web-based Management Console. The Management CLI command is given afterward.
Procedure 18.2. Configure the Transaction Logger Using the Management Console
Navigate to the Logging configuration area.
In the Management Console, click the Profiles tab at the top left of the screen. If you use a managed domain, choose the server profile you wish to configure, from the Profile selection box at the top right.Expand the Core menu, and click the Logging label.Edit the
com.arjuna
attributes.Click the Edit button in the Details section, toward the bottom of the page. This is where you can add class-specific logging information. Thecom.arjuna
class is already present. You can change the log level and whether to use parent handlers.- Log Level
- The log level is
WARN
by default. Because transactions can produce a large quantity of logging output, the meaning of the standard logging levels is slightly different for the transaction logger. In general, messages tagged with levels at a lower severity than the chosen level are discarded.Transaction Logging Levels, from Most to Least Verbose
- TRACE
- DEBUG
- INFO
- WARN
- ERROR
- FAILURE
- Use Parent Handlers
- Whether the logger should send its output to its parent logger. The default behavior is
true
.
- Changes take effect immediately.