3:48 p.m.
Author: objectiser
Date: 2009-11-09 09:48:03 -0500 (Mon, 09 Nov 2009)
New Revision: 255
Modified:
trunk/docs/docbook/userguide/src/main/module/esb.xml
Log:
Document fault handling approach for ESB to BPEL process integration.
Modified: trunk/docs/docbook/userguide/src/main/module/esb.xml
===================================================================
--- trunk/docs/docbook/userguide/src/main/module/esb.xml 2009-11-09 14:18:16 UTC (rev
254)
+++ trunk/docs/docbook/userguide/src/main/module/esb.xml 2009-11-09 14:48:03 UTC (rev
255)
@@ -159,6 +159,79 @@
element representing the root node of a more complex XML value.
</para>
+ <section>
+ <title>Fault Handling</title>
+
+ <para>
+ The normal response from a WSDL operation will be returned from the
<emphasis>BPELInvoke</emphasis>
+ ESB action as a normal message and placed on the action pipeline ready for
processing by the next
+ ESB action, or alternatively if no further actions have been defined, then
returned back to the
+ service client.
+ </para>
+
+ <para>
+ Faults, associated with a WSDL operation, are handled slightly differently.
Depending on configuration
+ it is possible to receive the fault as an ESB message or for the fault to be
treated as an
+ exception which aborts the action pipeline. The configuration property used to
determine which
+ behaviour is used is called <emphasis>abortOnFault</emphasis>. The
default value for this property
+ is "true". As an example, from the loan fault quickstart sample,
+ </para>
+
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+<action name="action2"
class="org.jboss.soa.esb.actions.bpel.BPELInvoke">
+ <property name="service"
value="{http://example.com/loan-approval/wsdl/}loanService"/>
+ <property name="operation" value="request" />
+ <property name="abortOnFault" value="true" />
+</action>
+ ]]></programlisting>
+ </informalexample>
+
+ <para>
+ A WSDL fault has two relevant pieces of information, the fault type (or code)
and the fault details.
+ These are both returned in specific parts of ESB message's body.
+ </para>
+
+ <orderedlist>
+ <listitem>
+ Fault code (as javax.xml.namespace.QName)
+ <para>
+ ESB message body part:
<emphasis>org.jboss.soa.esb.message.fault.detail.code</emphasis>
+ </para>
+ <para>
+ This body part identifies the specific WSDL fault returned by the BPEL
process, associated with
+ the WSDL operation that was invoked.
+ </para>
+ <warning>
+ The specific version of the QName used by the JBoss server is from the
stax-api.jar found in the
+ server's lib/endorsed directory. If the client does not also include this
jar in a folder that is
+ in its endorsed directories, then a class version exception will occur when
this ESB message
+ part is accessed.
+ </warning>
+ </listitem>
+ <listitem>
+ Fault code (as textual representation of QName)
+ <para>
+ ESB message body part:
<emphasis>org.jboss.soa.bpel.message.fault.detail.code</emphasis>
+ </para>
+ <para>
+ This body part will return the textual representation of the QName for the
fault code. The textual
+ representation is of the form "{namespace}localpart" and can be
converted back into a QName using the
+ <emphasis>javax.xml.namespace.QName.valueOf(String)</emphasis>
method.
+ </para>
+ </listitem>
+ <listitem>
+ Fault details
+ <para>
+ ESB message body part:
<emphasis>org.jboss.soa.esb.message.fault.detail.detail</emphasis>
+ </para>
+ <para>
+ This body part will contain the textual representation of the message content
associated
+ with the fault.
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
</section>
</chapter>