[overlord-commits] Overlord SVN: r360 - in cdl/trunk/docs/docbook/userguide/src/main: module and 1 other directory.
overlord-commits at lists.jboss.org
overlord-commits at lists.jboss.org
Fri Oct 3 12:29:14 EDT 2008
Author: objectiser
Date: 2008-10-03 12:29:14 -0400 (Fri, 03 Oct 2008)
New Revision: 360
Added:
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/images/genesbconfig3.png
Modified:
cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml
Log:
Finished initial draft of user guide, converting from previous open office docs into docbook format. Added new section on dealing with conformance issues.
Added: cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig1.png
===================================================================
(Binary files differ)
Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig1.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig2.png
===================================================================
(Binary files differ)
Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig3.png
===================================================================
(Binary files differ)
Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig3.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
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 2008-10-02 14:56:11 UTC (rev 359)
+++ cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml 2008-10-03 16:29:14 UTC (rev 360)
@@ -259,28 +259,495 @@
</section>
<section>
<title>Instantiating top level and child sessions</title>
+ <para>
+A session, whether top level or a child sub-session, will be instantiated by defining a service descriptor that starts with a <emphasis>CreateSessionAction</emphasis>. For example,
+ </para>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+ <action class="org.jboss.soa.overlord.jbossesb.actions.CreateSessionAction"
+ process="process" name="...">
+ <property name="session"
+ value="org.jboss.soa.overlord.samples.jbossesb.loan.broker.BrokerMain" />
+ </action>
+ ]]></programlisting>
+ </informalexample>
+ <para>
+where the 'session' property references the pojo defined previously. What distinguishes whether the session is a top level or child sub-session is the value of the 'root' attribute on the pojo annotation (or property on the <emphasis>CreateSessionAction</emphasis> if no annotation is defined on the pojo), i.e. if root is true, then the service descriptor will represent the top level session.
+ </para>
+ <para>
+Only a single top level (root) session can be defined per service description.
+ </para>
</section>
<section>
<title>Retrieving an existing session</title>
- </section>
+ <para>
+Certain service descriptors, and actions within those service descriptors, will need to be able to access the session in which they are executing. In many situations the session will automatically be available due to prior activities that may have occurred, causing the session reference to be cached and retrieved when required.
+ </para>
+ <para>
+However, in some situations (such as receiving a response message from another service) there may not be enough context information to understand which session should be retrieved from the database to handle the incoming message.
+ </para>
+ <para>
+The solution to this problem is to ensure that the first "conversation aware" ESB action in the receiving service descriptor has the additional information required to resolve the context. This information will include:
+ </para>
+ <itemizedlist>
+ <listitem>
+Message identities
+ <para>
+Message identities refer to the extraction of information from the message content to be used to uniquely identify a session instance. This information can be associated with any "conversation aware" ESB action, and has the following format:
+ </para>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+
+ <property name="identities" >
+ <identity type="primary" >
+ <token name="<name>" locator="<xpath expression>" />
+ </identity>
+ </property>
+ ]]></programlisting>
+ </informalexample>
+
+ <para>
+Multiple identities can be derived from an incoming message. Each identity will have a type, either <emphasis>primary</emphasis>, <emphasis>alternate</emphasis>, <emphasis>derived</emphasis> or <emphasis>association</emphasis>.
+ </para>
+ <para>
+Each identity can have one or more tokens defined. If more than one is defined, then it will represent a composite identity.
+ </para>
+ <para>
+The name of the token is not relevant, just used for information purposes. The main purpose of the token is to locate a value from the message content.
+ </para>
+ </listitem>
+ <listitem>
+Session pojo
+ <para>
+The session pojo class can be used to narrow down the specific sub-session, within a service instance, that the message should be routed to.
+ </para>
+ </listitem>
+ <listitem>
+Service description name (which may be available on a <emphasis>Service</emphasis> annotation on the Session pojo).
+ </listitem>
+ </itemizedlist>
</section>
+
+ </section>
<section>
<title>Interacting</title>
<para>
+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>
+ <para>
+Therefore, the set of "conversation aware" ESB actions include actions for sending and receiving messages. Although these actions are not strictly necessary for the ESB to process messages, they make the communication behaviour of the ESB service explicit, which enables it to be statically checked (validated) against a description of the expected behaviour.
</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.actions.SendMessageAction"
+ process="process" name="...">
+ <property name="operation" value="getQuote" />
+ <property name="messageType" value="requestForQuote" />
+ ....
+ </action>
+ ]]></programlisting>
+ </informalexample>
+ <para>
+In this example, the message type has no 'namespace'. If a namespace is appropriate, it can be defined inside {} curly braces (e.g. "{http://www.jboss.org/examples}requestForQuote" for an XML type, or "{java:org.jboss.example}Quote" for a Java type).
+ </para>
+ <para>
+The next important aspect is to define the destination of the message. This will be dependent upon whether the message being sent is a request or a response/notification.
+ </para>
+ <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.actions.SendMessageAction"
+ process="process" name="...">
+ ....
+ <property name="serviceName" value="RequestForQuote.main" />
+ <property name="serviceCategory" value="ESBBroker.SupplierParticipant" />
+ ....
+ </action>
+ ]]></programlisting>
+ </informalexample>
+ <para>
+or based on expressions using the <emphasis>serviceCategoryExpression</emphasis> and <emphasis>serviceNameExpression</emphasis> properties:
+ </para>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+
+ <action class="org.jboss.soa.overlord.jbossesb.actions.SendMessageAction"
+ process="process" name="...">
+ ....
+ <property name="serviceNameExpression" value="supplier.serviceName" />
+ <property name="serviceCategoryExpression" value="supplier.serviceCategory" />
+ ....
+ </action>
+ ]]></programlisting>
+ </informalexample>
+ <para>
+The second approach enables the category/name details to be obtained from the session pojo, using an expression (see later for details of specifying expressions).
+ </para>
+ <para>
+If a response is expected from the request, then the optional <emphasis>responseServiceName</emphasis> and <emphasis>responseServiceCategory</emphasis> can be used to specify the service descriptor that should receive the response message.
+ </para>
+ </listitem>
+ <listitem>
+Sending a response
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+
+ <action class="org.jboss.soa.overlord.jbossesb.actions.SendMessageAction"
+ process="process" name="...">
+ ....
+ <property name="clientEPR" value="buyer" />
+ ....
+ </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).
+ </para>
+ <para>
+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>
+ </listitem>
+ </itemizedlist>
+ <para>
+The final part of the <emphasis>SendMessageAction</emphasis> is the identity declaration. See discussion on Message Identities early in this chapter.
+ </para>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+
+ <action class="org.jboss.soa.overlord.jbossesb.actions.SendMessageAction"
+ process="process" name="...">
+ ....
+ <property name="identities" >
+ <identity type="primary" >
+ <token name="id" locator="//@id" />
+ <token name="supplierId" locator="//@supplierId" />
+ </identity>
+ </property>
+ </action>
+ ]]></programlisting>
+ </informalexample>
+ <para>
+The identity information extracts values from the message content being sent, and determines whether it correlates with the identity already associated with the session (or sub-session). If the message is correctly correlated to the session, then it will be sent. Otherwise an exception will be generated.
+ </para>
+ <para>
+It is possible that multiple identities can be defined, associating new 'alternate' or 'derived' identities with the session (or sub-session). These can be used to link subsequent messages (send or received) to the same session.
+ </para>
+ </section>
+
+ <section>
+ <title>Receiving a message</title>
+
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+ <action class="org.jboss.soa.overlord.jbossesb.actions.ReceiveMessageAction"
+ process="process" name="s1-2">
+ <property name="operation" value="makeEnquiry" />
+ <property name="messageType" value="enquiry" />
+ <property name="clientEPR" value="buyer" />
+ <property name="identities" >
+ <identity type="primary" >
+ <token name="id" locator="//@id" />
+ </identity>
+ </property>
+ </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, including conforming that the extracted identity details correlate correctly with the session (or sub-session).
+ </para>
+ <para>
+The optional 'clientEPR' property is 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>Managing Information</title>
<para>
</para>
+
+ <section>
+ <title>Manipulating State Information</title>
+ <para>
+As previously mentioned, each session or sub-session is associated with a business state pojo which contains the information required by the session. The relevant class is identified by the 'session' property on appropriate "conversation aware" ESB actions.
+ </para>
+ <para>
+When an action needs to access (read) information defined on this business state pojo, it will simply define an expression that can access (and navigate) the properties and invoke methods on the object where appropriate.
+ </para>
+ <para>
+However we also need to have the ability to modify the state information. This is achieved using the <emphasis>SetStateAction</emphasis>. For example,
+ </para>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+ <action class="org.jboss.soa.overlord.jbossesb.actions.SetStateAction" name="...">
+ <property name="variable" value="supplierIndex" />
+ <property name="stateExpression" value="nextSupplier()" />
+ </action>
+ ]]></programlisting>
+ </informalexample>
+
+ <para>
+With this action, it is possible to specify a target 'variable' on the pojo business object, associated with the session (or sub-session), and have the value associated with an expression assigned to that variable.
+ </para>
+ <para>
+In the example above, the expression is defined using the 'stateExpression' property. This expression will be applied to the pojo business object associated with the session (or sub-session), to extract information from variables, or invoke methods on the object.
+ </para>
+ <para>
+The other type of expression that can be used is defined in the 'messageExpression' property. This will apply the expression to the content of the current message on the ESB action pipeline.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Manipulating Message Information</title>
+ <para>
+The other action that can be used to manipulate information is <emphasis>SetMessageAction</emphasis>. This action can be used to set the contents or a header property of the message on the ESB action pipeline. For example,
+ </para>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+ <action class="org.jboss.soa.overlord.jbossesb.actions.SetMessageAction"
+ process="process" name="...">
+ <property name="headerProperty" value="quoteList" />
+ <property name="stateExpression" value="quotes" />
+ </action>
+ ]]></programlisting>
+ </informalexample>
+ <para>
+This example shows how information from the session's associated business pojo state can be placed in a header property of the current message passing through the action pipeline.
+ </para>
+ <para>
+If the 'headerProperty' property is not specified, then the value extracted from the state object will be placed in the default entry within the message contents, replacing any existing value.
+ </para>
+ </section>
</section>
<section>
<title>Controlling Flow</title>
<para>
+This section describes the various control flow mechanisms that are supported by the "conversation aware" 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.actions.IfAction" process="process" name="...">
+ <property name="paths">
+ <if expression="isCreditHistoryAvailable()"
+ service-category="ESBBroker.CreditAgency"
+ service-name="CreditAgency.decision1"
+ immediate="true" />
+ <elseif expression="isBadCreditHistory()"
+ service-category="ESBBroker.CreditAgency"
+ service-name="CreditAgency.decision2"
+ immediate="true" />
+ <else service-category="ESBBroker.CreditAgency"
+ service-name="CreditAgency.decision3"
+ immediate="true" />
+ </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 'expression' attribute to be evaluated at runtime, to determine if the associated 'service-category' and 'service-name' should be invoked.
+ </para>
+ <para>
+If the 'immediate' boolean attribute is defined as true on any of the elements, it means that the associated service category/name should be invoked immediately (i.e. it represents a control link). However, if this attribute is false, or not specified, then the associated service category/name is expected to be triggered upon the receipt of a message from an external source.
+ </para>
+ </section>
+
+ <section>
+ <title>Selecting paths based on the type of a received message</title>
+ <para>
+The action used to select paths based on a received message type is <emphasis>SwitchAction</emphasis>. For example,
+ </para>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+ <action class="org.jboss.soa.overlord.jbossesb.actions.SwitchAction"
+ process="process" name="...">
+ <property name="paths">
+ <case service-category="ESBBroker.BrokerParticipant"
+ service-name="ESBBrokerProcess.main.7" >
+ <message type="buy" />
+ </case>
+ <case service-category="ESBBroker.BrokerParticipant"
+ service-name="ESBBrokerProcess.main.6" >
+ <message type="cancel" />
+ </case>
+ </property>
+ </action>
+ ]]></programlisting>
+ </informalexample>
+
+ <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>
+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>
+ <title>Executing multiple paths concurrently</title>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+ <action class="org.jboss.soa.overlord.jbossesb.actions.ParallelAction"
+ process="process" name="...">
+ <property name="paths">
+ <path service-category="ESBBroker.BrokerParticipant"
+ service-name="ESBBrokerProcess.main.2"
+ immediate="true" />
+ <path service-category="ESBBroker.BrokerParticipant"
+ service-name="ESBBrokerProcess.main.3"
+ immediate="true" />
+ <join service-category="ESBBroker.BrokerParticipant"
+ service-name="ESBBrokerProcess.main.4" />
+ </property>
+ </action>
+ ]]></programlisting>
+ </informalexample>
+ <para>
+The <emphasis>ParallelAction</emphasis> is used to initiate multiple concurrent threads of activity. These are represented by the 'path' elements within the 'paths' property. Each path identifies its service category/name and also whether it should be invoked immediately (i.e. 'immediate' attribute set to 'true'), or will be triggered by a message from an external source.
+ </para>
+ <para>
+The other element contained within the 'paths' property is the 'join' element, which represents the service category/name that acts as a convergence point across all of the concurrent threads. When all of the initiated threads have completed, the service category/name associated with the 'join' element will be invoked.
+ </para>
+ </section>
+
+ <section>
+ <title>Repetition</title>
+ <para>
+The mechanism for performing repetition is through the use of two actions, <emphasis>WhileAction</emphasis> and <emphasis>ScheduleStateAction</emphasis>. The <emphasis>WhileAction</emphasis> defines the condition to be evaluated, and the two relevant paths, i.e. one that enters the loop body and one that represents the activities that occur after the while loop, when the conditions have not been met. The <emphasis>ScheduleStateAction</emphasis> is used within the loop body to return back to the service descriptor containing the <emphasis>WhileAction</emphasis>, to cause the loop to be re-evaluated.
+ </para>
+ <para>
+For example,
+ </para>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+
+ <service category="ESBBroker.BrokerParticipant" name="ESBBrokerProcess.main.1" description="">
+ ......
+ <actions mep="OneWay">
+ <action class="org.jboss.soa.overlord.jbossesb.actions.WhileAction"
+ process="process" name="...">
+ <property name="paths">
+ <while expression="hasNextSupplier()"
+ service-category="ESBBroker.BrokerParticipant"
+ service-name="ESBBrokerProcess.main.2"
+ immediate="true" />
+ <exit service-category="ESBBroker.BrokerParticipant"
+ service-name="ESBBrokerProcess.main.3"
+ immediate="true" />
+ </property>
+ </action>
+ </actions>
+ </service>
+ ]]></programlisting>
+ </informalexample>
+
+ <para>
+The <emphasis>WhileAction</emphasis> defines a 'paths' property which contains two elements, a 'while' and an 'exit' element. Both elements define the service category and name they will invoke, and whether the service descriptors will be triggered immediately or based on an incoming message from an external source.
+ </para>
+ <para>
+Additionally, the 'while' path defines the condition that will decide whether to enter or skip the loop.
+ </para>
+ <para>
+Then at some point in the activities directly or indirectly associated with the service descriptor "ESBBroker.BrokerParticipant/ESBBrokerProcess.main.2", there would be,
+ </para>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+
+ <action class="org.jboss.soa.overlord.jbossesb.actions.ScheduleStateAction"
+ process="process" name="...">
+ <property name="serviceCategory" value="ESBBroker.BrokerParticipant" />
+ <property name="serviceName" value="ESBBrokerProcess.main.1" />
+ <property name="immediate" value="true" />
+ </action>
+ ]]></programlisting>
+ </informalexample>
+
+ <para>
+while results in the service descriptor associated with the <emphasis>WhileAction</emphasis> being re-evaluated (i.e. executed again). The <emphasis>ScheduleStateAction</emphasis> will define the service category and name to invoke, and whether to invoke them immediately, or whether the service descriptor will be triggered via an incoming message from an external source.
+ </para>
+ </section>
+
+ <section>
+ <title>Composing reusable sub-conversions into a higher level conversation</title>
+ <para>
+The ability to compose reusable modules into higher level functions is a useful capability in any language. This mechanism is also supported in the "conversation aware" ESB actions, using the <emphasis>PerformAction</emphasis> to invoke a sub-session. For example,
+ </para>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+
+ <actions mep="OneWay">
+ <action class="org.jboss.soa.overlord.jbossesb.actions.PerformAction"
+ process="process" name="...">
+ <property name="serviceCategory" value="ESBBroker.BrokerParticipant" />
+ <property name="serviceName" value="RequestForQuote.main" />
+ <property name="returnServiceCategory" value="ESBBroker.BrokerParticipant" />
+ <property name="returnServiceName" value="ESBBrokerProcess.main.9" />
+ <property name="bindDetails" >
+ <bind from-expression="getCurrentSupplier()"
+ to-variable="supplier" />
+ </property>
+ <property name="parentReference" value="parent" />
+ </action>
+ </actions>
+ ]]></programlisting>
+ </informalexample>
+ <para>
+The 'serviceCategory' and 'serviceName' properties define the service descriptor that will be invoked (i.e. that represents the sub-session). This service descriptor must begin with a <emphasis>CreateSessionAction</emphasis>, to indicate that it represents the start of a sub-session.
+ </para>
+ <para>
+The optional 'returnServiceCategory' and 'returnServiceName' represent the service descriptor that will be invoked once the sub-session has completed, to enable the parent session to continue. If these properties are not defined, then it means that sub-session is being performed asynchronously, and therefore the parent session will not wait for it to complete.
+ </para>
+ <para>
+The optional 'bindDetails' provides the means for the parent session to assign specific information from its state to the newly created pojo associated with the child session.
+ </para>
+<note>
+Currently the bound details from the parent will be copied into the child pojo, and therefore modifications will not be reflected back into the parent pojo.
+</note>
+ <para>
+The optional 'parentReference' is used to set a reference, on the child session's pojo, to the parent session's pojo. The value of the 'parentReference' identifies the property on the child session's pojo that will be used to reference the parent pojo.
+ </para>
</section>
+ </section>
</section>
<section>
@@ -288,12 +755,43 @@
<section>
<title>Overview</title>
<para>
+This section explains how to generate a template JBossESB configuration file from a pi4soa choreography description (.cdm) file.
</para>
</section>
<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" menu item from the context menu associated with the choreography description (.cdm) file.
</para>
+
+ <imageobject>
+ <imagedata fileref="images/genesbconfig1.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/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.
+ </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>
+
+ <imageobject>
+ <imagedata fileref="images/genesbconfig3.png" />
+ </imageobject>
+
+ <para>
+In the above image, on the left it shows the generated project structure for the Broker service role. On the right it shows a portion of a generated session class, with the accessor and modifier for one of the variables associated with that session.
+ </para>
+ <para>
+Although an initial build script will be created, depending on the build system selected, the user may need to edit the script to set certain properties, or change the way the build occurs. For example, with the Ant build, the deploy target (which is the default) will attempt to place the deployed .esb file into a location defined by the <filename>${org.jboss.esb.server.deploy.dir}</filename>. If this variable has not been defined, then a folder called <filename>${org.jboss.esb.server.deploy.dir}</filename> will be created in the root folder of the project, containing the .esb file.
+ </para>
</section>
</section>
@@ -302,9 +800,77 @@
<section>
<title>Overview</title>
<para>
-<todo>Explain how conformance issues are reported and about the quickfix mechanism - including the standard ways to resolve problems</todo>
+ Conformance checking can be used to determine whether an ESB configuration, containing "conversation aware" ESB actions, matches the expected behaviour as defined within a choreography description (.cdm file). The Eclipse environment will report any conformance issues as errors in the <emphasis>Problems</emphasis> view.
</para>
+ <para>
+ This section will explain the types of conformance errors that may be reported and how to deal with them. Not all errors, associated with an ESB configuration, will be discussed in this section. Many errors may be detected that will indicate problems associated with the way that behaviour has been specified in the configuration file (e.g. conversation type has not been defined). These are not directly related to conformance.
+ </para>
</section>
+
+ <section>
+ <title>Show referenced description</title>
+ <para>
+When an error occurs, related to conformance between the ESB configuration file and a choreography description, it will have an associated <emphasis>quick fix</emphasis> resolution that can be used to display the relevant activity being referred to within the choreography description.
+ </para>
+ </section>
+
+ <section>
+ <title>Error: Expecting additional activities as defined in referenced description</title>
+ <para>
+This error message indicates that the reference description contains activities that were not found in the ESB configuration.
+ </para>
+ <para>
+This error has an associated <emphasis>quick fix</emphasis> to enable the missing activities to be inserted in the appropriate location within the ESB configuration.
+ </para>
+
+<note>
+When this resolution is selected, if it displays an error <quote>Could not insert activities found in referenced description</quote>, this means that it was not possible to insert the additional activities automatically.
+</note>
+ </section>
+
+ <section>
+ <title>Error: Type mismatch with referenced description, was expecting '...'</title>
+ <para>
+This error occurs when an activity contains a type that does not match with the equivalent activity in the choreography description. A common example would be an interaction, where the message types are not compatible.
+ </para>
+
+ <para>
+This error has an associated <emphasis>quick fix</emphasis> to enable the type to be updated in the relevant activity within the ESB configuration.
+ </para>
+
+<note>
+When this resolution is selected, if it displays an error <quote>Could not update activity with information from referenced description</quote>, this means that it was not possible to update the information automatically.
+</note>
+ </section>
+
+ <section>
+ <title>Error: Behaviour not present in referenced description</title>
+ <para>
+This error occurs when there are extra activities within the ESB configuration that do not appear within the choreography description.
+ </para>
+ <para>
+This error has an associated <emphasis>quick fix</emphasis> to enable the unwanted activities to be removed from the ESB configuration.
+ </para>
+
+<note>
+When this resolution is selected, if it displays an error <quote>Could not delete activities from the model</quote>, this means that it was not possible to delete the activities automatically.
+</note>
+ </section>
+
+ <section>
+ <title>Error: Additional unmatched paths in model</title>
+ <para>
+This error indicates that a grouping contruct (e.g. <emphasis>ParallelAction</emphasis>, <emphasis>IfAction</emphasis> or <emphasis>SwitchAction</emphasis>) in the ESB configuration has additional paths that do not match the equivalent grouping construct in the choreography description.
+ </para>
+ </section>
+
+ <section>
+ <title>Error: Additional unmatched paths in referenced description</title>
+ <para>
+This error indicates that a grouping contruct (e.g. <emphasis>Choice</emphasis> or <emphasis>Parallel</emphasis>) in the choreography description has additional paths that do not match the equivalent grouping construct in the ESB configuration.
+ </para>
+ </section>
+
</section>
</chapter>
More information about the overlord-commits
mailing list