[savara-commits] savara SVN: r91 - in tools/eclipse/trunk/docs: gettingstartedguide and 5 other directories.

Author: objectiser Date: 2009-11-24 18:47:13 -0500 (Tue, 24 Nov 2009) New Revision: 91 Added: tools/eclipse/trunk/docs/userguide/pom.xml tools/eclipse/trunk/docs/userguide/src/main/images/SVJBossESBAnnotation.jpg tools/eclipse/trunk/docs/userguide/src/main/images/editvalidatorann.png tools/eclipse/trunk/docs/userguide/src/main/images/editvalidatoranndiag.png tools/eclipse/trunk/docs/userguide/src/main/images/editvalidatorannselect.png tools/eclipse/trunk/docs/userguide/src/main/images/genbpel1.png tools/eclipse/trunk/docs/userguide/src/main/images/genbpel2.png tools/eclipse/trunk/docs/userguide/src/main/images/genbpel3.png tools/eclipse/trunk/docs/userguide/src/main/images/genesbconfig1.png tools/eclipse/trunk/docs/userguide/src/main/images/genesbconfig2.png tools/eclipse/trunk/docs/userguide/src/main/images/genesbconfig3.png tools/eclipse/trunk/docs/userguide/src/main/images/genvalidatordialog.png tools/eclipse/trunk/docs/userguide/src/main/images/genvalidatormenu.png tools/eclipse/trunk/docs/userguide/src/main/images/monitorui.png tools/eclipse/trunk/docs/userguide/src/main/images/setconversationtype.png tools/eclipse/trunk/docs/userguide/src/main/master.xml tools/eclipse/trunk/docs/userguide/src/main/module/author_group.xml tools/eclipse/trunk/docs/userguide/src/main/module/bpel-governance.xml tools/eclipse/trunk/docs/userguide/src/main/module/cdlconformance.xml tools/eclipse/trunk/docs/userguide/src/main/module/conversation-aware-esb.xml tools/eclipse/trunk/docs/userguide/src/main/module/conversation-validation-with-cdl.xml tools/eclipse/trunk/docs/userguide/src/main/module/overview.xml tools/eclipse/trunk/docs/userguide/src/main/xslt/pdf.xsl Modified: tools/eclipse/trunk/docs/gettingstartedguide/pom.xml tools/eclipse/trunk/docs/pom.xml Log: Initial version of Eclipse tools user guide. Modified: tools/eclipse/trunk/docs/gettingstartedguide/pom.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/pom.xml 2009-11-24 21:53:27 UTC (rev 90) +++ tools/eclipse/trunk/docs/gettingstartedguide/pom.xml 2009-11-24 23:47:13 UTC (rev 91) @@ -59,7 +59,7 @@ <format> <formatName>pdf</formatName> <stylesheetResource>file:///${basedir}/src/main/xslt/pdf.xsl</stylesheetResource> - <finalName>GettingStartedGuide.pdf</finalName> + <finalName>SAVARA-Eclipse-Tools-GettingStartedGuide.pdf</finalName> </format> <format> <formatName>html</formatName> Modified: tools/eclipse/trunk/docs/pom.xml =================================================================== --- tools/eclipse/trunk/docs/pom.xml 2009-11-24 21:53:27 UTC (rev 90) +++ tools/eclipse/trunk/docs/pom.xml 2009-11-24 23:47:13 UTC (rev 91) @@ -16,7 +16,7 @@ </parent> <modules> - <!-- >module>userguide</module --> + <module>userguide</module> <module>gettingstartedguide</module> </modules> Added: tools/eclipse/trunk/docs/userguide/pom.xml =================================================================== --- tools/eclipse/trunk/docs/userguide/pom.xml (rev 0) +++ tools/eclipse/trunk/docs/userguide/pom.xml 2009-11-24 23:47:13 UTC (rev 91) @@ -0,0 +1,86 @@ +<project xmlns="http://maven.apache.org/POM/4.0.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> + + <modelVersion>4.0.0</modelVersion> + + <groupId>org.jboss.savara.tools.eclipse.docs</groupId> + <artifactId>userguide</artifactId> + <packaging>jdocbook</packaging> + <name>Savara::Tools::Eclipse::Docs::UserGuide</name> + + <parent> + <groupId>org.jboss.savara.tools.eclipse</groupId> + <artifactId>docs</artifactId> + <version>1.0-SNAPSHOT</version> + </parent> + + + <build> + <plugins> + <plugin> + <groupId>org.jboss.maven.plugins</groupId> + <artifactId>maven-jdocbook-plugin</artifactId> + <version>2.1.2</version> + <extensions>true</extensions> + <executions> + <execution> + <id>generate-docbook</id> + <phase>package</phase> + <goals> + <goal>resources</goal> + <goal>generate</goal> + </goals> + </execution> + </executions> + <dependencies> + <dependency> + <groupId>org.jboss</groupId> + <artifactId>jbossorg-docbook-xslt</artifactId> + <version>1.1.0</version> + </dependency> + <dependency> + <groupId>org.jboss</groupId> + <artifactId>jbossorg-jdocbook-style</artifactId> + <version>1.1.0</version> + <type>jdocbook-style</type> + </dependency> + </dependencies> + <configuration> + <sourceDocumentName>master.xml</sourceDocumentName> + <sourceDirectory>${basedir}/src/main</sourceDirectory> + <imageResource> + <directory>${basedir}/src/main</directory> + <includes> + <include>images/**/*</include> + </includes> + </imageResource> + <formats> + <format> + <formatName>pdf</formatName> + <stylesheetResource>file:///${basedir}/src/main/xslt/pdf.xsl</stylesheetResource> + <finalName>SAVARA-Eclipse-Tools-UserGuide.pdf</finalName> + </format> + <format> + <formatName>html</formatName> + <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource> + <finalName>index.html</finalName> + </format> + <format> + <formatName>html_single</formatName> + <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource> + <finalName>index.html</finalName> + </format> + </formats> + <options> + <xincludeSupported>true</xincludeSupported> + <xmlTransformerType>saxon</xmlTransformerType> + <docbookVersion>1.72.0</docbookVersion> + </options> + </configuration> + </plugin> + </plugins> + </build> + + +</project> Added: tools/eclipse/trunk/docs/userguide/src/main/images/SVJBossESBAnnotation.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/SVJBossESBAnnotation.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/editvalidatorann.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/editvalidatorann.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/editvalidatoranndiag.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/editvalidatoranndiag.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/editvalidatorannselect.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/editvalidatorannselect.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/genbpel1.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/genbpel1.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/genbpel2.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/genbpel2.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/genbpel3.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/genbpel3.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/genesbconfig1.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/genesbconfig1.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/genesbconfig2.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/genesbconfig2.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/genesbconfig3.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/genesbconfig3.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/genvalidatordialog.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/genvalidatordialog.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/genvalidatormenu.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/genvalidatormenu.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/monitorui.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/monitorui.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/images/setconversationtype.png =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/userguide/src/main/images/setconversationtype.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/userguide/src/main/master.xml =================================================================== --- tools/eclipse/trunk/docs/userguide/src/main/master.xml (rev 0) +++ tools/eclipse/trunk/docs/userguide/src/main/master.xml 2009-11-24 23:47:13 UTC (rev 91) @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent"> +]> + +<book lang="en"> + <bookinfo> + <title>SAVARA Eclipse Tools 1.0-SNAPSHOT</title> + <subtitle>User Guide</subtitle> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/author_group.xml"/> + </bookinfo> + + <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/bpel-governance.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/cdlconformance.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/conversation-aware-esb.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/conversation-validation-with-cdl.xml"/> + +</book> Added: tools/eclipse/trunk/docs/userguide/src/main/module/author_group.xml =================================================================== --- tools/eclipse/trunk/docs/userguide/src/main/module/author_group.xml (rev 0) +++ tools/eclipse/trunk/docs/userguide/src/main/module/author_group.xml 2009-11-24 23:47:13 UTC (rev 91) @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> +<authorgroup> + <corpauthor>Gary Brown</corpauthor> + <corpauthor>Jeff Yu</corpauthor> +</authorgroup> Added: tools/eclipse/trunk/docs/userguide/src/main/module/bpel-governance.xml =================================================================== --- tools/eclipse/trunk/docs/userguide/src/main/module/bpel-governance.xml (rev 0) +++ tools/eclipse/trunk/docs/userguide/src/main/module/bpel-governance.xml 2009-11-24 23:47:13 UTC (rev 91) @@ -0,0 +1,71 @@ +<?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="bpelgovernance"> + <title>BPEL Governance</title> + + <section> + <title>Overview</title> + <para> +This section will describe governance features related to WS-BPEL. This initial release provides basic support for generating BPEL processes from a choreography description. Subsequent releases will also provide conformance checking, to ensure that changes to a BPEL process are validated to ensure the process remains conformant with the choreography. + </para> + </section> + + <section> + <title>Generating a BPEL process from CDL</title> + <section> + <title>Overview</title> + <para> +This section explains how to generate a template BPEL process from a pi4soa choreography description (.cdm) file. + </para> + </section> + <section> + <title>Generating the BPEL Process</title> + <para> +When the choreography description has been completed, and has no errors, the user should select the "Overlord->Generate->WS-BPEL" menu item from the popup menu associated with the choreography description (.cdm) file. + </para> + + <imageobject> + <imagedata fileref="images/genbpel1.png" width="4in" /> + </imageobject> + + <para> +When the dialog window is displayed, it will contain the list of services that can be generated, along with the project names that will be created. The user can unselect the services they do not wish to generate (also using the 'Check All' or 'Clear All' buttons). + </para> + + <imageobject> + <imagedata fileref="images/genbpel2.png" /> + </imageobject> + + <para> +The user can also select their preferred build system, which will create the relevant build structure. + </para> + <para> +If there is a problem with the name of the project select, such as invalid characters used in the name, or the project name already exists, then it will be displayed in red. + </para> + + <para> +Once the BPEL is generated, it can be viewed using the Eclipse BPEL editor, e.g. + </para> + + <imageobject> + <imagedata fileref="images/genbpel3.png" /> + </imageobject> + + </section> + + <section> + <title>Limitations with the current CDL to BPEL mapping</title> + + <para> +This initial version of the BPEL generation is primarily targeted at generating the interactions and grouping constructs. These are the important components that will be required when doing conformance checking as part of the next milestone. + </para> + + <para> +This means that assignments and conditional expressions are not currently generated. The 'when' construct in CDL (also known as the blocking workunit) is also not currently handled. This may possible be implemented using flow links. + </para> + </section> + </section> + +</chapter> + Added: tools/eclipse/trunk/docs/userguide/src/main/module/cdlconformance.xml =================================================================== --- tools/eclipse/trunk/docs/userguide/src/main/module/cdlconformance.xml (rev 0) +++ tools/eclipse/trunk/docs/userguide/src/main/module/cdlconformance.xml 2009-11-24 23:47:13 UTC (rev 91) @@ -0,0 +1,192 @@ +<?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(for both stateful and stateless), and the conformance checking against a choreography. + </para> + <para> +These are <filename>purchasing</filename>, a simple customer/supplier example with two associated Eclipse projects (<filename>purchasing-store-stateful/less</filename> and <filename>purchasing-models</filename>), 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, defined within three Eclipse projects (<filename>brokerage-broker-stateful/less</filename>, <filename>brokerage-supplier-stateful/less</filename> and <filename>brokerage-models</filename>). + </para> + <para> +These examples make use of a common <emphasis>Credit Agency</emphasis> service, defined within the <filename>common-creditAgency-stateful/less</filename> Eclipse project, and are executed through the use of client applications defined in the <filename>${OverlordCDL}/samples/client</filename> folder. + </para> + + <warning> + At the moment, the conversation aware ESB runtime doesn't support the hot-deploy. That means if you update the business pojo class, such as <emphasis role="bold">$creditAgency/src/main/com/acme/services/creditAgency/CreditAgencyPurchase.java</emphasis> file, + You need to re-deploy it, and then <emphasis role="bold">restart the server </emphasis> to cause it to take effect. This issue has been tracked under <ulink url="https://jira.jboss.org/jira/browse/SOAG-72">https://jir...;. Will be fixed in the next release. + </warning> + + <section> + <title>Purchasing Example</title> + <section> + <title>Overview</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 refer to the model and service implementation projects in the Eclipse environment. +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[-stateful/less]/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> + + <section> + <title>Running the Example</title> + <para> + This example has two versions, stateful and stateless. in the sample folder, you will find the samples were grouped in stateful and stateless folder. + One is the stateful purchasing example (this is the example that we had since M1 release),the other is stateless purchasing example that is introduced in the M2 release. + </para> + <orderedlist> + <listitem> + First step is to install the ESB services. (Presumely the JBoss ESB server started already) + In a command window, Go to the the <filename>$Overlord/samples/stateful</filename> folder (or <filename>$Overlord/sample/stateless</filename> in the stateless approach), execute the <emphasis role="bold">ant deploy-purchasing</emphasis>. + </listitem> + <listitem> + Go to the <filename>$Overlord/samples/client</filename> folder and execute <emphasis role="bold">ant runPurchasingClient</emphasis> (or <emphasis role="bold"> ant runStatelessPurchasingClient</emphasis> in stateless approach.), 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 to return <emphasis>false</emphasis>, 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> + + <tip> + <para>You can undeploy the corresponding esb artifact by through command <command>ant undeploy-purchasing</command> in the <filename>$Overlord/samples/stateful</filename> folder or <filename>$Overlord/samples/stateless</filename> folder respectively.</para> + </tip> + + </section> + + </section> + + <section> + <title>Brokerage Example</title> + + <section> + <title>Overview</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 refer to the model and service implementation projects in the Eclipse environment. +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[-stateful/less]/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> + + <section> + <title>Running the Example</title> + <para> + This example has two versions, stateful and stateless. in the sample folder, you will find the samples were grouped in stateful and stateless folder. + one is the sateful broker example (this is the example that we had since M1 release), the other is stateless broker example that is introduced in the M2 release. + </para> + <orderedlist> + <listitem> + First step is to install the ESB services (Presumely the JBoss ESB server started already) + In a command window, Go to the <filename>$Overlord/samples/stateful</filename> folder (or <filename>$Overlord/samples/stateless</filename> in the stateless approach), execute <emphasis role="bold">ant deploy-broker</emphasis> + </listitem> + <listitem> + Go to the <filename>$Overlord/samples/client</filename> folder and execute <emphasis role="bold">ant runBrokerageClient</emphasis> (or <emphasis role="bold"> ant runStatelessBrokerageClient</emphasis> in stateless approach), 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> + + <tip> + <para>You can undeploy the corresponding esb artifact by through command <command>ant undeploy-broker</command> in $Overlord/samples/stateful or $Overlord/samples/stateless respectively.</para> + </tip> + </section> + + </section> + +</chapter> Added: tools/eclipse/trunk/docs/userguide/src/main/module/conversation-aware-esb.xml =================================================================== --- tools/eclipse/trunk/docs/userguide/src/main/module/conversation-aware-esb.xml (rev 0) +++ tools/eclipse/trunk/docs/userguide/src/main/module/conversation-aware-esb.xml 2009-11-24 23:47:13 UTC (rev 91) @@ -0,0 +1,483 @@ +<?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="conversationawareesb"> + <title>Conversation Aware ESB</title> + <section> + + <warning> + <para> +The <emphasis>conversation aware ESB actions</emphasis> mechanism should be considered an alpha version only, +and subject to change in future releases. Its inclusion within this release is intended to enable the community +to experiment with the approach and hopefully provide feedback that can be used to guide the direction of this capability. + </para> + </warning> + + <title>Conversation based Conformance</title> + <section> + <title>Overview</title> + <para> +The term "conversation" represents a structured set of interactions (or message exchanges) between +one or more peer to peer services, to conduct a business transaction. The "conversation" is defined +from a service neutral (i.e. global) perspective. + </para> + <para> +This document explains how such a "conversation" description can be used to ensure conformance of +one or more service implementations, within an ESB, during the design and implementation phase of +the system. + </para> + <para> +This section introduces the choreography description language (CDL) defined by W3C, which is a +standard notation for defining conversations from a global perspective, and the +<emphasis>pi4soa</emphasis> open source project which provides an editor for creating choreography +descriptions, as well as utilizing these descriptions for conformance checking, monitoring and +execution purposes. + </para> + <para> +Finally the section will provide a brief discussion of how CDL can be used to provide conformance +checking of an ESB, through the use of 'conversation aware' ESB actions. + </para> + </section> + <section> + <title>CDL Conformance Checking</title> + <para> +In general, conformance checking is the procedure for ensuring that a component has been correctly +built according to some specification or standard. In terms of CDL, it more specifically ensures +that one or more services perform their responsibilities correctly in accordance with the +choreography description. + </para> + <para> +The <emphasis>pi4soa</emphasis> tools suite provide the mechanism for producing service endpoint +descriptions for each service within a choreography description. The relevant service descriptions +can then be compared (for conformance) against their ESB service implementations. + </para> + <para> +However, to make this possible, it is necessary to be able to derive the communication 'type' +structure from the ESB implementation, i.e. where messages (of particular types) are sent and +received, where decision points are, where actions are performed concurrently, etc. + </para> + <para> +This is why a specific set of 'conversation aware' ESB actions have been defined (discussed in a +later section), to make it possible to derive the communication 'type' structure from an ESB +service implementation. + </para> + <para> +Once the communication 'type' structure has been obtained from the ESB implementation, it can be +compared against the relevant service endpoint description projected from the choreography description, +to determine if there are any differences. These can then be reported to the ESB service developer, +so that they can fix the problems, before the service is deployed to the runtime environment. + </para> + <para> +This ensures that all of the services will interact correctly, as they will all have been validated +against the choreography, and therefore work together by design. + </para> + <para> +In the following section, we will describe how ESB services can be described using +"conversation aware" ESB actions. + </para> + </section> + </section> + + <section> + <title>"Conversation Aware" ESB Actions</title> + <section> + <title>Overview</title> + + <para> +The "conversation aware" ESB action mechanism provides a set of ESB actions that can be used +to instrument an ESB service with constructs that enable the communication structure to be +inferred. This is useful, as it enables the communication structure to be compared against the +expected behaviour defined in a choreography (global) model, or service design. + </para> + + <para> +Usually the stateful behaviour of a service is required to enable it to be compared against +the stateful behaviour defined in a choreography. However this would result in a stateful +service implementation being required for each ESB service, adding state management etc. +which would result in more complex service implementations. + </para> + + <para> +To void adding this complexity to the ESB service implementation, an approach called +<emphasis>stateful fragments</emphasis> has been used. This enables the causality to +be inferred based on dealing with each inbound event - however the causality between +received events is not modelled. The benefit of this approach is its simplicity, and +therefore it has less impact on the +way that users create ESB service descriptors. The disadvantage with this approach is that only +fragments of stateful behaviour can be derived from the ESB jboss-esb.xml. However, +this is useful enough to perform static conformance checking of the service implementation +against a choreography description, and when used in conjunction with the dynamic +conversation validation mechanism, it is still possible to determine out of sequence messages. + </para> + </section> + + <section> + <title>Interaction</title> + <para> +Firstly, let's see the two basic actions for interaction. +Services interact by sending and receiving messages, whether synchronously or asynchronously. + </para> + <para> +JBossESB is designed to anonymously handle inbound messages (possibly requests), without explicitly defining restrictions on message type, and then optionally returning responses (again without explicitly defining the response message type). + </para> + <para> +Although this is sufficient for a runtime mechanism, where issues related to unexpected message types can be handled with suitable exceptions/faults, it does not enable the communication type structure to be understood by examination of the JBossESB configuration. + </para> + + <section> + <title>Sending a message</title> + <para> +When sending a message, the first thing to consider is the type of the message. This can be declared as a property on the <emphasis>SendMessageAction</emphasis>. +If dealing with RPC style interactions, then we may also want to optionally specify an operation name. + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ + <action class="org.jboss.savara.jbossesb.actions.SendMessageAction" + process="process" name="..."> + <property name="operation" value="getQuote" /> + <property name="messageType" value="requestForQuote" /> + .... + </action> + ]]></programlisting> + </informalexample> + + <itemizedlist> + <listitem> +Sending a request + <para> +When sending a request, we need to identify the destination service category/name. This is done by either specifying the category and name explicitly, using the <emphasis>serviceCategory</emphasis> and <emphasis>serviceName</emphasis> properties: + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ + + <action class="org.jboss.savara.jbossesb.actions.SendMessageAction" + process="process" name="..."> + .... + <property name="serviceName" value="RequestForQuote.main" /> + <property name="serviceCategory" value="ESBBroker.SupplierParticipant" /> + .... + </action> + ]]></programlisting> + </informalexample> + + </listitem> + + <listitem> +Sending a response + <informalexample> + <programlisting role="XML" ><![CDATA[ + + <action class="org.jboss.savara.jbossesb.actions.SendMessageAction" + process="process" name="..."> + .... + <property name="clientRole" value="buyer" /> + <property name="eprStore" value="orgization.your.impl.EPRStorageImpl" /> + .... + </action> + ]]></programlisting> + </informalexample> + <para> +When sending a response, the destination will not be directly available. The destination would have been received as a 'reply to' EPR (Endpoint Reference) in a previously received request (see <emphasis>ReceiveMessageAction</emphasis> for details of how to store the 'reply to' EPR). +Therefore, to indicate which EPR to respond to, a property called 'clientEPR' is specified with the name of the stored EPR. This must match up to a previously stored EPR name within a <emphasis>ReceiveMessageAction</emphasis>. + </para> + <para> +The value of <emphasis>storageClass</emphasis> should be a class that implements the <emphasis>org.jboss.soa.savara.jbossesb.EPRStorage</emphasis> interface, basically this class is responsible for registering, getting EPR from roleName. + </para> + </listitem> + </itemizedlist> + + </section> + + <section> + <title>Receiving a message</title> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <action class="org.jboss.savara.jbossesb.actions.ReceiveMessageAction" + process="process" name="s1-2"> + <property name="operation" value="makeEnquiry" /> + <property name="messageType" value="enquiry" /> + <property name="clientRole" value="buyer" /> + <property name="eprStore" value="com.acme.services.creditAgency.MemoryEPRStorage" /> + </action> + ]]></programlisting> + </informalexample> + + <para> +The <emphasis>ReceiveMessageAction</emphasis> is used to explicitly define the message type that should be received. +If an RPC style has been used, then the optional operation name can also be defined. + </para> + <para> +Unlike the <emphasis>SendMessageAction</emphasis>, which will actually send a message to the specified service category/name, +the <emphasis>ReceiveMessageAction</emphasis> primarily serves to provide explicit details about the expected message and to perform any relevant validation of the message content. If an incorrect message type is received, then an error will be logged. + </para> + <para> +The optional 'clientRole' and 'storageClass' properties are used to store any specific "reply to" EPR (associated with the message) against the specified name. This makes the EPR accessible to any subsequent <emphasis>SendMessageAction</emphasis> activities that need to return a response or send a notification. + </para> + </section> + </section> + + <section> + <title>Controlling Flow</title> + <para> +This section describes the two control flow mechanisms that are supported by the stateless ESB actions. + </para> + <para> +The default control flow, supported natively by the ESB action pipeline design, is a sequence. As the name implies, the actions are performed one at a time in the order they defined in the action pipeline, i.e. in a sequence. + </para> + + <section> + <title>Selecting paths based on a decision</title> + <para> +The action associated with the 'selection of a path based on a decision' is the <emphasis>IfAction</emphasis>. An example of this construct is: + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ +<action class="org.jboss.savara.jbossesb.actions.IfAction" name="..." + process="process"> + <property name="paths"> + <if service-category="PurchaseGoods.CreditAgency" + service-name="CreditAgency.decision1" + decision-class="org.jboss.soa.savara.jbossesb.TestDecision"/> + <elseif service-category="PurchaseGoods.CreditAgency" + service-name="CreditAgency.decision2" + decision-class="org.jboss.soa.savara.jbossesb.Test2ndDecision"/> + <else service-category="PurchaseGoods.CreditAgency" + service-name="CreditAgency.decision3"/> + </property> +</action> + ]]></programlisting> + </informalexample> + <para> +This construct defines a 'path' property with one or more elements, representing the <emphasis>if</emphasis>, <emphasis>elseif</emphasis> and <emphasis>else</emphasis> aspects of the traditional if/else construct. Only the <emphasis>if</emphasis> element is mandatory, and can be followed by zero or more <emphasis>elseif</emphasis> elements before ending with the optional <emphasis>else</emphasis> element. + </para> + <para> +The <emphasis>if</emphasis> and <emphasis>elseif</emphasis> elements can define an 'decision-class' attribute to be evaluated at runtime, to determine if the associated 'service-category' and 'service-name' should be invoked. +the value of decision-class must implement the interface of <emphasis>org.jboss.soa.savara.jbossesb.Decision</emphasis>. + </para> + </section> + + <section> + <title>Message router action</title> + <para> +The action used to select paths based on a received message type is <emphasis>SwitchAction</emphasis>. +In the stateless esb actions approach, we are using this as the <emphasis>Message Router</emphasis>. +The configuration of <emphasis>SwithAction</emphasis> is like: + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ +<action class="org.jboss.savara.jbossesb.actions.SwitchAction" + name="..." process="process"> + <property name="serviceDescriptionName" + value="{org.pi4soa.esbbroker.esbbroker}ESBBrokerProcess-Broker"/> + <property name="conversationType" value="savara.samples.LoanBroker@Broker"/> + <property name="paths"> + <case service-category="org.pi4soa.esbbroker.esbbroker" + service-name="ESBBrokerProcess_Broker__1"> + <message type="enquiry"/> + </case> + <case service-category="org.pi4soa.esbbroker.esbbroker" + service-name="ESBBrokerProcess_Broker__7"> + <event description="Event trigger to send quoteList message type(s)"/> + </case> + <case service-category="org.pi4soa.esbbroker.esbbroker" + service-name="ESBBrokerProcess_Broker__8"> + <message type="buy"/> + </case> + </property> +</action> + ]]></programlisting> + </informalexample> + <para> +In this approach, the <emphasis>SwitchAction</emphasis> typically is the point of contact for other services. Also true for the internal services. In the same manner as the <emphasis>Stateful</emphasis> ESB actions, it is necessary to specify the 'conversation type' that the service represents, to enable conformance checking to be performed against a choreography description that provides the associated conversation type. In the <emphasis>Stateless</emphasis> ESB actions, this initial <emphasis>SwitchAction</emphasis> defines this information in the <emphasis>conversationType</emphasis> property. + </para> + <para> +The 'paths' property defines one or more 'case' elements. These elements identify a service category and name that should be invoked upon receipt of one or more message types, as specified by 'message' elements contained within the 'case' elements. + </para> + <para> +The 'type' attribute on the 'message' element defines the type of message that can be routed to the specified service category/name. In the example above, the message types have no namespace. +However if they have a namespace, this can be defined in curly braces, e.g. "{http://www.jboss.org/samples}buy". + </para> + <para> +The 'event' element is defined for paths with no associated message type. These paths are expected to be triggered by a different sort of event, for example an internal timeout managed by the service implementation. However these internal events are triggered, and directed to the appropriate service descriptor is a implementation issue for the service. The inclusion of this path in the <emphasis>SwitchAction</emphasis> symbolises the exist of this asynchronously triggered path in the behaviour of the service. + </para> + <para> +Once a path has been selected, the associated service category/name will be invoked immediately. +If none of the paths specified within this action are relevant to the received message, then a runtime exception will be thrown. + </para> + </section> + + </section> + + <tip> + In this M2 release, we've just had these four actions in the stateless esb action approach. + we might add other actions in the subsequent release. If you have any comments and feedback, you can go to the forum or issue track to raise your request. + </tip> + + </section> + + <section> + <title>Generating a JBossESB Configuration from CDL</title> + <section> + <title>Overview</title> + <para> +This section explains how to generate a template JBossESB configuration file from a pi4soa choreography +description (.cdm) file. + </para> + </section> + <section> + <title>Generating the JBossESB Configuration</title> + <para> +When the choreography description has been completed, and has no errors, the user should select the +"SAVARA->Generate->JBossESB Services" menu item from the popup menu associated with the choreography +description (.cdm) file. + </para> + + <imageobject> + <imagedata fileref="images/genesbconfig1.png" width="4in" /> + </imageobject> + + <para> +When the dialog window is displayed, it will contain the list of services that can be generated, along with the project names that will be created. The user can unselect the services they do not wish to generate (also using the 'Check All' or 'Clear All' buttons). There is also a checkbox to determine whether a stateful or stateless (the default) implementation should be generated. + </para> + + <imageobject> + <imagedata fileref="images/genesbconfig2.png" /> + </imageobject> + + <para> +The user can also select their preferred build system, which will create the relevant build structure + and script in the generated Java project to enable the JBossESB service to be deployed, as well as + the appropiate messaging system to use. + </para> + <para> +If there is a problem with the name of the project select, such as invalid characters used in the name, +or the project name already exists, then it will be displayed in red. + </para> + + <imageobject> + <imagedata fileref="images/genesbconfig3.png" /> + </imageobject> + + <para> +In the above image, on the left it shows the generated project structure for the Broker service role. +On the right it shows a portion of a generated session class, with the accessor and modifier for one +of the variables associated with that session. + </para> + <para> +Although an initial build script will be created, depending on the build system selected, the user +may need to edit the script to set certain properties, or change the way the build occurs. For +example, with the Ant build, the deploy target (which is the default) will attempt to place the +deployed .esb file into a location defined by the <filename>${org.jboss.esb.server.deploy.dir}</filename>. +If this variable has not been defined, then a folder called +<filename>${org.jboss.esb.server.deploy.dir}</filename> will be created in the root folder of the +project, containing the .esb file. + </para> + </section> + </section> + + <section> + <title>Dealing with Conformance Issues</title> + <section> + <title>Overview</title> + <para> +Conformance checking can be used to determine whether an ESB configuration, containing +"conversation aware" ESB actions, matches the expected behaviour as defined within a choreography +description (.cdm file). The Eclipse environment will report any conformance issues as errors in +the <emphasis>Problems</emphasis> view. + </para> + <para> +This section will explain the types of conformance errors that may be reported and how to +deal with them. Not all errors, associated with an ESB configuration, will be discussed in this +section. Many errors may be detected that will indicate problems associated with the way that +behaviour has been specified in the configuration file (e.g. conversation type has not been defined). +These are not directly related to conformance. + </para> + </section> + + <section> + <title>Show referenced description</title> + <para> +When an error occurs, related to conformance between the ESB configuration file and a choreography +description, it will have an associated <emphasis>quick fix</emphasis> resolution that can be used +to display the relevant activity being referred to within the choreography description. + </para> + </section> + + <section> + <title>Error: Expecting additional activities as defined in referenced description</title> + <para> +This error message indicates that the reference description contains activities that were not found +in the ESB configuration. + </para> + <para> +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><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. +</para></note> + </section> + + <section> + <title>Error: Type mismatch with referenced description, was expecting '...'</title> + <para> +This error occurs when an activity contains a type that does not match with the equivalent activity +in the choreography description. A common example would be an interaction, where the message types +are not compatible. + </para> + + <para> +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><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. +</para></note> + </section> + + <section> + <title>Error: Behaviour not present in referenced description</title> + <para> +This error occurs when there are extra activities within the ESB configuration that do not appear +within the choreography description. + </para> + <para> +This error has an associated <emphasis>quick fix</emphasis> to enable the unwanted activities to be +removed from the ESB configuration. + </para> + +<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. +</para></note> + </section> + + <section> + <title>Error: Additional unmatched paths in model</title> + <para> +This error indicates that a grouping contruct (e.g. <emphasis>IfAction</emphasis> or +<emphasis>SwitchAction</emphasis>) in the ESB configuration has +additional paths that do not match the equivalent grouping construct in the choreography description. + </para> + </section> + + <section> + <title>Error: Additional unmatched paths in referenced description</title> + <para> +This error indicates that a grouping contruct (e.g. <emphasis>IfAction</emphasis> or +<emphasis>SwitchAction</emphasis>) in the choreography description has additional paths that do not +match the equivalent grouping construct in the ESB configuration. + </para> + </section> + + </section> + +</chapter> + Added: tools/eclipse/trunk/docs/userguide/src/main/module/conversation-validation-with-cdl.xml =================================================================== --- tools/eclipse/trunk/docs/userguide/src/main/module/conversation-validation-with-cdl.xml (rev 0) +++ tools/eclipse/trunk/docs/userguide/src/main/module/conversation-validation-with-cdl.xml 2009-11-24 23:47:13 UTC (rev 91) @@ -0,0 +1,301 @@ +<?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="conversationvalidationwithcdl"> + <title>Conversation Validation with CDL</title> + <section> + <title>Overview</title> + <para> +Conversation validation is a form of runtime governance concerned with the dynamic behaviour of a system. + </para> + <para> +When coupled with a choreography description model of a system, this means having the ability to ensure that the way a collection of services interact correctly adheres to a description of the business process being enacted. + </para> + <para> +This section introduces the choreography description language (CDL) defined by W3C, and the <emphasis>pi4soa</emphasis> open source project which provides an editor for creating choreography descriptions, as well as utilizing these descriptions for runtime validation and execution purposes. + + </para> + + </section> + + <section> + <title>Configuration of Conversation Validation</title> + + <para> + This section explains how to configure the conversation validation mechanism to validate ESB services + against a choreography description. The first sub-section describes how the mechanism is hooked into the + JBossESB environment. The following two sub-sections explain two alternate ways that relevant endpoint + references can be configured for validation. + </para> + + <section> + <title>Installing the Conversation Validation Mechanism</title> + <para> +The principle mechanism used for validating conversations within an ESB is through the use of a global filter registered with the <emphasis>jbossesb-properties.xml</emphasis>. This file is located in the <emphasis>$JBossESB/server/default/deploy/jbossesb.sar</emphasis> folder. + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ + <properties name="filters"> + ... + <property name="org.jboss.soa.esb.filter.10" + value="org.jboss.soa.overlord.validator.jbossesb.ValidatorFilter"/> + </properties> + ]]></programlisting> + </informalexample> + + <para> +This filter is installed as part of the installation process for the Overlord-CDL distribution. + </para> + </section> + + <section> + <title>Explicit Configuration</title> + + <para> +The information concerning which destinations will be validated, and to which model/role they relate, can be explicitly +defined within the <emphasis>validator-config.xml</emphasis> file, contained within the <emphasis>overlord-cdl-validator.esb</emphasis> bundle. + </para> + <para> +An example of the contents of this file, that would related to the TrailBlazer example, is: + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ + <validator mode="monitor" replyToTimeout="10000" > + <service model="TrailBlazer.cdm" + role="LoanBrokerParticipant" > + <output epr="jms:queue/esb-tb-creditAgencyQueue" /> + <input epr="jms:queue/esb-tb-creditAgencyQueue_reply" /> + <output epr="jms:queue/esb-tb-jmsBankRequestQueue" /> + <output epr="jms:queue/esb-tb-fileBankRequestQueue" /> + <input epr="jms:queue/esb-tb-jmsBankResponseQueue" /> + <output epr="jms:queue/esb-tb-customerNotifier" /> + <input epr="jms:queue/esb-tb-fileBankResponseQueue" /> + </service> + <service model="TrailBlazer.cdm" + role="CreditAgencyParticipant" > + <input epr="jms:queue/esb-tb-creditAgencyQueue" /> + <output epr="jms:queue/esb-tb-creditAgencyQueue_reply" /> + </service> + <service model="TrailBlazer.cdm" + role="BankParticipant" > + <input epr="jms:queue/esb-tb-jmsBankRequestQueue" /> + <input epr="jms:queue/esb-tb-fileBankRequestQueue" /> + <output epr="jms:queue/esb-tb-jmsBankResponseQueue" /> + <output epr="jms:queue/esb-tb-fileBankResponseQueue" /> + </service> + <service model="TrailBlazer.cdm" + role="NotifierParticipant" > + <input epr="jms:queue/esb-tb-customerNotifier" /> + </service> + </validator> + ]]></programlisting> + </informalexample> + + <para> +The 'validator' element has an optional attribute called 'mode', with the possible values of 'monitor' or 'manage'. If the +mode is 'monitor' (which is the default), then any messages that result in validation errors being detected will continue to be received or sent, with the errors only be reported for information purposes. If the mode is 'manage', then any erronous messages detected during validation, that conflict with the behaviour as described in the choreography, will be prevented from being received or sent. + </para> + <note> + <para> + It is important to note that if 'manage' validation mode is used, then the validation mechanism will be an integral part of the message flow. This may have a slight performance impact on the delivery of messages between services. + </para> + </note> + + <para> +The optional 'replyToTimeout' (defined in milliseconds) is used to determine how long a dynamic reply-to destination should be monitored for validation purposes. In some message exchanges, the response destination will not always be known in advance. Therefore the configuration can identify such situations, and monitor the reply-to destination for the response. However, if a response is not delivered in a particular time period, we need to be able to discontinue the validation of the dynamic endpoint. If this did not occur, then over time too many endpoints would be monitored, which may result in out-of-memory problems. The default timeout period is 10 seconds. + </para> + <para> +Within the 'validator' element is a list of 'service' elements, one per service being validated. The behaviour of the service being validated is identified by specifying the model (e.g. choreography description file) and the role (e.g. participant type) within the model. Therefore, within the above configuration, the first set of destinations (eprs) are associated with the <emphasis>LoanBrokerParticipant</emphasis> defined within the choreography description model found in the file <filename>TrailBlazer.cdm</filename>, which will be located within the <filename>models</filename> folder contained within the +<emphasis>overlord-cdl-validator.esb</emphasis> bundle. + </para> + <para> +The elements contained within the 'service' element define the <emphasis>input</emphasis> and <emphasis>output</emphasis> eprs (Endpoint References) that are associated with the service. The <emphasis>input</emphasis> eprs are the destinations on which messages will be received and the <emphasis>output</emphasis> eprs are the destinations on which messages will be sent by the service. + </para> + <para> +The format of the 'epr' attribute will be specific to the type of transport used for the ESB aware destination. Currently only JMS is supported, and can be identified by the protocol prefix 'jms:'. + </para> + <para> +Each 'input' and 'output' element can also define an optional 'dynamicReplyTo' boolean attribute. If defined, it will indicate to the Service Validator that the message on the specified endpoint (epr) will contain a dynamically defined 'reply-to' destination that needs to be monitored for a response. + </para> + + </section> + + <section> + <title>Defining the Validator Configuration within a Choreography</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 popup 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/SVJBossESBAnnotation.jpg" width="5in" /> + </imageobject> + + <para> + To specify the EPR for a particular message exchange, enter the EPR into the + <emphasis>Destination</emphasis> field. If the exchange is a request, that + will result in a response being sent on a dynamically provided "reply-to" + destination, then the <emphasis>Dynamic Reply-To</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> + + <para> + When all of the relevant 'exchange details' components have been configured with + a <emphasis>jbossesb</emphasis> annotation, defining the EPR to be validated, + then the choreography description file can be copied into the + <filename>overlord-cdl-validator.esb/models</filename> folder. This will cause + the validation mechanism to derive the configuration information from the choreography + description model, and begin validating the defined destinations against that + choreography description model. + </para> + + </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 +description, and the server has been started, then the next step is to launch a tool to view the correlated information from +the service validators - and determine if the transactions are being correctly executed. +</para> +<para> +Within an Eclipse Java project, that contains the choreography description to be monitored, a configuration file called <emphasis>pi4soa.xml</emphasis> needs to be defined on the project's classpath. This file provides details of the JMS configuration parameters required to subscribe for the information generated by the service validators. The contents of this file is: +</para> + <informalexample> + <programlisting role="XML" ><![CDATA[ +<pi4soa> + <tracker> + <jndi> + <initialContextFactory>org.jnp.interfaces.NamingContextFactory</initialContextFactory> + <providerURL>jnp://localhost:1099</providerURL> + <factoryURLPackages>org.jboss.naming:org.jnp.interfaces</factoryURLPackages> + </jndi> + <jms> + <connectionFactory>ConnectionFactory</connectionFactory> + <connectionFactoryAlternate>ConnectionFactory</connectionFactoryAlternate> + <destination>topic/tracker</destination> + </jms> + </tracker> +</pi4soa> + ]]></programlisting> + </informalexample> + +<para> +The destination defined in this file must match the one configured in the <emphasis>pi4soa.sar/pi4soa.xml</emphasis> file within the server. +</para> + <para> +The next step is to launch the monitoring tool. This is located on the popup 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> + + <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. + </para> + <para> +If any <emphasis>out of sequence</emphasis> or other error situations arise, these are displayed in red. + </para> + </section> + + <section> + <title>Configuration for Conversation Recording</title> + + <para> + As well as validating the interactions between a set of + services, against a pre-defined choreography description, + it is also possible to use the <emphasis>Service Validators</emphasis> + in a non-validating record mode. + </para> + + <para> + This will be useful in situations where a choreography + description does not currently exist, and we wish to + use the stream of business events being sent and received + by each identified service (or participant type) to + gain an understanding of the current business process. + </para> + + <para> + An example of this type of configuration, associated + with the TrailBlazer example, is: + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ + <validator> + <service role="LoanBrokerParticipant" validate="false" > + <output epr="jms:queue/esb-tb-creditAgencyQueue" /> + <input epr="jms:queue/esb-tb-creditAgencyQueue_reply" /> + <output epr="jms:queue/esb-tb-jmsBankRequestQueue" /> + <output epr="jms:queue/esb-tb-fileBankRequestQueue" /> + <input epr="jms:queue/esb-tb-jmsBankResponseQueue" /> + <output epr="jms:queue/esb-tb-customerNotifier" /> + <input epr="jms:queue/esb-tb-fileBankResponseQueue" /> + </service> + <service role="CreditAgencyParticipant" validate="false" > + <input epr="jms:queue/esb-tb-creditAgencyQueue" /> + <output epr="jms:queue/esb-tb-creditAgencyQueue_reply" /> + </service> + <service role="BankParticipant" validate="false" > + <input epr="jms:queue/esb-tb-jmsBankRequestQueue" /> + <input epr="jms:queue/esb-tb-fileBankRequestQueue" /> + <output epr="jms:queue/esb-tb-jmsBankResponseQueue" /> + <output epr="jms:queue/esb-tb-fileBankResponseQueue" /> + </service> + <service role="NotifierParticipant" validate="false" > + <input epr="jms:queue/esb-tb-customerNotifier" /> + </service> + </validator> + ]]></programlisting> + </informalexample> + + <para> + To define a <emphasis>Service Validator</emphasis> in record + only mode, the <emphasis>model</emphasis> attribute + is not specified (because no choreography description exists + to be validated against), and the optional <emphasis>validate</emphasis> + attribute should be set to <emphasis role="bold">false</emphasis> (by default + this attribute is <emphasis role="bold">true</emphasis>). + </para> + </section> + +</chapter> Added: tools/eclipse/trunk/docs/userguide/src/main/module/overview.xml =================================================================== --- tools/eclipse/trunk/docs/userguide/src/main/module/overview.xml (rev 0) +++ tools/eclipse/trunk/docs/userguide/src/main/module/overview.xml 2009-11-24 23:47:13 UTC (rev 91) @@ -0,0 +1,207 @@ +<?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 CDL component of the Overlord SOA governance project aims to leverage the concept of a choreography (or conversation) + description to provide design-time and run-time governance of an SOA. + </para> + <para> + A Choreography provides the means to describe the service interactions between multiple parties from a global (or service neutral) perspective. + This means that it is possible for an organisation to define how an end-to-end business process should function, regardless of whether orchestrated + or peer-to-peer service collaboration will be used. + </para> + <para> + Although in simple situations, a BPEL process description can provide a description of the interactions between multiple services, this only works where a + single orchestrating process is in control. The benefit of the choreography description is that it can be used to provide a global view of a process across multiple + orchestrated service domains. + </para> + <para> + This document will outline how the Choreography Description is being used as part of Project Overlord to provide SOA governance capabilities + for each phase of the SOA lifecycle. + </para> + <para> + When a validated design has been approved by the users, it can be used to generate an initial skeleton of the implementation for each service. + The current version of Overlord enables a skeleton implementation to be generated as a JBossESB service configuration file, + using 'conversation aware' ESB actions. For more information on these, please see the “Conversational ESB User Guide”. + </para> + + <section> + <title>WS-CDL</title> + + <para> +WS-CDL, or Web Service Choreography Description Language, is a candidate recommendation from W3C. Although associated with W3C and Web Services, it is important to begin by stating that the Choreography Description Language (CDL) is <emphasis role="bold">not</emphasis> web service specific. + </para> + <para> +The purpose of CDL is to enable the interactions between a collection of peer to peer services to be described from a neutral (or global) perspective. This is different to other standards, such as WS-BPEL, that describe interactions from a service specific viewpoint. + </para> + <para> +In essence a choreography description declares roles which will pass messages between each other, called interactions. The interactions are ordered based on a number of structuring mechanism which enables loops, conditional, choices and parallelism to be described. In CDL variables used for messages and for conditionals are all situated at roles. There is no shared state rather there is a precise description of the state at each role and a precise description of how these roles interact in order to reach some notion of common state in which information is exchanged and processed between them. + </para> + <para> +In CDL we use interactions and these structuring mechanisms to describe the observable behaviour, the messages exchanges and the rules for those exchanges and any supporting observable state on which they depend, of a system. + </para> + </section> + + <section> + <title>pi4soa</title> + <para> +<emphasis>pi4soa</emphasis> is an open source project established to demonstrate the potential benefits that a global model (as described using CDL) can provide when building an SOA. The open source project is managed by the Pi4 Technologies Foundation, which is a collaboration between industry and academia. + </para> + <para> +Building complex distributed systems, without introducing unintended consequences, is a real challenge. Although the Choreography Description Language provides a means of describing complex systems at a higher level, and therefore help to reduce such complexity, it does not necessarily guarantee that erronous situations cannot occur due to inappropriately specified interactions. The research, being carried out by members of the Pi4 Technologies Foundation, into the global model and endpoint projection is targeted at identifying potential unintended consequences, to ensure that a global description of a system can be reliably executed and can be free from unintended consequences. + </para> + <para> +The tool suite currently offers the ability to: + </para> + <para> + <itemizedlist> + <listitem> + Define a choreography description + </listitem> + <listitem> + Export the description to a range of other formats, such as BPMN, UML activity/state/sequence models, and HTML + </listitem> + <listitem> + Define scenarios (equivalent to sequence diagrams), with example messages, which can then be simulated against an associated choreography + </listitem> + <listitem> + Generate template endpoint implementations: + <para> + <itemizedlist> + <listitem> + WS-BPEL for deployment in ActiveBPEL + </listitem> + <listitem> + Java stubs for execution with the pi4soa state machine, with deployment options for Apache Axis, J2EE (JBoss, Glassfish) and JBoss ESB + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section> + <title> SOA Lifecycle Governance </title> + + <section> + <title>Design Time Governance</title> + <para> + Design-time governance is concerned with ensuring that the resulting system correctly implements requirements (whether functional or non-functional). + A choreography description can be used to ensure that the implemented system meets the behavioural requirements. + </para> + <para> + The behavioural requirements can be captured as a collection of scenarios (e.g. sequence diagrams) with associated example messages. + This enables an unambiguous representation of the business requirements to be stored in a machine processable form, which can subsequently + be used to validate other phases of the SOA lifecycle. + </para> + <para> + Once the choreography description for the SOA has been defined, it can be validated against the scenarios, + to ensure that the choreography correctly handles all of the business requirements. + </para> + <para> + Once the service enters the implementation phase, it is important to ensure that it continues to adhere to the design + and therefore meets the business requirements. Currently this is achieved through the use of techniques such as continuous testing. + However this is only as reliable as the quality of the unit tests that have been written. + </para> + <para> + When a 'structured' implementation language has been used, such as WS-BPEL, jPDL or the new 'conversation aware' ESB actions, + it will be possible to infer the behaviour of the service being implemented, to compare it against the choreography description. + Currently this has been implemented for the “conversation aware” ESB actions, and is demonstrated using the samples in this Overlord-CDL distribution. + </para> + <para> + Detecting incorrectly implemented behaviour at the earliest possible time saves on downstream costs associated with finding and fixing errors. + By using static validation against the original design, it ensures that the implemented service will deliver its expected behaviour first time. + This is important in building large scale SOAs where different services may be implemented in different locations. + </para> + <para> + There are two other areas where a choreography description can be used as part of design-time governance, + that are not currently implemented in Overlord: + </para> + <itemizedlist> + <listitem> + Service lookup – the choreography description can be used to determine if a service already exists in the Service Repository that meets the appropriate behavioural requirements. + </listitem> + <listitem> + Service unit testing - this can be achieved using the scenarios originally specified to document the behavioural requirements. + Rather than develop an independent source of test data, the scenarios can be used to validate the sequence of messages sent to, + and received from, a service, as well as validating the contents of the messages returned from the service under test. + </listitem> + </itemizedlist> + </section> + + <section> + <title>Runtime Governance</title> + <para> + Runtime governance ensures that the SOA executes as expected according to predefined policies. In this context, a choreography description can be used in two ways. + </para> + + <section> + <title> Service validator</title> + <para> + The choreography description represents the interactions between multiple services to deliver a business goal. + To validate the behaviour of each individual service, within the choreography description, the behaviour of each service can be derived from the choreography. + </para> + <para> + The derived behaviour (or “endpoint projection”) of a service can be used within a 'service validator' to monitor the inbound and outbound messages for the service, + to ensure they conform to the expected behaviour. + If an invalid message is detected, it would be possible to block it, to prevent it from causing subsequent problems in downstream systems. + The error can also be reported to a central management capability. + </para> + <para> + The CDL component of Overlord provides the ability to configure service validators to monitor the behaviour of individual services. + An enhanced version of the JBossESB trailblazer example has been included, with the appropriate validator configuration, to demonstrate this mechanism. + </para> + </section> + + <section> + <title>Process correlation</title> + <para> + Validating each service locally can enable errors to be detected quickly, + and the effects of the error prevented from contaminating other systems by blocking the erroneous messages. + </para> + <para> + However local service specific validation may not be adequate to identify errors that would affect the end-to-end business process. + Therefore the message activity at each service validator can be reported to a central 'process correlation engine' which can reconstitute a global view of the business transaction, + and determine if it matches the expected behaviour as defined in the choreography description. + </para> + <para> + The benefit of a correlated global view of the distributed business transaction is that it can be further analysed to ensure other governance polices have been followed – e.g. SLAs. + </para> + <para> + The pi4soa tool suite includes a simple GUI based monitoring tool to display the information obtained from correlating message events associated with individual services. + The trailblazer example has been written to cause out of sequence messages under certain circumstances. See the “Samples Guide” for more information on how to run this example. + </para> + </section> + </section> + </section> + + <section> + <title> First Steps </title> + <para>The first step will be to follow the instructions in the Getting Started Guide to install Overlord. </para> + <para> Once installed, the next step should be to try out the examples in the samples folder. The examples consistent of:</para> + <itemizedlist> + <listitem> + Service Validation related examples + <para> + The samples folder contains an enhanced version of the trailblazer example from the JBossESB, with the addition of a File Based Bank, and message content including a conversation id to enable the messages to be correlated with a specific session. + </para> + </listitem> + <listitem> + Conversation aware ESB actions, with conformance checking against Choreography + <para> + Two examples have been included, one simple example (purchasing) and the other more advanced (brokerage). Both relate to the business process of purchasing items. The second example introduces the concept of a broker to act on behalf of the customer, interacting with multiple potential suppliers. + </para> + <para> + These examples show how a service implementation (built using “conversation aware ESB actions” in this case), can be continuously checked for conformance against a choreography description. + </para> + <para> + The final step should be to review all of the documents in the docs folder to understand more about each capability, and then try using the techniques on your own project. + </para> + </listitem> + </itemizedlist> + </section> +</chapter> Added: tools/eclipse/trunk/docs/userguide/src/main/xslt/pdf.xsl =================================================================== --- tools/eclipse/trunk/docs/userguide/src/main/xslt/pdf.xsl (rev 0) +++ tools/eclipse/trunk/docs/userguide/src/main/xslt/pdf.xsl 2009-11-24 23:47:13 UTC (rev 91) @@ -0,0 +1,91 @@ +<?xml version="1.0" encoding="UTF-8"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:fo="http://www.w3.org/1999/XSL/Format" + version="1.0"> + + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.72.0/fo/docbook.x... /> + <xsl:import href="classpath:/xslt/org/jboss/pdf.xsl" /> + + <!-- Override the default font settings --> + <xsl:param name="body.font.family" select="'Times New Roman, serif'" /> + <xsl:param name="monospace.font.family" select="'DejaVu Sans Mono, monospace'" /> + <xsl:param name="sans.font.family" select="'Arial, sans-serif'" /> + <xsl:param name="title.font.family" select="$body.font.family" /> + <xsl:param name="programlisting.font" select="$monospace.font.family" /> + <xsl:param name="programlisting.font.size" select="'75%'" /> + + <!-- Remove the blank pages between the chapters --> + <xsl:param name="double.sided" select="0" /> + + <!-- Use SVG for callout images instead of PNG --> + <xsl:param name="callout.graphics" select="1" /> + <xsl:param name="callout.graphics.extension" select="'.svg'" /> + + <!-- Hide URL --> + <xsl:param name="ulink.show" select="0"/> + + <!-- Don't use italic font for links --> + <xsl:attribute-set name="xref.properties"> + <xsl:attribute name="font-style">normal</xsl:attribute> + </xsl:attribute-set> + + <!-- Decrease the link font size in the program listing --> + <xsl:attribute-set name="monospace.properties"> + <xsl:attribute name="font-size">1em</xsl:attribute> + <xsl:attribute name="font-family"> + <xsl:value-of select="$monospace.font.family"/> + </xsl:attribute> + </xsl:attribute-set> + + <!-- Add some spacing between callout listing items --> + <xsl:template match="callout"> + <xsl:variable name="id"><xsl:call-template name="object.id"/></xsl:variable> + <fo:list-item id="{$id}" space-before="1em"> + <fo:list-item-label end-indent="label-end()"> + <fo:block> + <xsl:call-template name="callout.arearefs"> + <xsl:with-param name="arearefs" select="@arearefs"/> + </xsl:call-template> + </fo:block> + </fo:list-item-label> + <fo:list-item-body start-indent="body-start()"> + <fo:block padding-top="0.2em"> + <xsl:apply-templates/> + </fo:block> + </fo:list-item-body> + </fo:list-item> + </xsl:template> + + <!-- Slight baseline-shift for callouts in the program listing --> + <xsl:template name="callout-bug"> + <xsl:param name="conum" select='1'/> + <xsl:choose> + <xsl:when test="$conum &lt;= $callout.graphics.number.limit"> + <xsl:variable name="filename" + select="concat($callout.graphics.path, $conum, + $callout.graphics.extension)"/> + + <fo:external-graphic content-width="{$callout.icon.size}" + width="{$callout.icon.size}" + padding="0.0em" margin="0.0em" + baseline-shift="-0.375em"> + <xsl:attribute name="src"> + <xsl:choose> + <xsl:when test="$passivetex.extensions != 0 + or $fop.extensions != 0 + or $arbortext.extensions != 0"> + <xsl:value-of select="$filename"/> + </xsl:when> + <xsl:otherwise> + <xsl:text>url(</xsl:text> + <xsl:value-of select="$filename"/> + <xsl:text>)</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:attribute> + </fo:external-graphic> + </xsl:when> + </xsl:choose> + </xsl:template> +</xsl:stylesheet> +