[savara-commits] savara SVN: r89 - in tools/eclipse/trunk: docs and 9 other directories.

Author: objectiser Date: 2009-11-24 16:41:13 -0500 (Tue, 24 Nov 2009) New Revision: 89 Added: tools/eclipse/trunk/docs/ tools/eclipse/trunk/docs/gettingstartedguide/ tools/eclipse/trunk/docs/gettingstartedguide/pom.xml tools/eclipse/trunk/docs/gettingstartedguide/src/ tools/eclipse/trunk/docs/gettingstartedguide/src/main/ tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ChoreoMonReady.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ConformanceCheckError.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ConformanceCheckErrorMessage.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ConformanceCheckErrorMessageMenu.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/GenerateESBServicesDialog.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/GenerateESBServicesMenu.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/GenerateESBServicesNav.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportDialog.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportFileDialog.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportMenu.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportProjectsDialog.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportedProjects.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/InvalidPurchasePostTest.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/JavaCompiler1-5Compliant.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/MonitorMenu.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/PurchaseGoods.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/QuickFixDialog.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SVJBossESBAnnotation.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SVJBossESBAnnotationToolTip.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SVJBossESBEditAnnotation.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ShowReferencedDescription.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SuccessfulPurchasePostTest.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SuccessfulPurchasePreTest.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/TrailBlazerMonitorError.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/TrailblazerWebPage.jpg tools/eclipse/trunk/docs/gettingstartedguide/src/main/master.xml tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/ tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/author_group.xml tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/businessanalysis.xml tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/installation.xml tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/overview.xml tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/runtimevalidation.xml tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/serviceanalysisdesign.xml tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/servicedev.xml tools/eclipse/trunk/docs/gettingstartedguide/src/main/xslt/ tools/eclipse/trunk/docs/gettingstartedguide/src/main/xslt/pdf.xsl tools/eclipse/trunk/docs/pom.xml tools/eclipse/trunk/docs/userguide/ tools/eclipse/trunk/docs/userguide/src/ tools/eclipse/trunk/docs/userguide/src/main/ tools/eclipse/trunk/docs/userguide/src/main/images/ tools/eclipse/trunk/docs/userguide/src/main/module/ tools/eclipse/trunk/docs/userguide/src/main/xslt/ tools/eclipse/trunk/pom.xml Log: Added tool getting started guide, and template structure for user guide. Added: tools/eclipse/trunk/docs/gettingstartedguide/pom.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/pom.xml (rev 0) +++ tools/eclipse/trunk/docs/gettingstartedguide/pom.xml 2009-11-24 21:41:13 UTC (rev 89) @@ -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>gettingstartedguide</artifactId> + <packaging>jdocbook</packaging> + <name>Savara::Tools::Eclipse::Docs::GettingStartedGuide</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>GettingStartedGuide.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/gettingstartedguide/src/main/images/ChoreoMonReady.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ChoreoMonReady.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ConformanceCheckError.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ConformanceCheckError.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ConformanceCheckErrorMessage.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ConformanceCheckErrorMessage.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ConformanceCheckErrorMessageMenu.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ConformanceCheckErrorMessageMenu.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/GenerateESBServicesDialog.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/GenerateESBServicesDialog.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/GenerateESBServicesMenu.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/GenerateESBServicesMenu.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/GenerateESBServicesNav.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/GenerateESBServicesNav.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportDialog.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportDialog.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportFileDialog.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportFileDialog.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportMenu.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportMenu.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportProjectsDialog.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportProjectsDialog.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportedProjects.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ImportedProjects.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/InvalidPurchasePostTest.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/InvalidPurchasePostTest.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/JavaCompiler1-5Compliant.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/JavaCompiler1-5Compliant.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/MonitorMenu.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/MonitorMenu.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/PurchaseGoods.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/PurchaseGoods.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/QuickFixDialog.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/QuickFixDialog.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SVJBossESBAnnotation.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SVJBossESBAnnotation.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SVJBossESBAnnotationToolTip.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SVJBossESBAnnotationToolTip.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SVJBossESBEditAnnotation.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SVJBossESBEditAnnotation.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ShowReferencedDescription.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/ShowReferencedDescription.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SuccessfulPurchasePostTest.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SuccessfulPurchasePostTest.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SuccessfulPurchasePreTest.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/SuccessfulPurchasePreTest.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/TrailBlazerMonitorError.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/TrailBlazerMonitorError.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/TrailblazerWebPage.jpg =================================================================== (Binary files differ) Property changes on: tools/eclipse/trunk/docs/gettingstartedguide/src/main/images/TrailblazerWebPage.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/master.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/master.xml (rev 0) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/master.xml 2009-11-24 21:41:13 UTC (rev 89) @@ -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>Getting Started 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/installation.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/businessanalysis.xml"/> + <!-- xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/serviceanalysisdesign.xml"/ --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/servicedev.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/runtimevalidation.xml"/> +</book> Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/author_group.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/author_group.xml (rev 0) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/author_group.xml 2009-11-24 21:41:13 UTC (rev 89) @@ -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/gettingstartedguide/src/main/module/businessanalysis.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/businessanalysis.xml (rev 0) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/businessanalysis.xml 2009-11-24 21:41:13 UTC (rev 89) @@ -0,0 +1,121 @@ +<?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="businessanalysis"> + <title>Business Analysis</title> + + <para> + </para> + + <section> + <title>Defining Requirements</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 business requirements can therefore defined as a set of scenarios, each demonstrating + a specific use-case, or path through the business process being enacted. + </para> + + </section> + + <section> + <title>Creating a Global Model</title> + + <para> +The next step in the development process is to specific a Global Model to implement +the requirements described within the set of scenarios. + </para> + + <para> +The current representation used to define Global Models within SAVARA is the W3C Web Service +Choreography Description Language (WS-CDL). The pi4soa tools provide a WS-CDL (or choreography +description) editor. Although this standard is associated with web services, it does not mean +that a system specified using this standard needs to be implemented using web services. The +actual WS-CDL language is used for defining the interactions between any distributed system. + </para> + + <para> +The choreography description 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> + + </section> + + <section> + <title>Validating Requirements against Global Model</title> + + <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, the +next step may be to obtain approval to proceed to the analysis/design phase. To help support +this effort, the pi4soa tools provide the means to export the choreography description to +a range of representations (e.g. BPMN, UML or HTML documentation +<emphasis>TO BE CONFIRMED</emphasis>). + </para> + </section> + +</chapter> Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/installation.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/installation.xml (rev 0) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/installation.xml 2009-11-24 21:41:13 UTC (rev 89) @@ -0,0 +1,121 @@ +<?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="installation"> + <title>Installation</title> + + <para> + This section describes the installation procedure for the SAVARA Eclipse Tools. + </para> + + <section> + <title>Prerequisites</title> + <para> + The pre-requisites for the SAVARA Eclipse Tools are: + </para> + <orderedlist> + <listitem>Eclipse JEE (3.5 or higher) <ulink url="http://www.eclipse.org">http://www.eclipse.org</ulink></listitem> + <listitem>SAVARA Eclipse Tools (version 1.0-M1 or higher), available from <ulink url="http://www.jboss.org/savara">http://www.jboss.org/savar... + <listitem>JBoss Tools (3.1 or higher) <ulink url="http://www.jboss.org/tools">http://www.jboss.org/tools&... + available from an update site</listitem> + </orderedlist> + </section> + + <section> + <title>Installation Instructions</title> + <para> + The installation instructions for the SAVARA Eclipse Tools are: + </para> + <orderedlist> + <listitem> + Eclipse + <para> + Download the latest version of Eclipse JEE, and install in your environment. + </para> + </listitem> + + <listitem> + JBoss Tools + <para> + Start up your Eclipse environment, and go to the <emphasis>Help->Install New Software..</emphasis> + menu item. Select the appropriate update site URL from the JBoss Tools download + page, and enter it into the top text field in the dialog window, and press the + <emphasis>Add</emphasis> button. Once the contents of the update site is available, + then select the appropriate components and follow the instructions to install + them within your Eclipse environment. + </para> + </listitem> + + <listitem> + Install SAVARA Eclipse plugins + <para> + Start up your Eclipse environment, and go to the + <emphasis>Help->Install New Software..</emphasis>. Instead of entering a URL, + just press the <emphasis>Add</emphasis> button and then when the dialog + window is displayed, select the <emphasis>Local</emphasis> button. Select + the location of the local update site within the SAVARA Eclipse Tools + distribution. Again, as with the previous step, follow the instructions provided + by the Eclipse update manager to complete the installation. + </para> + </listitem> + + </orderedlist> + </section> + + <section> + <title>Importing Samples into Eclipse</title> + + <para> + Once the SAVARA Eclipse Tool distribution has been correctly installed, if you wish to try out + any of the examples then the following steps should be followed to import the relevant + projects into the previously configured Eclipse environment. + </para> + + <orderedlist> + <listitem> + <para> +Select the 'Import...' menu item, associated with the popup menu on the background of the left +panal (Navigator or Package depending on perspective being viewed). + </para> + <imageobject> + <imagedata fileref="images/ImportMenu.jpg" align="center" width="2in" /> + </imageobject> + </listitem> + <listitem> + <para> +When the import dialog appears, select the <emphasis>General->ExistingProject from Workspace</emphasis> +option and press the 'Next' button. + </para> + <imageobject> + <imagedata fileref="images/ImportDialog.jpg" align="center" width="4in" /> + </imageobject> + </listitem> + <listitem> + <para> +Ensuring that the 'Select root directory' radio button is selected, press the 'Browse' button and +navigate to the <filename>${SAVARA-Tools}/samples</filename> folder, then press 'Ok'. + </para> + <imageobject> + <imagedata fileref="images/ImportFileDialog.jpg" align="center" width="3in" /> + </imageobject> + </listitem> + <listitem> + <para> +All of the Eclipse projects contained within the <filename>samples</filename> directory structure +will be listed. Press the 'Finish' button to import them all. + </para> + <imageobject> + <imagedata fileref="images/ImportProjectsDialog.jpg" align="center" width="4in" /> + </imageobject> + <para> + Once imported, the Eclipse navigator will list the sample projects: + </para> + <imageobject> + <imagedata fileref="images/ImportedProjects.jpg" align="center" width="2in" /> + </imageobject> + </listitem> + </orderedlist> + + </section> + +</chapter> Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/overview.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/overview.xml (rev 0) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/overview.xml 2009-11-24 21:41:13 UTC (rev 89) @@ -0,0 +1,38 @@ +<?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> + This is the Getting Started Guide for the SAVARA Eclipse Tools. + </para> + + <para> + This guide starts with the installation instructions for the SAVARA Eclipse Tools. + </para> + + <para> + The remainder of the document is organised to reflect phases within the SAVARA + Methodology, and how the current tools can be used in support of that methodology. + The tools are still in development, and therefore not all phases will have tools, + and the tools in some phases will not necessarily be complete. + </para> + + <para> + As an overview, the tools currently include capabilities for: + </para> + + <itemizedlist> + <listitem>Definition of business requirements as scenarios</listitem> + <listitem>Creation of a choreography (global model) to represent the architecture for a system + that delivers the requirements</listitem> + <listitem>Generation of documentation based on the choreography</listitem> + <listitem>Generation of service implementation using WS-BPEL</listitem> + <listitem>Conformance checking a WS-BPEL service implementation against a choreography</listitem> + <listitem>Generation of service implementation using "conversation aware" ESB actions</listitem> + <listitem>Conformance checking a "conversation aware" ESB service implementation against a choreography</listitem> + <listitem>Runtime validation of an ESB service against a choreography description</listitem> + </itemizedlist> + +</chapter> Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/runtimevalidation.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/runtimevalidation.xml (rev 0) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/runtimevalidation.xml 2009-11-24 21:41:13 UTC (rev 89) @@ -0,0 +1,225 @@ +<?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="runtimevalidation"> + <title>Runtime Validation</title> + + <note> + <para> + Before you can deploy and run the runtime validation example, you will + need to install the SAVARA Validator module for JBossESB. + </para> + </note> + + <para> +Once services have been deployed, as mentioned in the previous section, we still need to be +able to verify that the services continue to conform to the choreography description. +The <emphasis>Conversation Validation</emphasis> capability within the SAVARA-Validator distribution +can be used to validate the behaviour of each service. + </para> + + <para> +In this section, we will use the Trailblazer example found in the <filename>${SAVARA-Validator}/samples/trailblazer</filename> folder and the <filename>trailblazer-models</filename> Eclipse project. + </para> + + <section> + <title>Service Validator Configuration</title> + + <para> +The JBossESB service validator configuration is defined using jbossesb specific annotations, that are associated +with the 'exchange details' components (contained within interactions), within the choreography description. + </para> + + <para> +To view the pre-configured service validator configuration defined for the Trailblazer example, edit the +<filename>TrailBlazer.cdm</filename> file, navigate to the <emphasis>Choreography Flows</emphasis> tab and then +select the <emphasis>Choreography->Edit Annotations</emphasis> menu item associated with the first 'exchange details' +component (as shown below). + </para> + + <imageobject> + <imagedata fileref="images/SVJBossESBEditAnnotation.jpg" align="center" width="3in" /> + </imageobject> + + <para> +This will display the annotation editor, with the single configured annotation called 'jbossesb'. This annotation defines +the information required for the Service Validator to monitor this specific message exchange (i.e. the JMS destination +on which the message will be passed). + </para> + + <imageobject> + <imagedata fileref="images/SVJBossESBAnnotation.jpg" align="center" width="3in" /> + </imageobject> + + <para> +Once an annotation has been defined, it will also be displayed as part of the tooltip for the associated model component, for example: + </para> + + <imageobject> + <imagedata fileref="images/SVJBossESBAnnotationTooltip.jpg" align="center" width="3in" /> + </imageobject> + + <para> +Once the jbossesb annotations have been defined for all relevant 'exchange details' components +in the choreography description, the choreography file can be copied to the +<filename>${JBossAS}/server/default/deploy/savara-validator.esb/models</filename> +folder in the JBossAS environment. The service validator configuration for the +<emphasis>trailblazer</emphasis> example has been preconfigured to be deployed as part of +the installation procedure. + </para> + + <note> + <para> +If the <filename>savara-validator.esb/validator-config.xml</filename> within the JBossAS +environment is modified, or choreography description files added, removed or updated within +the <filename>savara-validator.esb/models</filename> sub-folder, then the changes will +automatically be detected and used to re-configure the service validators without having to +restart the JBossESB server. + </para> + </note> + + </section> + + <section> + <title>Deploy the TrailBlazer Example</title> + + <para> +The first step to deploying the Trailblazer example is to configure the JBossAS environment: + </para> + + <orderedlist> + <listitem> +Update the <filename>${JBossAS}/server/default/deploy/jbossesb.sar/jbossesb-properties.xml</filename> +file, in the section entitled "transports" and specify all of the SMTP mail server settings for +your environment. + </listitem> + <listitem> +Update the <filename>trailblazer/trailblazer.properties</filename> + <para> +Update the <property>file.bank.monitored.directory</property> and <property>file.output.directory</property> properties. These are folders used by the File Based Bank, and are set to <filename>/tmp/input</filename> and <filename>/tmp/output</filename> by default. + </para> + </listitem> + <listitem> +Update the <filename>trailblazer/esb/conf/jboss-esb.xml</filename> + <para> +There is a <emphasis>fs-provider</emphasis> block, update the <property>directory</property> attribute value to be the same as the <property>file.output.directory</property> value in <filename>trailblazer.properties</filename> file. + </para> + </listitem> + <listitem> +Start the JBossAS server + </listitem> + </orderedlist> + + <para> +One the server has been started, the next step is to deploy the relevant components into the JBossAS environment. This is achieved by: + </para> + + <orderedlist> + <listitem> +From the <filename>trailblazer</filename> folder, execute the following command to deploy the example to the ESB: <emphasis role="bold">ant deploy</emphasis> + <para> +this should deploy the ESB and WAR files to your JBoss AS <filename>server/default</filename>. + </para> + </listitem> + <listitem> +From the <filename>trailblazer/banks</filename> folder, execute the command to start the JMS Bank service: <emphasis role="bold">ant runJMSBank</emphasis>. + </listitem> + <listitem> +From the <filename>trailblazer/banks</filename> folder, execute the command to start the JMS Bank service: <emphasis role="bold">ant runFileBank</emphasis>. + </listitem> + </orderedlist> + + </section> + + <section> + <title>Starting the pi4soa Monitor</title> + + <para> +The pi4soa Monitor is used to observe a correlated view of the executing business transactions. Each service validator can be configured to report activites (i.e. sent and received messages) that it validates, to enable the correlator to reconstitute a global interpretation of each transaction. + </para> + + <para> +This correlated view of each transaction can be used to understand where each transaction is within the process. It can also be used to report <emphasis>out of sequence</emphasis>, <emphasis>unexpected messages</emphasis> and more general errors in the context of the business process. + </para> + + <para> +A simple monitoring tool is currently provided with the pi4soa tools, to enable the correlated global view of the transactions to be observed. Once the Trailblazer example has been deployed to the JBossAS environment, and the server is running, then the monitoring tool can be launched from the Eclipse environment by selecting the <emphasis>Choreography->Monitor</emphasis> menu item from the popup menu associated with the <filename>TrailBlazer.cdm</filename> file. + </para> + + <imageobject> + <imagedata fileref="images/MonitorMenu.jpg" align="center" width="2in" /> + </imageobject> + + <para> +Wait for the monitor window to start, and indicate that the choreography is being monitored, +shown in the status line at the bottom of the window. + </para> + + <imageobject> + <imagedata fileref="images/ChoreoMonReady.jpg" align="center" width="4in" /> + </imageobject> + + </section> + + <section> + <title>Running the Example</title> + + <para> +To run the example, you need to start a browser and select the URL +<ulink url="http://localhost:8080/trailblazer">localhost:8080/trailblazer</ulink>. This will +show the following page, if the server has been configured correctly and the TrailBlazer +example deployed: + </para> + + <imageobject> + <imagedata fileref="images/TrailblazerWebPage.jpg" align="center" width="4in" /> + </imageobject> + + <para> +Now you can submit quotes, You will see either a loan request rejected (single email) because +the score is less than 4, or two emails (one from JMS bank and one from FileBased bank) with +valid quotes. When entering subsequent quotes, make sure that the quote reference is updated, +so that each session has a unique id. + </para> + + </section> + + <section> + <title>Detecting a Validation Error</title> + + <para> +To demonstrate the detection of validation errors, there is an alternative implementation of the +trailblazer modules that behaviour differently to the choreography that is being monitored. +Specifically, the credit score threshold used to determine whether a loan request should be +issued to the banks, is raised from 4 to 7. + </para> + + <para> +To deploy the version of the TrailBlazer example that results in validation errors, then: + </para> + + <itemizedlist> + <listitem> +From the <filename>${SAVARA-Validator}/samples/trailblazer</filename> folder, execute the +following command to deploy the example to the ESB: <emphasis role="bold">ant deploy-error-client</emphasis>. + </listitem> + </itemizedlist> + + <para> +The next step is to issue more transactions, until a credit check score occurs that is between +4 and 6 inclusive. This will result in a <emphasis>insufficientCredit</emphasis> interaction +being reported, which would be unexpected in terms of the choreography. + </para> + + <imageobject> + <imagedata fileref="images/TrailBlazerMonitorError.jpg" align="center" width="4in" /> + </imageobject> + + <para> +When errors, such as unexpected messages, are detected by the service validators and reported +to the Choreography Monitor, they are displayed in red. + </para> + + </section> + +</chapter> Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/serviceanalysisdesign.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/serviceanalysisdesign.xml (rev 0) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/serviceanalysisdesign.xml 2009-11-24 21:41:13 UTC (rev 89) @@ -0,0 +1,20 @@ +<?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="serviceanalysisdesign"> + <title>Service Oriented Analysis and Design</title> + + <para> + </para> + + <section> + <title>Service Oriented Analysis</title> + + </section> + + <section> + <title>Service Oriented Design</title> + + </section> + +</chapter> Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/servicedev.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/servicedev.xml (rev 0) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/servicedev.xml 2009-11-24 21:41:13 UTC (rev 89) @@ -0,0 +1,627 @@ +<?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="servicedev"> + <title>Service Development</title> + + <para> +Services can be developed by generating initial development artifacts, based on artifacts +created in preceding phases (e.g. global model or service contracts/designs). + </para> + + <para> +To ensure that the services continue to conform to the artifacts defined in the previous +phases, the tools perform conformance checking between the service implementation and +the existing architecture/design artifacts. This is not possible with all implementation +languages - they must provide the means to extract the communication structure for +comparison. + </para> + + <para> +The following sections explain how the generation and conformance checking can be achieved +for two implementation languages, WS-BPEL and a "conversation aware" ESB actions (a custom +extension to the JBossESB action language). + </para> + + <section> + <title>WS-BPEL</title> + + <para> +This tools include a capability to generate a service implementation, for a participant in a choreography, +using WS-BPEL. A completed version of the <emphasis>PurchasingGoods</emphasis> example can be +found in the samples directory (which can be imported into Eclipse). + </para> + + <para> +However if you wish to generate the example from scratch, the follow the instructions in this section. +More information about how to use this feature can be found in the User Guide. + </para> + + <section> + <title>Generating WS-BPEL based Services</title> + + <para> +When a choreography description has been created, it is possible to generate a BPEL Process (and associated +WSDL files and deployment descriptor) for each of the participants defined within the choreography. +To try this out, select the <emphasis>Savara->Generate->WS-BPEL</emphasis> menu item from the popup menu +associated with the <filename>PurchaseGoods.cdm</filename>. + </para> + + <imageobject> + <imagedata fileref="images/GenerateBPELMenu.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/GenerateBPELDialog.jpg" align="center" width="3in" /> + </imageobject> + + <para> +To test out this feature, uncheck the <emphasis>Buyer</emphasis> participant, leave the build system +as <emphasis>Ant</emphasis>, select the messaging system appropriate for your target environment and +press the 'Ok' button. This will create a single new project for the <emphasis>Store</emphasis> and +<emphasis>CreditAgency</emphasis> participants. + </para> + + <para> +Each project will contain a single <filename>bpel</filename> folder containing the WS-BPEL process +definition for the participant, a list of relevant WSDL files and a deployment descriptor file +for use with RiftSaw. Howeve the WS-BPEL and WSDL files are standard, so can be deployed to any +WS-BPEL 2.0 compliant engine. + </para> + + <imageobject> + <imagedata fileref="images/GenerateBPELNav.jpg" align="center" width="2in" /> + </imageobject> + + </section> + + <section> + <title>Adding implementation details to CreditAgency</title> + + <section> + <title>Deployment Descriptor</title> + + <para> + When generated, the deployment descriptor initially has the following content: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03" xmlns:ns1="http://www.jboss.org/examples/creditAgency"> + <process name="ns1:PurchaseGoodsProcess_CreditAgency"> + <active> + true + </active> + <provide partnerLink="StoreToCreditAgency"> + <service/> + </provide> + </process> +</deploy> + ]]></programlisting> + </informalexample> + + <para> +The only change necessary is to add some attributes to the <emphasis>service</emphasis> element: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <service name="ns1:CreditAgencyService" port="CreditAgencyInterfacePort"/> + ]]></programlisting> + </informalexample> + + </section> + + <section> + <title>BPEL Process Definition</title> + + <para> +The generated BPEL process for the CreditAgency participant is as follows: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<process xmlns:bpel="http://docs.oasis-open.org/wsbpel/2.0/process/executable... + xmlns:ca="http://www.jboss.org/examples/creditAgency" + xmlns:pur="http://www.jboss.org/examples/purchasing" + xmlns:sto="http://www.jboss.org/examples/store" + xmlns:tns="http://www.jboss.org/savara/examples" + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + xmlns:ns0="http://www.scribble.org/conversation" + ns0:conversationType="savara.samples.Common@CreditAgency" + name="PurchaseGoodsProcess_CreditAgency" + targetNamespace="http://www.jboss.org/examples/creditAgency" + xmlns="http://docs.oasis-open.org/wsbpel/2.0/process/executable"... + <import importType="http://schemas.xmlsoap.org/wsdl/" + location="PurchaseGoodsProcess_CreditAgency.wsdl" + namespace="http://www.jboss.org/examples/creditAgency"/> + <import importType="http://schemas.xmlsoap.org/wsdl/" + location="PurchaseGoodsProcess_Store.wsdl" + namespace="http://www.jboss.org/examples/store"/> + <import importType="http://schemas.xmlsoap.org/wsdl/" + location="CreditAgencyPartnerLinkTypes.wsdl" + namespace="http://www.jboss.org/examples/creditAgency"/> + <partnerLinks> + <partnerLink myRole="CreditAgencyService" name="StoreToCreditAgency" + partnerLinkType="ca:StoreToCreditAgencyServiceLT"/> + </partnerLinks> + <variables> + <variable messageType="ca:CreditCheckRequest" name="creditCheckRequestVar"/> + <variable messageType="ca:CreditCheckOk" name="creditCheckOkVar"/> + <variable messageType="ca:CreditCheckInvalid" name="creditCheckInvalidVar"/> + </variables> + <sequence> + <receive createInstance="yes" operation="checkCredit" + partnerLink="StoreToCreditAgency" portType="ca:CreditAgencyInterface" + variable="creditCheckRequestVar"/> + <if> + <sequence> + <reply operation="checkCredit" partnerLink="StoreToCreditAgency" + portType="ca:CreditAgencyInterface" variable="creditCheckOkVar"/> + </sequence> + <else> + <sequence> + <reply faultName="ca:CreditCheckFailed" operation="checkCredit" + partnerLink="StoreToCreditAgency" + portType="ca:CreditAgencyInterface" + variable="creditCheckInvalidVar"/> + </sequence> + </else> + </if> + </sequence> +</process> + ]]></programlisting> + </informalexample> + + <para> + There are three changes required, the first being to add a condition following + the <emphasis>if</emphasis> element: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <if> + <condition> + $creditCheckRequestVar.CreditCheckRequest/pur:amount &lt;= 500 + </condition> + .... + ]]></programlisting> + </informalexample> + + <para> + The next two changes relate to taking the information provided in the request + and constructing an appropriate normal and fault response. In this simple + example we only echo back the information received in the request, however + more complicated processing could be performed before returning either + response. + </para> + + <para> + The following XML code should be added before the normal response (i.e. + just inside the <emphasis>sequence</emphasis> element following the + condition: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <assign name="CopyPurchaseDetails"> + <copy> + <from>$creditCheckRequestVar.CreditCheckRequest</from> + <to>$creditCheckOkVar.CreditCheckOk</to> + </copy> + </assign> + ]]></programlisting> + </informalexample> + + <para> + The following XML code should be added before the fault response (i.e. + just inside the <emphasis>sequence</emphasis> element that is contained + in the <emphasis>else</emphasis> element: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <assign name="CopyPurchaseDetails"> + <copy> + <from>$creditCheckRequestVar.CreditCheckRequest</from> + <to>$creditCheckInvalidVar.CreditCheckInvalid</to> + </copy> + </assign> + ]]></programlisting> + </informalexample> + + </section> + </section> + + <section> + <title>Adding implementation details to Store</title> + + <section> + <title>Deployment Descriptor</title> + + <para> + When generated, the deployment descriptor initially has the following content: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03" xmlns:ns1="http://www.jboss.org/examples/store"> + <process name="ns1:PurchaseGoodsProcess_Store"> + <active> + true + </active> + <provide partnerLink="BuyerToStore"> + <service/> + </provide> + <invoke partnerLink="StoreToCreditAgency"> + <service/> + </invoke> + </process> +</deploy> + ]]></programlisting> + </informalexample> + + <para> + The only changes necessary are, (1) to add a namespace prefix definition, + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + xmlns:ns2="http://www.jboss.org/examples/creditAgency" + ]]></programlisting> + </informalexample> + + <para> + and (2) to add some attributes to the <emphasis>service</emphasis> element: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <provide partnerLink="BuyerToStore"> + <service name="ns1:StoreService" port="StoreInterfacePort"/> + </provide> + <invoke partnerLink="StoreToCreditAgency"> + <service name="ns2:CreditAgencyService" port="CreditAgencyInterfacePort"/> + </invoke> + ]]></programlisting> + </informalexample> + + </section> + + <section> + <title>BPEL Process Definition</title> + + <para> + The generated BPEL process for the Store participant is as follows: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<process xmlns:bpel="http://docs.oasis-open.org/wsbpel/2.0/process/executable... + xmlns:ca="http://www.jboss.org/examples/creditAgency" + xmlns:pur="http://www.jboss.org/examples/purchasing" + xmlns:sto="http://www.jboss.org/examples/store" + xmlns:tns="http://www.jboss.org/savara/examples" + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + xmlns:ns0="http://www.scribble.org/conversation" + ns0:conversationType="savara.samples.Purchasing@Store" + name="PurchaseGoodsProcess_Store" + targetNamespace="http://www.jboss.org/examples/store" + xmlns="http://docs.oasis-open.org/wsbpel/2.0/process/executable"... + <import importType="http://schemas.xmlsoap.org/wsdl/" + location="PurchaseGoodsProcess_Store.wsdl" + namespace="http://www.jboss.org/examples/store"/> + <import importType="http://schemas.xmlsoap.org/wsdl/" + location="PurchaseGoodsProcess_CreditAgency.wsdl" + namespace="http://www.jboss.org/examples/creditAgency"/> + <import importType="http://schemas.xmlsoap.org/wsdl/" + location="StorePartnerLinkTypes.wsdl" + namespace="http://www.jboss.org/examples/store"/> + <partnerLinks> + <partnerLink myRole="StoreService" name="BuyerToStore" + partnerLinkType="sto:BuyerToStoreServiceLT"/> + <partnerLink name="StoreToCreditAgency" + partnerLinkType="sto:StoreToCreditAgencyLT" + partnerRole="CreditAgencyRequester"/> + </partnerLinks> + <variables> + <variable messageType="sto:BuyRequest" name="buyRequestVar"/> + <variable messageType="ca:CreditCheckRequest" name="creditCheckRequestVar"/> + <variable messageType="ca:CreditCheckOk" name="creditCheckOkVar"/> + <variable messageType="sto:BuyConfirmed" name="buyConfirmedVar"/> + <variable messageType="sto:BuyFailed" name="buyFailedVar"/> + </variables> + <sequence> + <receive createInstance="yes" operation="buy" partnerLink="BuyerToStore" + portType="sto:StoreInterface" variable="buyRequestVar"/> + <scope> + <faultHandlers> + <catch faultMessageType="ca:CreditCheckInvalid" + faultName="ca:CreditCheckFailed" faultVariable="creditCheckInvalidVar"> + <sequence> + <reply faultName="sto:BuyFailed" operation="buy" + partnerLink="BuyerToStore" portType="sto:StoreInterface" + variable="buyFailedVar"/> + </sequence> + </catch> + </faultHandlers> + <sequence> + <invoke inputVariable="creditCheckRequestVar" operation="checkCredit" + outputVariable="creditCheckOkVar" partnerLink="StoreToCreditAgency" + portType="ca:CreditAgencyInterface"/> + <reply operation="buy" partnerLink="BuyerToStore" portType="sto:StoreInterface" + variable="buyConfirmedVar"/> + </sequence> + </scope> + </sequence> +</process> + ]]></programlisting> + </informalexample> + + <para> + There are three changes required. The first being to add an assignment + statement within the <emphasis>catch</emphasis> element's + <emphasis>sequence</emphasis> prior to the <emphasis>reply</emphasis>: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <assign name="CopyPurchaseDetails"> + <copy> + <from>$creditCheckInvalidVar.CreditCheckInvalid</from> + <to>$buyFailedVar.BuyFailed</to> + </copy> + </assign> + ]]></programlisting> + </informalexample> + + <para> + The remaining two changes relate to taking the information received in the + initial request, to construct a request to the credit agency, and then + extracting the information from the credit agency response, to return it + to the <emphasis>Store</emphasis> client. The following snippet shows + the two assignment statements either side of the <emphasis>invoke</emphasis> + statement: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <assign name="CopyPurchaseDetails"> + <copy> + <from>$buyRequestVar.BuyRequest</from> + <to>$creditCheckRequestVar.CreditCheckRequest</to> + </copy> + </assign> + <invoke inputVariable="creditCheckRequestVar" operation="checkCredit" + outputVariable="creditCheckOkVar" partnerLink="StoreToCreditAgency" + portType="ca:CreditAgencyInterface"/> + <assign name="CopyPurchaseDetails"> + <copy> + <from>$creditCheckOkVar.CreditCheckOk</from> + <to>$buyConfirmedVar.BuyConfirmed</to> + </copy> + </assign> + ]]></programlisting> + </informalexample> + + </section> + </section> + + </section> + + <section> + <title>"Conversation Aware" ESB Actions</title> + + <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 and switch. + </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 preceding artifacts (e.g. service design or choreography description). +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>SAVARA->Generate->JBossESB 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>, select the messaging system appropriate for your target environment 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>src/conf</filename> folder) and the relevant Java classes in the <filename>src/java</filename> folder. The contents of this project represents a template of the service. Before it can be executed, the ESB configuration file will need to be enhanced to include internal implementation details for the service. The contents of this generated project should be compared to the completed version in the <filename>purchasing-store</filename> project. + </para> + + <note> + <para> +When the project is generated, if errors are reported against the <filename>jboss-esb.xml</filename>, then simply double-click on the error to launch the ESB configuration file. Then make a minor change, such as adding a new line and then removing it, and save the file again (to force re-validation). This should cause the errors to be cleared. This occurs because the Eclipse tasks that validate the <filename>jboss-esb.xml</filename> file and compiling the new Java classes in the project sometimes gets confused, causing the classes not to be present when the validation rules attempt to access them. This issue is being investigated. + </para> + </note> + </section> + + <section> + <title>Conformance Checking "Conversation Aware" ESB Services</title> + + <para> +To demonstrate the conformance checking mechanism, where the behaviour of the ESB service is verifed against its responsiblities as defined within the choreography description, open the <filename>src/conf/jboss-esb.xml</filename> in the <filename>PurchaseGoodsProcess-Store</filename> generated in the previous sub-section. + </para> + + <para> +When the ESB configuration has been loaded into an editor, locate the first <emphasis>ReceiveMessageAction</emphasis> ESB action, which should have a property called <emphasis>messageType</emphasis> with a value of <emphasis>BuyRequest</emphasis>. To cause a conformance checking error, simply append an 'X' to the end of the message type value, as shown in the following screenshot: + </para> + + <imageobject> + <imagedata fileref="images/ConformanceCheckError.jpg" align="center" width="4in" /> + </imageobject> + + <para> +This results in an error message being reported: + </para> + + <imageobject> + <imagedata fileref="images/ConformanceCheckErrorMessage.jpg" align="center" width="4in" /> + </imageobject> + + <para> +To fix conformance issues, some of the error messages will provide <emphasis>Quick Fix</emphasis> solutions. These can be access using the popup menu associated with the error message: + </para> + + <imageobject> + <imagedata fileref="images/ConformanceCheckErrorMessageMenu.jpg" align="center" width="4in" /> + </imageobject> + + <para> +This will display the <emphasis>Quick Fix</emphasis> dialog listing the available resolutions. + </para> + + <imageobject> + <imagedata fileref="images/QuickFixDialog.jpg" align="center" width="4in" /> + </imageobject> + + <para> +If the <emphasis>Show Referenced Description</emphasis> resolution is selected, then it will cause the choreography description to be launched and the specific interaction to be focused. + </para> + + <imageobject> + <imagedata fileref="images/ShowReferencedDescription.jpg" align="center" width="4in" /> + </imageobject> + + <para> +If the <emphasis>Update from Referenced Description</emphasis> is selected, then the <filename>jboss-esb.xml</filename> will be automatically updated to remove the appended 'X' from the message type. + </para> + + </section> + + <section> + <title>Running "Conversation Aware" ESB Services</title> + + <note> + <para> + Before you can deploy and run the "conversation aware" ESB example, you will + need to install the SAVARA Runtime module for JBossESB. + </para> + </note> + + <para> +The purchasing example describes the interactions between a Buyer, Store and Credit Agency. +The flow for this example would be: + </para> + + <itemizedlist> + <listitem> +Buyer send a 'buy' request to Store + </listitem> + <listitem> +Store send a 'credit check' request to the Credit Agency. + </listitem> + <listitem> +If the Credit Agency returns a successful message, then the Store will send a 'BuyConfirmed' to user. + </listitem> + <listitem> +If the Credit Agency returns a failed message, then the Store will send a 'BuyFailed' to user. + </listitem> + </itemizedlist> + + <para> +To run the <emphasis>purchasing</emphasis> example, firstly ensure that the SAVARA Runtime for +JBossESB has been deployed and configured within the JBoss Application +Server/ESB environment: + </para> + + <orderedlist> + <listitem> +In a command window, go to the <filename>${SAVARA-Runtime}/samples</filename> folder and +execute <emphasis role="bold">ant deploy-purchasing</emphasis> + </listitem> + <listitem> +In a command window, go to the <filename>${SAVARA-Runtime}/samples/client</filename> folder +and execute <emphasis role="bold">ant runPurchasingClient</emphasis>, which will send a +'BuyRequest' message to the <emphasis>Store</emphasis>, +which will then perform the credit check before returning a response to the client. + </listitem> + </orderedlist> + + <para> +In this example, the conversation ESB actions will do the validation in the runtime. +As we've said, the client send the 'buyRequest' message to the store, +firstly the store service will check the received message based on its messageType attribute. +and then send another message to the <emphasis>CreditAgency</emphasis> service it goes +through its validation. +If the messageType that <emphasis>Store</emphasis> service received is not as same +as the one defined in the "conversation aware" ESB actions, it will throw out the +exception and ends its flow. + </para> + + </section> + </section> + + <section> + <title>Summary</title> + + <para> +This section has provided a brief introduction to the design-time SOA governance features +provided within the SAVARA Eclipse Tools distribution. + </para> + + <para> +The aim of these capabilities are to enable verification of an implementation, defined +using <emphasis>conversation aware</emphasis> ESB actions or BPEL, against a +choreography, which in turn has been verified against business requirements defined using +scenarios. Therefore this helps to ensure that the implemented system meets the original +business requirements. + </para> + + <para> +Being able to statically check that the implementation should send or receive messages +in the correct order is important, as it will reduce the amount of testing required +to ensure the service behaves correctly. However it does not enable the internal +implementation details to be verified, which may result in invalid decisions being +made at runtime, resulting in unexpected paths being taken. Therefore, to ensure this +situation does not occur, we also need runtime governance, which is discussed in a +later section (Runtime Validation). + </para> + + </section> + +</chapter> Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/xslt/pdf.xsl =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/xslt/pdf.xsl (rev 0) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/xslt/pdf.xsl 2009-11-24 21:41:13 UTC (rev 89) @@ -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> + Added: tools/eclipse/trunk/docs/pom.xml =================================================================== --- tools/eclipse/trunk/docs/pom.xml (rev 0) +++ tools/eclipse/trunk/docs/pom.xml 2009-11-24 21:41:13 UTC (rev 89) @@ -0,0 +1,23 @@ +<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</groupId> + <artifactId>docs</artifactId> + <packaging>pom</packaging> + <name>Savara::Tools::Eclipse::Docs</name> + + <parent> + <groupId>org.jboss.savara.tools</groupId> + <artifactId>eclipse</artifactId> + <version>1.0-SNAPSHOT</version> + </parent> + + <modules> + <!-- >module>userguide</module --> + <module>gettingstartedguide</module> + </modules> + +</project> Added: tools/eclipse/trunk/pom.xml =================================================================== --- tools/eclipse/trunk/pom.xml (rev 0) +++ tools/eclipse/trunk/pom.xml 2009-11-24 21:41:13 UTC (rev 89) @@ -0,0 +1,196 @@ +<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/maven-v4_0_0.xsd"> + <modelVersion>4.0.0</modelVersion> + <groupId>org.jboss.savara.tools</groupId> + <artifactId>eclipse</artifactId> + <version>1.0-SNAPSHOT</version> + <packaging>pom</packaging> + <name>Savara::Tools::Eclipse</name> + <url>http://www.jboss.org/savara</url> + <description> + The JBoss SAVARA Eclipse Tools. + </description> + <scm> + <connection>scm:svn:https://svn.jboss.org/repos/savara/tools/eclipse<... + </scm> + <developers> + <developer> + <name>Jeff Yu</name> + <id>jeff.yuchang</id> + <email&gt;cyu(a)redhat.com&lt;/email&gt; + <organization>Red Hat</organization> + <roles> + <role>Developer</role> + </roles> + <timezone>+8</timezone> + </developer> + <developer> + <name>Gary Brown</name> + <id>objectiser</id> + <email&gt;gbrown(a)redhat.com&lt;/email&gt; + <organization>Red Hat</organization> + <roles> + <role>Developer</role> + </roles> + <timezone>+1</timezone> + </developer> + </developers> + <modules> + <module>docs</module> + </modules> + + <build> + <!-- This section defines the default plugin settings inherited by child projects. --> + <pluginManagement> + <plugins> + <!-- Fixes how test resources of a project can be used in projects dependent on it --> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-jar-plugin</artifactId> + <version>2.2</version> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <version>2.2</version> + <configuration> + <aggregate>true</aggregate> + </configuration> + </plugin> + </plugins> + </pluginManagement> + <plugins> + <!-- Specify the compiler options and settings --> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-compiler-plugin</artifactId> + <version>2.0.2</version> + <configuration> + <source>1.5</source> + <target>1.5</target> + <showDeprecation>false</showDeprecation> + <showWarnings>false</showWarnings> + </configuration> + </plugin> + <!-- Produce source jars during the 'verify' phase --> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-source-plugin</artifactId> + <executions> + <execution> + <id>attach-sources</id> + <phase>verify</phase> + <goals> + <goal>jar</goal> + </goals> + </execution> + </executions> + </plugin> + <plugin> + <artifactId>maven-surefire-plugin</artifactId> + <configuration> + <includes> + <include>**/*TestCase.java</include> + <include>**/*Test.java</include> + </includes> + </configuration> + </plugin> + </plugins> + </build> + + <properties> + <savara-version>1.0-SNAPSHOT</savara-version> + <junit.version>4.4</junit.version> + <rosetta.version>4.5</rosetta.version> + <log4j.version>1.2.14</log4j.version> + <mvel.version>1.3.4-java1.5</mvel.version> + </properties> + + <dependencyManagement> + <dependencies> + <dependency> + <groupId>junit</groupId> + <artifactId>junit</artifactId> + <version>${junit.version}</version> + <scope>test</scope> + </dependency> + <dependency> + <groupId>org.jboss.overlord.dependencies.org.jboss.esb</groupId> + <artifactId>jbossesb-rosetta</artifactId> + <version>${rosetta.version}</version> + </dependency> + <dependency> + <groupId>log4j</groupId> + <artifactId>log4j</artifactId> + <version>${log4j.version}</version> + </dependency> + <dependency> + <groupId>org.mvel</groupId> + <artifactId>mvel</artifactId> + <version>${mvel.version}</version> + </dependency> + </dependencies> + </dependencyManagement> + + + <reporting> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-surefire-report-plugin</artifactId> + </plugin> + </plugins> + </reporting> + + <repositories> + <repository> + <id>jboss</id> + <url>http://repository.jboss.com/maven2/</url> + <snapshots> + <enabled>false</enabled> + </snapshots> + </repository> + + <repository> + <id>jboss-snapshot</id> + <url>http://snapshots.jboss.org/maven2</url> + <snapshots> + <enabled>true</enabled> + </snapshots> + </repository> + + <repository> + <id>maven.repo</id> + <name>maven repository</name> + <url>http://repo1.maven.org/maven2</url> + </repository> + + <repository> + <id>ibiblio</id> + <name>ibiblio repository</name> + <url>http://mirrors.ibiblio.org/pub/mirrors/maven2</url> + </repository> + + <repository> + <id>codehaus</id> + <name>codehaus repository</name> + <url>http://repo1.maven.org/maven2</url> + </repository> + + </repositories> + + <distributionManagement> + <repository> + <id>jboss</id> + <name>JBoss Maven Repository</name> + <url>file://${jboss.maven.repository}</url> + </repository> + <snapshotRepository> + <id>jboss-snapshots</id> + <name>JBoss Snapshot Repository</name> + <url>dav:https://snapshots.jboss.org/maven2</url> + </snapshotRepository> + </distributionManagement> + +</project>