Author: jeff.yuchang Date: 2009-04-27 04:05:58 -0400 (Mon, 27 Apr 2009) New Revision: 601 Added: cdl/trunk/docs/docbook/userguide/src/main/module/stateless-conversation-aware-esb.xml Modified: cdl/trunk/docs/docbook/userguide/src/main/master.xml Log: * Add the stateless esb actions document. Modified: cdl/trunk/docs/docbook/userguide/src/main/master.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/master.xml 2009-04-26 22:47:59 UTC (rev 600) +++ cdl/trunk/docs/docbook/userguide/src/main/master.xml 2009-04-27 08:05:58 UTC (rev 601) @@ -14,5 +14,5 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/overview.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/conversation-validation-with-cdl.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/conversation-aware-esb.xml"/> - + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/stateless-conversation-aware-esb.xml"/> </book> Added: cdl/trunk/docs/docbook/userguide/src/main/module/stateless-conversation-aware-esb.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/module/stateless-conversation-aware-esb.xml (rev 0) +++ cdl/trunk/docs/docbook/userguide/src/main/module/stateless-conversation-aware-esb.xml 2009-04-27 08:05:58 UTC (rev 601) @@ -0,0 +1,215 @@ +<?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="statelessconversationawareesb"> + <title>Stateless ESB Actions</title> + <section> + + <title>Stateless ESB Actions</title> + <section> + <title>Overview</title> + <para> +After the M1 release, we've found some problems in the conversation aware esb actions approach, mainly due to its complexity. +Therefore, we've introduced the Stateless conversation ESB actions, which we will see it later on. +With this new approach, users can still validate the message exchange in the runtime, but it doesn't need us to store +the state. So it simplified a lot without losing its functionality. + </para> + + </section> + + <section> + <title>Interaction</title> + <para> +Firstly, let's see the two basic actions for interaction. +Services interact by sending and receiving messages, whether synchronously or asynchronously. + </para> + <para> +JBossESB is designed to anonymously handle inbound messages (possibly requests), without explicitly defining restrictions on message type, and then optionally returning responses (again without explicitly defining the response message type). + </para> + <para> +Although this is sufficient for a runtime mechanism, where issues related to unexpected message types can be handled with suitable exceptions/faults, it does not enable the communication type structure to be understood by examination of the JBossESB configuration. + </para> + + <section> + <title>Sending a message</title> + <para> +When sending a message, the first thing to consider is the type of the message. This can be declared as a property on the <emphasis>SendMessageAction</emphasis>. +If dealing with RPC style interactions, then we may also want to optionally specify an operation name. + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ + <action class="org.jboss.soa.overlord.jbossesb.stateless.actions.SendMessageAction" + process="process" name="..."> + <property name="operation" value="getQuote" /> + <property name="messageType" value="requestForQuote" /> + .... + </action> + ]]></programlisting> + </informalexample> + + <itemizedlist> + <listitem> +Sending a request + <para> +When sending a request, we need to identify the destination service category/name. This is done by either specifying the category and name explicitly, using the <emphasis>serviceCategory</emphasis> and <emphasis>serviceName</emphasis> properties: + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ + + <action class="org.jboss.soa.overlord.jbossesb.stateless.actions.SendMessageAction" + process="process" name="..."> + .... + <property name="serviceName" value="RequestForQuote.main" /> + <property name="serviceCategory" value="ESBBroker.SupplierParticipant" /> + .... + </action> + ]]></programlisting> + </informalexample> + + </listitem> + + <listitem> +Sending a response + <informalexample> + <programlisting role="XML" ><![CDATA[ + + <action class="org.jboss.soa.overlord.jbossesb.stateless.actions.SendMessageAction" + process="process" name="..."> + .... + <property name="clientRole" value="buyer" /> + <property name="storageClass" value="orgization.your.impl.EPRStorageImpl" /> + .... + </action> + ]]></programlisting> + </informalexample> + <para> +When sending a response, the destination will not be directly available. The destination would have been received as a 'reply to' EPR (Endpoint Reference) in a previously received request (see <emphasis>ReceiveMessageAction</emphasis> for details of how to store the 'reply to' EPR). +Therefore, to indicate which EPR to respond to, a property called 'clientEPR' is specified with the name of the stored EPR. This must match up to a previously stored EPR name within a <emphasis>ReceiveMessageAction</emphasis>. + </para> + <para> +The value of <emphasis>storageClass</emphasis> should be a class that implements the <emphasis>org.jboss.soa.overlord.jbossesb.EPRStorage</emphasis> interface, basically this class is responsible for registering, getting EPR from roleName. + </para> + </listitem> + </itemizedlist> + + </section> + + <section> + <title>Receiving a message</title> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <action class="org.jboss.soa.overlord.jbossesb.stateless.actions.ReceiveMessageAction" + process="process" name="s1-2"> + <property name="operation" value="makeEnquiry" /> + <property name="messageType" value="enquiry" /> + <property name="clientRole" value="buyer" /> + <property name="storageClass" value="com.acme.services.creditAgency.MemoryEPRStorage" /> + </action> + ]]></programlisting> + </informalexample> + + <para> +The <emphasis>ReceiveMessageAction</emphasis> is used to explicitly define the message type that should be received. +If an RPC style has been used, then the optional operation name can also be defined. + </para> + <para> +Unlike the <emphasis>SendMessageAction</emphasis>, which will actually send a message to the specified service category/name, +the <emphasis>ReceiveMessageAction</emphasis> primarily serves to provide explicit details about the expected message and to perform any relevant validation of the message content. If an incorrect message type is received, then an error will be logged. + </para> + <para> +The optional 'cliengRole' and 'storageClass' properties are used to store any specific "reply to" EPR (associated with the message) against the specified name. This makes the EPR accessible to any subsequent <emphasis>SendMessageAction</emphasis> activities that need to return a response or send a notification. + </para> + </section> + </section> + + <section> + <title>Controlling Flow</title> + <para> +This section describes the two control flow mechanisms that are supported by the stateless ESB actions. + </para> + <para> +The default control flow, supported natively by the ESB action pipeline design, is a sequence. As the name implies, the actions are performed one at a time in the order they defined in the action pipeline, i.e. in a sequence. + </para> + + <section> + <title>Selecting paths based on a decision</title> + <para> +The action associated with the 'selection of a path based on a decision' is the <emphasis>IfAction</emphasis>. An example of this construct is: + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ + <action class="org.jboss.soa.overlord.jbossesb.stateless.actions.IfAction" name="..." process="process"> + <property name="paths"> + <if service-category="PurchaseGoods.CreditAgency" service-name="CreditAgency.decision1" decision-class="org.jboss.soa.overlord.jbossesb.TestDecision"/> + <elseif service-category="PurchaseGoods.CreditAgency" service-name="CreditAgency.decision2" decision-class="org.jboss.soa.overlord.jbossesb.Test2ndDecision"/> + <else service-category="PurchaseGoods.CreditAgency" service-name="CreditAgency.decision3"/> + </property> + </action> + ]]></programlisting> + </informalexample> + <para> +This construct defines a 'path' property with one or more elements, representing the <emphasis>if</emphasis>, <emphasis>elseif</emphasis> and <emphasis>else</emphasis> aspects of the traditional if/else construct. Only the <emphasis>if</emphasis> element is mandatory, and can be followed by zero or more <emphasis>elseif</emphasis> elements before ending with the optional <emphasis>else</emphasis> element. + </para> + <para> +The <emphasis>if</emphasis> and <emphasis>elseif</emphasis> elements can define an 'decision-class' attribute to be evaluated at runtime, to determine if the associated 'service-category' and 'service-name' should be invoked. +the value of decision-class must implement the interface of <emphasis>org.jboss.soa.overlord.jbossesb.Decision</emphasis>. + </para> + </section> + + <section> + <title>Message router action</title> + <para> +The action used to select paths based on a received message type is <emphasis>SwitchAction</emphasis>. +In the stateless esb actions approach, we are using this as the <emphasis>Message Router</emphasis>. +The configuration of <emphasis>SwithAction</emphasis> is like: + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ + <action class="org.jboss.soa.overlord.jbossesb.stateless.actions.SwitchAction" name="..." process="process"> + <property name="serviceDescriptionName" value="{org.pi4soa.esbbroker.esbbroker}ESBBrokerProcess-Broker"/> + <property name="conversationType" value="overlord.cdl.samples.LoanBroker@Broker"/> + <property name="paths"> + <case service-category="org.pi4soa.esbbroker.esbbroker" service-name="ESBBrokerProcess_Broker__1"> + <message type="enquiry"/> + </case> + <case service-category="org.pi4soa.esbbroker.esbbroker" service-name="ESBBrokerProcess_Broker__7"> + <event description="Event trigger to send quoteList message type(s)"/> + </case> + <case service-category="org.pi4soa.esbbroker.esbbroker" service-name="ESBBrokerProcess_Broker__8"> + <message type="buy"/> + </case> + </property> + </action> + ]]></programlisting> + </informalexample> + <para> +In this approach, the <emphasis>SwitchAction</emphasis> typically is the point of contact for other services. Also true for the internal services. + + </para> + <para> +The 'paths' property defines one or more 'case' elements. These elements identify a service category and name that should be invoked upon receipt of one or more message types, as specified by 'message' elements contained within the 'case' elements. + </para> + <para> +The 'type' attribute on the 'message' element defines the type of message that can be routed to the specified service category/name. In the example above, the message types have no namespace. +However if they have a namespace, this can be defined in curly braces, e.g. "{http://www.jboss.org/samples}buy". + </para> + <para> +the 'event' attribute for paths with no associated message type. + </para> + <para> +Once a path has been selected, the associated service category/name will be invoked immediately. +If none of the paths specified within this action are relevant to the received message, then a runtime exception will be thrown. + </para> + </section> + + </section> + + <tip> + In this M2 release, we've just had these four actions in the stateless esb action approach. + we might add other actions in the subsequent release. If you have any comments and feedback, you can go to the forum or issue track to raise your request. + </tip> + + </section> +</chapter> +