[overlord-commits] Overlord SVN: r416 - 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
Wed Oct 22 18:06:34 EDT 2008
Author: objectiser
Date: 2008-10-22 18:06:34 -0400 (Wed, 22 Oct 2008)
New Revision: 416
Added:
cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorann.png
cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatoranndiag.png
cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorannparams.png
cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorannselect.png
cdl/trunk/docs/docbook/userguide/src/main/images/genvalidatordialog.png
cdl/trunk/docs/docbook/userguide/src/main/images/genvalidatormenu.png
Modified:
cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig1.png
cdl/trunk/docs/docbook/userguide/src/main/images/setconversationtype.png
cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml
cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml
Log:
Updated images, added 'WhenAction' description, and added section discussing new validator-config.xml generator.
Added: cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorann.png
===================================================================
(Binary files differ)
Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorann.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatoranndiag.png
===================================================================
(Binary files differ)
Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatoranndiag.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorannparams.png
===================================================================
(Binary files differ)
Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorannparams.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorannselect.png
===================================================================
(Binary files differ)
Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorannselect.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: cdl/trunk/docs/docbook/userguide/src/main/images/genesbconfig1.png
===================================================================
(Binary files differ)
Added: cdl/trunk/docs/docbook/userguide/src/main/images/genvalidatordialog.png
===================================================================
(Binary files differ)
Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/genvalidatordialog.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: cdl/trunk/docs/docbook/userguide/src/main/images/genvalidatormenu.png
===================================================================
(Binary files differ)
Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/genvalidatormenu.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: cdl/trunk/docs/docbook/userguide/src/main/images/setconversationtype.png
===================================================================
(Binary files differ)
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-22 17:51:16 UTC (rev 415)
+++ cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml 2008-10-22 22:06:34 UTC (rev 416)
@@ -202,7 +202,7 @@
process="process" name="...">
....
<property name="conversationType"
- value="jboss.overlord.samples.LoanBroker at Broker" />
+ value="overlord.cdl.samples.LoanBroker at Broker" />
....
</action>
]]></programlisting>
@@ -211,7 +211,7 @@
The <emphasis>conversation type</emphasis> is specified in the <emphasis>CreateSessionAction</emphasis> ESB action, described later in this section, and is associated as a semantic annotation against the relevant Participant Type or Participant Instance within the choreography description.
<para>
</para>
-To associate the <emphasis>conversation type</emphasis> with either the Participant Type or Instance, open the choreography description in the <emphasis>pi4soa</emphasis> choreography designer. Then select the "Choreography->Edit Annotations" menu item from the context menu associated with the Participant Type or Instance. In the lefthand panel, select "Add Freeform Annotation" from the context menu, then specify "conversationType" as the annotation type and press 'Ok'. Then select the 'Annotation' tab in the righthand panel, and enter the conversation type, e.g. "jboss.overlord.samples.LoanBroker at Broker". Note the '@' is important, as the following word indicates the 'role' associated with the conversation type which precedes the '@' symbol.
+To associate the <emphasis>conversation type</emphasis> with either the Participant Type or Instance, open the choreography description in the <emphasis>pi4soa</emphasis> choreography designer. Then select the "Choreography->Edit Annotations" menu item from the context menu associated with the Participant Type or Instance. In the lefthand panel, select "Add Freeform Annotation" from the context menu, then specify "conversationType" as the annotation type and press 'Ok'. Then select the 'Annotation' tab in the righthand panel, and enter the conversation type, e.g. "overlord.cdl.samples.LoanBroker at Broker". Note the '@' is important, as the following word indicates the 'role' associated with the conversation type which precedes the '@' symbol.
</para>
<imagedata fileref="images/setconversationtype.png" width="4in" />
@@ -244,7 +244,7 @@
import org.jboss.soa.overlord.jbossesb.actions.Service;
@Service(name="{http://www.jboss.org/overlord/loanBroker}Broker",
- conversationType="jboss.overlord.samples.LoanBroker at Broker",
+ conversationType="overlord.cdl.samples.LoanBroker at Broker",
root=true)
public class BrokerMain {
....
@@ -667,23 +667,18 @@
<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>
+ <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>
]]></programlisting>
</informalexample>
@@ -713,7 +708,41 @@
</para>
</section>
+
<section>
+ <title>Blocking awaiting a decision</title>
+ <para>
+The <emphasis>WhenAction</emphasis> is used to block one or more awaiting paths, until an expression associated
+with one of the paths becomes true.
+ </para>
+ <para>
+For example,
+ </para>
+ <informalexample>
+ <programlisting role="XML" ><![CDATA[
+
+ <action class="org.jboss.soa.overlord.jbossesb.actions.WhenAction"
+ process="process" name="s4-1">
+ <property name="session"
+ value="org.jboss.soa.overlord.samples.jbossesb.loan.broker.BrokerMain" />
+ <property name="paths">
+ <when expression="receivedAllQuotes()"
+ service-category="ESBBroker.BrokerParticipant"
+ service-name="ESBBrokerProcess.main.4" />
+ </property>
+ </action>
+ ]]></programlisting>
+ </informalexample>
+
+ <para>
+In this example, there is only one path defined, which will block until the <emphasis>receivedAllQuotes()</emphasis>
+expression becomes true. When this expression evaluates to true, the service category and name defined for the
+<emphasis>when</emphasis> element will be scheduled.
+ </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,
@@ -767,7 +796,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" menu item from the context 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->JBossESB->Generate ESB Services" menu item from the context menu associated with the choreography description (.cdm) file.
</para>
<imageobject>
Modified: cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml
===================================================================
--- cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml 2008-10-22 17:51:16 UTC (rev 415)
+++ cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml 2008-10-22 22:06:34 UTC (rev 416)
@@ -130,6 +130,115 @@
</section>
<section>
+ <title>Generating the Validator Configuration from a Choreography</title>
+
+ <section>
+ <title>Defining the ESB Service endpoints</title>
+
+ <para>
+ The first step to configuring the validator is to associate the endpoint references (EPRs)
+ against the relevant choreography interactions. This is achieved by defining an
+ annotation for each 'exchange details' component (i.e. each request and response/notification).
+ </para>
+
+ <imageobject>
+ <imagedata fileref="images/editvalidatorann.png" width="5in" />
+ </imageobject>
+
+ <para>
+ When the annotation editor is displayed for the relevant 'exchange details' component,
+ the <emphasis>jbossesb</emphasis> annotation should be added. This is achieved by
+ selecting the context menu associated with the background of the lefthand panel,
+ and selecting the <emphasis>Add Defined Annotation</emphasis> menu item.
+ </para>
+
+ <imageobject>
+ <imagedata fileref="images/editvalidatoranndiag.png" width="5in" />
+ </imageobject>
+
+ <para>
+ When the list of defined annotations is displayed, select the
+ <emphasis>jbossesb</emphasis> annotation.
+ </para>
+
+ <imageobject>
+ <imagedata fileref="images/editvalidatorannselect.png" width="3in" />
+ </imageobject>
+
+ <para>
+ After pressing the <emphasis>Ok</emphasis> button, the annotation editor
+ will configure the righthand panel with the parameters associated with this
+ annotation.
+ </para>
+
+ <imageobject>
+ <imagedata fileref="images/editvalidatorannparams.png" width="5in" />
+ </imageobject>
+
+ <para>
+ To specify the EPR for a particular message exchange, enter the EPR into the
+ <emphasis>Destination</emphasis> field. If however a temporary destination is
+ used for a message exchange (usually when dealing with responses), then the
+ <emphasis>temporary</emphasis> checkbox should be selected.
+ </para>
+
+ <para>
+ Once the annotation has been defined, then press the <emphasis>Save</emphasis>
+ button to save the annotation against the interaction's exchange details.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Generating the <emphasis>validator-config.xml</emphasis></title>
+
+ <para>
+ To generate the validator configuration details from a choreography description
+ into the format used by the central configuration mechanism (described previously),
+ select the <emphasis>Overlord->JBossESB->Generate Validator</emphasis> menu item
+ associated with the context menu for the choreography description.
+ </para>
+
+ <imageobject>
+ <imagedata fileref="images/genvalidatormenu.png" width="5in" />
+ </imageobject>
+
+ <para>
+ When the dialog box is displayed, either enter the path to the <filename>validator-config.xml</filename>
+ in the text field, or use the <emphasis>Browse</emphasis> button to locate the file3
+ </para>
+
+ <imageobject>
+ <imagedata fileref="images/genvalidatordialog.png" width="5in" />
+ </imageobject>
+
+ <para>
+ If the selected file does not exist, then when the <emphasis>Ok</emphasis> button is pressed,
+ it will be created with the validator configuration associated with the choreography
+ description.
+ </para>
+
+ <para>
+ If the selected file already exists, then any 'service' entries associated with the
+ choreography file will be updated with the new information from the choreography
+ description. All other entries in the selected validator configuration file will be
+ retained.
+ </para>
+
+ <note>
+ <para>
+ If the <emphasis>validator-config.xml</emphasis> file within the JBoss server environment
+ is directly updated, then the server will need to be restarted before the new configuration
+ will take effect. Tools to support hot reconfiguration of this file will be provided
+ in the future.
+ </para>
+ </note>
+
+ </section>
+
+ </section>
+
+ <section>
<title>Monitoring the Choreography Description</title>
<para>
Once the JBossESB environment has been configured, to perform service validation of a set of ESB services against a choreography
@@ -165,7 +274,9 @@
The next step is to launch the monitoring tool. This is located on the context menu, for the choreography description (i.e. .cdm) file, by selecting the Choreography->Monitor menu item. Once the tool has been launched, it will load the choreography description, subscribe to the relevant event destination, and then indicate via a message in the bottom status line that it is ready to monitor.
</para>
- <imagedata fileref="images/monitorui.png" width="5in" />
+ <imageobject>
+ <imagedata fileref="images/monitorui.png" width="5in" />
+ </imageobject>
<para>
When the information is received, from the service validators representing the different participants (services), it is correlated to show the global status of the business transaction. The list of correlated interactions is show in reverse time order in the image, so in this example a <emphasis>LoanBroker</emphasis> sends a <emphasis>creditCheck</emphasis> message to a <emphasis>CreditAgency</emphasis>, followed by a <emphasis>creditCheckResult</emphasis> being returned.
More information about the overlord-commits
mailing list