Author: objectiser Date: 2008-11-12 05:57:21 -0500 (Wed, 12 Nov 2008) New Revision: 435 Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateESBServicesDialog.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateESBServicesMenu.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateESBServicesNav.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/InvalidPurchasePostTest.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/PurchaseGoods.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/SuccessfulPurchasePostTest.jpg cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/SuccessfulPurchasePreTest.jpg Modified: cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml Log: Intermediate save of new chapter 2 for Getting Started Guide with images. Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateESBServicesDialog.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateESBServicesDialog.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateESBServicesMenu.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateESBServicesMenu.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateESBServicesNav.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/GenerateESBServicesNav.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/InvalidPurchasePostTest.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/InvalidPurchasePostTest.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/PurchaseGoods.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/PurchaseGoods.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/SuccessfulPurchasePostTest.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/SuccessfulPurchasePostTest.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/SuccessfulPurchasePreTest.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/SuccessfulPurchasePreTest.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-11 15:25:46 UTC (rev 434) +++ cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml 2008-11-12 10:57:21 UTC (rev 435) @@ -6,17 +6,145 @@ I wasn't expecting Chapter 2 until much later. I thought that after installation we'd take people through a worked example (glossing over the concepts, but showing people what can be accomplished), but Chapter 2 dives into terms and concepts. I suppose what I was expecting was something like "make sure your Eclipse workspace is set to blah" and blah is a pre-configured workspace that we've set up with a number of different out-of-the-box examples. Then we'd go quickly through them in Chapter 2 before going into more detail about what's going on in subsequent chapters. That way we almost convince people in Chapter 2 that it's worth their while continuing on with the rest of the document. I know that Steve used to do something like this when demo-ing the original CDL tooling, so hopefully it's not too much effort to try to put this in? + <para> +The Choreography Description Language (CDL) provides a means of describing a process, that executes across a distributed set of services, from a global (or service independent) perspective. + </para> -Explain about testable architecture, managing the lifecycle - possibly a cut down version of best practice guide, showing where the conformance checking, generation and monitoring fit in. + <para> +SOA Governance, using CDL, is about ensuring a process is correctly implemented (as part of design-time governance), and executes as expected (part of runtime governance). + </para> + <para> +In this chapter we will take you through a worked example associated with each of these aspects. + </para> + <note> + <para> +Before proceeding, please make sure that the Overlord CDL distribution has been correctly installed and that the samples have been imported into the Eclipse environment. + </para> + </note> <section> - <title>Conversation Validation</title> + <title>Design Time Governance using "Conversation Aware" ESB Actions</title> + <section> + <title>Creating a Choreography</title> + + <para> +When designing a system, it is necessary to capture requirements. Various approaches can be used for this, but currently there are no mechanisms that enable the requirements to be documented in such a way to enable an implementation to be validated back against the requirements. + </para> + + <para> +The pi4soa tools provide a means of describing requirements, representing specific use cases for the interactions between a set of cooperating services, using scenarios - which can be considered similar to UML sequence diagrams that have been enhanced to include example messages. + </para> + + <para> +In the <filename>purchasing-models</filename> Eclipse project, the <filename>SuccessfulPurchase.scn</filename> scenario looks like this: + </para> + + <imageobject> + <imagedata fileref="images/SuccessfulPurchasePreTest.jpg" align="center" width="5in" /> + </imageobject> + + <para> +The next step in the development process is to specific a Choreography Description to implement the requirements described within the set of scenarios. The choreography for the Purchasing example can be found in <filename>purchasing-models/PurchaseGoods.cdm</filename>. When the choreography editor has been launched, by double-clicking on this file within the Eclipse environment, then navigate to the <emphasis>Choreography Flows</emphasis> tab to see the definition of the purchasing process: + </para> + + <imageobject> + <imagedata fileref="images/PurchaseGoods.jpg" align="center" width="5in" /> + </imageobject> + + <para> +The pi4soa tools can be used to test the scenarios against the choreography description, to ensure that the choreography correctly implements the requirements. To test the <filename>SuccessfulPurchase.scn</filename> scenario against the choreography, launch the scenario editor by double-clicking on the scenario file, and then pressing the green <emphasis>play</emphasis> button in the toolbar. When complete, the scenario should look like the following image, indicating that the scenario completed successfully. + </para> + + <imageobject> + <imagedata fileref="images/SuccessfulPurchasePostTest.jpg" align="center" width="5in" /> + </imageobject> + + <para> +To view a scenario that demonstrates a test failure, open the <filename>InvalidPurchase.scn</filename> scenario by double-clicking on the file, and then initiate the test using the green <emphasis>play</emphasis> button in the toolbar. When complete, the scenario should look like the following image. + </para> + + <imageobject> + <imagedata fileref="images/InvalidPurchasePostTest.jpg" align="center" width="5in" /> + </imageobject> + + <para> +You will notice that the <emphasis>Store</emphasis> participant has a red 'send' node, indicating that this action was not expected behaviour when compared with the choreography description. The reason this is considered an error, is that the <emphasis>Store</emphasis> participant should only send a <emphasis>BuyFailed</emphasis> message following an invalid credit check. + </para> + + <para> +When an error is detected in a scenario, the choreography designer can then determine whether the scenario is wrong (i.e. it does not correctly describe a business requirement), or whether the choreography is wrong and needs to be updated to accomodate the scenario. + </para> + + <para> +Once the choreography description has been successfully tested against the scenarios, and therefore is shown to meet the business requirements, the next step is to design and implement each service involved in the choreography. The pi4soa tools provide the means to export BPMN, UML or HTML documentation to aid the implementation phase. However there is special support for a concept called "Conversation Aware" ESB Actions. + </para> + </section> + + <section> + <title>What are "Conversation Aware" ESB Actions?</title> + + <para> +<emphasis>Conversation aware</emphasis> ESB actions refer to a set of pre-defined ESB actions that enable the structure (or behaviour) of a service to be inferred. + </para> + + <para> +For example, there are actions that explicitly define the sending and receiving of messages. These actions define a property that declares the type of the message being sent or received. Other actions describe grouping constructs such as if/else, parallel and while loop. + </para> + + <para> +The benefit of making these concepts explicit within the ESB service configuration, is that it makes it possible to check the implementation correctly matches the expected behaviour as defined within the choreography. This will be demonstrated in the following sub-section discussing conformance checking. + </para> + + </section> + + <section> + <title>Generating an ESB Service using "Conversation Aware" ESB Actions</title> + + <para> +Once we have a choreography description, it is possible to generate an ESB Service (with <emphasis>conversation aware</emphasis> ESB actions), for each of the participants defined within the choreography. To try this out, select the <emphasis>Overlord->JBossESB->Generate ESB Services</emphasis> menu item from the popup menu associated with the <filename>PurchaseGoods.cdm</filename>. + </para> + + <imageobject> + <imagedata fileref="images/GenerateESBServicesMenu.jpg" align="center" width="3in" /> + </imageobject> + + <para> +This will display a dialog listing the possible services that can be generated from this choreography, with a proposed Eclipse project name. + </para> + + <imageobject> + <imagedata fileref="images/GenerateESBServicesDialog.jpg" align="center" width="3in" /> + </imageobject> + + <para> +To test out this feature, uncheck the <emphasis>Buyer</emphasis> and <emphasis>CreditAgency</emphasis> participants, leave the build system as <emphasis>Ant</emphasis> and press the 'Ok' button. This will create a single new project for the <emphasis>Store</emphasis> participant. + </para> + + <imageobject> + <imagedata fileref="images/GenerateESBServicesNav.jpg" align="center" width="2in" /> + </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. + </para> + </section> + + <section> + <title>Conformance Checking "Conversation Aware" ESB Services</title> + + </section> + + <section> + <title>Running "Conversation Aware" ESB Services</title> + + </section> + </section> <section> - <title>Conversation Aware ESB</title> + <title>Runtime Governance using Conversation Validation</title> </section>