Chapter 8. Stand-Alone Coordination

The XTS service is deployed as a JBoss service archive (SAR). The version of the service archive provided with the Transaction Service implements version 1.1 of the WS-C, WS-AT and WS-BA services. You can rebuild the XTS service archive to include both the 1.0 and 1.1 implementations and deploy them side by side. See the service archive build script for for further details.

The release service archive obtains coordination contexts from the Activation Coordinator service running on the deployed host. Therefore, WS-AT transactions or WS-BA activities created by a locally-deployed client application are supplied with a context which identifies the Registration Service running on the client's machine. Any Web Services invoked by the client are coordinated by the Transaction Protocol services running on the client's host. This is the case whether the Web Services are running locally or remotely. Such a configuration is called local coordination.

You can reconfigure this setting globally for all clients, causing context creation requests to be redirected to an Activation Coordinator Service running on a remote host. Normally, the rest of the coordination process is executed from the remote host. This configuration is called stand-alone coordination.

Reasons for Choosing a Stand-Alone Coordinator

Efficiency: if a client application invokes Web Services on a remote JBoss Application Server, coordinating the transaction from the remote server might be more efficient, since the protocol-specific messages between the coordinator and the participants do not need to travel over the network.
Reliability: if the coordinator service runs on a dedicated host, there is no danger of failing applications or services affecting the coordinator and causing failures for unrelated transactions.
A third reason might be to use a coordination service provided by a third party vendor.

8.2. Configuring the Activation Coordinator

The XTS service archive used to deploy XTS to the JBoss Application Server includes a bean configuration file, xts-jboss-beans.xml, in its META-INF directory. This file specifies configuration values which the JBoss Application Server injects into the beans, and which define the XTS runtime configuration when it starts the XTS service. The location of the XTS coordinator is defined by values injected into the WSCEnvironmentBean. Example 8.1, “Example xts-jboss-beans.xml configuration settings” shows a fragment of this file which details serveral possible configuration options.

Example 8.1. Example xts-jboss-beans.xml configuration settings


<bean name="XTS:WSCEnvironmentBean" class="org.jboss.jbossts.xts.environment.WSCEnvironmentBean">

  <constructor factoryClass="org.jboss.jbossts.xts.environment.XTSPropertyManager"

               factoryMethod="getWSCEnvironmentBean"/>

  <!-- we need the bind address and port from jboss web -->

  <depends>jboss.web:service=WebServer</depends>

  <depends>jboss:service=TransactionManager</depends>

  . . .

  <!--

      if you want to use a coordinator running in a remote JVM then you can

      simply configure the URL. This will also be necessary if you are using

      a non-JBoss coordination service.

      

      <property name="coordinatorURL11">

         <value>http://10.0.1.99:8080/ws-c11/ActivationService</value>

      </property>

  -->

  <!--

      if you are using a remote JBoss XTS coordinator you can just redefine

      the scheme, address, port or path to the desired value and the ones

      left undefined will be defaulted to use the standard XTS coordinator

      URL elements. So, for example if your XTS coordinator services is

      deployed in another AS on host myhost.myorg.com you only need to define

      property coordinatorAddress11 to have value myhost.myorg.com and the

      coordinator address used by clients will be

      http://myhost.myorg.com:8080/ws-c11/ActivationService n.b. if the remote

      machine is using JBoss XTS then you won't want to redefine the port

      unless you have monkeyed around with the port config in the remote AS. also

      you won't need to change the path unless you have tweaked the deployment

      descriptor to relocate the XTS services.



      <property name="coordinatorScheme11">

         <value>http</value>

      </property>

      <property name="coordinatorAddress11">

         <value>10.0.1.99</value>

      </property>

      <property name="coordinatorPort11">

         <value>9191</value>

      </property>

      <property name="coordinatorPath11">

         <value>ws-c11/ActivationService</value>

      </property>

  -->

</bean>

The simplest way to configure a stand-alone coordinator is to provide a complete URL for the remote coordinator. The example shows how the bean property with name coordinatorURL11 would be configured with value http://10.0.1.99:8080/ws-c11/ActivationService.

You can also specify the individual elements of the URL using the properties coordinatorScheme11, coordinatorAddress11, and so forth. These values only apply when the coordinatorURL11 is not set. The URL is constructed by combining the specified values with default values for any missing elements. This is particularly useful for two specific use cases.

The first case is where the client is expected to use an XTS coordinator deployed in another JBoss Application Server. If, for example, this JBoss Application Server is bound to address 10.0.1.99, setting property coordinatorAddress11 to 10.0.1.99 is normally all that is required to configure the coordinator URL to idenitfy the remote JBoss Application Server's coordination service. If the Web service on the remote JBoss Application Server were reset to9090 then it would also be necessary to set property coordinatorPort11 to this value.
The second common use case is where communications between client and coordinator, and between participant and coordinator, must use secure connections. If property coordinatorScheme11 is set to value https, the client's request to begin a transaction is sent to the coordinator service over a secure https connection. The XTS coordinator and participant services will ensure that all subsequent communications between coordinator and client or coordinator and web services also employ secure https connections. Note that this requires configuring the trust stores in the JBoss Application Server running the client, coordinator and participant web services with appropriate trust certificates.

If none of the above properties is specified, the coordinator URL uses the http scheme. The coordinator address and port are obtained from the host address and port configured for the JBoss Web service. These default to localhost and 8080, respectively. The URL path takes the value shown in Example 8.1, “Example xts-jboss-beans.xml configuration settings”.

You can configure the bean properties defined above by setting System properties on the Java command line. This is useful in pre-deployment testing. So, for example, command line option -Dorg.jboss.jbossts.xts11.coordinator.address=10.0.1.99 resets property coordinatorAddress11. System properties do not override property values configured in the configuration file. The following table identifies the System properties which can be configured.

Note

The property names have been abbreviated in order to fit into the table. They should each start with prefix org.jboss.jbossts.xts11.coordinator.

Table 8.1. Command-Line Options Passed with the -D Parameter, Ordered by Priority