
JBossTS 4.6.GA is designed for use standalone or with JBossAS 5.1.0
It is not suitable for use with earlier versions of JBossAS.

The installation procedure has changed from earlier releases due to the move from
a JMX configuration style to the POJO microcontainer used by AS 5.x, packaging and config files changes.
Upgrading users should take care to read the steps below carefully.

Installing JBossTS 4.6.GA JTA into JBossAS 5.1.0
------------------------------------------------------------

The application server ships with a earlier release of JBossTS JTA as its default transaction manager.
To update the JTA the following steps are necessary:

 - Replace JBossAS  common/lib/jbossjta.jar and common/lib/jbossjta-integration.jar with the newer
versions from JBossTS lib

 - Replace JBossAS  common/lib/jbossts-common.jar with the newer version from JBossTS lib/ext/

 - Remove JBossAS  server/xxx/conf/jbossjta-properties.xml if present
 
 - Copy JBossTS  etc/jbossts-properties.xml to JBossAS server/xxx/conf


Installing JBossTS 4.6.GA JTS into JBossAS 5.0.0.GA
------------------------------------------------------------

The JTS binaries are now bundled with JBossAS. To change the default JTA to JTS in JBossAS,
follow the instructions in the app server's docs/examples/transactions/README.txt file.

To upgrade the version of JTS bundled with JBossAS to the one from this JBossTS release,
locate and replace jbossjts.jar, jbossjts-integration.jar, jbossjts-jacorb.jar,
jbossts-common.jar and jbossjts-properties.jar in the app server tree with the versions
from this release bundle. Note that you must still install the JTS per the above instructions
for it to take effect and that if you upgrade after installation there may be multiple
copies of the files in the AS tree that need replacing.



                         Web Services Transactions
                         -------------------------

The Web Services Transactions component (XTS) binary now ships within JBossAS. It is recommended to install the
bundled version by copying $JBOSS_HOME/docs/examples/transactions/jbossxts.sar to $JBOSS_HOME/server/<xxx>/deploy/

Build and deploy from source
----------

In JBossAS 5.x XTS is deployed as a service archive (sar) which can be
deployed with either the JTA or JTS Transaction Service
implementation. This sar implements both the participant and the
coordinator services required to support web service transactions. By
default the services deployed in the sar implement both the 1.0 and
1.1 OASIS WSCOOR, WSAT and WSBA protocols. It is also possible to
build the sar so that only the 1.0 or the 1.1 implementations are
deployed (see the build script in XTS/sar for details).

The default XTS build produces a service archive which contains both
sets of partipant and coordinator services configured to support
transactional web service invocations within a single JVM. The services
employ the JBoss Application Server bind address and JBoss Web listener
port which default to address localhost and port 8080. This default build
is suitable for demonstrating the functionality of XTS using the supplied
demo programs. One of the demos displays use of the WS 1.1 protocols when
invoking web services via JaxWS. The other displays use of the WS 1.0
protcols when invoking web services via JaxRPC.

To build the default sar, cd to the XTS root directory and invoke the
ant build script

  cd <JBossTSDir>/XTS
  ant clean install

Note that this assumes you have already built the JBossTS JTA or JBossTS JTS
release in directory <JBossTSDir> and deployed it into your
application server. Although JBossAS contains a JBossTS JTA installation
by default, this should be upgraded to exactly match the version of XTS if required.

The newly built sar will be located in the installed XTS tree:

  <JBossTSDir>/xts-install/sar/jbossxts.sar

Deploy this sar by copying it into the relevant JBossAS server deploy
directory

  cp <JBossTSDir>/xts-install/sar/jbossxts.sar <JBossDir>/server/<xxx>/deploy

Alternatively, you can set the environmwent variable JBOSS_HOME and
then deploy using the build script in the XTS/sar subdirectory:

  setenv JBOSS_HOME <JBossDir>
  cd <JBossTSDir>/XTS/sar
  ant deploy

This will install the sar in subdirectory server/default/deploy of
$JBOSS_HOME

Stand-alone coordinator configuration
---------------------------------

The JBoss AS command line can be used to disable use of the local
coordinator services and direct the participants to negotiate with
a remote coordinator located in a different JBoss application server.

The -D option can be used to set a property defining an absolute URL
for the coordinator service to be used by XTS clients. So, for example,
the 1.0 and 1.1 implementations would be configured independently by
providing, respectively, the following command line arguments

  -Dorg.jboss.jbossts.xts.coordinatorURL=http://foo.example.com:8080/ws-c10/soap/ActivationCoordinator

  -Dorg.jboss.jbossts.xts11.coordinatorURL=http://bar.example.com:9090/ws-c11/ActivationService

This would cause all XTS 1.0 clients to negotiate with the coordinator
services deployed on host foo.example.com via port 8080 and all XTS 1.1
clients to negotiate with the coordinator services deployed on host
bar.example.com via port 9090. The URL paths supplied are appropriate
to a JBoss AS with XTS deployed. These will need to be redefined if
another vendor's coordination service implementation is being used.

It is also possible to respecify individual components of the coordinator
URL using the following property settings

    org.jboss.jbossts.xts.coordinator.host
    org.jboss.jbossts.xts.coordinator.port
    org.jboss.jbossts.xts.coordinator.path

    org.jboss.jbossts.xts11.coordinator.host
    org.jboss.jbossts.xts11.coordinator.port
    org.jboss.jbossts.xts11.coordinator.path

The host and port default to the server bind address and the JBoss Web
listener port. The paths default to the values supplied in the example
above.

It is possible to rebuild the XTS sar so that it employs a stand-alone
coordinator without the need to supply arguments on the AS command line.

So, for example,

  setenv JBOSS_HOME <JBossDir>
  cd <JBossTSDir>/XTS/sar
  ant clean install
  cd sar
  ant deploy -Dcoordinator.hostname=foo.example.com \
             -Dcoordinator.port=9090

will build and deploy a sar which, by default will direct clients
to the coordinator located in a JBoss AS instance running on host
foo.example.com and configured to use port 9090 as the JBoss Web
listener port. It is not possible to redefine the coordinator URL
path using this mechanism.

Configuration of a remote coordinator provided by another XTS
implementation is available by editing the configuration files in
directory XTS/xts-install/conf and setting an appropriate URL for
the coordinator URL property. The value specified for property
org.jboss.jbossts.xts.coordinatorURL in file wstx.xml is used by
the 1.0 protocol implementation. The value specified for property
org.jboss.jbossts.xts11.coordinatorURL in file wstx11.xml is used
by the 1.1 protocol implementation.


XTS Trailmap Documentation
--------------------------

We recommend that you run through the XTS trailmap in order to
understand how to build and use transaction-aware Web Services, before
deciding whether or not to use a stand alone coordinator service. The
trail map web pages are located in the htdocs subdirectory of the XTS
installed tree.

                         Embedded Tools
                         --------------

Deployment
----------

Embedded tools is an applet that runs in proccess with the AS which
includes an interface for inspecting transactions. It is deployed as
a service archive and can be found in the product install directory:
<install directory>/bin/jbossts-tools.sar

To start the tool simply copy the sar to the AS deploy directory, open
the JMX console (http://.../jmx-console) and click on the service named
EmbeddedTools.

