[jboss-cvs] JBossAS SVN: r100672 - in projects/docs/enterprise: EWP_5.0/Administration_And_Configuration_Guide/en-US and 1 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Sun Feb 7 20:21:01 EST 2010
Author: laubai
Date: 2010-02-07 20:21:00 -0500 (Sun, 07 Feb 2010)
New Revision: 100672
Modified:
projects/docs/enterprise/5.0/Release_Notes_GA/en-US/Book_Info.xml
projects/docs/enterprise/5.0/Release_Notes_GA/en-US/Revision_History.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Revision_History.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Transactions.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Virtual_Deployment_Framework.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Web_Services.xml
projects/docs/enterprise/EWP_5.0/RESTEasy/en-US/RESTEasy_Reference_Guide.ent
Log:
Removed 5.0.1 folder.
Modified: projects/docs/enterprise/5.0/Release_Notes_GA/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/5.0/Release_Notes_GA/en-US/Book_Info.xml 2010-02-07 23:07:07 UTC (rev 100671)
+++ projects/docs/enterprise/5.0/Release_Notes_GA/en-US/Book_Info.xml 2010-02-08 01:21:00 UTC (rev 100672)
@@ -6,7 +6,7 @@
<title>Release Notes</title>
<subtitle>for Use with JBoss Enterprise Application Platform 5.0.0</subtitle>
<edition>1.0</edition>
- <pubsnumber>4.3</pubsnumber>
+ <pubsnumber>4.9</pubsnumber>
<productname>JBoss Enterprise Application Platform</productname>
<productnumber>5.0.0</productnumber>
<abstract>
Modified: projects/docs/enterprise/5.0/Release_Notes_GA/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/5.0/Release_Notes_GA/en-US/Revision_History.xml 2010-02-07 23:07:07 UTC (rev 100671)
+++ projects/docs/enterprise/5.0/Release_Notes_GA/en-US/Revision_History.xml 2010-02-08 01:21:00 UTC (rev 100672)
@@ -7,8 +7,8 @@
<simpara>
<revhistory>
<revision>
- <revnumber>1.6</revnumber>
- <date>Wed Dec 23 2009</date>
+ <revnumber>1.9</revnumber>
+ <date>Mon Jan 25 2010</date>
<author>
<firstname>Laura</firstname>
<surname>Bailey</surname>
@@ -16,7 +16,7 @@
</author>
<revdescription>
<simplelist>
- <member>JBoss WS CXF added.</member>
+ <member>JBoss mod_cluster added.</member>
</simplelist>
</revdescription>
</revision>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.xml 2010-02-07 23:07:07 UTC (rev 100671)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.xml 2010-02-08 01:21:00 UTC (rev 100672)
@@ -29,7 +29,7 @@
<!-- <xi:include href="Cache.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
<xi:include href="Transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- <xi:include href="JGroups.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
- <xi:include href="Remoting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<!-- <xi:include href="Remoting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
<!-- <xi:include href="Messaging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
<xi:include href="Alternative_DBs.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml 2010-02-07 23:07:07 UTC (rev 100671)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml 2010-02-08 01:21:00 UTC (rev 100672)
@@ -7,7 +7,7 @@
<subtitle>for JBoss Enterprise Web Platform 5.0</subtitle>
<edition>1</edition>
<issuenum>1</issuenum>
- <pubsnumber>1.2</pubsnumber>
+ <pubsnumber>1.4</pubsnumber>
<productname>JBoss Enterprise Web Platform</productname>
<productnumber>5.0</productnumber>
<!-- <pubdate>, 2009</pubdate> -->
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml 2010-02-07 23:07:07 UTC (rev 100671)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml 2010-02-08 01:21:00 UTC (rev 100672)
@@ -243,14 +243,14 @@
</para>-->
</listitem>
</varlistentry>
- <varlistentry>
+ <!--<varlistentry>
<term><varname>jboss.vfs.forceVfsJar</varname></term>
<listitem>
<para>
When <literal>true</literal>, implements old JAR handling. This value is false by default. Old JAR handling was deprecated in favor of new ZIP handling code.
</para>
</listitem>
- </varlistentry>
+ </varlistentry>-->
<varlistentry>
<term><varname>jboss.vfs.forceNoReaper</varname></term>
<listitem>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Revision_History.xml 2010-02-07 23:07:07 UTC (rev 100671)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Revision_History.xml 2010-02-08 01:21:00 UTC (rev 100672)
@@ -8,8 +8,8 @@
<simpara>
<revhistory>
<revision>
- <revnumber>2.3</revnumber>
- <date>Wed Feb 03 2010</date>
+ <revnumber>2.4</revnumber>
+ <date>Fri Feb 05 2010</date>
<author>
<firstname>Laura</firstname>
<surname>Bailey</surname>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Transactions.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Transactions.xml 2010-02-07 23:07:07 UTC (rev 100671)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Transactions.xml 2010-02-08 01:21:00 UTC (rev 100672)
@@ -121,405 +121,416 @@
<para>The following configuration properties can also be specified in
<filename>jbossts-properties.xml</filename> may also be of interest:</para>
- <!--hajime-->
- <itemizedlist>
- <listitem>
- <para>com.arjuna.common.util.logging.DebugLevel</para>
- <para>This setting determines the internal log threshold for
- the transaction manager codebase. It is independent
- of the server's wider log4j logging configuration
- and represents an additional hurdle that log
- messages must pass before being printed. The default
- value is “0x00000000” i.e. no debug logging. INFO
- and WARN messages will still be printed by default.
- This provides optimal performance. The value
- “0xffffffff” should be used when full debug logging
- is required. This is very verbose and will result in
- large log files. Log messages that pass the internal
- DebugLevel check will be passed to the server's
- logging system for further processing. Thus it may
- also be necessary to set appropriate configuration
- for “com.arjuna” code in the
- server/[name]/conf/jboss-log4j.xml file. Note that
- whilst a value of “0xffffffff” may be left in place
- permanently and the log4j settings used to turn
- logging on or off, this is less performant than
- using the internal DebugLevel checking.</para>
- </listitem>
- <listitem>
- <para>com.arjuna.ats.arjuna.coordinator.commitOnePhase</para>
- <para>This setting determines if the transaction manager
- will automatically apply the one-phase commit
- optimization to the transaction completion protocol
- in cases where only a single resource is registered
- with the transaction. It is enabled (“YES”) by
- default to provide optimal performance, since no
- transaction log write is necessary in such cases.
- Some resource managers may not be compatible with
- this optimization and it is occasionally necessary
- to disable it. This can be done by changing the
- value to “NO”.</para>
- </listitem>
- <listitem>
- <para>com.arjuna.ats.arjuna.objectstore.transactionSync</para>
- <para>This setting controls the flushing of transaction logs
- to disk during the transaction termination. It is
- enabled (“ON”) by default, which results in a
- FileDescriptor.sync call for each committing
- transaction. This is required to provide recovery
- guarantees and hence ACID properties. If the
- applications running in the server can tolerate data
- inconsistency or loss, greater performance may be
- achieved by disabling this behavior by setting the
- property value to “OFF”. This is not recommended –
- it is usually preferable to recraft such
- applications to avoid using the transaction manager
- entirely.</para>
- </listitem>
- <listitem>
- <para>com.arjuna.ats.arjuna.xa.nodeIdentifier and
- com.arjuna.ats.jta.xaRecoveryNode</para>
- <para>These properties determine the behavior of the
- transaction recovery system. Correct configuration
- is essential to ensure transactions are resolved
- correctly in the event of a server crash and
- restart. See the crash recovery section below for
- details.</para>
- <para>Additional properties that may be added to the
- jbossts-properties.xml include the following. Care
- should be taken to place these in the appropriate
- section of the file, or they may not be correctly
- processed.</para>
- </listitem>
- <listitem>
- <para>com.arjuna.ats.arjuna.coordinator.enableStatistics</para>
- <para>This property enables the gathering of transaction
- statistics, which may be viewed via methods on the
- TransactionManagerService bean or, more commonly,
- its corresponding JMX MBean. This option is disabled
- by default, as the additional locking needed to
- record statistics accurately may cause a slight
- performance impact. Thus the statistics getter
- methods will thus normally return zero values. To
- enable the option, set its value to “YES” in the
- properties file.</para>
- </listitem>
- </itemizedlist>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>com.arjuna.common.util.logging.DebugLevel</varname></term>
+ <listitem>
+ <para>This setting determines the internal log threshold for
+ the transaction manager codebase. It is independent
+ of the server's wider log4j logging configuration
+ and represents an additional hurdle that log
+ messages must pass before being printed. The default
+ value is <literal>0x00000000</literal>, that is, no debug logging. <literal>INFO</literal>
+ and <literal>WARN</literal> messages will still be printed by default.
+ This provides optimal performance. The value
+ <literal>0xffffffff</literal> should be used when full debug logging
+ is required. This is very verbose and will result in
+ large log files. Log messages that pass the internal
+ DebugLevel check will be passed to the server's
+ logging system for further processing. Thus it may
+ also be necessary to set appropriate configuration
+ for <literal>com.arjuna</literal> code in the
+ <filename>server/$PROFILE/conf/jboss-log4j.xml</filename> file. Note that
+ whilst a value of <literal>0xffffffff</literal> may be left in place
+ permanently and the log4j settings used to turn
+ logging on or off, this is less performant than
+ using the internal <classname>DebugLevel</classname> checking.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>com.arjuna.ats.arjuna.coordinator.commitOnePhase</varname></term>
+ <listitem>
+ <para>This setting determines if the transaction manager
+ will automatically apply the one-phase commit
+ optimization to the transaction completion protocol
+ in cases where only a single resource is registered
+ with the transaction. It is enabled (set to <literal>YES</literal>) by
+ default to provide optimal performance, since no
+ transaction log write is necessary in such cases.
+ Some resource managers may not be compatible with
+ this optimization and it is occasionally necessary
+ to disable it. This can be done by changing the
+ value to <literal>NO</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>com.arjuna.ats.arjuna.objectstore.transactionSync</varname></term>
+ <listitem>
+ <para>This setting controls the flushing of transaction logs
+ to disk during the transaction termination. It is
+ enabled (set to <literal>ON</literal>) by default, which results in a
+ FileDescriptor.sync call for each committing
+ transaction. This is required to provide recovery
+ guarantees and hence ACID properties. If the
+ applications running in the server can tolerate data
+ inconsistency or loss, greater performance may be
+ achieved by disabling this behavior by setting the
+ property value to “OFF”. This is not recommended –
+ it is usually preferable to recraft such
+ applications to avoid using the transaction manager
+ entirely.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>com.arjuna.ats.arjuna.xa.nodeIdentifier</varname> and
+ <varname>com.arjuna.ats.jta.xaRecoveryNode</varname></term>
+ <listitem>
+ <para>These properties determine the behavior of the
+ transaction recovery system. Correct configuration
+ is essential to ensure transactions are resolved
+ correctly in the event of a server crash and
+ restart. See the crash recovery section that follows for
+ details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>com.arjuna.ats.arjuna.coordinator.enableStatistics</varname></term>
+ <listitem>
+ <para>This property enables the gathering of transaction
+ statistics, which may be viewed via methods on the
+ <classname>TransactionManagerService</classname> bean or, more commonly,
+ its corresponding JMX MBean. This option is disabled
+ by default, as the additional locking needed to
+ record statistics accurately may cause a slight
+ performance impact. Thus the statistics getter
+ methods will thus normally return zero values. To
+ enable the option, set its value to <literal>YES</literal> in the
+ properties file.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
<section>
- <title>Transactional Resources</title>
- <para>The transaction manager coordinates the update of state via XAResource
- implementations, which are provided by the various resource managers. In
- most instances, resource managers will be databases, message queues or 3rd
- party JCA resource adapters. The list of JDBC database drivers and servers
- certified for use with JBoss Enterprise Web Platform can be found on the redhat.com website. In
- addition there is a reasonable probability of any driver that complies with
- the relevant standards functioning correctly. However, interpretation of the
- XA specification does differ from one vendor to another, as does quality of
- driver code. For maximum surety in transactional applications, thorough
- testing is essential, especially with regard to recovery behavior. </para>
- <para>Database connection pools configured via the application server's -ds.xml
- files using <![CDATA[<xa-datasource>]]> (see chapter 11) will automatically
- interact with the transaction manager. i.e. Connections obtained by looking
- up such datasource in JNDI and calling getConnection will automatically
- participate correctly in an ongoing transaction. This is the dominant use
- case and should be preferred where transactional guarantees for data access
- are required. For cases where the database cannot support XA transactions,
- it is also feasible to deploy a connection pool using
- <![CDATA[<local-xa-datasource>]]> Such datasources participate in the
- managed transaction using the last resource commit optimization (see below)
- and as such provide more limited transactional guarantees. Applications
- using this approach should be aware of the limitations and implemented
- accordingly. Connections obtained from a <![CDATA[<no-tx-datasource>]]> will
- not interact with the transaction manager and any work done on such
- connections must be explicitly committed or rolled back by the application
- via the JDBC API.</para>
- <para>Many databases require additional configuration if they are to be used as XA
- resource managers. For example, MS SQL Server requires configuration of the
- DTC service and installation of a server side component of the JDBC drivers.
- Some versions of Oracle similarly require a server side package to be
- installed in the database instance. PostgreSQL installations may require an
- alteration to the number of outstanding transactions they permit – the
- default is normally too low for production usage. MySQL has significant
- limitations on its XA implementation and is not recommended for use in an XA
- transaction. If it is used, the InnoDB storage engine must be configured.
- Please consult your DBA or database documentation for further product
- specific information. In addition, it is important to take any further
- database configuration steps needed to support XA recovery, see the recovery
- section below.</para>
- <para>JBoss Messaging provides an XA aware driver and can participate in XA
- transactions. This is also the case for many 3rd party message queuing (JMS)
- products, subject to the same caveats on product specific configuration as
- with databases.</para>
+ <title>Transactional Resources</title>
+ <para>The transaction manager coordinates the update of state via <classname>XAResource</classname>
+ implementations, which are provided by the various resource managers. In
+ most instances, resource managers will be databases, message queues or third-party
+ JCA resource adapters. The list of JDBC database drivers and servers
+certified for use with JBoss Enterprise Web Platform can be found on the redhat.com website. In
+ addition there is a reasonable probability of any driver that complies with
+ the relevant standards functioning correctly. However, interpretation of the
+ XA specification does differ from one vendor to another, as does quality of
+ driver code. For maximum surety in transactional applications, thorough
+ testing is essential, especially with regard to recovery behavior. </para>
+ <para>Database connection pools configured via the application server's <filename>*-ds.xml</filename>
+ files using <literal><![CDATA[<xa-datasource>]]></literal> will automatically
+ interact with the transaction manager. Connections obtained by looking
+ up such datasource in JNDI and calling <methodname>getConnection</methodname> will automatically
+ participate correctly in an ongoing transaction. This is the dominant use
+ case and should be preferred where transactional guarantees for data access
+ are required. For cases where the database cannot support XA transactions,
+ it is also feasible to deploy a connection pool using
+ <literal><![CDATA[<local-xa-datasource>]]></literal> Such datasources participate in the
+ managed transaction using the last resource commit optimization (see below)
+ and as such provide more limited transactional guarantees. Applications
+ using this approach should be aware of the limitations and implemented
+ accordingly. Connections obtained from a <literal><![CDATA[<no-tx-datasource>]]></literal> will
+ not interact with the transaction manager and any work done on such
+ connections must be explicitly committed or rolled back by the application
+ via the JDBC API.</para>
+ <para>Many databases require additional configuration if they are to be used as XA
+ resource managers. For example, MS SQL Server requires configuration of the
+ DTC service and installation of a server side component of the JDBC drivers.
+ Some versions of Oracle similarly require a server side package to be
+ installed in the database instance. PostgreSQL installations may require an
+ alteration to the number of outstanding transactions they permit – the
+ default is normally too low for production usage. MySQL has significant
+ limitations on its XA implementation and is not recommended for use in an XA
+ transaction. If it is used, the InnoDB storage engine must be configured.
+ Please consult your database administrator or database documentation for further
+ product-specific information. In addition, it is important to take any further
+ database configuration steps needed to support XA recovery, see the recovery
+ section below.</para>
+ <!--<para>JBoss Messaging provides an XA aware driver and can participate in XA
+ transactions. This is also the case for many third-party message queuing (JMS)
+ products, subject to the same caveats on product specific configuration as
+ with databases.</para>-->
</section>
<section>
- <title>Last Resource Commit Optimization (LRCO)</title>
- <para>Although the XA transaction protocol is designed to provide ACID properties by
- using a two phase commit protocol, it is recognized that this is not
- possible in all circumstances. In particular, it is occasionally necessary
- to have a resource manager that is not XA aware participate in the
- transaction. This is often the case with data stores that can't or won't
- support distributed transactions. For such circumstances it is possible to
- employ a technique variously known as the Last Resource Gambit or last
- Resource Commit Optimization. Using this technique, the one phase resource
- is processed last in the prepare phase of the transaction, at which time an
- attempt is made to commit it. If successful, the transaction log is written
- and the remaining resources go through the phase two commit. If the last
- resource fails to commit, the transaction is rolled back. Whilst this
- protocol allows for most transactions to complete normally, certain types of
- error can cause an inconsistent transaction outcome. Therefore, we recommend
- using this approach only when no alternative is available. Where a single
- <![CDATA[<local-tx-datasource>]]> is used in a transaction, the LRCO will be
- automatically applied to it. For other cases it is possible to designate a
- last resource by using a special marker interface. See the JBossTS
- documentation for details.</para>
- <para>It is not transactionally safe (or rather, it is even more unsafe) to use more
- than a single one-phase resource in the same transaction. For this reason
- JBossTS treats an attempt to enlist a second such resource as an error and
- will terminate the transaction. This use case is most commonly found in
- applications migrating from JBossAS 4.0.x servers, where this usage was not
- considered an error. Whenever possible the <![CDATA[<local-tx-datasource>]]>
- should be changed to <![CDATA[<xa-datasource>]]> to resolve the difficulty.
- Where this is not possible, the transaction manager may be configured to
- allow multiple last resources. Although this is not recommended, details of
- the configuration steps may be found on the jboss.org wiki.</para>
+ <title>Last Resource Commit Optimization (LRCO)</title>
+ <para>Although the XA transaction protocol is designed to provide ACID properties by
+ using a two-phase commit protocol, it is recognized that this is not
+ possible in all circumstances. In particular, it is occasionally necessary
+ to have a resource manager that is not XA aware participate in the
+ transaction. This is often the case with data stores that can't or won't
+ support distributed transactions. For such circumstances it is possible to
+ employ a technique variously known as the Last Resource Gambit or Last
+ Resource Commit Optimization (LRCO). Using this technique, the one phase resource
+ is processed last in the prepare phase of the transaction, at which time an
+ attempt is made to commit it. If successful, the transaction log is written
+ and the remaining resources go through the phase two commit. If the last
+ resource fails to commit, the transaction is rolled back. Whilst this
+ protocol allows for most transactions to complete normally, certain types of
+ error can cause an inconsistent transaction outcome. Therefore, we recommend
+ using this approach only when no alternative is available. Where a single
+ <literal><![CDATA[<local-tx-datasource>]]></literal> is used in a transaction, the LRCO will be
+ automatically applied to it. For other cases it is possible to designate a
+ last resource by using a special marker interface. See the JBoss Transactions
+ documentation for details.</para>
+ <para>It is not transactionally safe (or rather, it is even more unsafe) to use more
+ than a single one-phase resource in the same transaction. For this reason
+ JBoss Transactions treats an attempt to enlist a second such resource as an error and
+ will terminate the transaction. This use case is most commonly found in
+ applications migrating from JBoss Application Server 4.0.x servers, where this usage was not
+ considered an error. Whenever possible the <literal><![CDATA[<local-tx-datasource>]]></literal>
+ should be changed to <literal><![CDATA[<xa-datasource>]]></literal> to resolve the difficulty.
+ Where this is not possible, the transaction manager may be configured to
+ allow multiple last resources, although this is not recommended.</para>
</section>
<section>
- <title>Transaction Timeout Handling</title>
- <para>In order to prevent indefinite locking of resources, the transaction manager
- will abort in-flight transactions that have not completed after a specified
- interval. This abort is done by a set of background processes, coordinated
- by the TransactionReaper. It should be noted that the reaper will rollback
- transactions without interrupting any threads that may be operating within
- their scope. This prevents instability that can result from interrupting
- threads executing arbitrary code. Furthermore, it allows for timely abort of
- transactions where the business logic thread may be executing
- non-interruptable operations such as network I/O calls. This approach may,
- however, cause unexpected behavior in code that is not designed to handle
- multithreaded transactions. Warning or error messages may be printed from
- e.g. hibernate or other transaction aware components as a result of the
- unexpected transaction status change. These should not affect the
- transaction outcome. The problem can be minimized by appropriate turning of
- the transaction timeout.</para>
+ <title>Transaction Timeout Handling</title>
+ <para>In order to prevent indefinite locking of resources, the transaction manager
+ will abort in-flight transactions that have not completed after a specified
+ interval. This abort is done by a set of background processes, coordinated
+ by the <classname>TransactionReaper.</classname> This reaper will roll back
+ transactions without interrupting any threads that may be operating within
+ their scope. This prevents instability that can result from interrupting
+ threads executing arbitrary code. Furthermore, it allows for timely abort of
+ transactions where the business logic thread may be executing
+ non-interruptable operations such as network I/O calls. This approach may,
+ however, cause unexpected behavior in code that is not designed to handle
+ multithreaded transactions. Warning or error messages may be printed from
+ Hibernate or other transaction-aware components as a result of the
+ unexpected transaction status change. These should not affect the
+ transaction outcome. The problem can be minimized by appropriate turning of
+ the transaction timeout.</para>
</section>
<section>
- <title>Recovery Configuration</title>
- <para>To ensure that the transaction manager can, upon server restart after a crash,
- successfully complete any prepared transactions, it is necessary to
- configure the recovery system correctly.</para>
- <para>After the prepare phase of the transaction commit, the transaction manager
- writes state information to disk in order that, should a failure occur, it
- can still complete the transaction and thereby assure ACID properties. The
- transaction log storage, which JBossTS terms the ObjectStore, should be
- configured in accordance with the guidance provided above. In addition, it
- is necessary to configure the recovery system to process the logs.</para>
- <para>The information that is written into the logs includes the transaction
- identity and the xid values associated to the XAResources enlisted with the
- transaction. In case where the XAResource itself implements Serializable, it
- is also written to the log. Such cases simplify recovery considerably, but
- unfortunately are a minority. Most XAResources, including those presented to
- the transaction manager by the application server's
- <![CDATA[<xa-datasource>]]>, are not Serializable. Therefore, it is
- necessary to explicitly provide the transaction manager with sufficient
- information to instantiate a new XAResource instance connected to the same
- resource manager upon server restart. For resource managers configured by
- <![CDATA[<xa-datasource>]]> elements in -ds.xml files, this is best achieved
- by using the AppServerJDBCXARecovery plugin. One instance is required for
- each resource manager. JBoss Messaging includes its own recovery plugin,
- which must be configured if messaging operations are required within a
- transaction. Refer to the JBoss Messaging documentation for further details.
- Users may develop their own plugins for resource managers not covered by the
- previous cases, by implementing the XAResourceRecovery interface. See the
- JBossTS documentation for further details.</para>
- <para>In addition to configuring the recovery plugins, it is necessary to set a
- unique identifier for each JBossTS (i.e. application server) instance and to
- configure which node identifiers each server will attempt to recover. For
- most situations it is recommended that each server instance operate
- independently, using its own ObjectStore and recovering its own
- transactions. In such cases the com.arjuna.ats.arjuna.xa.nodeIdentifier and
- com.arjuna.ats.jta.xaRecoveryNode properties in each server instance should
- share the same value and this value should be unique to the instance.</para>
+ <title>Recovery Configuration</title>
+ <para>To ensure that the transaction manager can, upon server restart after a crash,
+ successfully complete any prepared transactions, it is necessary to
+ configure the recovery system correctly.</para>
+ <para>After the prepare phase of the transaction commit, the transaction manager
+ writes state information to disk in order that, should a failure occur, it
+ can still complete the transaction and thereby assure ACID properties. The
+ transaction log storage, which JBossTS terms the ObjectStore, should be
+ configured in accordance with the guidance provided above. In addition, it
+ is necessary to configure the recovery system to process the logs.</para>
+ <para>The information that is written into the logs includes the transaction
+ identity and the xid values associated to the XAResources enlisted with the
+ transaction. In case where the XAResource itself implements Serializable, it
+ is also written to the log. Such cases simplify recovery considerably, but
+ unfortunately are a minority. Most XAResources, including those presented to
+ the transaction manager by the application server's
+ <literal><![CDATA[<xa-datasource>]]></literal>, are not Serializable. Therefore, it is
+ necessary to explicitly provide the transaction manager with sufficient
+ information to instantiate a new XAResource instance connected to the same
+ resource manager upon server restart. For resource managers configured by
+ <literal><![CDATA[<xa-datasource>]]></literal> elements in <filename>*-ds.xml</filename>
+ files, this is best achieved by using the <classname>AppServerJDBCXARecovery</classname> plugin.
+ One instance is required for each resource manager.
+ <!--JBoss Messaging includes its own recovery plugin,
+ which must be configured if messaging operations are required within a
+ transaction. Refer to the JBoss Messaging documentation for further details.-->
+ Users may develop their own plugins for resource managers not covered by the
+ previous cases, by implementing the XAResourceRecovery interface. See the
+ JBoss Transactions documentation for further details.</para>
+ <para>In addition to configuring the recovery plugins, it is necessary to set a
+ unique identifier for each JBoss Transactions instance (that is, each application server),
+ and to configure which node identifiers each server will attempt to recover. For
+ most situations it is recommended that each server instance operate
+ independently, using its own <classname>ObjectStore</classname> and recovering its own
+ transactions. In such cases the <varname>com.arjuna.ats.arjuna.xa.nodeIdentifier</varname> and
+ <varname>com.arjuna.ats.jta.xaRecoveryNode</varname> properties in each server instance should
+ share the same value and this value should be unique to the instance.</para>
</section>
<section>
- <title>Troubleshooting</title>
- <para>This section presents guidance on the possible causes are resolutions for
- common transaction related problems.</para>
- <para>
- <itemizedlist>
- <listitem>
- <para>I turned on debug logging, but nothing shows
- up.</para>
- <para>JBossTS sends log statements though two levels of
- filters. Firstly, its own internal logging
- abstraction layer, then the application server's
- log4j. A log statement must pass both filters to be
- printed. The most likely case is that's you have
- enabled only one or the other. See information on
- the DebugLevel property above.</para>
- </listitem>
- <listitem>
- <para>My server logs show <code>WARN Adding multiple last
- resources is disallowed.</code> and my
- transactions are aborted. Why?</para>
- <para>You are probably using
- <![CDATA[<local-xa-datasource>]]> rather than
- <![CDATA[<xa-datasource>]]> See the Last Resource
- Commit Optimization section above and refer to
- http://www.jboss.org/community/wiki/Multiple1pc</para>
- </listitem>
- <listitem>
- <para>My server crashed (or was killed). Now it's running
- again, but my logs are filling with <code>WARN
- [com.arjuna.ats.jta.logging.loggerI18N]
- [com.arjuna.ats.internal.jta.resources.arjunacore.norecoveryxa]
- Could not find new XAResource to use for
- recovering non-serializable
- XAResource</code></para>
- <para>You probably forgot to configure recovery for one or
- more resource managers used in a transaction. See
- the recovery section above and
- http://www.jboss.org/community/wiki/TxNonSerializableXAResource</para>
- </listitem>
- <listitem>
- <para>My transactions take a long time and sometimes strange
- things happen. The server log contains <code>WARN
- [arjLoggerI18N] [BasicAction_58] - Abort of action
- id ... invoked while multiple threads active
- within it.</code></para>
- <para>Transactions which exceed their timeout may be rolled
- back. This is done by a background thread, which can
- confuse some application code that may be expecting
- an interrupt. See the transaction timeout handling
- section above and
- http://www.jboss.org/community/wiki/TxMultipleThreads</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>Additional information on these and other issues may be found in the JBossTS
- documentation and on the wiki at
- http://www.jboss.org/community/wiki/JBossTransactions</para>
+ <title>Troubleshooting</title>
+ <para>This section presents guidance on the possible causes are resolutions for
+ common transaction related problems.</para>
+ <qandaset>
+ <qandaentry>
+ <question>
+ <para>I turned on debug logging, but nothing shows up.</para>
+ </question>
+ <answer>
+ <para>JBoss Transactions sends log statements through two levels of filters:
+ its own internal logging abstraction layer, then the application server's
+ log4j. A log statement must pass both filters to be printed. If nothing is
+ being printed, it is possible only one of these filters is enabled.
+ For more information, see the section on the <varname>DebugLevel</varname>
+ property earlier in this chapter.</para>
+ </answer>
+ </qandaentry>
+ <qandaentry>
+ <question>
+ <para>My server logs show <code>WARN Adding multiple last resources is disallowed</code>
+ and my transactions are aborted. Why?</para>
+ </question>
+ <answer>
+ <para>You are probably using <literal><![CDATA[<local-xa-datasource>]]></literal> instead
+ of <literal><![CDATA[<xa-datasource>]]></literal>. See the section on
+ Last Resource Commit Optimization earlier in this chapter. You can also refer to
+ <ulink url="http://www.jboss.org/community/wiki/Multiple1pc">http://www.jboss.org/community/wiki/Multiple1pc</ulink> for more information.</para>
+ </answer>
+ </qandaentry>
+ <qandaentry>
+ <question>
+ <para>My server failed/crashed. It is running again, but my logs are full of
+ <code>WARN [com.arjuna.ats.jta.logging.loggerI18N]
+ [com.arjuna.ats.internal.jta.resources.arjunacore.norecoveryxa] Could not find
+ new XAResource to use for recovering non-serializable XAResource</code>. Why?</para>
+ </question>
+ <answer>
+ <para>You probably did not configure recovery for one or more of the resource managers
+ used in a transaction. For configuration details, see the Recovery section earlier in
+ this chapter. You can also check <ulink url="http://www.jboss.org/community/wiki/TxNonSerializableXAResource">http://www.jboss.org/community/wiki/TxNonSerializableXAResource</ulink>
+ for further information.</para>
+ </answer>
+ </qandaentry>
+ <qandaentry>
+ <question>
+ <para>My transactions take a long time and sometimes strange things happen.
+ The server log contains <code>WARN [arjLoggerI18N] [BasicAction_58] - Abort
+ of action id ... invoked while multiple threads active within it.</code></para>
+ </question>
+ <answer>
+ <para>Transactions which exceed their timeout may be rolled back. This is done by a
+ background thread, which can confuse application code that expects an interrupt.
+ See the transaction timeout handling section earlier in the chapter, or
+ <ulink url="http://www.jboss.org/community/wiki/TxMultipleThreads"></ulink>
+ for more information.</para>
+ </answer>
+ </qandaentry>
+ </qandaset>
+
+ <para>You can find more information in the JBoss Transactions documentation, or in the
+ JBoss Transactions wiki at <ulink url="http://www.jboss.org/community/wiki/JBossTransactions">http://www.jboss.org/community/wiki/JBossTransactions</ulink>.</para>
</section>
<section>
- <title>Installing JBossTS JTS</title>
- <para>Users who require transaction propagation between business logic in different
- servers will benefit from installing the JTS component. Although the JTS
- does have its own API, it is most commonly accessed via the standard JTA
- classes. In such cases, it's a drop in replacement for the default
- local-only JTA implementation. The necessary implementation classes are
- already in place, it is required only to modify the relevant config file to
- move between the JTA and JTS modules. The directory
- docs/examples/transactions/ contains a version of the jbossts-properties.xml
- file suitable for running the JTS mode. It also contains a README.txt file
- detailing the changes necessary to various other files, including the
- transactions-jboss-beans.xml. An ant script which will perform these steps
- on your behalf is also included. However, we strongly recommend to consult
- the README file for additional information before running the script, as
- well as backing up any server configuration files which may be changed. Note
- that it is necessary to install the JTS into a server configuration that
- also contains the CORBA ORB service, as the JTS relies on this. We recommend
- the 'all' configuration as a starting point for this. The selection of
- distributed JTA (JTS, also known internally as jtax) or local-only JTA (the
- default) is done at the server level. The additional complexity of the JTS
- carries a slight performance overhead, so it is recommended to install the
- JTS only for servers which host applications requiring transaction context
- distribution. Servers running JTA will log:</para>
- <para>
- <code>INFO [TransactionManagerService] JBossTS Transaction Service (JTA
- version - ...)</code>
- </para>
- <para>at startup, whereas those running the JTS will log:</para>
- <para>
- <code>INFO [TransactionManagerService] JBossTS Transaction Service (JTS
- version - ...)</code>
- </para>
+ <title>Installing JBossTS JTS</title>
+ <para>Users who require transaction propagation between business logic in different
+ servers will benefit from installing the JTS component. Although the JTS
+ does have its own API, it is most commonly accessed via the standard JTA
+ classes. In such cases, it's a drop in replacement for the default
+ local-only JTA implementation. The necessary implementation classes are
+ already in place, it is required only to modify the relevant configuration file to
+ move between the JTA and JTS modules. The <filename>docs/examples/transactions/</filename>
+ contains a version of the <filename>jbossts-properties.xml</filename>
+ file suitable for running the JTS mode. It also contains a <filename>README.txt</filename> file
+ detailing the changes necessary to various other files, including the
+ <filename>transactions-jboss-beans.xml</filename>. An ant script which will perform these steps
+ on your behalf is also included. However, we strongly recommend to consult
+ the README file for additional information before running the script, as
+ well as backing up any server configuration files which may be changed. Note
+ that it is necessary to install the JTS into a server configuration that
+ also contains the CORBA ORB service, as the JTS relies on this. We recommend
+ the <literal>production</literal> configuration as a starting point for this. The selection of
+ distributed JTA (JTS) or local-only JTA (the default) is done at the server
+ level. The additional complexity of the JTS
+ carries a slight performance overhead, so it is recommended to install the
+ JTS only for servers which host applications requiring transaction context
+ distribution. Servers running JTA will log:</para>
+ <screen>INFO [TransactionManagerService] JBossTS Transaction Service (JTA version - ...)</screen>
+ <para>at startup, whereas those running the JTS will log:</para>
+ <screen>INFO [TransactionManagerService] JBossTS Transaction Service (JTS version - ...)</screen>
</section>
<section>
- <title>Installing JBossTS XTS</title>
- <para>The Web Services transaction component, XTS, may be installed to provide WS-AT
- and WS-BA support for web services hosted in the server. The application is
- packaged as a .sar file found in docs/examples/transactions/ and should be
- installed by unpacking this archive into the a new jbossxts.sar directory
- which you should create in the server/[name]/deploy/ directory of a suitable
- server. Consult the README.txt in docs/examples/transactions/ for any
- additional deployment information. The server must also be running either
- JBossTS JTA or JTS and JBossWS Native. Note that XTS is not currently
- expected to work with other JBossWS backends such as CXF. The default XTS
- configuration is suitable for most usage and will automatically pick up
- network interface and port binding information from the application server
- configuration. Manual configuration changes are necessary only for
- deployments where applications require use of a transaction coordinator on a
- separate host, for which the XTS documentation should be consulted. The
- directory tree created by unpacking the jbossxts.sar file will contain a
- jbossxts-api.jar Developers may link against this .jar at build time, but
- should not package it with their applications in order to avoid classloading
- problems. The remaining .jar files contain internal implementation classes
- and should not be used directly by application code.</para>
+ <title>Installing JBossTS XTS</title>
+ <para>The Web Services transaction component, XTS, may be installed to provide WS-AT
+ and WS-BA support for web services hosted in the server. The application is
+ packaged as a <filename>.sar</filename> file found in
+ <filename>docs/examples/transactions/</filename> and should be
+ installed by unpacking this archive into the a new <filename>jbossxts.sar</filename> directory
+ which you should create in the <filename>server/$PROFILE/deploy/</filename> directory of a suitable
+ server. Consult the <filename>README.txt</filename> in
+ <filename>docs/examples/transactions/</filename> for any
+ additional deployment information. The server must also be running either
+ JBossTS JTA or JTS and JBossWS Native.</para>
+ <note>
+ <para>XTS is does not work with other JBossWS backends such as CXF.</para>
+ </note>
+ <para>The default XTS configuration is suitable for most usage and will automatically pick up
+ network interface and port binding information from the application server
+ configuration. Manual configuration changes are necessary only for
+ deployments where applications require use of a transaction coordinator on a
+ separate host, for which the XTS documentation should be consulted. The
+ directory tree created by unpacking the <filename>jbossxts.sar</filename> file will contain a
+ <filename>jbossxts-api.jar</filename>. Developers may link against this <filename>.jar</filename>
+ at build time, but should not package it with their applications in order to avoid classloading
+ problems. The remaining <filename>.jar</filename> files contain internal implementation classes
+ and should not be used directly by application code.</para>
</section>
- <section>
- <title>Transaction Management Console</title>
- <para>To facilitate investigation of issues resulting from heuristic or unrecovered
- transactions, a simple GUI tool is available for inspection of the internal
- state of the ObjectStore, in which transaction state logs are recorded. The
- tool allows users to view transactions and their enlisted resources, as well
- as forcing transaction resolutions i.e. commit or rollback. The tool is an
- unsupported experimental prototype and should be used at your own risk. It
- is available from docs/example/transactions/ and the README.txt file in that
- directory describes how it may be deployed. </para>
+ <!--<section>
+ <title>Transaction Management Console</title>
+ <warning>
+ <title>The Transaction Managent Console is not supported</title>
+ <para>The tool is an unsupported experimental prototype and should be used at your own risk.</para>
+ </warning>
+ <para>To facilitate investigation of issues resulting from heuristic or unrecovered
+ transactions, a simple GUI tool is available for inspection of the internal
+ state of the <classname>ObjectStore</classname>, in which transaction state logs are recorded. The
+ tool allows users to view transactions and their enlisted resources, as well
+ as forcing transaction resolutions such as commit or rollback.</para>
+ <para>It is available from <filename>docs/example/transactions/</filename> and the
+ <filename>README.txt</filename> file in that directory describes how it may be deployed. </para>
</section>
<section>
- <title>Experimental Components</title>
- <para> In addition to the supported components of JBossTS that ship as part of JBoss
- Enterprise Web Platform, there is ongoing feature work that may eventually find its way into
- future releases of the product. Meanwhile these prototype components are
- available via from the jboss.org community site. Users are cautioned that
- there is no guarantee these will work correctly and nor are they covered by
- the Enterprise Web Platform support agreement. However, some of the advanced functionality
- available may nevertheless be attractive to projects in the early stages of
- development. Users downloading these prototypes must be aware of the
- limitations concerning module compatibility, in accordance with the 'source
- code and customization' section below.</para>
- <para>
- <itemizedlist>
- <listitem>
- <para>txbridge</para>
- <para>For certain use cases it is desirable to be able to
- invoke traditional transaction components such as
- EJBs, within the scope of a Web Services
- transaction. Likewise, such components may wish to
- invoke transactional web services. This involves two
- distinct transaction types: JTA i.e. XA based
- transactions for the JEE components and WS-AT
- transactions for the web services. It is necessary
- to integrate these transactions into a single entity
- spanning all the involved components. It is this
- problem that the transaction bridge
- addresses.</para>
- </listitem>
- <listitem>
- <para>BA Framework</para>
- <para>The techniques required for writing extended,
- compensation based transactions for WS-BA are still
- in their infancy. The API provided by XTS is low
- level, requiring the business programmer to
- undertake much of the transaction plumbing work. The
- BA Framework provides high level annotations that
- move responsibility for much of the transaction
- handling into the application server middleware.
- Using the framework, programmers can focus on
- writing business logic and thus be considerably more
- productive.</para>
- </listitem>
- </itemizedlist>
- </para>
+ <title>Experimental Components</title>
+ <para> In addition to the supported components of JBossTS that ship as part of JBoss
+Enterprise Web Platform, there is ongoing feature work that may eventually find its way into
+ future releases of the product. Meanwhile these prototype components are
+ available via from the jboss.org community site. Users are cautioned that
+ there is no guarantee these will work correctly and nor are they covered by
+the Enterprise Web Platform support agreement. However, some of the advanced functionality
+ available may nevertheless be attractive to projects in the early stages of
+ development. Users downloading these prototypes must be aware of the
+ limitations concerning module compatibility, in accordance with the 'source
+ code and customization' section below.</para>
+ <variablelist>
+ <varlistentry>
+ <term><application>txbridge</application></term>
+ <listitem>
+ <para>For certain use cases it is desirable to be able to
+ invoke traditional transaction components such as
+ EJBs, within the scope of a Web Services
+ transaction. Likewise, such components may wish to
+ invoke transactional web services. This involves two
+ distinct transaction types: JTA (XA based
+ transactions for the JEE components), and WS-AT
+ transactions for the web services. It is necessary
+ to integrate these transactions into a single entity
+ spanning all the involved components. It is this
+ problem that the transaction bridge
+ addresses.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><application>BA Framework</application></term>
+ <listitem>
+ <para>The techniques required for writing extended,
+ compensation based transactions for WS-BA are still
+ in their infancy. The API provided by XTS is low
+ level, requiring the business programmer to
+ undertake much of the transaction plumbing work. The
+ BA Framework provides high level annotations that
+ move responsibility for much of the transaction
+ handling into the application server middleware.
+ Using the framework, programmers can focus on
+ writing business logic and thus be considerably more
+ productive.</para>
+ </listitem>
+ </itemizedlist>
</section>
<section>
- <title>Source code and upgrading</title>
- <para> Most transaction related problems can be diagnosed by JBoss support, upon
+ <title>Source code and upgrading</title>
+ <para> Most transaction-related problems can be diagnosed by JBoss support, upon
provision of debug logs from the server. However, it is occasionally
desirable to be able to step though transaction code in a debugger, or
simply to review the code to help understanding of the provided
functionality.</para>
- <para> The source code for JBossTS can be downloaded direct from the project's svn
+ <para> The source code for JBoss Transactions can be downloaded direct from the project's svn
repository at http://anonsvn.jboss.org/repos/labs/labs/jbosstm/ To find the
version matching the binaries in JBoss Enterprise Web Platform, consult your server logs. At
startup the server prints a string similar to:</para>
@@ -536,5 +547,5 @@
supported to mix and match versions. i.e. do not run the JTA from one tag
with the XTS from another. API and functionality changes between releases
may make this unstable.</para>
- </section>
+ </section>-->
</chapter>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Virtual_Deployment_Framework.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Virtual_Deployment_Framework.xml 2010-02-07 23:07:07 UTC (rev 100671)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Virtual_Deployment_Framework.xml 2010-02-08 01:21:00 UTC (rev 100672)
@@ -3,11 +3,11 @@
]>
<chapter id="virtual_deployment_framework">
- <title>JBoss5 Virtual Deployment Framework</title>
+<!-- <title>JBoss5 Virtual Deployment Framework</title>
<para>
<indexterm><primary>JBoss5 Virtual Deployment Framework</primary><secondary>virtual deployment framework</secondary></indexterm>
<indexterm><primary>Virtual Deployment Framework</primary><see>JBoss5 Virtual Deployment Framework</see></indexterm>
- As indicated in <xref linkend="JBoss_Enterprise_Application_Platform_5_Introduction"/> the JBoss Enterprise Web Platform 5 is designed around the advanced concept of a Virtual Deployment Framework (VDF). This chapter discusses the JBoss5 Virtual Deployment Framework further. The following UML diagram illustrates an overview of the key JBoss5 Deployment Framework classes.
+ As indicated in <xref linkend="JBoss_Enterprise_Application_Platform_5_Introduction"/> the JBoss Enterprise Web Platform 5 is designed around the advanced concept of a Virtual Deployment Framework (VDF). This chapter discusses the Virtual Deployment Framework further. The following UML diagram illustrates an overview of the key Deployment Framework classes.</para>
<figure id="JBoss5_virtual_deployment_framework_diagram">
<title>The JBoss5 Deployment Framework Classes</title>
@@ -18,29 +18,25 @@
</mediaobject>
</figure>
+<para>The key classes in the above diagram are:</para>
-The key classes in the above diagram are:
+<variablelist>
+ <varlistentry>
+ <term><classname>MainDeployer</classname></term>
+ <listitem>
+ <para>
+ This interface defines the contract for the <classname>MainDeployer</classname>. The <classname>MainDeployer</classname> handles parsing of deployment archives into deployment instances and deployment of those instances into the microcontainer. This update of the JMX-based <classname>MainDeployer</classname> moves it to one based on the Microcontainer, JBoss5VirtualFileSystem, and Virtual Deployment Framework (VDF). Deployers are registered with the <classname>MainDeployer</classname> as an ordered list of deployers.
+ </para>
+ <para>
+ MainDeployer contains <classname>StructureDeployer</classname>s used to analyze the structure of a <classname>DeploymentContext</classname> when <methodname>addDeploymentContext(DeploymentContext)</methodname> is invoked. For each <classname>StructureDeployer</classname>, the <methodname>determineStructure(DeploymentContext)</methodname> method is invoked to analyze the deployment. A <classname>StructureDeployer</classname> returns true to indicate that the deployment was recognized and no further StructureDeployer should analyze the DeploymentContext.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
-<itemizedlist>
- <listitem>
- <para>
- <emphasis>MainDeployer</emphasis> : this interface defines the contract for the MainDeployer. The MainDeployer handles parsing of deployment archives into Deployment instances and deployment of those instances into the microcontainer. This update of the JMX based MainDeployer moves it to one based on the Microcontainer, JBoss5VirtualFileSystem, and Virtual Deployment Framework (VDF). Deployers are registered with the MainDeployer as an ordered list of deployers. MainDeployer contains two sets of deployers:
- </para>
-
<itemizedlist>
<listitem>
<para>
- <emphasis>StructureDeployers</emphasis> used to analyze the structure of a DeploymentContext when <methodname>addDeploymentContext(DeploymentContext)</methodname> is invoked. For each StructureDeployer the <methodname>determineStructure(DeploymentContext)</methodname> method is invoked to analyze the deployment. A StructureDeployer returns true to indicate that the deployment was recognized and no further StructureDeployer should analyze the DeploymentContext.
- </para>
- </listitem>
- </itemizedlist>
-</listitem>
-</itemizedlist>
-
-
- <itemizedlist>
- <listitem>
- <para>
Deployers used to translate a DeploymentUnit into runtime kernel beans when the MainDeployer.process is run. The Deployer methods are:
</para>
@@ -543,6 +539,5 @@
</para>
-</section>
+</section>-->
</chapter>
-
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Web_Services.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Web_Services.xml 2010-02-07 23:07:07 UTC (rev 100671)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Web_Services.xml 2010-02-08 01:21:00 UTC (rev 100672)
@@ -9,7 +9,7 @@
<indexterm><primary>JBossWS</primary><secondary>Web Services</secondary></indexterm>
<indexterm><primary>JAX-WS</primary><see>Web Services</see></indexterm>
- Web services are a key contributing factor in the way Web commerce is conducted today.
+ Web services are a key contributing factor in the way web commerce is conducted today.
Web services enable applications to communicate by sending small and large chunks of data to each other.
</para>
<para>
@@ -186,7 +186,7 @@
<para>
- With RPC style web services the portType names the operation (i.e. the java method on the endpoint)
+ With RPC style web services the portType names the operation (that is, the java method on the endpoint)
</para>
<programlisting role="XML">
@@ -235,9 +235,9 @@
<section><title>RPC/Encoded</title>
<para>
- SOAP encodeding style is defined by the infamous <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383512">chapter 5</ulink> of the <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">SOAP-1.1</ulink> specification. It has inherent interoperability issues that cannot be fixed. The <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html">Basic Profile-1.0</ulink> prohibits this encoding style in <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html#refinement16448072">4.1.7 SOAP encodingStyle Attribute</ulink>.
+ SOAP encoding style is defined by the <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">SOAP-1.1</ulink> specification <!--by the infamous <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383512">chapter 5</ulink> of the <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">SOAP-1.1</ulink> specification.--> It has inherent interoperability issues that cannot be fixed. The <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html">Basic Profile-1.0</ulink> prohibits this encoding style in <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html#refinement16448072">4.1.7 SOAP encodingStyle Attribute</ulink>.
- JBossWS has basic support for RPC/Encoded that is provided as is for simple interop scenarios with SOAP stacks that do not support literal encoding.
+ JBossWS has basic support for RPC/Encoded that is provided as is for simple interoperability scenarios with SOAP stacks that do not support literal encoding.
Specifically, JBossWS does not support:-
<itemizedlist>
<listitem>
@@ -247,7 +247,7 @@
</listitem>
<listitem>
<para>
- soap arrays as bean properties
+ SOAP arrays as bean properties
</para>
</listitem>
</itemizedlist>
@@ -260,7 +260,7 @@
<para>JAX-WS simplifies the development model for a web service endpoint a great deal. In short, an endpoint implementation bean is annotated with JAX-WS annotations and deployed to the server. The server automatically generates and publishes the abstract contract (for instance, wsdl+schema) for client consumption. All marshalling/unmarshalling is delegated to JAXB.
</para>
- </section>
+
@@ -316,11 +316,6 @@
</section>
-
-
-
-
-
<section>
<title>Accessing the generated WSDL</title>
<para>A successfully deployed service endpoint will show up in the service endpoint manager. This is also where you find the links to the generated WSDL.</para>
@@ -329,6 +324,10 @@
<para>
It is also possible to generate the abstract contract off line using jboss tools. For details of that see <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSTools#TopDown_Using_wsconsume">#Top Down (Using wsconsume)</ulink></para>
</section>
+
+
+
+
<section>
<title>EJB3 Stateless Session Bean (SLSB)</title>
<para>The JAX-WS programming model support the same set of annotations on EJB3 stateless session beans as on <ulink url="http://www.jboss.org/community/wiki/JBossWS-UserGuide#Plain_old_Java_Object_POJO"># Plain old Java Object (POJO)</ulink> endpoints. EJB-2.1 endpoints are supported using the JAX-RPC progamming model.</para>
@@ -352,7 +351,7 @@
<formalpara>
<title>Packaging the endpoint</title>
<para>
- A JSR-181 EJB service endpoint is packaged as an ordinary ejb deployment.
+ A JSR-181 EJB service endpoint is packaged as an ordinary EJB deployment.
</para>
</formalpara>
<programlisting role="XML"><jar jarfile="${build.dir}/libs/jbossws-samples-jsr181ejb.jar">
@@ -372,7 +371,7 @@
<section>
<title>Endpoint Provider</title>
<para>JAX-WS services typically implement a native Java service endpoint interface (SEI), perhaps mapped from a WSDL port type, either directly or via the use of annotations.</para>
- <para>Java SEIs provide a high level Java-centric abstraction that hides the details of converting between Java objects and their XML representations for use in XML-based messages. However, in some cases it is desirable for services to be able to operate at the XML message level. The Provider interface offers an alternative to SEIs and may be implemented by services wishing to work at the XML message level.</para>
+ <para>Java SEIs provide a high level Java-centric abstraction that hides the details of converting between Java objects and their XML representations for use in XML-based messages. However, in some cases it is desirable for services to be able to operate at the XML message level. The <classname>Provider</classname> interface offers an alternative to SEIs and may be implemented by services wishing to work at the XML message level.</para>
<para>A Provider based service instance’s invoke method is called for each message received for the service.</para>
<programlisting role="JAVA">
@WebServiceProvider
@@ -384,8 +383,9 @@
// Access the entire request PAYLOAD and return the response PAYLOAD
}
}</programlisting>
- <para><property>Service.Mode.PAYLOAD</property> is the default and does not have to be declared explicitly. You can also use <property>Service.Mode.MESSAGE</property> to access the entire SOAP message (for example, with <property>MESSAGE</property> the Provider can also see SOAP Headers)</para>
+ <para><varname>Service.Mode.PAYLOAD</varname> is the default and does not have to be declared explicitly. You can also use <varname>Service.Mode.MESSAGE</varname> to access the entire SOAP message (for example, with <literal>MESSAGE</literal> the Provider can also see SOAP Headers)</para>
</section>
+ </section>
<section>
<title>WebServiceContext</title>
<para>The <classname>WebServiceContext</classname> is treated as an injectable resource that can be set at the time an endpoint is initialized. The <classname>WebServiceContext</classname> object will then use thread-local information to return the correct information regardless of how many threads are concurrently being used to serve requests addressed to the same endpoint object.</para>
@@ -422,14 +422,14 @@
<section>
<title>Service</title>
<para><literal>Service</literal> is an abstraction that represents a WSDL service. A WSDL service is a collection of related ports, each of which consists of a port type bound to a particular protocol and available at a particular endpoint address.</para>
- <para>For most clients, you will start with a set of stubs generated from the WSDL. One of these will be the service, and you will create objects of that class in order to work with the service (see "static case" below).</para>
+ <para>For most clients, you will start with a set of stubs generated from the WSDL. One of these will be the service, and you will create objects of that class in order to work with the service, as in the static case outlined in the following section.</para>
<section>
<title>Service Usage</title>
<formalpara>
<title>Static case</title>
- <para>Most clients will start with a WSDL file, and generate some stubs using jbossws tools like <emphasis>wsconsume</emphasis>. This usually gives a mass of files, one of which is the top of the tree. This is the service implementation class.</para>
+ <para>Most clients will start with a WSDL file, and generate some stubs using jbossws tools like <application>wsconsume</application>. This usually gives a mass of files, one of which is the top of the tree. This is the service implementation class.</para>
</formalpara>
- <para>The generated implementation class can be recognised as it will have two public constructors, one with no arguments and one with two arguments, representing the wsdl location (a java.net.URL) and the service name (a javax.xml.namespace.QName) respectively.</para>
+ <para>The generated implementation class can be recognised as it will have two public constructors, one with no arguments and one with two arguments, representing the wsdl location (a <varname>java.net.URL</varname>) and the service name (a <varname>javax.xml.namespace.QName</varname>) respectively.</para>
<para>Usually you will use the no-argument constructor. In this case the WSDL location and service name are those found in the WSDL. These are set implicitly from the WebServiceClient annotation that decorates the generated class.</para>
<para>The following code snippet shows the generated constructors from the generated class:</para>
<programlisting role="JAVA">
@@ -454,7 +454,7 @@
<para>Section <ulink url="http://www.jboss.org/community/wiki/JBossWS-UserGuide#Dynamic_Proxy">#Dynamic Proxy</ulink> explains how to obtain a port from the service and how to invoke an operation on the port. If you need to work with the XML payload directly or with the XML representation of the entire SOAP message, have a look at <ulink url="http://www.jboss.org/community/wiki/JBossWS-UserGuide#Dispatch">#Dispatch</ulink>.</para>
<formalpara>
<title>Dynamic case</title>
- <para>In the dynamic case, when nothing is generated, a web service client uses <literal>Service.create</literal> to create Service instances, the following code illustrates this process.</para>
+ <para>In the dynamic case, when nothing is generated, a web service client uses <methodname>Service.create</methodname> to create Service instances, the following code illustrates this process.</para>
</formalpara>
<programlisting role="JAVA">
URL wsdlLocation = new URL("http://example.org/my.wsdl");
@@ -597,7 +597,7 @@
<section>
<title>Dispatch</title>
<para>XML Web Services use XML messages for communication between services and service clients. The higher level JAX-WS APIs are designed to hide the details of converting between Java method invocations and the corresponding XML messages, but in some cases operating at the XML message level is desirable. The Dispatch interface provides support for this mode of interaction.</para>
- <para>Dispatch supports two usage modes, identified by the constants <property>javax.xml.ws.Service.Mode.MESSAGE</property> and <property>javax.xml.ws.Service.Mode.PAYLOAD</property> respectively:</para>
+ <para>Dispatch supports two usage modes, identified by the constants <varname>javax.xml.ws.Service.Mode.MESSAGE</varname> and <varname>javax.xml.ws.Service.Mode.PAYLOAD</varname> respectively:</para>
<formalpara>
<title>Message</title>
@@ -649,7 +649,7 @@
</section>
<section>
<title>Oneway Invocations</title>
- <para><property>@Oneway</property> indicates that the given web method has only an input message and no output. Typically, a one-way method returns the thread of control to the calling application prior to executing the actual business method.</para>
+ <para><literal>@Oneway</literal> indicates that the given web method has only an input message and no output. Typically, a one-way method returns the thread of control to the calling application prior to executing the actual business method.</para>
<programlisting role="JAVA">
@WebService (name="PingEndpoint")
@SOAPBinding(style = SOAPBinding.Style.RPC)
@@ -692,7 +692,7 @@
</section>
<section>
<title>Service endpoint handlers</title>
- <para>On the service endpoint, handlers are defined using the <property>@HandlerChain</property> annotation.</para>
+ <para>On the service endpoint, handlers are defined using the <literal>@HandlerChain</literal> annotation.</para>
<programlisting role="JAVA">
@WebService
@HandlerChain(file = "jaxws-server-source-handlers.xml")
@@ -700,9 +700,7 @@
{
...
}</programlisting>
- <para>The location of the handler chain file supports 2 formats</para>
- <para>1. An absolute java.net.URL in externalForm. (ex: <ulink url="http://myhandlers.foo.com/handlerfile1.xml">http://myhandlers.foo.com/handlerfile1.xml</ulink>)</para>
- <para>2. A relative path from the source file or class file. (ex: bar/handlerfile1.xml)</para>
+ <para>The location of the handler chain file supports two formats: either an absolute <varname>java.net.URL</varname> in <literal>externalForm</literal>, such as <ulink url="http://myhandlers.foo.com/handlerfile1.xml">http://myhandlers.foo.com/handlerfile1.xml</ulink>), or a relative path from the source file or class file, for example, <filename>bar/handlerfile1.xml</filename>.</para>
</section>
<section>
<title>Service client handlers</title>
@@ -722,24 +720,24 @@
</section>
<section>
<title>Message Context</title>
- <para>MessageContext is the super interface for all JAX-WS message contexts. It extends Map<String,Object> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state. For example, a handler may use the put method to insert a property in the message context that one or more other handlers in the handler chain may subsequently obtain via the get method.</para>
- <para>Properties are scoped as either APPLICATION or HANDLER. All properties are available to all handlers associated with particular endpoint. E.g., if a logical handler puts a property in the message context, that property will also be available to any protocol handlers in the chain during the execution. APPLICATION scoped properties are also made available to client applications and service endpoint implementations. The default scope for a property is HANDLER.</para>
+ <para><classname>MessageContext</classname> is the super interface for all JAX-WS message contexts. It extends <classname>Map<String,Object></classname> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state. For example, a handler may use the put method to insert a property in the message context that one or more other handlers in the handler chain may subsequently obtain via the get method.</para>
+ <para>Properties are scoped as either APPLICATION or HANDLER. All properties are available to all handlers associated with a particular endpoint, for example, if a logical handler puts a property in the message context, that property will also be available to any protocol handlers in the chain during the execution. APPLICATION scoped properties are also made available to client applications and service endpoint implementations. The default scope for a property is HANDLER.</para>
<section>
<title>Accessing the message context</title>
<para>Users can access the message context in handlers or in endpoints via <literal>@WebServiceContext</literal> annotation.</para>
</section>
<section>
<title>Logical Message Context</title>
- <para>LogicalMessageContext is passed to <literal>Logical Handlers</literal> at invocation time. LogicalMessageContext extends MessageContext with methods to obtain and modify the message payload, it does not provide access to the protocol specific aspects of a message. A protocol binding defines what component of a message are available via a logical message context. The SOAP binding defines that a logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers whereas the XML/HTTP binding defines that a logical handler can access the entire XML payload of a message.</para>
+ <para>LogicalMessageContext is passed to <literal>Logical Handlers</literal> at invocation time. <classname>LogicalMessageContext</classname> extends <classname>MessageContext</classname> with methods to obtain and modify the message payload, it does not provide access to the protocol specific aspects of a message. A protocol binding defines the components of a message that are available via a logical message context. The SOAP binding defines that a logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers whereas the XML/HTTP binding defines that a logical handler can access the entire XML payload of a message.</para>
</section>
<section>
<title>SOAP Message Context</title>
- <para>SOAPMessageContext is passed to <literal>SOAP handlers</literal> at invocation time. SOAPMessageContext extends MessageContext with methods to obtain and modify the SOAP message payload.</para>
+ <para><classname>SOAPMessageContext</classname> is passed to <literal>SOAP handlers</literal> at invocation time. <classname>SOAPMessageContext</classname> extends <classname>MessageContext</classname> with methods to obtain and modify the SOAP message payload.</para>
</section>
</section>
<section>
<title>Fault Handling</title>
- <para>An implementation may throw a SOAPFaultException</para>
+ <para>An implementation may throw a <exceptionname>SOAPFaultException</exceptionname></para>
<programlisting role="JAVA">
public void throwSoapFaultException()
{
@@ -750,7 +748,7 @@
throw new SOAPFaultException(fault);
}
</programlisting>
- <para>or an application specific user exception</para>
+ <para>or an application-specific user exception:</para>
<programlisting role="JAVA">
public void throwApplicationException() throws UserException
@@ -769,9 +767,8 @@
<title>DataBinding</title>
<section>
<title>Using JAXB with non annotated classes</title>
- <para>JAXB is heavily driven by Java Annotations on the Java Bindings. It currently doesn't support an external binding configuration.</para>
- <para>In order to support this, we built on a JAXB RI feature whereby it allows you to specify a RuntimeInlineAnnotationReader implementation during JAXBContext creation (see JAXBRIContext).</para>
- <para>We call this feature "JAXB Annotation Introduction" and we've made it available for general consumption i.e. it can be checked out, built and used from SVN:</para>
+ <para>JAXB is heavily driven by Java Annotations on the Java Bindings. It does not currently support an external binding configuration.</para>
+ <para>In order to support this, we built on a JAXB RI feature, which allows you to specify a <classname>RuntimeInlineAnnotationReader</classname> implementation during JAXBContext creation (see JAXBRIContext). This feature is called JAXB Annotation Introduction. You can check it out and build it from the following SVN repository:</para>
<itemizedlist>
<listitem>
<para>
@@ -1057,7 +1054,7 @@
</informaltable>
<section>
<title>Bottom-Up (Using wsprovide)</title>
- <para>The bottom-up strategy involves developing the Java code for your service, and then annotating it using JAX-WS annotations. These annotations can be used to customize the contract that is generated for your service. For example, you can change the operation name to map to anything you like. However, all of the annotations have sensible defaults, so only the @WebService annotation is required.</para>
+ <para>The bottom-up strategy involves developing the Java code for your service, and then annotating it using JAX-WS annotations. These annotations can be used to customize the contract that is generated for your service. For example, you can change the operation name to map to anything you like. However, all of the annotations have sensible defaults, so only the <literal>@WebService</literal> annotation is required.</para>
<para>This can be as simple as creating a single class:</para>
<programlisting role="JAVA">
package echo;
@@ -1072,7 +1069,7 @@
}
</programlisting>
<para>A JSE or EJB3 deployment can be built using this class, and it is the only Java code needed to deploy on JBossWS. The WSDL, and all other Java artifacts called "wrapper classes" will be generated for you at deploy time. This actually goes beyond the JAX-WS specification, which requires that wrapper classes be generated using an offline tool. The reason for this requirement is purely a vender implementation problem, and since we do not believe in burdening a developer with a bunch of additional steps, we generate these as well. However, if you want your deployment to be portable to other application servers, you will need to use a tool and add the generated classes to your deployment.</para>
- <para>This is the primary purpose of the <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide</ulink> tool, to generate portable JAX-WS artifacts. Additionally, it can be used to "provide" the abstract contract (WSDL file) for your service. This can be obtained by invoking <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide</ulink> using the "-w" option:</para>
+ <para>This is the primary purpose of the <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide</ulink> tool, to generate portable JAX-WS artifacts. Additionally, it can be used to "provide" the abstract contract (WSDL file) for your service. This can be obtained by invoking <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide</ulink> using the <code>-w</code> option:</para>
<programlisting role="JAVA">
$ javac -d . -classpath jboss-jaxws.jar Echo.java
$ wsprovide -w echo.Echo
@@ -1082,7 +1079,7 @@
echo/jaxws/Echo.class
echo/jaxws/EchoResponse.class
</programlisting>
- <para>Inspecting the WSDL reveals a service called EchoService:</para>
+ <para>Inspecting the WSDL reveals a service called <classname>EchoService</classname>:</para>
<programlisting role="XML">
<service name='EchoService'>
<port binding='tns:EchoBinding' name='EchoPort'>
@@ -1098,8 +1095,8 @@
</operation>
</portType></programlisting>
<para>
- <note><title>Note</title>
- <para>Remember that <emphasis role="bold">when deploying on JBossWS you do not need to run this tool.</emphasis> You only need it for generating portable artifacts and/or the abstract contract for your service.</para>
+ <note><title>This tool is not required to deploy on JBossWS</title>
+ <para>You only need it for generating portable artifacts and/or the abstract contract for your service.</para>
</note>
</para>
@@ -1134,7 +1131,7 @@
adding: WEB-INF/classes/echo/Echo.class(in = 340) (out= 247)(deflated 27%)
adding: WEB-INF/web.xml(in = 576) (out= 271)(deflated 52%)
]]> </programlisting>
- <para>The war can then be deployed:</para>
+ <para>The WAR can then be deployed:</para>
<programlisting> <![CDATA[
cp echo.war $JBOSS_HOME/server/default/deploy
]]> </programlisting>
@@ -1262,14 +1259,8 @@
</section>
<section>
<title>Client Side</title>
- <para>Before going into detail on the client-side it is important to understand the decoupling concept that is central to Web Services. Web Services are not the best fit for internal RPC, even though they can be used in this way; there are much better technologies for achieving this (CORBA, and RMI for example). Web Services were designed specifically for interoperable coarse-grained correspondence. There is no expectation or guarantee that any party participating in a Web Service interaction will be at any particular location, running on any particular operating system, or written in any particular programming language. So because of this, it is important to clearly separate client and server implementations. The only thing they should have in common is the abstract contract definition. If, for whatever reason, your software does not adhere to this principal, then you should not be using Web Services. For the above reasons, the <emphasis role="bold">
- <emphasis>recommended methodology for developing a client is</emphasis>
- </emphasis>
- to follow <emphasis role="bold">
- <emphasis>the top-down approach</emphasis>
- </emphasis>
- , even if the client is running on the same server.</para>
- <para>Let's repeat the process of the top-down section, although using the deployed WSDL, instead of the one generated offline by <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide</ulink>. The reason why we do this is just to get the right value for soap:address. This value must be computed at deploy time, since it is based on container configuration specifics. You could of course edit the WSDL file yourself, although you need to ensure that the path is correct.</para>
+ <para>Before going into detail on the client-side it is important to understand the decoupling concept that is central to Web Services. Web Services are not the best fit for internal RPC, even though they can be used in this way; there are much better technologies for achieving this (CORBA, and RMI for example). Web Services were designed specifically for interoperable coarse-grained correspondence. There is no expectation or guarantee that any party participating in a Web Service interaction will be at any particular location, running on any particular operating system, or written in any particular programming language. So because of this, it is important to clearly separate client and server implementations. The only thing they should have in common is the abstract contract definition. If, for whatever reason, your software does not adhere to this principal, then you should not be using Web Services. For the above reasons, the recommended methodology for developing a c!
lient is to follow the top-down approach, even if the client is running on the same server.</para>
+ <para>Let's repeat the process of the top-down section, although using the deployed WSDL, instead of the one generated offline by <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide</ulink>. The reason why we do this is just to get the right value for soap:address. This value must be computed at deploy time, since it is based on container configuration specifics. You could of course edit the WSDL file yourself, although you need to ensure that the path is correct.</para>
<para>Offline version:</para>
<programlisting role="XML">
<service name='EchoService'>
@@ -1502,7 +1493,7 @@
<para>
<emphasis role="bold">SOAP message exchange</emphasis>
</para>
- <para>Below you see the SOAP messages that are beeing exchanged.</para>
+ <para>Below you see the SOAP messages that are being exchanged.</para>
<programlisting role="XML">
<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
<env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'>
@@ -1609,12 +1600,12 @@
<para>JBossWS uses handlers to identify ws-security encoded requests and invoke the security components to sign and encrypt messages. In order to enable security processing, the client and server side need to include a corressponding handler configuration. The preferred way is to reference a predefined <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSEndpointConfiguration">JAX-WS Endpoint Configuration</ulink> or <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSClientConfiguration">JAX-WS Client Configuration</ulink> respectively.</para>
<para>
<note><title>Note</title>
- <para>You need to setup both the endpoint configuration and the WSSE declarations i. e. two separate steps.</para>
+ <para>You need to set up the endpoint configuration and the WSSE declarations separately.</para>
</note>
</para>
</section>
<section>
- <title>Server side WSSE declaration (jboss-wsse-server.xml)</title>
+ <title>Server side WSSE declaration (<filename>jboss-wsse-server.xml</filename>)</title>
<para>In this example we configure both the client and the server to sign the message body. Both also require this from each other. So, if you remove either the client or the server security deployment descriptor, you will notice that the other party will throw a fault explaining that the message did not conform to the proper security requirements.</para>
<programlisting role="XML">
<jboss-ws-security xmlns="http://www.jboss.com/ws-security/config"
@@ -1635,31 +1626,31 @@
</programlisting>
<orderedlist>
<listitem>
- <para> This specifies that the key store we wish to use is <filename>WEB-INF/wsse.keystore</filename>, which is located in our war file.</para>
+ <para> This specifies that the key store we wish to use is <filename>WEB-INF/wsse.keystore</filename>, which is located in our WAR file.</para>
</listitem>
<listitem>
- <para> This specifies that the store password is "jbossws". Password can be encypted using the {EXT} and {CLASS} commands. Please see samples for their usage.</para>
+ <para> This specifies that the store password is <literal>jbossws</literal>. Password can be encypted using the {EXT} and {CLASS} commands. Please see samples for their usage.</para>
</listitem>
<listitem>
<para> This specifies that the trust store we wish to use is <filename>WEB-INF/wsse.truststore</filename>, which is located in our war file.</para>
</listitem>
<listitem>
- <para> This specifies that the trust store password is also "jbossws". Password can be encrypted using the {EXT} and {CLASS} commands. Please see samples for their usage.</para>
+ <para> This specifies that the trust store password is also <literal>jbossws</literal>. Password can be encrypted using the {EXT} and {CLASS} commands. Please see samples for their usage.</para>
</listitem>
<listitem>
<para> Here we start our root config block. The root config block is the default configuration for all services in this war file.</para>
</listitem>
<listitem>
- <para> This means that the server must sign the message body of all responses. Type means that we are using X.509v3 certificate (a standard certificate). The alias option says that the certificate and key pair to use for signing is in the key store under the "wsse" alias</para>
+ <para> This means that the server must sign the message body of all responses. Type means that we are using X.509v3 certificate (a standard certificate). The alias option says that the certificate and key pair to use for signing is in the key store under the <literal>wsse</literal> alias</para>
</listitem>
<listitem>
<para> Here we start our optional requires block. This block specifies all security requirements that must be met when the server receives a message.</para>
</listitem>
<listitem>
- <para> This means that all web services in this war file require the message body to be signed.</para>
+ <para> This means that all web services in this WAR file require the message body to be signed.</para>
</listitem>
</orderedlist>
- <para>By default an endpoint does not use the WS-Security configuration. Users can use proprietary <literal>@EndpointConfig</literal> annotation to set the config name. See <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSEndpointConfiguration">JAX-WS_Endpoint_Configuration</ulink> for the list of available config names.</para>
+ <para>By default an endpoint does not use the WS-Security configuration. Users can use proprietary <literal>@EndpointConfig</literal> annotation to set the configuration name. See <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSEndpointConfiguration">http://www.jboss.org/community/wiki/JBossWS-JAX-WSEndpointConfiguration</ulink> for the list of available configuration names.</para>
<programlisting role="JAVA">
@WebService
@EndpointConfig(configName = "Standard WSSecurity Endpoint")
@@ -1686,10 +1677,10 @@
</programlisting>
<orderedlist>
<listitem>
- <para> Here we start our root config block. The root config block is the default configuration for all web service clients (Call, Proxy objects).</para>
+ <para> Here we start our root configuration block. The root configuration block is the default configuration for all web service clients (Call, Proxy objects).</para>
</listitem>
<listitem>
- <para> This means that the client must sign the message body of all requests it sends. Type means that we are to use a X.509v3 certificate (a standard certificate). The alias option says that the certificate/key pair to use for signing is in the key store under the "wsse" alias</para>
+ <para> This means that the client must sign the message body of all requests it sends. Type means that we are to use a X.509v3 certificate (a standard certificate). The alias option says that the certificate/key pair to use for signing is in the key store under the <literal>wsse</literal> alias</para>
</listitem>
<listitem>
<para> Here we start our optional requires block. This block specifies all security requirements that must be met when the client receives a response.</para>
@@ -1700,7 +1691,7 @@
</orderedlist>
<section>
<title>Client side key store configuration</title>
- <para>We did not specify a key store or trust store, because client apps instead use the wsse System properties instead. If this was a web or ejb client (meaning a webservice client in a war or ejb jar file), then we would have specified them in the client descriptor.</para>
+ <para>We did not specify a key store or trust store, because client applications use the wsse System properties instead. If this were a web or ejb client (meaning a webservice client in a WAR or EJB jar file), then we would have specified them in the client descriptor.</para>
<para>Here is an excerpt from the JBossWS samples:</para>
<programlisting role="XML">
<sysproperty key="org.jboss.ws.wsse.keyStore"
@@ -1744,19 +1735,18 @@
</section>
<section>
<title>Installing the BouncyCastle JCE provider</title>
- <para>The information below has originaly been provided by <ulink url="http://www.bouncycastle.org/specifications.html#install">The Legion of the Bouncy Castle</ulink>.</para>
+ <para>The information below has originally been provided by <ulink url="http://www.bouncycastle.org/specifications.html#install">The Legion of the Bouncy Castle</ulink>.</para>
<para>The provider can be configured as part of your environment via static registration by adding an entry to the <filename>java.security</filename> properties file (found in <filename>$JAVA_HOME/jre/lib/security/java.security</filename>, where <filename>$JAVA_HOME</filename> is the location of your JDK and JRE distribution). You will find detailed instructions in the file but basically it comes down to adding a line:</para>
<programlisting> <![CDATA[
security.provider.<n>=org.bouncycastle.jce.provider.BouncyCastleProvider
]]> </programlisting>
<para>Where <code><n></code> is the preference you want the provider at.</para>
<para>
- <note><title>Note</title>
-
+ <note><title>Note</title>
<para>Issues may arise if the Sun provided providers are not first.</para>
</note>
</para>
- <para>Where users will put the provider jar is mostly up to them, although with jdk5 the best (and in some cases only) place to have it is in <filename>$JAVA_HOME/jre/lib/ext</filename>. Under Windows there will normally be a JRE and a JDK install of Java. If user think he have installed it correctly and it still doesn't work then with high probability the provider installation is not used.</para>
+ <para>Where users will put the provider JAR is mostly up to them, although with JDK5 the best (and in some cases only) place to have it is in <filename>$JAVA_HOME/jre/lib/ext</filename>. Under Windows there will normally be a JRE and a JDK install of Java. If an installation does not work despite apparently correct installation, it is likely that the provider installation has not been used.</para>
</section>
</section>
<section>
@@ -1767,30 +1757,42 @@
<title>Apache jUDDI Configuration</title>
<para>Configuration of the jUDDI registry happens via an MBean Service that is deployed in the juddi-service.sar archive in the "all" configuration. The configuration of this service can be done in the <filename>jboss-service.xml</filename> of the META-INF directory in the <filename>juddi-service.sar</filename></para>
<para>Let us look at the individual configuration items that can be changed.</para>
- <para>DataSources configuration</para>
-<programlisting role="XML">
-<!-- Datasource to Database -->
-<attribute name="DataSourceUrl">java:/DefaultDS</attribute>
-</programlisting>
- <para>Database Tables (Should they be created on start, Should they be dropped on stop, Should they be dropped on start etc)</para>
-<programlisting role="XML">
-<!-- Should all tables be created on Start-->
+ <variablelist>
+ <varlistentry>
+ <term>Datasource Configuration</term>
+ <listitem>
+ <programlisting role="XML"><!-- Datasource to Database -->
+<attribute name="DataSourceUrl">java:/DefaultDS</attribute></programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Database Tables</term>
+ <listitem>
+ <para>Defines whether tables should be created on start, dropped on stop, dropped on start, etc.</para>
+ <programlisting role="XML"><!-- Should all tables be created on Start-->
<attribute name="CreateOnStart">false</attribute>
<!-- Should all tables be dropped on Stop-->
<attribute name="DropOnStop">true</attribute>
<!-- Should all tables be dropped on Start-->
-<attribute name="DropOnStart">false</attribute>
-</programlisting>
- <para>JAXR Connection Factory to be bound in JNDI. (Should it be bound? and under what name?)</para>
-<programlisting role="XML"><!-- Should I bind a Context to which JaxrConnectionFactory bound-->
+<attribute name="DropOnStart">false</attribute></programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>JAXR Connection Factory to be bound in JNDI</term>
+ <listitem>
+ <para>Defines whether the connection factory should be bound, and the binding name.</para>
+ <programlisting role="XML"><!-- Should I bind a Context to which JaxrConnectionFactory bound-->
<attribute name="ShouldBindJaxr">true</attribute>
<!-- Context to which JaxrConnectionFactory to bind to. If you have remote clients, please bind it to the global namespace(default behavior).
To just cater to clients running on the same VM as JBoss, change to java:/JAXR -->
-<attribute name="BindJaxr">JAXR</attribute>
-</programlisting>
- <para>Other common configuration:</para>
- <para>Add authorized users to access the jUDDI registry. (Add a sql insert statement in a single line)</para>
+<attribute name="BindJaxr">JAXR</attribute></programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Other common configuration</term>
+ <listitem>
+ <para>Add authorized users to access the jUDDI registry. (Add a SQL insert statement in a single line)</para>
<programlisting> <![CDATA[
Look at the script META-INF/ddl/juddi_data.ddl for more details. Example for a user 'jboss'
@@ -1798,6 +1800,9 @@
EMAIL_ADDRESS,IS_ENABLED,IS_ADMIN)
VALUES ('jboss','JBoss User','jboss at xxx','true','true');
]]> </programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
<section>
<title>JBoss JAXR Configuration</title>
@@ -1809,14 +1814,14 @@
jaxr.publish.url=http://localhost:8080/juddi/publish
scout.proxy.transportClass=org.jboss.jaxr.scout.transport.SaajTransport
]]> </programlisting>
- <para>Please remember to change the hostname from "localhost" to the hostname of the UDDI service/JBoss Server.</para>
+ <para>Please remember to change the hostname from <literal>localhost</literal> to the hostname of the UDDI service/JBoss Server.</para>
<para>You can pass the System Properties to the JVM in the following ways:</para>
<itemizedlist>
<listitem>
- <para> When the client code is running inside JBoss (maybe a servlet or an EJB). Then you will need to pass the System properties in the <filename>run.sh</filename> or <filename>run.bat</filename> scripts to the java process via the <code>"-D"</code> option.</para>
+ <para> When the client code is running inside JBoss (maybe a servlet or an EJB). Then you will need to pass the System properties in the <filename>run.sh</filename> or <filename>run.bat</filename> scripts to the java process via the <code>-D</code> option.</para>
</listitem>
<listitem>
- <para> When the client code is running in an external JVM. Then you can pass the properties either as "-D" options to the java process or explicitly set them in the client code(not recommended).</para>
+ <para> When the client code is running in an external JVM. Then you can pass the properties either as <code>-D</code> options to the java process or explicitly set them in the client code(not recommended).</para>
</listitem>
</itemizedlist>
<programlisting> <![CDATA[
@@ -1826,21 +1831,30 @@
<section>
<title>JAXR Sample Code</title>
<para>There are two categories of API: JAXR Publish API and JAXR Inquiry API. The important JAXR interfaces that any JAXR client code will use are the following.</para>
- <itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term><classname>javax.xml.registry.RegistryService</classname></term>
<listitem>
- <para> <ulink url="http://java.sun.com/javaee/5/docs/api/javax/xml/registry/RegistryService.html">javax.xml.registry.RegistryService</ulink> From J2EE 5.0 JavaDoc: "This is the principal interface implemented by a JAXR provider. A registry client can get this interface from a Connection to a registry. It provides the methods that are used by the client to discover various capability specific interfaces implemented by the JAXR provider."</para>
+ <para>The principal interface implemented by a JAXR provider. A registry client can get this interface from a Connection to a registry. It provides the methods that are used by the client to discover various capability specific interfaces implemented by the JAXR provider.</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><classname>javax.xml.registry.BusinessLifeCycleManager</classname></term>
<listitem>
- <para> <ulink url="http://java.sun.com/javaee/5/docs/api/javax/xml/registry/BusinessLifeCycleManager.html">javax.xml.registry.BusinessLifeCycleManager</ulink> From J2EE 5.0 JavaDoc: "The <classname>BusinessLifeCycleManager</classname> interface, which is exposed by the Registry Service, implements the life cycle management functionality of the Registry as part of a business level API. There is no authentication information provided, because the Connection interface keeps that state and context on behalf of the client."</para>
+ <para>This interface is exposed by the Registry Service, and implements the life cycle management functionality of the Registry as part of a business level API. There is no authentication information provided, because the Connection interface keeps that state and context on behalf of the client.</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><classname>javax.xml.registry.BusinessQueryManager</classname></term>
<listitem>
- <para> <ulink url="http://java.sun.com/javaee/5/docs/api/javax/xml/registry/BusinessQueryManager.html">javax.xml.registry.BusinessQueryManager</ulink> From J2EE 5.0 JavaDoc: "The <classname>BusinessQueryManager</classname> interface, which is exposed by the Registry Service, implements the business style query interface. It is also referred to as the focused query interface."</para>
+ <para>This interface is exposed by the Registry Service, and implements the business style query interface. It is also referred to as the focused query interface.</para>
</listitem>
- </itemizedlist>
+ </varlistentry>
+ </variablelist>
<para>Let us now look at some of the common programming tasks performed while using the JAXR API:</para>
- <para>Getting a JAXR Connection to the registry.</para>
-<programlisting role="JAVA">
-String queryurl = System.getProperty("jaxr.query.url", "http://localhost:8080/juddi/inquiry");
+ <formalpara>
+ <title>Getting a JAXR Connection to the registry</title>
+ <para><programlisting role="JAVA">String queryurl = System.getProperty("jaxr.query.url", "http://localhost:8080/juddi/inquiry");
String puburl = System.getProperty("jaxr.publish.url", "http://localhost:8080/juddi/publish");
..
Properties props = new Properties();
@@ -1854,9 +1868,10 @@
factory = ConnectionFactory.newInstance();
factory.setProperties(props);
connection = factory.createConnection();
-</programlisting>
- <para>Authentication with the registry.</para>
-<programlisting role="JAVA">
+</programlisting></para>
+ </formalpara>
+ <formalpara><title>Authentication with the registry</title>
+<para><programlisting role="JAVA">
/**
* Does authentication with the uddi registry
*/
@@ -1868,10 +1883,11 @@
connection.setCredentials(creds);
}
-</programlisting>
- <para>Save a Business</para>
-<programlisting role="JAVA">
-/**
+</programlisting></para>
+ </formalpara>
+ <formalpara>
+ <title>Save a Business</title>
+<para><programlisting role="JAVA">/**
* Creates a Jaxr Organization with 1 or more services
*/
protected Organization createOrganization(String orgname) throws JAXRException
@@ -1924,11 +1940,11 @@
org.addService(service);
return org;
-}
-</programlisting>
- <para>Query a Business</para>
-<programlisting role="JAVA">
-/**
+}</programlisting></para>
+ </formalpara>
+ <formalpara>
+ <title>Query a Business</title>
+<para><programlisting role="JAVA">/**
* Locale aware Search a business in the registry
*/
public void searchBusiness(String bizname) throws JAXRException
@@ -1976,26 +1992,31 @@
connection.close();
}
}
-</programlisting>
- <para>For more examples of code using the JAXR API, please refer to the resources in the Resources Section.</para>
+</programlisting></para>
+ </formalpara>
+ <para>For more examples of code using the JAXR API, refer to the resources in the Resources Section.</para>
</section>
<section>
<title>Troubleshooting</title>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">I cannot connect to the registry from JAXR.</emphasis> Please check the inquiry and publish url passed to the JAXR ConnectionFactory.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">I cannot connect to the jUDDI registry.</emphasis> Please check the jUDDI configuration and see if there are any errors in the server.log. And also remember that the jUDDI registry is available only in the "all" configuration.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">I cannot authenticate to the jUDDI registry.</emphasis> Have you added an authorized user to the jUDDI database, as described earlier in the chapter?</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">I would like to view the SOAP messages in transit between the client and the UDDI Registry.</emphasis> Please use the tcpmon tool to view the messages in transit. <ulink url="http://tcpmon.dev.java.net/">TCPMon</ulink></para>
- </listitem>
- </itemizedlist>
- </section>
+ <qandaset>
+ <qandaentry>
+ <question><para>I cannot connect to the registry from JAXR.</para></question>
+ <answer><para>Check the inquiry and publish url passed to the JAXR <classname>ConnectionFactory</classname>.</para></answer>
+ </qandaentry>
+ <qandaentry>
+ <question><para>I cannot connect to the jUDDI registry.</para></question>
+ <answer><para>Check the jUDDI configuration and see if there are any errors in the server log. Remember that the jUDDI registry is available only in the <literal>production</literal> configuration.</para></answer>
+ </qandaentry>
+ <qandaentry>
+ <question><para>I cannot authenticate to the jUDDI registry.</para></question>
+ <answer><para>Check that you have added an authorized user to the jUDDI datavase, as described earlier in this chapter.</para></answer>
+ </qandaentry>
+ <qandaentry>
+ <question><para>I would like to view the SOAP messages in transit between the client and the UDDI Registry.</para></question>
+ <answer><para>Use the <application>tcpmon</application> tool <ulink url="http://tcpmon.dev.java.net/">http://tcpmon.dev.java.net/</ulink> to view the messages in transit.</para></answer>
+ </qandaentry>
+ </qandaset>
+ </section>
<section>
<title>Resources</title>
<itemizedlist>
@@ -2020,7 +2041,7 @@
</section>
<section>
<title>JBossWS Extensions</title>
- <para>This section describes propriatary JBoss extensions to JAX-WS.</para>
+ <para>This section describes proprietary JBoss extensions to JAX-WS.</para>
<section>
<title>Proprietary Annotations</title>
<para>For the set of standard annotations, please have a look at <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSAnnotations">JAX-WS Annotations</ulink></para>
@@ -2141,7 +2162,7 @@
String value();
/**
- * The name for the unauthenticated pricipal
+ * The name for the unauthenticated principal
*/
String unauthenticatedPrincipal() default "";
}</programlisting>
@@ -2180,4 +2201,3 @@
</orderedlist>
</section>
</chapter>
-
Modified: projects/docs/enterprise/EWP_5.0/RESTEasy/en-US/RESTEasy_Reference_Guide.ent
===================================================================
--- projects/docs/enterprise/EWP_5.0/RESTEasy/en-US/RESTEasy_Reference_Guide.ent 2010-02-07 23:07:07 UTC (rev 100671)
+++ projects/docs/enterprise/EWP_5.0/RESTEasy/en-US/RESTEasy_Reference_Guide.ent 2010-02-08 01:21:00 UTC (rev 100672)
@@ -2,3 +2,5 @@
<!ENTITY JBEAPVERS "5.0">
<!ENTITY HOLDER "Red Hat, Inc">
<!ENTITY YEAR "2010">
+<!ENTITY PRODUCT "JBoss Enterprise Web Platform">
+<!ENTITY BOOKID "RESTEasy_Reference_Guide">
More information about the jboss-cvs-commits
mailing list