Author: objectiser
Date: 2008-10-09 06:59:41 -0400 (Thu, 09 Oct 2008)
New Revision: 373
Added:
cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlconformance.xml
cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlvalidator.xml
Modified:
cdl/trunk/docs/docbook/samplesguide/src/main/master.xml
cdl/trunk/docs/docbook/samplesguide/src/main/module/overview.xml
cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml
Log:
Converted samples guide into docbook format.
Modified: cdl/trunk/docs/docbook/samplesguide/src/main/master.xml
===================================================================
--- cdl/trunk/docs/docbook/samplesguide/src/main/master.xml 2008-10-09 08:15:52 UTC (rev
372)
+++ cdl/trunk/docs/docbook/samplesguide/src/main/master.xml 2008-10-09 10:59:41 UTC (rev
373)
@@ -12,5 +12,7 @@
<toc/>
<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/cdlvalidator.xml"/>
+ <xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="module/cdlconformance.xml"/>
</book>
Added: cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlconformance.xml
===================================================================
--- cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlconformance.xml
(rev 0)
+++ cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlconformance.xml 2008-10-09
10:59:41 UTC (rev 373)
@@ -0,0 +1,226 @@
+<?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="cdlconformance">
+ <title>CDL Conformance</title>
+
+ <para>
+There are two examples to demonstrate the conversation aware ESB actions, and the
conformance checking against a choreography. These are
<filename>purchasing</filename>, a simple customer/supplier example, and
<filename>brokerage</filename> which extends the purchasing example through
the introduction of a broker that mediates between potentially multiple suppliers to find
the best deal.
+ </para>
+ <para>
+The other relevant folders for these examples are,
<filename>common</filename> which contains the service implementation of the
'Credit Agency' which is used by both examples, and
<filename>client</filename> which contains client applications to test both
examples.
+ </para>
+
+ <section>
+ <title>Purchasing Example</title>
+
+ <para>
+The purchasing example describes the interactions between a Buyer, Store and Credit
Agency. The flow for this example would be:
+ </para>
+ <itemizedlist>
+ <listitem>
+Buyer send a 'buy' request to Store
+ </listitem>
+ <listitem>
+Store send a 'credit check' request to the Credit Agency.
+ </listitem>
+ <listitem>
+If the Credit Agency returns a successful message, then the Store will send a
'BuyConfirmed' to user.
+ </listitem>
+ <listitem>
+If the Credit Agency returns a failed message, then the Store will send a
'BuyFailed' to user.
+ </listitem>
+ </itemizedlist>
+
+ <para>
+To check conformance, we need to import the model and service implementation projects
into the Eclipse environment. This is achieved by:
+ </para>
+ <orderedlist>
+ <listitem>
+Select the 'Import...' menu item, associated with the context menu on the
background of the left panal (Navigator or Package depending on perspective being viewed).
When the import dialog appears, select the General->ExistingProject from Workspace
option and press the 'Next' button.
+ </listitem>
+ <listitem>
+Ensuring that the 'Select root directory' radio button is selected, press the
'Browse' button and navigate to the
<filename>samples/purchasing/models</filename> folder, press 'Ok' and
then press 'Finish'.
+ </listitem>
+ <listitem>
+Then repeat steps (1) and (2) for the following project folders:
+ <itemizedlist>
+ <listitem>
+ <filename>samples/purchasing/store</filename>
+ </listitem>
+ <listitem>
+ <filename>samples/common/creditAgency</filename>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </orderedlist>
+ <para>
+The <filename>purchasing-models</filename> project contains the CDL used to
perform conformance checking on the
<filename>src/main/resources/META-INF/jboss-esb.xml</filename> files within
the other projects. A full explanation of the conversation aware ESB actions can be found
in the <emphasis>Conversational Aware ESB</emphasis> section of the
<emphasis>User Guide</emphasis> in the <filename>docs</filename>
folder.
+ </para>
+ <para>
+To provide a simple demonstration of the conformance checking:
+ </para>
+ <orderedlist>
+ <listitem>
+Double click on
<filename>purchasing-store/src/main/resources/META-INF/jboss-esb.xml</filename>
+ </listitem>
+ <listitem>
+Scroll down to the second action, within the first service. This represents a
<emphasis>ReceiveMessageAction</emphasis> and has a property defining the
message type to be received.
+ </listitem>
+ <listitem>
+Edit the 'messageType' property value, e.g. by adding an 'X' to the end
of the value.
+ </listitem>
+ <listitem>
+Then save the file. This should result in an error being generated, complaining about a
type mismatch.
+ </listitem>
+ </orderedlist>
+ <para>
+The information regarding the expected message type is obtained from the choreography
description in the <filename>purchasing-models</filename> project. To identify
the precise interaction within the choreography that this error relates to, select the
context menu associated with the error and choose the Quick Fix menu item. This will
display a dialog with a list of fixes, select the <emphasis>Show referenced
description</emphasis> option and press OK. This will cause the relevant interaction
within the choreography description to be displayed.
+ </para>
+ <para>
+Another Quick Fix option associated with this error is <emphasis>Update from
Referenced Description</emphasis>. By selecting this option, you will notice that
the message type is changed back to the value without the 'X'.
+ </para>
+
+ <section>
+ <title>Running the Example</title>
+
+ <orderedlist>
+ <listitem>
+ First step is to install the ESB services. In a command window,
+ <itemizedlist>
+ <listitem>
+ Go to the <filename>$Overlord/samples/purchasing/store</filename> folder
and execute <emphasis role="bold">ant deploy</emphasis>
+ </listitem>
+ <listitem>
+ Go to the $Overlord/samples/common/creditAgency folder and execute <emphasis
role="bold">ant deploy</emphasis>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ Go to the <filename>$Overlord/samples/client</filename> folder and execute
<emphasis role="bold">ant runPurchasingClient</emphasis>, which will
send a 'BuyRequest' message to the Store, which will then perform the credit check
before returning a response to the client.
+ </listitem>
+ </orderedlist>
+
+ <para>
+To see a different response from the client, change the
<emphasis>isCreditValid</emphasis> method on the
<emphasis>CreditAgencyPurchase</emphasis> class, within the
<filename>common/creditAgency</filename> ESB service implementation, and then
re-deploy the Credit Agency service. Then when the client is re-run, a 'BuyFailed'
message will be returned.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Brokerage Example</title>
+
+ <para>
+The brokerage example describes the interactions between a Customer, Broker, Supplier and
Credit Agency. The flow for this example would be:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+Customer sends an 'enquiry' request to Broker
+ </listitem>
+ <listitem>
+Broker sends the request to one or more Suppliers concurrently
+ </listitem>
+ <listitem>
+When all of the quote responses have been received, or a timeout expires, the available
information is returned to the Customer
+ </listitem>
+ <listitem>
+Customer decides whether to:
+ <itemizedlist>
+ <listitem>
+ Cancel the transaction, or
+ </listitem>
+ <listitem>
+ Send a 'buy' request to the Broker
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+If a 'buy' request is received by the Broker, it will send a 'credit
check' request to the Credit Agency
+ </listitem>
+ <listitem>
+If the Credit Agency returns a successful message, then the Broker sends a 'buy'
request to the Supplier selected by the Customer (in the 'buy' request), followed
by a confirmation back to the Customer
+ </listitem>
+ <listitem>
+If the Credit Agency returns a failed message, then the Broker will inform the Customer
+ </listitem>
+ </itemizedlist>
+
+ <para>
+To check conformance, we need to import the model and service implementation projects
into the Eclipse environment. This is achieved by:
+ </para>
+ <orderedlist>
+ <listitem>
+Select the 'Import...' menu item, associated with the context menu on the
background of the left panal (Navigator or Package depending on perspective being viewed).
When the import dialog appears, select the <emphasis>General->ExistingProject
from Workspace</emphasis> option and press the 'Next' button.
+ </listitem>
+ <listitem>
+Ensuring that the 'Select root directory' radio button is selected, press the
'Browse' button and navigate to the
<emphasis>samples/brokerage/models</emphasis> folder, press 'Ok' and
then press 'Finish'.
+ </listitem>
+ <listitem>
+Then repeat steps (1) and (2) for the following project folders:
+ <itemizedlist>
+ <listitem>
+ <filename>samples/brokerage/broker</filename>
+ </listitem>
+ <listitem>
+ <filename>samples/brokerage/supplier</filename>
+ </listitem>
+ <listitem>
+ <filename>samples/common/creditAgency</filename> (if not already imported
for the previous example)
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </orderedlist>
+ <para>
+The <filename>brokerage-models</filename> project contains the CDL used to
perform conformance checking on the
<filename>src/main/resources/META-INF/jboss-esb.xml</filename> files within
the other brokerage projects. A full explanation of the conversation aware ESB actions can
be found in the <emphasis>Conversational Aware ESB</emphasis> section of the
<emphasis>User Guide</emphasis> in the <filename>docs</filename>
folder.
+ </para>
+ <para>
+To provide a simple demonstration of the conformance checking:
+ </para>
+ <orderedlist>
+ <listitem>
+Double click on
<filename>brokerage-broker/src/main/resources/META-INF/jboss-esb.xml</filename>
+ </listitem>
+ <listitem>
+Scroll down to the second action, within the first service. This represents a
<emphasis>ReceiveMessageAction</emphasis> and has a property defining the
message type to be received.
+ </listitem>
+ <listitem>
+Edit the 'messageType' property value, e.g. by adding an 'X' to the end
of the value.
+ </listitem>
+ <listitem>
+Then save the file. This should result in an error being generated, complaining about a
type mismatch.
+ </listitem>
+ </orderedlist>
+ <para>
+The information regarding the expected message type is obtained from the choreography
description in the <filename>brokerage-models</filename> project. To identify
the precise interaction within the choreography that this error relates to, select the
context menu associated with the error and choose the Quick Fix menu item. This will
display a dialog with a list of fixes, select the <emphasis>Show referenced
description</emphasis> option and press OK. This will cause the relevant interaction
within the choreography description to be displayed.
+ </para>
+
+ <section>
+ <title>Running the Example</title>
+
+ <orderedlist>
+ <listitem>
+ First step is to install the ESB services. In a command window,
+ <itemizedlist>
+ <listitem>
+ Go to the <filename>$Overlord/samples/brokerage/supplier</filename>
folder and execute <emphasis role="bold">ant deploy</emphasis>
+ </listitem>
+ <listitem>
+ Go to the <filename>$Overlord/samples/brokerage/broker</filename> folder
and execute <emphasis role="bold">ant deploy</emphasis>
+ </listitem>
+ <listitem>
+ Go to the <filename>$Overlord/samples/common/creditAgency</filename>
folder and execute <emphasis role="bold">ant deploy</emphasis>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ Go to the <filename>$Overlord/samples/client</filename> folder and execute
<emphasis role="bold">ant runBrokerageClient</emphasis>, which will
initially send an 'enquiry' message to the Broker, which will communicate with the
set of Suppliers to obtain the best quote. The client will then send a 'buy'
request, which will result in the Broker performing a credit check before returning a
response to the client.
+ </listitem>
+ </orderedlist>
+ </section>
+
+ </section>
+
+</chapter>
Added: cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlvalidator.xml
===================================================================
--- cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlvalidator.xml
(rev 0)
+++ cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlvalidator.xml 2008-10-09
10:59:41 UTC (rev 373)
@@ -0,0 +1,100 @@
+<?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="cdlvalidator">
+ <title>CDL Validator</title>
+
+ <section>
+ <title>Trailblazer Example</title>
+
+ <para>
+This example can be found in the <filename>trailblazer</filename> folder,
which contains an enhanced version of the trailblazer example found in the JBossESB
distribution. The main changes are the introduction of a File Based Bank, and
modifications to the message structures to enable a consistent conversation id to be
carried with the messages.
+ </para>
+
+ <orderedlist>
+ <listitem>
+Update the
<filename>$JbossAS/server/default/deploy/jbossesb.sar/jbossesb-properties.xml</filename>
file, in the section entitled "transports" and specify all of the SMTP mail
server settings for your environment.
+ </listitem>
+ <listitem>
+Select the 'Import...' menu item, associated with the context menu on the
background of the left panal (Navigator or Package depending on perspective being viewed).
When the import dialog appears, select the <emphasis>General->ExistingProject
from Workspace</emphasis> option and press the 'Next' button.
+ </listitem>
+ <listitem>
+Ensuring that the 'Select root directory' radio button is selected, press the
'Browse' button and navigate to the
<filename>samples/trailblazer/models</filename> folder, press 'Ok' and
then press 'Finish'.
+
+<note>
+ <para>
+Once the models project has been installed, you can open the choreography for the
trailblazer (trailblazer.cdm) and also a scenario representing a valid transaction
associated with the choreography (LoanRequest.scn). In the choreography description
editor, view the "Choreography Flows" tab to see the structure of the process.
+ </para>
+ <para>
+To simulate the scenario against the choreography, to ensure that the choreography
correctly caters for the valid business scenario, the user should press the green
'play' button in the toolbar, associated with the Scenario Editor.
+ </para>
+</note>
+ </listitem>
+ <listitem>
+Update the <filename>trailblazer/trailblazer.properties</filename>
+ <para>
+Update the <property>file.bank.monitored.directory</property> and
<property>file.output.directory</property> properties. These are folders used
by the File Based Bank, and are set to <filename>/tmp/input</filename> and
<filename>/tmp/output</filename> by default.
+ </para>
+ </listitem>
+ <listitem>
+Update the <filename>trailblazer/esb/conf/jboss-esb.xml</filename>
+ <para>
+There is a <emphasis>fs-provider</emphasis> block, update the
<property>directory</property> attribute value to be the same as the
<property>file.output.directory</property> value in
<filename>trailblazer.properties</filename> file.
+ </para>
+ </listitem>
+ <listitem>
+Start the JBossAS server
+ </listitem>
+ <listitem>
+From the <filename>trailblazer</filename> folder, execute the command to
start the ESB: <emphasis role="bold">ant deploy</emphasis>
+ <para>
+this should deploy the ESB and WAR files to your JBoss AS
<filename>server/default</filename>.
+ </para>
+ </listitem>
+ <listitem>
+From the <filename>trailblazer/banks</filename> folder, execute the command
to start the JMS Bank service: <emphasis role="bold">ant
runJMSBank</emphasis>.
+ </listitem>
+ <listitem>
+From the <filename>trailblazer/banks</filename> folder, execute the command
to start the JMS Bank service: <emphasis role="bold">ant
runFileBank</emphasis>.
+ </listitem>
+ <listitem>
+In the Eclipse environment, select the context menu associated with the
<filename>trailblazer.cdm</filename> file, and choose the
<emphasis>Choreography->Monitor</emphasis> menu item. Wait for the monitor
window to start, and indicate that the choreography is being monitored, shown in the
status line at the bottom of the window.
+ </listitem>
+ <listitem>
+Start a browser and enter the URL: <ulink
url="http://localhost:8080/trailblazer">localhost:8080/trailblazer</ulink>.
+ </listitem>
+ <listitem>
+Now you can submit quotes, You will see either a loan request rejected (single email)
because the score is less than 4, or two emails (one from JMS bank and one from FileBased
bank) with valid quotes. When entering subsequent quotes, make sure that the quote
reference is updated, so that each session has a unique id.
+ </listitem>
+ </orderedlist>
+ <para>
+To demonstrate what occurs when the implementation deviates from the expected behaviour
as defined in the choreography description, try the following steps:
+ </para>
+ <orderedlist>
+ <listitem>
+Edit the LoanBroker.java in the
<filename>$Overlord/samples/trailblazer/client/src/org/jboss/soa/esb/samples/trailblazer/loanbroker</filename>
folder
+ </listitem>
+ <listitem>
+Find the following code within the <emphasis>processLoanRequest</emphasis>
method, and change the 4 to a 7
+
+<programlisting>
+ //step 2 - check if score is acceptable
+
+ if (score >= 4) {
+</programlisting>
+ </listitem>
+ <listitem>
+Re-deploy the trailblazer example (step 7 above)
+ </listitem>
+ <listitem>
+Issue further loan requests, remembering to change the quote reference each time, until a
Credit Check result of between 4 and 6 inclusive occurs, which will result in an out of
sequence message being reported (in red) to the Choreography Monitor
+
+<note><para>
+It is currently a requirement that the choreography used within the Choreography Monitor
is the same as the description used to locally monitor the services (i.e. within the
overlord-cdl-validator.esb/models directory).
+</para></note>
+ </listitem>
+ </orderedlist>
+
+ </section>
+
+</chapter>
Modified: cdl/trunk/docs/docbook/samplesguide/src/main/module/overview.xml
===================================================================
--- cdl/trunk/docs/docbook/samplesguide/src/main/module/overview.xml 2008-10-09 08:15:52
UTC (rev 372)
+++ cdl/trunk/docs/docbook/samplesguide/src/main/module/overview.xml 2008-10-09 10:59:41
UTC (rev 373)
@@ -1,30 +1,30 @@
-<?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="overview">
- <title>Overview</title>
- <para>The Overlord CDL distribution contains two main types of
functionality:</para>
- <orderedlist>
- <listitem>
- the ability to validate executing services against a choreography description (an
example of runtime governance).
- </listitem>
- <listitem>
- the ability to build an ESB using 'conversation aware' actions which can be
checked for conformance against a choreography description (an example of design time
governance).
- </listitem>
- </orderedlist>
-
- <para>
- This document will describe the samples available to demonstrate each aspect of the
functionality.
- </para>
- <para>
- Further information about configuring the runtime validation of services against a
choreography can be found in the <emphasis
role="bold">UserGuide</emphasis>.
- Information regarding the conversation aware ESB actions, and how to use them in
conjunction with conformance checking against a choreography description, can also be
found in the <emphasis role="bold">UserGuide</emphasis>.
- </para>
-
- <note>
- <para>
- Before attempting to install and run these examples, you must follow the instructions
in the <emphasis role="bold">"Getting Started"
Chapter</emphasis> of <emphasis role="bold">User
Guide</emphasis> regarding installing Overlord CDL into a JBossAS environment.
- </para>
- </note>
-
-</chapter>
+<?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="overview">
+ <title>Overview</title>
+ <para>The Overlord CDL distribution contains two main types of
functionality:</para>
+ <orderedlist>
+ <listitem>
+ the ability to validate executing services against a choreography description (an
example of runtime governance).
+ </listitem>
+ <listitem>
+ the ability to build an ESB using 'conversation aware' actions which can be
checked for conformance against a choreography description (an example of design time
governance).
+ </listitem>
+ </orderedlist>
+
+ <para>
+ This document will describe the samples available to demonstrate each aspect of the
functionality.
+ </para>
+ <para>
+ Further information about configuring the runtime validation of services against a
choreography can be found in the <emphasis
role="bold">UserGuide</emphasis>.
+ Information regarding the conversation aware ESB actions, and how to use them in
conjunction with conformance checking against a choreography description, can also be
found in the <emphasis role="bold">UserGuide</emphasis>.
+ </para>
+
+ <note>
+ <para>
+ Before attempting to install and run these examples, you must follow the instructions
in the <emphasis role="bold">"Getting Started"
Chapter</emphasis> of the <emphasis role="bold">User
Guide</emphasis> regarding installing Overlord CDL into a JBossAS environment.
+ </para>
+ </note>
+
+</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 2008-10-09
08:15:52 UTC (rev 372)
+++ cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml 2008-10-09
10:59:41 UTC (rev 373)
@@ -165,13 +165,13 @@
<para>
The one or more 'messageType' elements, contained within the 'route'
element, defines the message type(s) that should be routed to the service descriptor
associated with the 'route' element.
</para>
-<note>
+<note><para>
If a route is marked as <emphasis>initiate='true'</emphasis>, with
the correct message type for an inbound message, but a service instance already exists for
the identity information extracted from the message, then the route will not be selected.
The converse is also true.
-</note>
+</para></note>
-<note>
+<note><para>
Similarly, even if a message type match is found, if the service instance is not in an
appropriate state to invoke the target service descriptor, then the route will not be
selected.
-</note>
+</para></note>
<para>
If no routes are found for a particular inbound message, then an exception will be
reported.
</para>
@@ -740,9 +740,9 @@
<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>
+<note><para>
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></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>
@@ -823,9 +823,9 @@
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>
+<note><para>
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>
+</para></note>
</section>
<section>
@@ -838,9 +838,9 @@
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>
+<note><para>
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>
+</para></note>
</section>
<section>
@@ -852,9 +852,9 @@
This error has an associated <emphasis>quick fix</emphasis> to enable the
unwanted activities to be removed from the ESB configuration.
</para>
-<note>
+<note><para>
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>
+</para></note>
</section>
<section>