[savara-commits] savara SVN: r93 - runtime/trunk/docs/samplesguide/src/main and 3 other directories.

Author: objectiser Date: 2009-11-26 16:24:56 -0500 (Thu, 26 Nov 2009) New Revision: 93 Added: validator/trunk/docs/samplesguide/src/main/module/servicevalidator.xml Removed: runtime/trunk/docs/userguide/ validator/trunk/docs/samplesguide/src/main/module/cdlvalidator.xml Modified: runtime/trunk/docs/pom.xml runtime/trunk/docs/samplesguide/src/main/master.xml runtime/trunk/docs/samplesguide/src/main/module/convawareesb.xml runtime/trunk/docs/samplesguide/src/main/module/overview.xml validator/trunk/docs/samplesguide/src/main/master.xml validator/trunk/docs/samplesguide/src/main/module/overview.xml Log: Further updates to convert from Overlord CDL based to SAVARA docs. Modified: runtime/trunk/docs/pom.xml =================================================================== --- runtime/trunk/docs/pom.xml 2009-11-25 22:14:32 UTC (rev 92) +++ runtime/trunk/docs/pom.xml 2009-11-26 21:24:56 UTC (rev 93) @@ -16,7 +16,6 @@ </parent> <modules> - <module>userguide</module> <module>samplesguide</module> </modules> Modified: runtime/trunk/docs/samplesguide/src/main/master.xml =================================================================== --- runtime/trunk/docs/samplesguide/src/main/master.xml 2009-11-25 22:14:32 UTC (rev 92) +++ runtime/trunk/docs/samplesguide/src/main/master.xml 2009-11-26 21:24:56 UTC (rev 93) @@ -5,7 +5,7 @@ <book lang="en"> <bookinfo> - <title>JBoss Savara 1.0-SNAPSHOT</title> + <title>SAVARA Runtime 1.0-SNAPSHOT</title> <subtitle>Samples Guide</subtitle> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/author_group.xml"/> </bookinfo> Modified: runtime/trunk/docs/samplesguide/src/main/module/convawareesb.xml =================================================================== --- runtime/trunk/docs/samplesguide/src/main/module/convawareesb.xml 2009-11-25 22:14:32 UTC (rev 92) +++ runtime/trunk/docs/samplesguide/src/main/module/convawareesb.xml 2009-11-26 21:24:56 UTC (rev 93) @@ -5,16 +5,25 @@ <title>"Conversation Aware" ESB Services</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. +There are two examples to demonstrate the <emphasis>conversation aware</emphasis> ESB actions. </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>). +These are <filename>purchasing</filename>, a simple customer/supplier example with two associated +Eclipse projects (<filename>purchasing-store</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</filename>, +<filename>brokerage-supplier</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. +These examples make use of a common <emphasis>Credit Agency</emphasis> service, defined within +the <filename>common-creditAgency</filename> Eclipse project, and are executed through the use +of client applications defined in the <filename>${SAVARA-Runtime}/samples/client</filename> folder. </para> <warning> + JEFF - DOES THIS STILL APPLY??? 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> @@ -24,7 +33,8 @@ <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: +The purchasing example describes the interactions between a Buyer, Store and Credit Agency. +The flow for this example would be: </para> <itemizedlist> <listitem> @@ -42,18 +52,24 @@ </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. +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>SAVARA Eclipse Tools User Guide</emphasis>. </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> +Double click on <filename>purchasing-store/src/main/resources/META-INF/jboss-esb.xml</filename> </listitem> <listitem> -Scroll down to the second action, within the first service. This represents a <emphasis>ReceiveMessageAction</emphasis> and has a property defining the message type to be received. +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. @@ -63,35 +79,47 @@ </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. +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'. +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>. + In a command window, Go to the the <filename>${SAVARA-Runtime}/samples</filename> folder, + 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. + 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 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. +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> + <para>You can undeploy the corresponding esb artifact by through command + <command>ant undeploy-purchasing</command> in the <filename>${SAVARA-Runtime}/samples</filename> + folder.</para> </tip> </section> @@ -105,7 +133,8 @@ <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: +The brokerage example describes the interactions between a Customer, Broker, Supplier and Credit Agency. +The flow for this example would be: </para> <itemizedlist> @@ -116,7 +145,8 @@ 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 +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: @@ -133,7 +163,8 @@ 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 +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 @@ -142,17 +173,22 @@ <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. +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>SAVARA Eclipse Tools User Guide</emphasis>. </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> +Double click on <filename>brokerage-broker/src/main/resources/META-INF/jboss-esb.xml</filename> </listitem> <listitem> -Scroll down to the second action, within the first service. This represents a <emphasis>ReceiveMessageAction</emphasis> and has a property defining the message type to be received. +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. @@ -162,28 +198,35 @@ </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. +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> + In a command window, Go to the <filename>${SAVARA-Runtime}/samples</filename> folder, + 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. + Go to the <filename>${SAVARA-Runtime}/samples/client</filename> folder and execute + <emphasis role="bold">ant runBrokerageClient</emphasis>, which will initially send an + 'enquiry' message to the Broker, which will communicate with the set of Suppliers to + obtain the best quote. The client will then send a 'buy' request, which will result in + the Broker performing a credit check before returning a response to the client. </listitem> </orderedlist> <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> + <para>You can undeploy the corresponding esb artifact by through command + <command>ant undeploy-broker</command> in ${SAVARA-Runtime}/samples.</para> </tip> </section> Modified: runtime/trunk/docs/samplesguide/src/main/module/overview.xml =================================================================== --- runtime/trunk/docs/samplesguide/src/main/module/overview.xml 2009-11-25 22:14:32 UTC (rev 92) +++ runtime/trunk/docs/samplesguide/src/main/module/overview.xml 2009-11-26 21:24:56 UTC (rev 93) @@ -3,27 +3,24 @@ ]> <chapter id="overview"> <title>Overview</title> - <para>The Overlord CDL distribution contains two main types of functionality:</para> - <orderedlist> - <listitem> - the ability to validate executing services against a choreography description (an example of runtime governance). - </listitem> - <listitem> - the ability to build an ESB using 'conversation aware' actions which can be checked for conformance against a choreography description (an example of design time governance). - </listitem> - </orderedlist> <para> - This document will describe the samples available to demonstrate each aspect of the functionality. + This document will describe the samples available to demonstrate the runtime capabilities using + the "conversation aware" ESB actions. </para> <para> - Further information about configuring the runtime validation of services against a choreography can be found in the <emphasis role="bold">UserGuide</emphasis>. - Information regarding the conversation aware ESB actions, and how to use them in conjunction with conformance checking against a choreography description, can also be found in the <emphasis role="bold">UserGuide</emphasis>. + Information regarding the conversation aware ESB actions, and how to use them in conjunction with + conformance checking against a choreography description, can also be found in the + <emphasis role="bold">SAVARA Eclipse Tools User Guide</emphasis>. </para> <note> <para> - Before attempting to install and run these examples, you must follow the instructions in the <emphasis role="bold">"Installation" Chapter</emphasis> of the <emphasis role="bold">Getting Started Guide</emphasis> regarding installing Overlord CDL into a JBossAS environment, and importing the samples into the Eclipse environment. + Before attempting to deploy and run these examples, you must install the SAVARA Runtime + by following the instructions + in the <filename>${SAVARA-Runtime}/install</filename> folder. To be able to + examine and modify the examples, it is advisable to install the SAVARA Eclipse Tools, + and import the samples into the Eclipse environment. </para> </note> Modified: validator/trunk/docs/samplesguide/src/main/master.xml =================================================================== --- validator/trunk/docs/samplesguide/src/main/master.xml 2009-11-25 22:14:32 UTC (rev 92) +++ validator/trunk/docs/samplesguide/src/main/master.xml 2009-11-26 21:24:56 UTC (rev 93) @@ -12,6 +12,6 @@ <toc/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/overview.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/cdlvalidator.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/servicevalidator.xml"/> </book> Deleted: validator/trunk/docs/samplesguide/src/main/module/cdlvalidator.xml =================================================================== --- validator/trunk/docs/samplesguide/src/main/module/cdlvalidator.xml 2009-11-25 22:14:32 UTC (rev 92) +++ validator/trunk/docs/samplesguide/src/main/module/cdlvalidator.xml 2009-11-26 21:24:56 UTC (rev 93) @@ -1,132 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> -<chapter id="cdlvalidator"> - <title>CDL Validator</title> - - <section> - <title>Trailblazer Example</title> - - <para> -This example can be found in the <filename>trailblazer</filename> folder, which contains an enhanced version of the trailblazer example found in the JBossESB distribution. See the TrailBlazer Guide in the JBossESB distribution (<filename>$JBossESB/docs/samples/TBGuide.pdf</filename>) for more information about the example. The main changes are the introduction of a File Based Bank, and modifications to the message structures to enable a consistent conversation id to be carried with the messages. - </para> - -<note> - <para> -The choreography description for the Trailblazer example can be found in the <emphasis>trailblazer-models</emphasis> project in the Eclipse environment. If the project has not yet been imported, then please refer to the instructions in the <emphasis>Getting Started Guide</emphasis>. - </para> - <para> -You can open the choreography for the trailblazer (trailblazer.cdm) and also a scenario representing a valid transaction associated with the choreography (LoanRequest.scn). In the choreography description editor, view the "Choreography Flows" tab to see the structure of the process. - </para> - <para> -To simulate the scenario against the choreography, to ensure that the choreography correctly caters for the valid business scenario, the user should press the green 'play' button in the toolbar, associated with the Scenario Editor. - </para> -</note> - - - <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. If the selected folders do not exist, then please ensure they are created prior to running the example. - </para> - </listitem> - <listitem> -Update the <filename>trailblazer/esb/conf/jboss-esb.xml</filename> - <para> -There is a <emphasis>fs-provider</emphasis> block, update the <property>directory</property> attribute value to be the same as the <property>file.output.directory</property> value in <filename>trailblazer.properties</filename> file. - </para> - </listitem> - <listitem> -Start the JBossAS server - </listitem> - <listitem> -From the <filename>trailblazer</filename> folder, execute the command to start the ESB: <emphasis role="bold">ant deploy</emphasis> - <para> -this should deploy the ESB and WAR files to your JBoss AS <filename>server/default</filename>. - </para> - </listitem> - <listitem> -From the <filename>trailblazer/banks</filename> folder, execute the command to start the JMS Bank service: <emphasis role="bold">ant runJMSBank</emphasis>. - </listitem> - <listitem> -From the <filename>trailblazer/banks</filename> folder, execute the command to start the JMS Bank service: <emphasis role="bold">ant runFileBank</emphasis>. - </listitem> - <listitem> - <para> -In the Eclipse environment, select the popup menu associated with the <filename>trailblazer.cdm</filename> file, and choose the <emphasis>Choreography->Monitor</emphasis> menu item. - </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> - - </listitem> - <listitem> - <para> -Start a browser and enter the URL: <ulink url="http://localhost:8080/trailblazer">localhost:8080/trailblazer</ulink>. - </para> - - <imageobject> - <imagedata fileref="images/TrailblazerWebPage.jpg" align="center" width="4in" /> - </imageobject> - - </listitem> - <listitem> -Now you can submit quotes, You will see either a loan request rejected (single email) because the score is less than 4, or two emails (one from JMS bank and one from FileBased bank) with valid quotes. When entering subsequent quotes, make sure that the quote reference is updated, so that each session has a unique id. - </listitem> - </orderedlist> - <para> -To demonstrate what occurs when the implementation deviates from the expected behaviour as defined in the choreography description, try the following steps: - </para> - <orderedlist> - <listitem> - Run the ant task <emphasis role="bold">ant deploy-error-client</emphasis> to redeploy the trailblaizer example. - </listitem> - <listitem> - Run the commands from step 6 above. - </listitem> - </orderedlist> - <para> - The above steps show how changing the service implementation without updating a choreography can result in behavioural validation errors being detected. - </para> - <tip> - <title>What is changed when we run ant deploy-error-client</title> - <para> - Compared to command of <emphasis role="bold">ant deploy</emphasis>, basically, we have just updated the following code in - <emphasis role="bold">$Overlord/samples/trailblazer/client/src/org/jboss/soa/esb/samples/trailblazer/loanbroker/LoanBroker.java</emphasis> file. - </para> - <para> - In the following code within the <emphasis role="bold">processLoanRequest</emphasis> method, we've changed the "4" to "7" - -<programlisting> - //step 2 - check if score is acceptable - if (score >= 4) { -</programlisting> - </para> - </tip> - - <para> - Issue further loan requests, remembering to change the quote reference each time, until a Credit Check result of between 4 and 6 inclusive occurs, which will result in an out of sequence message being reported (in red) to the Choreography Monitor - - <note> - <para> - It is currently a requirement that the choreography used within the Choreography Monitor is the same as the description used to locally monitor the services (i.e. within the overlord-cdl-validator.esb/models directory). - </para> - </note> - </para> - - </section> - -</chapter> Modified: validator/trunk/docs/samplesguide/src/main/module/overview.xml =================================================================== --- validator/trunk/docs/samplesguide/src/main/module/overview.xml 2009-11-25 22:14:32 UTC (rev 92) +++ validator/trunk/docs/samplesguide/src/main/module/overview.xml 2009-11-26 21:24:56 UTC (rev 93) @@ -3,27 +3,22 @@ ]> <chapter id="overview"> <title>Overview</title> - <para>The Overlord CDL distribution contains two main types of functionality:</para> - <orderedlist> - <listitem> - the ability to validate executing services against a choreography description (an example of runtime governance). - </listitem> - <listitem> - the ability to build an ESB using 'conversation aware' actions which can be checked for conformance against a choreography description (an example of design time governance). - </listitem> - </orderedlist> - + <para>The SAVARA Validator component provides the ability to validate executing services + against a choreography description, demonstrating a form runtime governance. + </para> + <para> - This document will describe the samples available to demonstrate each aspect of the functionality. + Further information about configuring the runtime validation of services against a choreography + can be found in the <emphasis role="bold">SAVARA Validator User Guide</emphasis> and the + <emphasis role="bold">SAVARA Eclipse Tools User Guide</emphasis>. </para> - <para> - Further information about configuring the runtime validation of services against a choreography can be found in the <emphasis role="bold">UserGuide</emphasis>. - Information regarding the conversation aware ESB actions, and how to use them in conjunction with conformance checking against a choreography description, can also be found in the <emphasis role="bold">UserGuide</emphasis>. - </para> <note> <para> - Before attempting to install and run these examples, you must follow the instructions in the <emphasis role="bold">"Installation" Chapter</emphasis> of the <emphasis role="bold">Getting Started Guide</emphasis> regarding installing Overlord CDL into a JBossAS environment, and importing the samples into the Eclipse environment. + Before attempting to deploy and run these examples, you must follow the instructions + in the <filename>${SAVARA-Validator}/install</filename> folder. To be able to + examine and modify the examples, it is advisable to install the SAVARA Eclipse Tools, + and import the samples into the Eclipse environment. </para> </note> Copied: validator/trunk/docs/samplesguide/src/main/module/servicevalidator.xml (from rev 92, validator/trunk/docs/samplesguide/src/main/module/cdlvalidator.xml) =================================================================== --- validator/trunk/docs/samplesguide/src/main/module/servicevalidator.xml (rev 0) +++ validator/trunk/docs/samplesguide/src/main/module/servicevalidator.xml 2009-11-26 21:24:56 UTC (rev 93) @@ -0,0 +1,171 @@ +<?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="servicevalidator"> + <title>Service Validator</title> + + <section> + <title>Trailblazer Example</title> + + <para> +This example can be found in the <filename>trailblazer</filename> folder. See the TrailBlazer Guide +(<filename>${SAVARA-Validator}/docs/samples/TBGuide.pdf</filename>) for more information about the example. + </para> + +<note> + <para> +The choreography description for the Trailblazer example can be found in the +<emphasis>trailblazer-models</emphasis> project in the Eclipse environment. If the project has +not yet been imported, then please refer to the instructions in the +<emphasis>SAVARA Eclipse Tools Getting Started Guide</emphasis>. + </para> + <para> +You can open the choreography for the trailblazer (trailblazer.cdm) and also a scenario representing +a valid transaction associated with the choreography (LoanRequest.scn). In the choreography description +editor, view the "Choreography Flows" tab to see the structure of the process. + </para> + <para> +To simulate the scenario against the choreography, to ensure that the choreography correctly caters +for the valid business scenario, the user should press the green 'play' button in the toolbar, associated +with the Scenario Editor. + </para> +</note> + + + <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. +If the selected folders do not exist, then please ensure they are created prior to running the example. + </para> + </listitem> + <listitem> +Update the <filename>trailblazer/esb/conf/jboss-esb.xml</filename> + <para> +There is a <emphasis>fs-provider</emphasis> block, update the <property>directory</property> +attribute value to be the same as the <property>file.output.directory</property> value in +<filename>trailblazer.properties</filename> file. + </para> + </listitem> + <listitem> +Start the JBossAS server + </listitem> + <listitem> +From the <filename>trailblazer</filename> folder, execute the command to start the ESB: +<emphasis role="bold">ant deploy</emphasis> + <para> +this should deploy the ESB and WAR files to your JBoss AS <filename>server/default</filename>. + </para> + </listitem> + <listitem> +From the <filename>trailblazer/banks</filename> folder, execute the command to start the JMS +Bank service: <emphasis role="bold">ant runJMSBank</emphasis>. + </listitem> + <listitem> +From the <filename>trailblazer/banks</filename> folder, execute the command to start the File based +Bank service: <emphasis role="bold">ant runFileBank</emphasis>. + </listitem> + <listitem> + <para> +In the Eclipse environment, select the popup menu associated with the <filename>trailblazer.cdm</filename> +file, and choose the <emphasis>Choreography->Monitor</emphasis> menu item. + </para> + +<note> +<para> +TO BE UPDATED WITH JOPR APPROACH +</para> +</note> + <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> + + </listitem> + <listitem> + <para> +Start a browser and enter the URL: +<ulink url="http://localhost:8080/trailblazer">localhost:8080/trailblazer</ulink>. + </para> + + <imageobject> + <imagedata fileref="images/TrailblazerWebPage.jpg" align="center" width="4in" /> + </imageobject> + + </listitem> + <listitem> +Now you can submit quotes, You will see either a loan request rejected (single email) because the +score is less than 4, or two emails (one from JMS bank and one from FileBased bank) with valid quotes. +When entering subsequent quotes, make sure that the quote reference is updated, so that each session +has a unique id. + </listitem> + </orderedlist> + <para> +To demonstrate what occurs when the implementation deviates from the expected behaviour as defined +in the choreography description, try the following steps: + </para> + <orderedlist> + <listitem> + Run the ant task <emphasis role="bold">ant deploy-error-client</emphasis> to redeploy the + trailblaizer example. + </listitem> + <listitem> + Run the commands from step 6 above. + </listitem> + </orderedlist> + <para> + The above steps show how changing the service implementation without updating a choreography + can result in behavioural validation errors being detected. + </para> + <tip> + <title>What is changed when we run ant deploy-error-client</title> + <para> + Compared to command of <emphasis role="bold">ant deploy</emphasis>, basically, we have + just updated the following code in + <emphasis role="bold">${SAVARA-Validator}/samples/trailblazer/client/src/org/jboss/soa/esb/samples/trailblazer/loanbroker/LoanBroker.java</emphasis> file. + </para> + <para> + In the following code within the <emphasis role="bold">processLoanRequest</emphasis> + method, we've changed the "4" to "7" + +<programlisting> + //step 2 - check if score is acceptable + if (score >= 4) { +</programlisting> + </para> + </tip> + + <para> + TO BE UPDATED WITH JOPR APPROACH: + Issue further loan requests, remembering to change the quote reference each time, until a Credit + Check result of between 4 and 6 inclusive occurs, which will result in an out of sequence message + being reported (in red) to the Choreography Monitor + + <note> + <para> + It is currently a requirement that the choreography used within the Choreography Monitor is + the same as the description used to locally monitor the services + (i.e. within the savara-validator-jbossesb.esb/models directory). + </para> + </note> + </para> + + </section> + +</chapter>