<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="esb">
  <title>JBoss ESB Integration</title>   
       
       <section>
       		<title>Overview</title>

       		<para>
       		This section outlines the support provided for the direct integration between RiftSaw
       		and JBossESB.
       		</para>
       		
       		<para>
       		Bi-directional loose integration is available through the use of web services.
       		For example, an ESB action may invoke a BPEL process running within RiftSaw
       		by invoking the appropriate web service represented by a WSDL interface.
       		Similarly, a BPEL process can invoke an ESB managed service that is capable
       		of presenting itself as a web service. 
       		</para>
       		
       		<para>
       		However this section will describe how integration between RiftSaw and JBossESB actions
       		can be achieved without the use of web services (i.e. WSDL and SOAP).
       		</para>
       </section>
  
       <section>
       		<title>Using the <emphasis>BPELInvoke</emphasis> ESB action</title>

			<para>
			The <emphasis>BPELInvoke</emphasis> ESB action can be used within a
			<emphasis>jboss-esb.xml</emphasis> to request an invocation on a BPEL
			process running inside RiftSaw. The only constraints are that RiftSaw is
			installed within the same Java VM  and that the requested BPEL process must
			have been deployed to the local RiftSaw engine.
			</para>
			
       		<para> 
       		The following example illustrates the <emphasis>BPELInvoke</emphasis> ESB action
       		being used as part of the <emphasis>bpel_helloworld</emphasis> sample.
       		</para>
       		
			<informalexample>
  				<programlisting role="XML" ><![CDATA[
<action name="action2" class="org.jboss.soa.esb.actions.bpel.BPELInvoke">
    <property name="service" value="{http://www.jboss.org/bpel/examples/wsdl}HelloService"/>
    <property name="port" value="HelloPort" />
    <property name="operation" value="hello" />
    <property name="requestPartName" value="TestPart" />
    <property name="responsePartName" value="TestPart" />
</action>
 				 ]]></programlisting>
			</informalexample>
       		
       		<para>
       		The ESB action class is <emphasis>org.jboss.soa.esb.actions.bpel.BPELInvoke</emphasis>.
       		</para>
       		
       		<para>
       		The properties for this ESB action are:
       		</para>
       		
       		<itemizedlist>
       			<listitem>
       			<para>
       			service
       			</para>
       			<para>
       			This property is mandatory, and defines the service name registered in the WSDL associated
       			with the deployed BPEL process.
       			</para>
       			</listitem>
       			<listitem>
       			<para>
       			port
       			</para>
       			<para>
       			This property is optional, and defines the port name registered in the WSDL associated
       			with the deployed BPEL process. This parameter is only required if port specific endpoint
       			configuration information has been registered as part of the BPEL process deployment.
       			</para>
       			</listitem>
       			<listitem>
       			<para>
       			operation
       			</para>
       			<para>
       			This property is mandatory, and represents the WSDL operation that is being invoked.
       			</para>
       			</listitem>
       			<listitem>
       			<para>
       			requestPartName
       			</para>
       			<para>
       			This optional property can be used to define the WSDL message part that the inbound
       			ESB message content should be mapped to. This property should be used where the
       			ESB message does not already represent a multi-part message.
       			</para>
       			</listitem>
       			<listitem>
       			<para>
       			responsePartName
       			</para>
       			<para>
       			This optional property can be used to extract the content of a response multi-part
       			WSDL message, and place this in the ESB message being passed to the next ESB
       			action in the pipeline. If this property is not defined, then the complete multi-part
       			message value will be placed in the ESB message.
       			</para>
       			</listitem>
       			<listitem>
       			<para>
       			abortOnFault
       			</para>
       			<para>
       			This optional property can be used to indicate whether a fault, generated during the
       			invocation of a BPEL process, should be treated as a message (when the value of this
       			property is 'false'), or as an exception that will abort the ESB service. The default
       			value is 'true', causing the ESB service to abort.
       			</para>
       			</listitem>
       		</itemizedlist>
       		
       		<para>
       		This ESB action supports inbound messages with content defined as either:
       		</para>
       		
       		<itemizedlist>
       			<listitem>
       			<para>DOM</para>
       			<para>
       			If the message content is a DOM document or element, then this can either be
       			used as the complete multi-part message, or as the content of a message part
       			defined using the <emphasis>requestPartName</emphasis> property.
       			</para>
       			<para>
       			If the message content is a DOM text node, then this can ONLY be used if a
       			multi-part name has been defined in the <emphasis>requestPartName</emphasis>
       			property.
       			</para>
       			</listitem>
       			<listitem>
       			<para>Java String</para>
       			<para>
       			If the message content is a string representation of an XML document, then
       			the <emphasis>requestPartName</emphasis> is optional. If not specified, then
       			the document must represent the multipart message.
       			</para>
       			<para>
       			If the message content is a string that does not represent an XML document, then
       			the <emphasis>requestPartName</emphasis> must be specified.
       			</para>
       			</listitem>
       		</itemizedlist>
       		
       		<para>
       		When the message content represents the complete multipart message, this must be defined as
       		a top level element (whose name is irrelevant) with immediate child elements that
       		represent each of the multiple parts of the message. Each of these elements must then
       		have a single element/node, that represents the value of the named part.
       		</para>
       		
			<informalexample>
  				<programlisting role="XML" ><![CDATA[
<message>
	<TestPart>
		Hello World
	</TestPart>
</message>
 				 ]]></programlisting>
			</informalexample>
			
			<para>
			This shows an example of a multipart message structure. The top element (i.e. <emphasis>message</emphasis>)
			is unimportant. The elements at the next level represent the part names - in this case
			there is only a single part, with name <emphasis>TestPart</emphasis>. The value of this
			part is defined as a text node, with value "Hello World". However this could have been an
			element representing the root node of a more complex XML value.
			</para>
			
			<para>
			The following diagram illustrates the inter-relationship of the JBossESB bpel_helloworld 
			quickstart and the RiftSaw BPEL process configuration files.
			</para>
       		
			<imageobject>
				<imagedata fileref="images/BPELInvokeRelationship.jpg" align="center" width="6in" />
			</imageobject>		

       		<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>
