savara SVN: r428 - in trunk/docs/gettingstartedguide/src/main/en-US: module and 1 other directory.
by do-not-reply@jboss.org
Author: objectiser
Date: 2010-10-01 06:02:06 -0400 (Fri, 01 Oct 2010)
New Revision: 428
Added:
trunk/docs/gettingstartedguide/src/main/en-US/images/ExpectedToFail.png
Modified:
trunk/docs/gettingstartedguide/src/main/en-US/module/tap.xml
Log:
Added validation aspects to the Testable Architecture Project section.
Added: trunk/docs/gettingstartedguide/src/main/en-US/images/ExpectedToFail.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/gettingstartedguide/src/main/en-US/images/ExpectedToFail.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: trunk/docs/gettingstartedguide/src/main/en-US/module/tap.xml
===================================================================
--- trunk/docs/gettingstartedguide/src/main/en-US/module/tap.xml 2010-09-30 19:57:46 UTC (rev 427)
+++ trunk/docs/gettingstartedguide/src/main/en-US/module/tap.xml 2010-10-01 10:02:06 UTC (rev 428)
@@ -4,34 +4,37 @@
<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[
+ <section>
+ <title>Managing Dependencies</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">
@@ -78,74 +81,149 @@
</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>
+ ]]></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>
+ </section>
+
+ <section>
+ <title>Validating a Testable Architecture Project</title>
+
+ <para>
+ To trigger validation of a Testable Architecture Project (TAP), select the <filename>.tap</filename>
+ file and choose the <emphasis>Savara->Validate</emphasis> menu item. If any errors or warnings are
+ detected, they will be recorded as errors in the Problems or Markers view (depending on which
+ perspective is being used).
+ </para>
+
+ <para>
+ If you invoke the validation on the TAP file within the <emphasis>purchasing</emphasis> project,
+ you will find that it will create an error associated with the choreography file, indicating
+ that it does not meet the scenario "InvalidPurchase.scn". This is because this scenario has
+ specifically been created to demonstrate how an error is reported.
+ </para>
+
+ <para>
+ If the scenario is simulated against the choreography, using the green <emphasis>play</emphasis> button on the
+ toolbar, then it will be possible to see specifically where the scenario is not met by the
+ choreography.
+ </para>
+
+ <imageobject>
+ <imagedata fileref="en-US/images/InvalidPurchasePostTest.jpg" align="center" width="5in" />
+ </imageobject>
+
+ <para>
+ In this case, it is because the CreditAgency has returned a credit check failed message, but the
+ Store is still attempting to return a buy confirmed message.
+ </para>
+
+ <para>
+ Its possible that this scenario is valid, and therefore the choreography needs to be updated
+ to cater for this scenario. However in this case, we may just be wanting to represent a
+ <emphasis>negative</emphasis> use case, and therefore deliberately describe a situation we
+ do not want the choreography to handle. Therefore we need to configure the scenario to
+ indicate that the failure is expected.
+ </para>
+
+ <imageobject>
+ <imagedata fileref="en-US/images/ExpectedToFail.png" align="center" width="5in" />
+ </imageobject>
+
+ <para>
+ Simply select the 'send' node for the final interaction between the Store and Buyer, and
+ set the 'Expected to Fail' property to true. This will cause a red boundary to be displayed
+ around the node, indicating that it is expected to fail. Now when the scenario is simulated
+ or validated, if that node does not fail, that will be reported as an error. However if the
+ node does fail as expected, that will be treated as a valid case.
+ </para>
+
+ <para>
+ If the validation of the TAP file is performed again, the error associated with the
+ <filename>InvalidPurchase.scn</filename> should no disappear.
+ </para>
+
+ <para>
+ To experiment with other types of validation that are performed, open the <filename>PurchaseGoods.cdm</filename>
+ and go to the <emphasis>Base Types</emphasis> tab. Then open up the node for
+ <emphasis>Information Types</emphasis> and select the <emphasis>CreditCheckOk</emphasis>
+ entry. In the <emphasis>Properties</emphasis> view, change the <emphasis>element</emphasis>
+ attribute, e.g. appending an 'X' to the "ca:CreditCheckOk" value.
+ </para>
+
+ <para>
+ When the choreography has been saved, re-perform the validation on the TAP file. This
+ should now display 'Type Mismatch' errors against the previously generated BPEL
+ processes, and also flag errors associated with the scenarios.
+ </para>
+
+ </section>
+
</chapter>