Author: objectiser Date: 2010-09-30 15:57:46 -0400 (Thu, 30 Sep 2010) New Revision: 427 Added: trunk/docs/gettingstartedguide/src/main/en-US/module/tap.xml Modified: trunk/docs/gettingstartedguide/src/main/en-US/master.xml trunk/docs/gettingstartedguide/src/main/en-US/module/installation.xml trunk/docs/gettingstartedguide/src/main/en-US/module/runtimevalidation.xml trunk/docs/gettingstartedguide/src/main/en-US/module/servicedev.xml Log: Updates to getting started guide to discuss BPEL runtime validation, update installation instructions and TAP. Modified: trunk/docs/gettingstartedguide/src/main/en-US/master.xml =================================================================== --- trunk/docs/gettingstartedguide/src/main/en-US/master.xml 2010-09-30 17:25:15 UTC (rev 426) +++ trunk/docs/gettingstartedguide/src/main/en-US/master.xml 2010-09-30 19:57:46 UTC (rev 427) @@ -17,5 +17,6 @@ <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/tap.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/runtimevalidation.xml"/> </book> Modified: trunk/docs/gettingstartedguide/src/main/en-US/module/installation.xml =================================================================== --- trunk/docs/gettingstartedguide/src/main/en-US/module/installation.xml 2010-09-30 17:25:15 UTC (rev 426) +++ trunk/docs/gettingstartedguide/src/main/en-US/module/installation.xml 2010-09-30 19:57:46 UTC (rev 427) @@ -14,19 +14,18 @@ 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 (version 1.0.0.CR2 or higher), available from <ulink url="http://www.jboss.org/savara/downloads">http://www.jboss... - <listitem>JBoss Tools (3.1 or higher) <ulink url="http://www.jboss.org/tools">http://www.jboss.org/tools&... + <listitem>Eclipse JEE (3.6 or higher) <ulink url="http://www.eclipse.org">http://www.eclipse.org</ulink></listitem> + <listitem>JBoss Tools (3.2 or higher) <ulink url="http://www.jboss.org/tools">http://www.jboss.org/tools&... available from an update site</listitem> </orderedlist> <para> - The pre-requisites for the SAVARA Service Validator (for JBossESB) are: + The pre-requisites for the SAVARA Service Validator are: </para> <orderedlist> <listitem>JBossAS (5.1.0.GA or higher) <ulink url="http://www.jboss.org/jbossas">http://www.jboss.org/jbos... <listitem>JBossAS (4.8 or higher) <ulink url="http://www.jboss.org/jbossesb">http://www.jboss.org/jbo... - <listitem>SAVARA (version 1.0.0.CR2 or higher), available from <ulink url="http://www.jboss.org/savara/downloads">http://www.jboss... + <listitem>SAVARA (version 1.1.0 or higher), available from <ulink url="http://www.jboss.org/savara/downloads">http://www.jboss... </orderedlist> </section> @@ -48,7 +47,7 @@ <para> When Eclipse has been lauched, go to the <emphasis>Help->Install New Software..</emphasis> menu item. Select the Eclipse update site - for the version of Eclipse (e.g. Galileo or Helios). Within the SOA Development + for the version of Eclipse (e.g. Helios). Within the SOA Development category, select the BPMN Project Feature. Follow the instructions to accept the license and then restart Eclipse after the plugins have been installed. @@ -65,34 +64,33 @@ them within your Eclipse environment. </para> <para> - The <emphasis>pi4soa core</emphasis> feature should be selected from the - <emphasis>All JBoss Tools</emphasis> category. + The <emphasis>JBoss Savara Tools</emphasis> feature should be selected from the + <emphasis>SOA Development</emphasis> category. </para> <para> If you wish to view the generated BPEL using a BPEL editor, rather than XML, then you should also select the <emphasis>JBoss BPEL Editor</emphasis> from the - <emphasis>All JBoss Tools</emphasis> category. + <emphasis>SOA Development</emphasis> category. </para> <para> NOTE: If you don't install the BPEL Editor, then you will have to install - GMF. This can be found on the Galileo/Helios update site, under the <emphasis>Modeling</emphasis> + GMF. This can be found on the Helios update site, under the <emphasis>Modeling</emphasis> category. Select the <emphasis>Graphical Modeling Framework</emphasis> entry, and following the instructions to install. </para> + + <para> + It is also recommended that you install the JBoss WebServices Tools, and JBossAS Tools, + from the All category. These are required to define and launch a JBossAS + server from within Eclipse, generate a JAX-WS web service from a WSDL definition, + and test a Web Service. + </para> </listitem> - - <listitem> - Install SAVARA Eclipse plugins - <para> - The Eclipse plugins for SAVARA are installed via an update site referenced - on the SAVARA <ulink url="http://www.jboss.org/savara/downloads">download page</ulink>. - </para> - </listitem> </orderedlist> <para> - The installation instructions for the SAVARA Service Validator (for JBossESB) are: + The installation instructions for the SAVARA Service Validator are: </para> <orderedlist> <listitem> Modified: trunk/docs/gettingstartedguide/src/main/en-US/module/runtimevalidation.xml =================================================================== --- trunk/docs/gettingstartedguide/src/main/en-US/module/runtimevalidation.xml 2010-09-30 17:25:15 UTC (rev 426) +++ trunk/docs/gettingstartedguide/src/main/en-US/module/runtimevalidation.xml 2010-09-30 19:57:46 UTC (rev 427) @@ -12,15 +12,34 @@ </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 previous sections have provided a brief introduction to the design-time + SOA governance features provided within the SAVARA Eclipse Tools distribution. + The aim of these capabilities are to enable verification of an implementation, initially + defined just using BPEL process definitions, 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. + </para> + + <para> + Therefore, to ensure this situation does not occur, we also need runtime governance. + We still need to be able to verify that the services continue to conform to the + choreography description. The <emphasis>Service Validator</emphasis> capability within the SAVARA distribution can be used to validate the behaviour of each service. </para> <para> In this section, we will use the <emphasis>purchasing</emphasis> example found in the - <filename>${SAVARA}/samples/purchasing]</filename> folder. + <filename>${SAVARA}/samples/purchasing</filename> folder. </para> <section> @@ -125,6 +144,83 @@ </section> <section> + <title>Web Service / WS-BPEL Example - Purchasing</title> + + <note> + <para> + Savara now includes the ability to validate web services (and therefore BPEL + processes) that use the jbossws-native stack. However the ODE engine, used + to execute BPEL processes within RiftSaw, currently optimises communications + between BPEL processes executing within the same engine, so that the communications + do not occur using the Web Service stack. This means that Savara is currently + unable to validate these interactions. Therefore it is currently recommended to + implement the 'Credit Agency' participant as a JAX-WS service. More information + on this will be available on the Savara blog. + </para> + </note> + + <section> + <title>Deploying the Example</title> + + <para> + The first step is to deploy the BPEL processes for the Store and CreditAgency + participants to a JBossAS server running RiftSaw. This can be achieved + using the Eclipse Web Tooling Project (WTP) server support, in conjunction with + the JBoss Tools features mentioned in the installation section. + </para> + + <para> + Create a JBossAS server, configured to point to a JBossAS environment that has + previously been configured to run RiftSaw. Select the server in the + <emphasis>Servers</emphasis> view, and then select the <emphasis>Add and Remove ...</emphasis> + menu item. This will show a dialog window that will include the CreditAgency + and Store BPEL projects on the left. Select both projects, and press the + <emphasis>Add</emphasis> button. When the <emphasis>Finish</emphasis> button + is selected, the BPEL processes will be associated with the server. + </para> + </section> + + <section> + <title>Running the Example</title> + + <para> + Start the server using the <emphasis>Start</emphasis> menu item associated with + the JBossAS server in the <emphasis>Servers</emphasis> view. Once the server + has fully started, the BPEL processes should have been deployed. + </para> + + <para> + The next step is to start the <emphasis>Savara->Monitor</emphasis> associated + with the <filename>PurchaseGoods.cdm</filename> choreography description. + </para> + + <para> + The final step is to send a test message to the <emphasis>Store</emphasis> + BPEL process. This can be achieved by selecting the <filename>PurchaseGoodsProcess_Store.wsdl</filename> + file, within the <emphasis>PurchaseGoodsProcess_Store</emphasis> project (bpelContents + folder), and then select the menu item <emphasis>Web Services->Test with Web Services Explorer</emphasis>. + </para> + + <para> + Expand the 'StoreInterfaceBinding' node, in the left hand panel of the explorer, + and select the 'buy' operation. Then select the 'Source' link, which will show the + various sections of the SOAP message to be sent. Edit the message body to be: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <q0:BuyRequest id="1" amount="200" /> + ]]></programlisting> + </informalexample> + + <para> + Then press the 'Ok' button further down the panel. This will send the message to the + Store process, and eventually cause a response to appear in the lower panel. + </para> + </section> + </section> + + <section> <title>JBossESB Example - Trailblazer</title> <section> Modified: trunk/docs/gettingstartedguide/src/main/en-US/module/servicedev.xml =================================================================== --- trunk/docs/gettingstartedguide/src/main/en-US/module/servicedev.xml 2010-09-30 17:25:15 UTC (rev 426) +++ trunk/docs/gettingstartedguide/src/main/en-US/module/servicedev.xml 2010-09-30 19:57:46 UTC (rev 427) @@ -104,33 +104,4 @@ </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, initially -defined just using BPEL process definitions, 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: trunk/docs/gettingstartedguide/src/main/en-US/module/tap.xml =================================================================== --- trunk/docs/gettingstartedguide/src/main/en-US/module/tap.xml (rev 0) +++ trunk/docs/gettingstartedguide/src/main/en-US/module/tap.xml 2010-09-30 19:57:46 UTC (rev 427) @@ -0,0 +1,151 @@ +<?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="tap"> + <title>Testable Architecture Project</title> + + <para> + The previous sections have discussed the various phases of the software development + lifecycle, and the artifacts that can be created. They have also outlined some + validation performed between the scenarios and choreography, when a specific link + has been established from the scenario. + </para> + + <para> + However the aim of the "Testable Architecture" methodology is to provide validation + between all artifacts, to ensure that artifacts defined at any particular phase + can be shown to be valid against the artifacts in preceding phases. + </para> + + <para> + Therefore the concept of a "Testable Architecture Project" or TAP has been introduced. + This is essentially a file that records information about the artifacts defined in + each phase of the software development lifecycle, and the relationships between them. + This file can then be validated to ensure that each artifact, and its dependencies, + are valid in respect of each other. + </para> + + <para> + For example, the <filename>purchasing</filename> example contains a TAP file with + the following contents: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<project xmlns="http://www.savara.org/ta/project" xmlns:xsi="http://www.w3.org/2001/XMLSchema" + xsi:schemaLocation="http://www.savara.org/ta/project tap.xsd" + name="Purchasing" version="1.0.0"> + + <phase name="requirements"> + <resource id="SuccessfulPurchase.scn"> + <uri type="eclipse" context="purchasing" locator="/SuccessfulPurchase.scn" /> + </resource> + <resource id="InvalidPurchase.scn"> + <uri type="eclipse" context="purchasing" locator="/InvalidPurchase.scn" /> + </resource> + </phase> + + <phase name="architecture"> + <resource id="PurchaseGoods.cdm"> + <uri type="eclipse" context="purchasing" locator="/PurchaseGoods.cdm" /> + <relationship type="depends" ref="SuccessfulPurchase.scn" /> + <relationship type="depends" ref="InvalidPurchase.scn" /> + </resource> + </phase> + + <phase name="implementation"> + <resource id="PurchaseGoodsProcess_Store.bpel"> + <uri type="eclipse" context="PurchaseGoodsProcess-Store" + locator="/bpelContent/PurchaseGoodsProcess_Store.bpel" /> + <relationship type="depends" ref="PurchaseGoods.cdm" > + <description> + Link from the BPEL process to the 'Store' participant + within the choreography + </description> + <link type="role" to="Store" /> + </relationship> + </resource> + <resource id="PurchaseGoodsProcess_CreditAgency.bpel"> + <uri type="eclipse" context="PurchaseGoodsProcess-CreditAgency" + locator="/bpelContent/PurchaseGoodsProcess_CreditAgency.bpel" /> + <relationship type="depends" ref="PurchaseGoods.cdm" > + <description> + Link from the BPEL process to the 'CreditAgency' participant + within the choreography + </description> + <link type="role" to="CreditAgency" /> + </relationship> + </resource> + </phase> +</project> + ]]></programlisting> + </informalexample> + + <para> + The top level element is <emphasis>project</emphasis>, with the <emphasis>name</emphasis> + and <emphasis>version</emphasis> attributes to define the details of the Testable Architecture + Project. + </para> + + <para> + The project then contains <emphasis>phase</emphasis> elements, one for each stage of the + software development lifecycle we are interested in. These elements are only used to + segment the artifacts into the different phases, which can be useful for tasks such as + project management or documentation generation. + </para> + + <para> + The phase element contains <emphasis>resource</emphasis> elements, one per artifact. A + resource represents an artifact that is of interest in the Testable Architecture Project. + </para> + + <para> + The resource element contains one or more of the following elements: + </para> + + <orderedlist> + <listitem> + uri + <para> + This element is used to define the location of a resource. A URI element is required for + each environent in which the resource may be accessed, for example, within Eclipse and + within an SOA Repository. + </para> + <para> + The <emphasis>type</emphasis> attribute defines the type of locator, which will usually + map onto the environment in which the resource exists. So in this case we are only + defining URI elements associated with the Eclipse environment. + </para> + <para> + The <emphasis>context</emphasis> attribute defines the local information that can be used + in the particular environment, to determine where the resource is contained. For example, + if the environment is Eclipse, the context would be the project name. + </para> + <para> + The <emphasis>locator</emphasis> attribute is used to specify the specific location of + the resource, within the particular specified context, in the environment type. For example, + if the environment was Eclipse, then the locator would be the relative path of the resource + within the project identified in the context attribute. + </para> + </listitem> + <listitem> + relationship + <para> + This element establishes a relationship from the containing resource, to another resource + identifed by the <emphasis>ref</emphasis> attribute. + </para> + <para> + The relationship element can optionally have additional information associated with it, + to help clarify the nature of the relationship between the two resources. + </para> + <para> + For example, in the TAP file illustrated above, the two BPEL resources (in the implementation + phase) have a relationship to the choreography file - however the relationship needs to be + more specific. We need to indicate what <emphasis>role</emphasis> within that choreography + the BPEL processes are associated with. The <emphasis>link</emphasis> element enables + the <emphasis>type</emphasis> to be defined, and a value to be specified in the + <emphasis>to</emphasis> attribute. + </para> + </listitem> + </orderedlist> +</chapter>