[overlord-commits] Overlord SVN: r436 - in cdl/trunk/docs/docbook/gettingstartedguide/src/main: module and 1 other directory.

Author: objectiser Date: 2008-11-12 10:57:50 -0500 (Wed, 12 Nov 2008) New Revision: 436 Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ChoreoMonReady.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ConformanceCheckError.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ConformanceCheckErrorMessage.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ConformanceCheckErrorMessageMenu.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateValidatorDialog.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateValidatorMenu.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/MonitorMenu.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/QuickFixDialog.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ShowReferencedDescription.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/TrailblazerWebPage.jpg Modified: cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml Log: Finished SOA Governance with CDL section of getting started guide. Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ChoreoMonReady.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ChoreoMonReady.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ConformanceCheckError.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ConformanceCheckError.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ConformanceCheckErrorMessage.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ConformanceCheckErrorMessage.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ConformanceCheckErrorMessageMenu.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ConformanceCheckErrorMessageMenu.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateValidatorDialog.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateValidatorDialog.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateValidatorMenu.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateValidatorMenu.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/MonitorMenu.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/MonitorMenu.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/QuickFixDialog.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/QuickFixDialog.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ShowReferencedDescription.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/ShowReferencedDescription.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/TrailblazerWebPage.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/TrailblazerWebPage.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml =================================================================== --- cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml 2008-11-12 10:57:21 UTC (rev 435) +++ cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml 2008-11-12 15:57:50 UTC (rev 436) @@ -127,25 +127,265 @@ </imageobject> <para> -The generated project includes the ESB configuration file (in the <filename>conf</filename> folder) and the relevant Java classes in the <filename>src/java</filename> folder. The contents of this project represents a template of the service. Before it can be executed, the ESB configuration file will need to be enhanced to include internal implementation details for the service. The contents of this generated project should be compared to the completed version in the <filename>purchasing-store</filename> project. +The generated project includes the ESB configuration file (in the <filename>src/conf</filename> folder) and the relevant Java classes in the <filename>src/java</filename> folder. The contents of this project represents a template of the service. Before it can be executed, the ESB configuration file will need to be enhanced to include internal implementation details for the service. The contents of this generated project should be compared to the completed version in the <filename>purchasing-store</filename> project. </para> + + <note> + <para> +When the project is generated, if errors are reported against the <filename>jboss-esb.xml</filename>, then simply double-click on the error to launch the ESB configuration file. Then make a minor change, such as adding a new line and then removing it, and save the file again (to force re-validation). This should cause the errors to be cleared. This occurs because the Eclipse tasks that validate the <filename>jboss-esb.xml</filename> file and compiling the new Java classes in the project sometimes gets confused, causing the classes not to be present when the validation rules attempt to access them. This issue is being investigated. + </para> + </note> </section> <section> <title>Conformance Checking "Conversation Aware" ESB Services</title> + <para> +To demonstrate the conformance checking mechanism, where the behaviour of the ESB service is verifed against its responsiblities as defined within the choreography description, open the <filename>src/conf/jboss-esb.xml</filename> in the <filename>PurchaseGoodsProcess-Store</filename> generated in the previous sub-section. + </para> + + <para> +When the ESB configuration has been loaded into an editor, locate the first <emphasis>ReceiveMessageAction</emphasis> ESB action, which should have a property called <emphasis>messageType</emphasis> with a value of <emphasis>BuyRequest</emphasis>. To cause a conformance checking error, simply append an 'X' to the end of the message type value, as shown in the following screenshot: + </para> + + <imageobject> + <imagedata fileref="images/ConformanceCheckError.jpg" align="center" width="4in" /> + </imageobject> + + <para> +This results in an error message being reported: + </para> + + <imageobject> + <imagedata fileref="images/ConformanceCheckErrorMessage.jpg" align="center" width="4in" /> + </imageobject> + + <para> +To fix conformance issues, some of the error messages will provide <emphasis>Quick Fix</emphasis> solutions. These can be access using the popup menu associated with the error message: + </para> + + <imageobject> + <imagedata fileref="images/ConformanceCheckErrorMessageMenu.jpg" align="center" width="4in" /> + </imageobject> + + <para> +This will display the <emphasis>Quick Fix</emphasis> dialog listing the available resolutions. + </para> + + <imageobject> + <imagedata fileref="images/QuickFixDialog.jpg" align="center" width="4in" /> + </imageobject> + + <para> +If the <emphasis>Show Referenced Description</emphasis> resolution is selected, then it will cause the choreography description to be launched and the specific interaction to be focused. + </para> + + <imageobject> + <imagedata fileref="images/ShowReferencedDescription.jpg" align="center" width="4in" /> + </imageobject> + + <para> +If the <emphasis>Update from Referenced Description</emphasis> is selected, then the <filename>jboss-esb.xml</filename> will be automatically updated to remove the appended 'X' from the message type. + </para> + </section> <section> <title>Running "Conversation Aware" ESB Services</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 run the <emphasis>purchasing</emphasis> example, firstly ensure that the JBoss Application Server has been fully configured as described in the <emphasis>Installation</emphasis> chapter, and then do the following: + </para> + + <orderedlist> + <listitem> +In a command window, go to the <filename>$Overlord/samples/purchasing/store</filename> folder and execute <emphasis role="bold">ant deploy</emphasis> + </listitem> + <listitem> +In a command window, go to the <filename>$Overlord/samples/common/creditAgency</filename> folder and execute <emphasis role="bold">ant deploy</emphasis> + </listitem> + <listitem> +In a command window, 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 <emphasis>Store</emphasis>, which will then perform the credit check before returning a response to the client. + </listitem> + </orderedlist> + </section> + <section> + <title>Summary</title> + + <para> +This section has provided a brief introduction to the design-time SOA governance features provided within the Overlord CDL distribution. + </para> + + <para> +The aim of these capabilities is to enable verification of an implementation, defined using <emphasis>conversation aware</emphasis> ESB actions in this example, against a choreography, which in turn has been verified against business requirements defined using scenarios. Therefore this helps to ensure that the implemented system meets the original business requirements. + </para> + + <para> +Being able to statically check that the implementation should send or receive messages in the correct order is important, as it will reduce the amount of testing required to ensure the service behaves correctly. However it does not enable the internal implementation details to be verified, which may result in invalid decisions being made at runtime, resulting in unexpected paths being taken. Therefore, to ensure this situation does not occur, we also need runtime governance, which is discussed in the following section. + </para> + + </section> + </section> <section> <title>Runtime Governance using Conversation Validation</title> + <para> +Once services have been deployed, as mentioned in the previous section, we still need to be able to verify that the services continue to conform to the choreography description. The <emphasis>Conversation Validation</emphasis> capability within the Overlord CDL distribution can be used to validate the behaviour of each service. + </para> + + <para> +In this section, we will use the Trailblazer example found in the <filename>$Overlord/samples/trailblazer</filename> folder and the <filename>trailblazer-models</filename> Eclipse project. + </para> + + <section> + <title>Service Validator Configuration</title> + + <para> +The service validator configuration for a choreography can be created using the <emphasis>Overlord->JBossESB->Generate Validator</emphasis> menu item on the popup menu associated with the <filename>TrailBlazer.cdm</filename> file. + </para> + + <imageobject> + <imagedata fileref="images/GenerateValidatorMenu.jpg" align="center" width="3in" /> + </imageobject> + + <para> +This results in a dialog being displayed, requesting the path to the file to be generated. The name of the file must be <filename>validator-config.xml</filename>, otherwise the 'Ok' button will not be enabled. + </para> + + <imageobject> + <imagedata fileref="images/GenerateValidatorDialog.jpg" align="center" width="4in" /> + </imageobject> + + <para> +The information contained within the generated <filename>validator-config.xml</filename> can be merged as appropriate with the file contained within the <filename>$JBossAS/server/default/deploy/overlord-cdl-validator.esb</filename> folder in the JBossAS environment. The validator configuration for the <emphasis>trailblazer</emphasis> example has been preconfigured to be deployed as part of the installation procedure. + </para> + + <note> + <para> +If the <filename>validator-config.xml</filename> within the JBossAS environment is modified, then the server needs to be restarted to cause the configuration to take effect. + </para> + </note> + + </section> + + <section> + <title>Deploy the TrailBlazer Example</title> + + <para> +The first step to deploying the Trailblazer example is to configure the JBossAS environment: + </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> +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> + </orderedlist> + + <para> +One the server has been started, the next step is to deploy the relevant components into the JBossAS environment. This is achieved by: + </para> + + <orderedlist> + <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> + </orderedlist> + + </section> + + <section> + <title>Starting the pi4soa Monitor</title> + + <para> +The pi4soa Monitor is used to observe a correlated view of the executing business transactions. Each service validator can be configured to report activites (i.e. sent and received messages) that it validates, to enable the correlator to reconstitute a global interpretation of each transaction. + </para> + + <para> +This correlated view of each transaction can be used to understand where each transaction is within the process. It can also be used to report <emphasis>out of sequence</emphasis>, <emphasis>unexpected messages</emphasis> and more general errors in the context of the business process. + </para> + + <para> +A simple monitoring tool is currently provided with the pi4soa tools, to enable the correlated global view of the transactions to be observed. Once the Trailblazer example has been deployed to the JBossAS environment, and the server is running, then the monitoring tool can be launched from the Eclipse environment by selecting the <emphasis>Choreography->Monitor</emphasis> menu item from the popup menu associated with the <filename>TrailBlazer.cdm</filename> file. + </para> + + <imageobject> + <imagedata fileref="images/MonitorMenu.jpg" align="center" width="2in" /> + </imageobject> + + <para> +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. + </para> + + <imageobject> + <imagedata fileref="images/ChoreoMonReady.jpg" align="center" width="4in" /> + </imageobject> + + </section> + + <section> + <title>Running the Example</title> + + <para> +To run the example, you need to start a browser and select the URL <ulink url="http://localhost:8080/trailblazer">localhost:8080/trailblazer</ulink>. This will show the following page, if the server has been configured correctly and the TrailBlazer example deployed: + </para> + + <imageobject> + <imagedata fileref="images/TrailblazerWebPage.jpg" align="center" width="4in" /> + </imageobject> + + <para> +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. + </para> + + </section> + </section> </chapter>