[overlord-commits] Overlord SVN: r608 - in cdl/trunk/docs/docbook: gettingstartedguide/src/main/module and 4 other directories.

Author: objectiser Date: 2009-04-29 14:54:19 -0400 (Wed, 29 Apr 2009) New Revision: 608 Added: cdl/trunk/docs/docbook/userguide/src/main/images/genbpel1.png cdl/trunk/docs/docbook/userguide/src/main/images/genbpel2.png cdl/trunk/docs/docbook/userguide/src/main/images/genbpel3.png cdl/trunk/docs/docbook/userguide/src/main/module/bpel-governance.xml Removed: cdl/trunk/docs/docbook/userguide/src/main/module/stateless-conversation-aware-esb.xml Modified: cdl/trunk/docs/docbook/gettingstartedguide/src/main/master.xml cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml cdl/trunk/docs/docbook/samplesguide/src/main/master.xml cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig1.png cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig2.png cdl/trunk/docs/docbook/userguide/src/main/master.xml cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml Log: Updated docs to include bpel generation and some minor restructuring of the stateless ESB actions section. Modified: cdl/trunk/docs/docbook/gettingstartedguide/src/main/master.xml =================================================================== --- cdl/trunk/docs/docbook/gettingstartedguide/src/main/master.xml 2009-04-29 11:12:05 UTC (rev 607) +++ cdl/trunk/docs/docbook/gettingstartedguide/src/main/master.xml 2009-04-29 18:54:19 UTC (rev 608) @@ -5,7 +5,7 @@ <book lang="en"> <bookinfo> - <title>JBoss Overlord CDL 1.0-M1</title> + <title>JBoss Overlord CDL 1.0-M2</title> <subtitle>Getting Started Guide</subtitle> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/author_group.xml"/> </bookinfo> Modified: cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml =================================================================== --- cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml 2009-04-29 11:12:05 UTC (rev 607) +++ cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml 2009-04-29 18:54:19 UTC (rev 608) @@ -22,7 +22,7 @@ </note> <section> - <title>Design Time Governance using "Conversation Aware" ESB Actions</title> + <title>Design Time Governance</title> <section> <title>Creating a Choreography</title> @@ -81,9 +81,26 @@ </section> <section> - <title>What are "Conversation Aware" ESB Actions?</title> + <title>Design Time Governance With WS-BPEL</title> <para> +This milestone release includes a basic capability to generate a service implementation, for a participant in a choreography, using WS-BPEL. + </para> + <para> +Subsequent milestone releases will include more capabilities as part of the service generation, including the generation of WSDL, as well as supporting conformance checking back against the choreography description. + </para> + <para> +More information about how to use this feature can be found in the User Guide. + </para> + </section> + + <section> + <title>Design Time Governance With "Conversation Aware" ESB Actions</title> + + <section> + <title>What are "Conversation Aware" ESB Actions?</title> + + <para> <emphasis>Conversation aware</emphasis> ESB actions refer to a set of pre-defined ESB actions that enable the structure (or behaviour) of a service to be inferred. </para> @@ -235,6 +252,7 @@ </orderedlist> </section> + </section> <section> <title>Summary</title> Modified: cdl/trunk/docs/docbook/samplesguide/src/main/master.xml =================================================================== --- cdl/trunk/docs/docbook/samplesguide/src/main/master.xml 2009-04-29 11:12:05 UTC (rev 607) +++ cdl/trunk/docs/docbook/samplesguide/src/main/master.xml 2009-04-29 18:54:19 UTC (rev 608) @@ -5,7 +5,7 @@ <book lang="en"> <bookinfo> - <title>JBoss Overlord CDL 1.0-M1</title> + <title>JBoss Overlord CDL 1.0-M2</title> <subtitle>Samples Guide</subtitle> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/author_group.xml"/> </bookinfo> Added: cdl/trunk/docs/docbook/userguide/src/main/images/genbpel1.png =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/genbpel1.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/userguide/src/main/images/genbpel2.png =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/genbpel2.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/userguide/src/main/images/genbpel3.png =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/genbpel3.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig1.png =================================================================== (Binary files differ) Modified: cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig2.png =================================================================== (Binary files differ) Modified: cdl/trunk/docs/docbook/userguide/src/main/master.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/master.xml 2009-04-29 11:12:05 UTC (rev 607) +++ cdl/trunk/docs/docbook/userguide/src/main/master.xml 2009-04-29 18:54:19 UTC (rev 608) @@ -5,7 +5,7 @@ <book lang="en"> <bookinfo> - <title>JBoss Overlord CDL 1.0-M1</title> + <title>JBoss Overlord CDL 1.0-M2</title> <subtitle>User Guide</subtitle> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/author_group.xml"/> </bookinfo> @@ -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"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/bpel-governance.xml"/> </book> Added: cdl/trunk/docs/docbook/userguide/src/main/module/bpel-governance.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/module/bpel-governance.xml (rev 0) +++ cdl/trunk/docs/docbook/userguide/src/main/module/bpel-governance.xml 2009-04-29 18:54:19 UTC (rev 608) @@ -0,0 +1,71 @@ +<?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="bpelgovernance"> + <title>BPEL Governance</title> + + <section> + <title>Overview</title> + <para> +This section will describe governance features related to WS-BPEL. This initial release provides basic support for generating BPEL processes from a choreography description. Subsequent releases will also provide conformance checking, to ensure that changes to a BPEL process are validated to ensure the process remains conformant with the choreography. + </para> + </section> + + <section> + <title>Generating a BPEL process from CDL</title> + <section> + <title>Overview</title> + <para> +This section explains how to generate a template BPEL process from a pi4soa choreography description (.cdm) file. + </para> + </section> + <section> + <title>Generating the BPEL Process</title> + <para> +When the choreography description has been completed, and has no errors, the user should select the "Overlord->Generate->WS-BPEL" menu item from the popup menu associated with the choreography description (.cdm) file. + </para> + + <imageobject> + <imagedata fileref="images/genbpel1.png" width="4in" /> + </imageobject> + + <para> +When the dialog window is displayed, it will contain the list of services that can be generated, along with the project names that will be created. The user can unselect the services they do not wish to generate (also using the 'Check All' or 'Clear All' buttons). + </para> + + <imageobject> + <imagedata fileref="images/genbpel2.png" /> + </imageobject> + + <para> +The user can also select their preferred build system, which will create the relevant build structure. + </para> + <para> +If there is a problem with the name of the project select, such as invalid characters used in the name, or the project name already exists, then it will be displayed in red. + </para> + + <para> +Once the BPEL is generated, it can be viewed using the Eclipse BPEL editor, e.g. + </para> + + <imageobject> + <imagedata fileref="images/genbpel3.png" /> + </imageobject> + + </section> + + <section> + <title>Limitations with the current CDL to BPEL mapping</title> + + <para> +This initial version of the BPEL generation is primarily targeted at generating the interactions and grouping constructs. These are the important components that will be required when doing conformance checking as part of the next milestone. + </para> + + <para> +This means that assignments and conditional expressions are not currently generated. The 'when' construct in CDL (also known as the blocking workunit) is also not currently handled. This may possible be implemented using flow links. + </para> + </section> + </section> + +</chapter> + Modified: cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml 2009-04-29 11:12:05 UTC (rev 607) +++ cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml 2009-04-29 18:54:19 UTC (rev 608) @@ -49,16 +49,24 @@ <para> This ensures that all of the services will interaction correctly, as they will all have been validated against the choreography, and therefore work together by design. </para> + <para> +In the following two sections, we will describe how ESB services can be described using either +<emphasis>Stateful</emphasis> or <emphasis>Stateless</emphasis> "conversation aware" ESB actions. +The benefits of each approach will be discussed. + </para> </section> </section> <section> - <title>JBossESB "Conversation Aware" ESB Actions</title> + <title>Stateful "Conversation Aware" ESB Actions</title> <section> <title>Overview</title> <para> -This section outlines the various "conversation aware" ESB actions that can be used to make the communication behaviour of a service implementation explicit, thus enabling it to be compared for conformance against a description of the expected behaviour. +This section outlines the various <emphasis>stateful</emphasis> "conversation aware" ESB actions that can be used to make the communication behaviour of a service implementation explicit, thus enabling it to be compared for conformance against a description of the expected behaviour. </para> + <para> +The benefit of this <emphasis>stateful</emphasis> approach is that the stateful behaviour of a service is explicitly defined, and can be used to perform a precise conformance check against the stateful behaviour expected from a choreography description. The disadvantage of the approach, and the reason why this section describes many more ESB action types than in the following section, is that the ESB service needs to maintain additional state information related to the individual sessions (i.e. a session per business transaction), and this state information needs to be persisted independently from other business information that the service may be accessing. This state information can be used to determine when messages have been received out of order, however this functionality is also available in the conversation validation mechanism. + </para> </section> <section> <title>Conversational Service</title> @@ -85,7 +93,7 @@ maxThreads="1"/> </listeners> <actions mep="OneWay"> - <action class="org.jboss.soa.overlord.jbossesb.actions.MessageRouterAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.MessageRouterAction" process="process" name="s0-1"> <property name="paths"> <route service-category="ESBBroker.BrokerParticipant" @@ -121,7 +129,7 @@ In this example, the 'service' endpoint reference will be associated with the service category "ESBBroker.BrokerParticipant" and name "ESBBrokerProcess". All inbound requests to an instance of this service will be routed via this service descriptor. </para> <para> -This service descriptor therefore only has a single action, which represents the message routing capability. The action class is <emphasis>org.jboss.soa.overlord.jbossesb.actions.MessageRouterAction</emphasis>. This action only defines a single property 'path' which defines one or more 'route' elements. The attributes associated with this 'route' element are: +This service descriptor therefore only has a single action, which represents the message routing capability. The action class is <emphasis>org.jboss.soa.overlord.jbossesb.stateful.actions.MessageRouterAction</emphasis>. This action only defines a single property 'path' which defines one or more 'route' elements. The attributes associated with this 'route' element are: </para> <para> <itemizedlist> @@ -207,7 +215,7 @@ <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.CreateSessionAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.CreateSessionAction" process="process" name="..."> .... <property name="conversationType" @@ -242,7 +250,7 @@ Each top level or sub-service description will be associated with a business state 'pojo' class that contains its business relevant information and logic (i.e. methods). This class is identified by the property 'session', which will be associated with the initial conversation based ESB actions in a service (or sub-service) description, or in any subsequent conversation based ESB actions that require the information to determine the session instance. </para> <para> -As well as representing the business state and logic for a session (or sub-session), the pojo can define an annotation that provides information about the session. The annotation type is <classname>org.jboss.soa.overlord.jbossesb.actions.Service</classname>. +As well as representing the business state and logic for a session (or sub-session), the pojo can define an annotation that provides information about the session. The annotation type is <classname>org.jboss.soa.overlord.jbossesb.stateful.actions.Service</classname>. </para> <informalexample> @@ -250,7 +258,7 @@ package org.jboss.soa.overlord.samples.jbossesb.loan.broker; - import org.jboss.soa.overlord.jbossesb.actions.Service; + import org.jboss.soa.overlord.jbossesb.stateful.actions.Service; @Service(name="{http://www.jboss.org/overlord/loanBroker}Broker", conversationType="overlord.cdl.samples.LoanBroker@Broker", @@ -279,7 +287,7 @@ </para> <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.CreateSessionAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.CreateSessionAction" process="process" name="..."> <property name="session" value="org.jboss.soa.overlord.samples.jbossesb.loan.broker.BrokerMain" /> @@ -369,7 +377,7 @@ <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.SendMessageAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.SendMessageAction" process="process" name="..."> <property name="operation" value="getQuote" /> <property name="messageType" value="requestForQuote" /> @@ -392,7 +400,7 @@ <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.SendMessageAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.SendMessageAction" process="process" name="..."> .... <property name="serviceName" value="RequestForQuote.main" /> @@ -407,7 +415,7 @@ <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.SendMessageAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.SendMessageAction" process="process" name="..."> .... <property name="serviceNameExpression" value="supplier.serviceName" /> @@ -428,7 +436,7 @@ <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.SendMessageAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.SendMessageAction" process="process" name="..."> .... <property name="clientEPR" value="buyer" /> @@ -450,7 +458,7 @@ <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.SendMessageAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.SendMessageAction" process="process" name="..."> .... <property name="identities" > @@ -475,7 +483,7 @@ <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.ReceiveMessageAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.ReceiveMessageAction" process="process" name="s1-2"> <property name="operation" value="makeEnquiry" /> <property name="messageType" value="enquiry" /> @@ -519,7 +527,7 @@ </para> <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.SetStateAction" name="..."> + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.SetStateAction" name="..."> <property name="variable" value="supplierIndex" /> <property name="stateExpression" value="nextSupplier()" /> </action> @@ -545,7 +553,7 @@ </para> <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.SetMessageAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.SetMessageAction" process="process" name="..."> <property name="headerProperty" value="quoteList" /> <property name="stateExpression" value="quotes" /> @@ -576,7 +584,7 @@ </para> <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.IfAction" process="process" name="..."> + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.IfAction" process="process" name="..."> <property name="paths"> <if expression="isCreditHistoryAvailable()" service-category="ESBBroker.CreditAgency" @@ -611,7 +619,7 @@ </para> <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.SwitchAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.SwitchAction" process="process" name="..."> <property name="paths"> <case service-category="ESBBroker.BrokerParticipant" @@ -642,7 +650,7 @@ <title>Executing multiple paths concurrently</title> <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.ParallelAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.ParallelAction" process="process" name="..."> <property name="paths"> <path service-category="ESBBroker.BrokerParticipant" @@ -676,7 +684,7 @@ <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.WhileAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.WhileAction" process="process" name="..."> <property name="paths"> <while expression="hasNextSupplier()" @@ -703,7 +711,7 @@ <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.ScheduleStateAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.ScheduleStateAction" process="process" name="..."> <property name="serviceCategory" value="ESBBroker.BrokerParticipant" /> <property name="serviceName" value="ESBBrokerProcess.main.1" /> @@ -730,7 +738,7 @@ <informalexample> <programlisting role="XML" ><![CDATA[ - <action class="org.jboss.soa.overlord.jbossesb.actions.WhenAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.WhenAction" process="process" name="s4-1"> <property name="session" value="org.jboss.soa.overlord.samples.jbossesb.loan.broker.BrokerMain" /> @@ -760,7 +768,7 @@ <programlisting role="XML" ><![CDATA[ <actions mep="OneWay"> - <action class="org.jboss.soa.overlord.jbossesb.actions.PerformAction" + <action class="org.jboss.soa.overlord.jbossesb.stateful.actions.PerformAction" process="process" name="..."> <property name="serviceCategory" value="ESBBroker.BrokerParticipant" /> <property name="serviceName" value="RequestForQuote.main" /> @@ -795,6 +803,227 @@ </section> <section> + <title>Stateless "Conversation Aware" ESB Actions</title> + <section> + <title>Overview</title> + <para> +After the M1 release, we've found some problems in the <emphasis>Stateful</emphasis> "conversation aware" ESB actions approach, mainly due to its complexity and the need to have services recording state information. +Therefore, we've introduced the <emphasis>Stateless</emphasis> "conversation aware" 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> + + <para> +Thus the benefit of this approach is its simplicity, and therefore it has less impact on the way that users create ESB service descriptors. The disadvantage with this approach is that only fragments of stateful behaviour can be derived from the ESB jboss-esb.xml. However, this is useful enough to perform static conformance checking of the service implementation against a choreography description, and when used in conjunction with the dynamic conversation validation mechanism, it is still possible to determine out of sequence messages. + </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 'clientRole' 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. In the same manner as the <emphasis>Stateful</emphasis> ESB actions, it is necessary to specify the 'conversation type' that the service represents, to enable conformance checking to be performed against a choreography description that provides the associated conversation type. In the <emphasis>Stateless</emphasis> ESB actions, this initial <emphasis>SwitchAction</emphasis> defines this information in the <emphasis>conversationType</emphasis> property. + </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' element is defined for paths with no associated message type. These paths are expected to be triggered by a different sort of event, for example an internal timeout managed by the service implementation. However these internal events are triggered, and directed to the appropriate service descriptor is a implementation issue for the service. The inclusion of this path in the <emphasis>SwitchAction</emphasis> symbolises the exist of this asynchronously triggered path in the behaviour of the service. + </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> + + <section> <title>Generating a JBossESB Configuration from CDL</title> <section> <title>Overview</title> @@ -805,7 +1034,7 @@ <section> <title>Generating the JBossESB Configuration</title> <para> -When the choreography description has been completed, and has no errors, the user should select the "Overlord->JBossESB->Generate ESB Services" menu item from the popup menu associated with the choreography description (.cdm) file. +When the choreography description has been completed, and has no errors, the user should select the "Overlord->Generate->JBossESB Services" menu item from the popup menu associated with the choreography description (.cdm) file. </para> <imageobject> @@ -813,14 +1042,15 @@ </imageobject> <para> -When the dialog window is displayed, it will contain the list of services that can be generated, along with the project names that will be created. The user can unselect the services they do not wish to generate (also using the 'Check All' or 'Clear All' buttons). +When the dialog window is displayed, it will contain the list of services that can be generated, along with the project names that will be created. The user can unselect the services they do not wish to generate (also using the 'Check All' or 'Clear All' buttons). There is also a checkbox to determine whether a stateful or stateless (the default) implementation should be generated. </para> <imageobject> <imagedata fileref="images/genesbconfig2.png" /> </imageobject> + <para> -The user can also select their preferred build system, which will create the relevant build structure and script in the generated Java project, to enable the JBossESB service to be deployed. +The user can also select their preferred build system, which will create the relevant build structure and script in the generated Java project to enable the JBossESB service to be deployed, as well as the appropiate messaging system to use. </para> <para> If there is a problem with the name of the project select, such as invalid characters used in the name, or the project name already exists, then it will be displayed in red. Deleted: 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 2009-04-29 11:12:05 UTC (rev 607) +++ cdl/trunk/docs/docbook/userguide/src/main/module/stateless-conversation-aware-esb.xml 2009-04-29 18:54:19 UTC (rev 608) @@ -1,215 +0,0 @@ -<?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> -