[overlord-commits] Overlord SVN: r373 - in cdl/trunk/docs/docbook: samplesguide/src/main/module and 1 other directories.

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>