[jboss-svn-commits] JBL Code SVN: r35439 - labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Programmers_Guide/en-US.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Oct 5 19:05:25 EDT 2010
Author: misty at redhat.com
Date: 2010-10-05 19:05:25 -0400 (Tue, 05 Oct 2010)
New Revision: 35439
Modified:
labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Programmers_Guide/en-US/Stand_Alone_Coordination.xml
Log:
(Re?)-added changes to Stand-Alone Coordination for XTS.
Modified: labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Programmers_Guide/en-US/Stand_Alone_Coordination.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Programmers_Guide/en-US/Stand_Alone_Coordination.xml 2010-10-05 22:55:13 UTC (rev 35438)
+++ labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Programmers_Guide/en-US/Stand_Alone_Coordination.xml 2010-10-05 23:05:25 UTC (rev 35439)
@@ -16,103 +16,177 @@
<section>
<title>Introduction</title>
<para>
- 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 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.
</para>
<para>
- 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 <firstterm>local coordination</firstterm>.
+ 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
+ <firstterm>local coordination</firstterm>.
</para>
<para>
- 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 <firstterm>stand-alone coordination</firstterm>.
+ 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 <firstterm>stand-alone coordination</firstterm>.
</para>
<itemizedlist>
<title>Reasons for Choosing a Stand-Alone Coordinator</title>
<listitem>
- <para>
- Efficiency: if a client application invokes Web Services on a remote &APPSERVER;, 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.
- </para>
+ <para>
+ Efficiency: if a client application invokes Web Services on a remote &APPSERVER;, 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.
+ </para>
</listitem>
<listitem>
- <para>
- 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.
- </para>
+ <para>
+ 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.
+ </para>
</listitem>
<listitem>
- <para>
- A third reason might be to use a coordination service provided by a third party vendor.
- </para>
+ <para>
+ A third reason might be to use a coordination service provided by a third party vendor.
+ </para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Configuring the Activation Coordinator</title>
+
<para>
- The simplest way to configure a stand-alone coordinator is to provide a command line switch when starting the &APPSERVER;. The <parameter>-D</parameter> option specifies a setting for a System property. Several configuration options can be enabled, taking effect in <xref linkend="list-option-priority" />.
+ The XTS service archive used to deploy XTS to the &APPSERVER; includes a bean configuration file,
+ <filename>xts-jboss-beans.xml</filename>, in its <filename>META-INF</filename> directory. This file specifies
+ configuration values which the &APPSERVER; 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
+ <classname>WSCEnvironmentBean</classname>. <xref linkend="example-xts-jboss-beans-wsc-environment-bean.xml" />
+ shows a fragment of this file which details serveral possible configuration options.
</para>
+ <example id="example-xts-jboss-beans-wsc-environment-bean.xml">
+ <title>Example <filename>xts-jboss-beans.xml</filename> configuration settings</title>
+ <programlisting language="XML" role="XML"><xi:include href="extras/example-xts-jboss-beans-wsc-environment-bean.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"
+ /></programlisting>
+ </example>
- <table id="list-option-priority">
- <title>Command-Line Options Passed with the <parameter>-D</parameter> Parameter, Ordered by Priority</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry><para>Category</para></entry>
- <entry><para>Property</para></entry>
- <entry><para>Format</para></entry>
- <entry><para>Description</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>Absolute URL</para></entry>
- <entry><para><varname>org.jboss.jbossts.xts11.coordinatorURL</varname></para></entry>
- <entry><para><ulink url="http://coord.host:coord.port/ws-c11/ActivationService" /></para></entry>
- <entry>
- <para>
- The value assigned to these URLs depends upon the configuration of the remote coordinator host. The sample values listed with the property names are appropriate when the coordinator is another JBoss Transaction Service XTS service. Substitute the <replaceable>coord.host</replaceable> and <replaceable>coord.port</replaceable> with the appropriate values for the &APPSERVER; instance running the Activation Coordinator service.
- </para>
- </entry>
- </row>
- <row>
- <entry><para>Coordinator Host, Port, and Path</para></entry>
- <entry>
- <para><varname>org.jboss.jbossts.xts11.coordinator.host</varname></para>
- <para><varname>org.jboss.jbossts.xts11.coordinator.port</varname></para>
- <para><varname>org.jboss.jbossts.xts11.coordinator.path</varname></para>
- </entry>
- <entry>
- <para><replaceable>server.bind.address</replaceable></para>
- <para><replaceable>jboss.web.bind.port</replaceable></para>
- <para><replaceable>ws-c11/ActivationService</replaceable></para>
- </entry>
- <entry>
- <para>
- If you set any of these three components, the coordinator URL is constructed using whichever of the component values is defined and substituting the default values specified for any undefined components. The values <replaceable>server.bind.address</replaceable> and <replaceable>jboss.web.bind.port</replaceable> represent the server bind address and the web service listener port obtained either from the application server command-line or the server configuration files.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <!-- Community version only
- <section>
- <title>Build-Time Default Coordinator Configuration</title>
<para>
- You can reset the default coordinator host name and port used by the XTS service archive by defining the properties coordinator.hostname and coordinator.port on the build command-line when building the service archive. See the service archive build script in the sar directory of the XTS source code for further details.
+ 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 <varname>coordinatorURL11</varname> would be
+ configured with value <literal>http://10.0.1.99:8080/ws-c11/ActivationService</literal>.
</para>
+
<para>
- You can also redefine the default absolute URL employed by the XTS service by modifying the values specified in the WSTX configuration files included in the service archive. The 1.0 specification URL is defined in the <filename>wstx.xml</filename> file, and the 1.1 specification URL is defined in the <filename>wstx11.xml</filename> file. You can redefine the values either by editing the service archive supplied in the <filename>sar</filename> directory of the XTS install tree, or by modifying the source files located in the <filename>config</filename> directory of the XTS source tree.
+ You can also specify the individual elements of the URL using the properties
+ <varname>coordinatorScheme11</varname>, <varname>coordinatorAddress11</varname>, and so forth. These values only
+ apply when the <varname>coordinatorURL11</varname> 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.
</para>
--->
- <!--
- <section>
- <title>The XTS Service Archive</title>
+ <orderedlist>
+ <listitem>
+ <para>
+ The first case is where the client is expected to use an XTS coordinator deployed in another &APPSERVER;. If,
+ for example, this &APPSERVER; is bound to address <literal>10.0.1.99</literal>, setting property
+ <varname>coordinatorAddress11</varname> to <literal>10.0.1.99</literal> is normally all that is required to
+ configure the coordinator URL to idenitfy the remote &APPSERVER;'s coordination service. If the Web service on
+ the remote &APPSERVER; were reset to<literal>9090</literal> then it would also be necessary to set property
+ <varname>coordinatorPort11</varname> to this value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The second common use case is where communications between client and coordinator, and between participant and
+ coordinator, must use secure connections. If property <varname>coordinatorScheme11</varname> is set to value
+ <literal>https</literal>, 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 &APPSERVER; running the client,
+ coordinator and participant web services with appropriate trust certificates.
+ </para>
+ </listitem>
+ </orderedlist>
<para>
- The XTS <firstterm>service archive (SAR)</firstterm> must be deployed on hosts running client applications and participant Web Services, as well as on the stand-alone coordinator host. Clients and participants need access to the libraries deployed with XTS. These libraries are bundled into the SAR. However, clients and participants also need the ability to receive transaction management messages dispatched from the coordinator host. The XTS SAR provides implementations of client-side and participant-side listeners for this purpose. Although these services can be deployed separately from the coordinator-side service listeners and implementation, they are all bundled into a single SAR for simplicity.
+ If none of the above properties is specified, the coordinator URL uses the <literal>http</literal> scheme. The
+ coordinator address and port are obtained from the host address and port configured for the JBoss Web
+ service. These default to <literal>localhost</literal> and <literal>8080</literal>, respectively. The URL path
+ takes the value shown in <xref linkend="example-xts-jboss-beans-wsc-environment-bean.xml" />.
</para>
+ <para>
+ 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
+ <option>-Dorg.jboss.jbossts.xts11.coordinator.address=10.0.1.99</option> resets property
+ <varname>coordinatorAddress11</varname>. System properties do not override property values configured in the
+ configuration file. The following table identifies the System properties which can be configured.
+ </para>
+
+ <note>
+ <para>
+ The property names have been abbreviated in order to fit into the table. They should each start with prefix
+ <literal>org.jboss.jbossts.xts11.coordinator</literal>.
+ </para>
+ </note>
+
+
+ <table id="list-option-priority">
+ <title>Command-Line Options Passed with the <parameter>-D</parameter> Parameter, Ordered by Priority</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry><para>Category</para></entry>
+ <entry><para>Property</para></entry>
+ <entry><para>Format</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>Absolute URL</para></entry>
+ <entry><para><varname>...coordinatorURL</varname></para></entry>
+ <entry><para><ulink url="http://coord.host:coord.port/ws-c11/ActivationService" /></para></entry>
+ </row>
+ <row>
+ <entry><para>Coordinator Scheme, Host, Port, and Path</para></entry>
+ <entry>
+ <para><varname>...coordinator.scheme</varname></para>
+ <para><varname>...coordinator.address</varname></para>
+ <para><varname>...coordinator.port</varname></para>
+ <para><varname>...coordinator.path</varname></para>
+ </entry>
+ <entry>
+ <para><literal>http</literal></para>
+ <para><replaceable>server.bind.address</replaceable></para>
+ <para><replaceable>jboss.web.bind.port</replaceable></para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</section>
+
+ <!-- Community version only <section> <title>Build-Time Default Coordinator Configuration</title> <para> You can reset
+ the default coordinator host name and port used by the XTS service archive by defining the properties
+ coordinator.hostname and coordinator.port on the build command-line when building the service archive. See the
+ service archive build script in the sar directory of the XTS source code for further details. </para> <para> You
+ can also redefine the default absolute URL employed by the XTS service by modifying the values specified in the
+ WSTX configuration files included in the service archive. The 1.0 specification URL is defined in the
+ <filename>wstx.xml</filename> file, and the 1.1 specification URL is defined in the
+ <filename>wstx11.xml</filename> file. You can redefine the values either by editing the service archive supplied
+ in the <filename>sar</filename> directory of the XTS install tree, or by modifying the source files located in
+ the <filename>config</filename> directory of the XTS source tree. </para>
-->
+ <!--
+ <section> <title>The XTS Service Archive</title> <para> The XTS <firstterm>service archive (SAR)</firstterm> must
+ be deployed on hosts running client applications and participant Web Services, as well as on the stand-alone
+ coordinator host. Clients and participants need access to the libraries deployed with XTS. These libraries are
+ bundled into the SAR. However, clients and participants also need the ability to receive transaction management
+ messages dispatched from the coordinator host. The XTS SAR provides implementations of client-side and
+ participant-side listeners for this purpose. Although these services can be deployed separately from the
+ coordinator-side service listeners and implementation, they are all bundled into a single SAR for simplicity.
+ </para> </section>
+ -->
</chapter>
More information about the jboss-svn-commits
mailing list