[overlord-commits] Overlord SVN: r350 - in cdl/trunk/docs/docbook: userguide and 3 other directories.

Author: jeff.yuchang Date: 2008-09-28 11:15:10 -0400 (Sun, 28 Sep 2008) New Revision: 350 Added: cdl/trunk/docs/docbook/userguide/ cdl/trunk/docs/docbook/userguide/pom.xml cdl/trunk/docs/docbook/userguide/src/ cdl/trunk/docs/docbook/userguide/src/main/ cdl/trunk/docs/docbook/userguide/src/main/images/ cdl/trunk/docs/docbook/userguide/src/main/master.xml cdl/trunk/docs/docbook/userguide/src/main/module/ cdl/trunk/docs/docbook/userguide/src/main/module/author_group.xml cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml cdl/trunk/docs/docbook/userguide/src/main/module/template.xml Removed: cdl/trunk/docs/docbook/images/ cdl/trunk/docs/docbook/master.xml cdl/trunk/docs/docbook/module/ cdl/trunk/docs/docbook/src/ Modified: cdl/trunk/docs/docbook/pom.xml Log: * Restructure the docbook module, so that it can be extend easily for producing multiple books. Deleted: cdl/trunk/docs/docbook/master.xml =================================================================== --- cdl/trunk/docs/docbook/master.xml 2008-09-27 12:26:19 UTC (rev 349) +++ cdl/trunk/docs/docbook/master.xml 2008-09-28 15:15:10 UTC (rev 350) @@ -1,16 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ -<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent"> -]> - -<book lang="en"> - <bookinfo> - <title>JBoss Overlord CDL 1.0</title> - <subtitle>User 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/getting_started.xml"/> - -</book> Modified: cdl/trunk/docs/docbook/pom.xml =================================================================== --- cdl/trunk/docs/docbook/pom.xml 2008-09-27 12:26:19 UTC (rev 349) +++ cdl/trunk/docs/docbook/pom.xml 2008-09-28 15:15:10 UTC (rev 350) @@ -5,80 +5,15 @@ <modelVersion>4.0.0</modelVersion> <groupId>org.jboss.soa.overlord.cdl</groupId> - <artifactId>userguide</artifactId> + <artifactId>docs</artifactId> <version>1.0-SNAPSHOT</version> <packaging>pom</packaging> - <name>Overlord::CDL::UserGuide</name> + <name>Overlord::CDL::Docs</name> + + <modules> + <module>userguide</module> + </modules> - <build> - <plugins> - <plugin> - <groupId>org.jboss.maven.plugins</groupId> - <artifactId>maven-jdocbook-plugin</artifactId> - <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}</sourceDirectory> - <imageResource> - <directory>${basedir}</directory> - <includes> - <include>images/**/*</include> - </includes> - </imageResource> - <formats> - <format> - <formatName>pdf</formatName> - <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource> - <finalName>Overlord-CDL.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> - <format> - <formatName>eclipse</formatName> - <stylesheetResource>classpath:/xslt/org/jboss/eclipse.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> - <repositories> <repository> <snapshots> Added: cdl/trunk/docs/docbook/userguide/pom.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/pom.xml (rev 0) +++ cdl/trunk/docs/docbook/userguide/pom.xml 2008-09-28 15:15:10 UTC (rev 350) @@ -0,0 +1,82 @@ +<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.soa.overlord.cdl.docs</groupId> + <artifactId>userguide</artifactId> + <version>1.0-SNAPSHOT</version> + <packaging>jdocbook</packaging> + <name>Overlord::CDL::Docs::userguide</name> + + <parent> + <groupId>org.jboss.soa.overlord.cdl</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>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource> + <finalName>UserGuide.pdf</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: cdl/trunk/docs/docbook/userguide/src/main/master.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/master.xml (rev 0) +++ cdl/trunk/docs/docbook/userguide/src/main/master.xml 2008-09-28 15:15:10 UTC (rev 350) @@ -0,0 +1,16 @@ +<?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>JBoss Overlord CDL 1.0</title> + <subtitle>User 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/getting_started.xml"/> + +</book> Added: cdl/trunk/docs/docbook/userguide/src/main/module/author_group.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/module/author_group.xml (rev 0) +++ cdl/trunk/docs/docbook/userguide/src/main/module/author_group.xml 2008-09-28 15:15:10 UTC (rev 350) @@ -0,0 +1,6 @@ +<?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> +</authorgroup> Added: cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml (rev 0) +++ cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml 2008-09-28 15:15:10 UTC (rev 350) @@ -0,0 +1,211 @@ +<?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="gettingstarted"> + <title>Getting Started</title> + <section> + <title>SOA Governance with CDL </title> + <section> + <title>Overview</title> + <para> + The CDL component of the Overlord SOA governance project aims to leverage the concept of a choreography (or conversation) + description to provide design-time and run-time governance of an SOA. + </para> + <para> + A Choreography provides the means to describe the service interactions between multiple parties from a global (or service neutral) perspective. + This means that it is possible for an organisation to define how an end-to-end business process should function, regardless of whether orchestrated + or peer-to-peer service collaboration will be used. + </para> + <para> + Although in simple situations, a BPEL process description can provide a description of the interactions between multiple services, this only works where a + single orchestrating process is in control. The benefit of the choreography description is that it can be used to provide a global view of a process across multiple + orchestrated service domains. + </para> + <para> + This document will outline how the Choreography Description is being used as part of Project Overlord to provide SOA governance capabilities + for each phase of the SOA lifecycle. + </para> + <para> + When a validated design has been approved by the users, it can be used to generate an initial skeleton of the implementation for each service. + The current version of Overlord enables a skeleton implementation to be generated as a JBossESB service configuration file, + using 'conversation aware' ESB actions. For more information on these, please see the “Conversational ESB User Guide”. + </para> + </section> + + <section> + <title> SOA Lifecycle Governance </title> + + <section> + <title>Design Time Governance</title> + <para> + Design-time governance is concerned with ensuring that the resulting system correctly implements requirements (whether functional or non-functional). + A choreography description can be used to ensure that the implemented system meets the behavioural requirements. + </para> + <para> + The behavioural requirements can be captured as a collection of scenarios (e.g. sequence diagrams) with associated example messages. + This enables an unambiguous representation of the business requirements to be stored in a machine processable form, which can subsequently + be used to validate other phases of the SOA lifecycle. + </para> + <para> + Once the choreography description for the SOA has been defined, it can be validated against the scenarios, + to ensure that the choreography correctly handles all of the business requirements. + </para> + <para> + Once the service enters the implementation phase, it is important to ensure that it continues to adhere to the design + and therefore meets the business requirements. Currently this is achieved through the use of techniques such as continuous testing. + However this is only as reliable as the quality of the unit tests that have been written. + </para> + <para> + When a 'structured' implementation language has been used, such as WS-BPEL, jPDL or the new 'conversation aware' ESB actions, + it will be possible to infer the behaviour of the service being implemented, to compare it against the choreography description. + Currently this has been implemented for the “conversation aware” ESB actions, and is demonstrated using the samples in this Overlord-CDL distribution. + </para> + <para> + Detecting incorrectly implemented behaviour at the earliest possible time saves on downstream costs associated with finding and fixing errors. + By using static validation against the original design, it ensures that the implemented service will deliver its expected behaviour first time. + This is important in building large scale SOAs where different services may be implemented in different locations. + </para> + <para> + There are two other areas where a choreography description can be used as part of design-time governance, + that are not currently implemented in Overlord: + </para> + <itemizedlist> + <listitem> + Service lookup – the choreography description can be used to determine if a service already exists in the Service Repository that meets the appropriate behavioural requirements. + </listitem> + <listitem> + Service unit testing - this can be achieved using the scenarios originally specified to document the behavioural requirements. + Rather than develop an independent source of test data, the scenarios can be used to validate the sequence of messages sent to, + and received from, a service, as well as validating the contents of the messages returned from the service under test. + </listitem> + </itemizedlist> + </section> + + <section> + <title>Runtime Governance</title> + <para> + Runtime governance ensures that the SOA executes as expected according to predefined policies. In this context, a choreography description can be used in two ways. + </para> + + <section> + <title> Service validator</title> + <para> + The choreography description represents the interactions between multiple services to deliver a business goal. + To validate the behaviour of each individual service, within the choreography description, the behaviour of each service can be derived from the choreography. + </para> + <para> + The derived behaviour (or “endpoint projection”) of a service can be used within a 'service validator' to monitor the inbound and outbound messages for the service, + to ensure they conform to the expected behaviour. + If an invalid message is detected, it would be possible to block it, to prevent it from causing subsequent problems in downstream systems. + The error can also be reported to a central management capability. + </para> + <para> + The CDL component of Overlord provides the ability to configure service validators to monitor the behaviour of individual services. + An enhanced version of the JBossESB trailblazer example has been included, with the appropriate validator configuration, to demonstrate this mechanism. + </para> + </section> + + <section> + <title>Process correlation</title> + <para> + Validating each service locally can enable errors to be detected quickly, + and the effects of the error prevented from contaminating other systems by blocking the erroneous messages. + </para> + <para> + However local service specific validation may not be adequate to identify errors that would affect the end-to-end business process. + Therefore the message activity at each service validator can be reported to a central 'process correlation engine' which can reconstitute a global view of the business transaction, + and determine if it matches the expected behaviour as defined in the choreography description. + </para> + <para> + The benefit of a correlated global view of the distributed business transaction is that it can be further analysed to ensure other governance polices have been followed – e.g. SLAs. + </para> + <para> + The pi4soa tool suite includes a simple GUI based monitoring tool to display the information obtained from correlating message events associated with individual services. + The trailblazer example has been written to cause out of sequence messages under certain circumstances. See the “Samples Guide” for more information on how to run this example. + </para> + </section> + </section> + </section> + + <section> + <title> First Steps </title> + <para>The first step will be to follow the instructions in the next chapter to install Overlord. </para> + <para> Once installed, the next step should be to try out the examples in the samples folder. The examples consistent of:</para> + <itemizedlist> + <listitem> + Service Validation related examples + <para> + The samples folder contains an enhanced version of the trailblazer example from the JBossESB, with the addition of a File Based Bank, and message content including a conversation id to enable the messages to be correlated with a specific session. + </para> + </listitem> + <listitem> + Conversation aware ESB actions, with conformance checking against Choreography + <para> + Two examples have been included, one simple example (purchasing) and the other more advanced (brokerage). Both relate to the business process of purchasing items. The second example introduces the concept of a broker to act on behalf of the customer, interacting with multiple potential suppliers. + </para> + <para> + These examples show how a service implementation (built using “conversation aware ESB actions” in this case), can be continuously checked for conformance against a choreography description. + </para> + <para> + The final step should be to review the other documents in the docs folder to understand more about each capability, and then try using the techniques on your own project. + </para> + </listitem> + </itemizedlist> + </section> + </section> + + <section> + <title>Installation</title> + + <section> + <title> Overview </title> + <para> + This section describes the installation procedure for the Overlord CDL based governance capabilities. These capabilities are: + </para> + <itemizedlist> + <listitem> Conversation aware ESB Actions with conformance checking against a Choreography Description </listitem> + <listitem> ESB Service validation against a Choreography Description </listitem> + </itemizedlist> + </section> + + <section> + <title>Prerequisites</title> + <orderedlist> + <listitem>JBossAS (version 4.2.3.GA or higher), available from http://www.jboss.org/jbossas</listitem> + <listitem>JBossESB (version 4.4.GA or higher), available from http://www.jboss.org/jbossesb</listitem> + <listitem>Overlord CDL (version 1.0.SNAPSHOT or higher) </listitem> + <listitem> + pi4soa (version 2.0.0 or higher), available from http://www.pi4soa.org + <note> + <para> + It is recommended that a pre-packaged version is used, which includes all of the necessary Eclipse related plugins. + However the plugins can be installed separately into an existing Eclipse environment by following the instructions on the www.pi4soa.org wiki. + </para> + </note> + </listitem> + <listitem> + Ant, available from http://ant.apache.org/ + </listitem> + </orderedlist> + </section> + + <section> + <title>Installation Instructions</title> + <orderedlist> + <listitem> + Install JBossAS + <para> Unpack the JBossAS installation into the required location. </para> + </listitem> + <listitem> + Install JBossESB + <para> Unpack the JBossESB installation into a location alongside the JBossAS installation. + Then follow the instructions in the JBossESB installation (install/readme.txt), to deploy JBossESB into the JBossAS environment. + </para> + </listitem> + + </orderedlist> + </section> + +</section> + +</chapter> Added: cdl/trunk/docs/docbook/userguide/src/main/module/template.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/module/template.xml (rev 0) +++ cdl/trunk/docs/docbook/userguide/src/main/module/template.xml 2008-09-28 15:15:10 UTC (rev 350) @@ -0,0 +1,7 @@ +<?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="chapter-id"> + <title>Chapter title</title> + <para>To be written...</para> +</chapter>