Author: objectiser Date: 2009-12-05 08:26:44 -0500 (Sat, 05 Dec 2009) New Revision: 105 Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/architecture.xml Modified: tools/eclipse/trunk/docs/gettingstartedguide/src/main/master.xml tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/businessanalysis.xml Log: Update to structure of getting started guide. Modified: tools/eclipse/trunk/docs/gettingstartedguide/src/main/master.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/master.xml 2009-12-05 12:46:40 UTC (rev 104) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/master.xml 2009-12-05 13:26:44 UTC (rev 105) @@ -14,6 +14,7 @@ <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/architecture.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"/> Added: tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/architecture.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/architecture.xml (rev 0) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/architecture.xml 2009-12-05 13:26:44 UTC (rev 105) @@ -0,0 +1,113 @@ +<?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="architecture"> + <title>Architecture</title> + + <para> + </para> + + <section> + <title>Define Information Model</title> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<tns:BuyRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:tns="http://www.jboss.org/examples/store" + xsi:schemaLocation="http://www.jboss.org/examples/store store.xsd " + id="1" /> + ]]></programlisting> + </informalexample> + + <section> + <title>Validating Example Messages against Schema</title> + + <para> + </para> + </section> + </section> + + <section> + <title>Define Choreography Model</title> + + <para> +The next step in the development process is to specify a Choreography Model to implement +the requirements described within the set of scenarios. + </para> + + <para> +The current representation used to define Choreography 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> + <title>Validating Requirements against Choreography 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> + </section> + + <section> + <title>Create Documentation</title> + + <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> + </section> + +</chapter> Modified: tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/businessanalysis.xml =================================================================== --- tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/businessanalysis.xml 2009-12-05 12:46:40 UTC (rev 104) +++ tools/eclipse/trunk/docs/gettingstartedguide/src/main/module/businessanalysis.xml 2009-12-05 13:26:44 UTC (rev 105) @@ -6,9 +6,26 @@ <para> </para> + + <section> + <title>Define Participants</title> + + <para> + In the current Eclipse tools, that use the pi4soa Scenario and Choreography based + models for defining requirements and architectural models, this phase would be + achieved by defining the Participants and Roles within the choreography model. + </para> + + <para> + Only these components need to be specified in the choreography model. This enables + them to be referenced in the subsequently defined scenarios. Otherwise it would be + necessary to return to the scenarios, once the choreography model had been defined + in the <emphasis>Architecture</emphasis> phase. + </para> + </section> <section> - <title>Defining Requirements</title> + <title>Outline Scenarios</title> <para> When designing a system, it is necessary to capture requirements. Various approaches can be @@ -39,83 +56,41 @@ </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> + <title>Create Example Messages</title> <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. + The next step is to create the example messages required by the scenarios. </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: + Some previously defined examples can be found in the <filename>process-models</filename> + Eclipse project. For example, the Buy request is defined as: </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<tns:BuyRequest xmlns:tns="http://www.jboss.org/examples/store" + id="1" /> + ]]></programlisting> + </informalexample> - <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. + Although a schema may not have been defined at this stage, unless one previously + existed that is being reused, it is a good idea to define a namespace for the + message type. This is because it will be used within the scenarios and + architectural models defined in the following stage. If the namespace was not + specified at this stage, then the example messages, scenarios and architectural + models would need to be updated at a later stage. </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. + Although this phase has been defined following the definition of the scenarios, + in practice these phases are iterative. So scenarios and example messages would be + defined concurrently. Similarly, new participants may be added in an evolutionary + manner, as scenarios are created that require them. </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>