Author: objectiser
Date: 2008-11-10 09:46:06 -0500 (Mon, 10 Nov 2008)
New Revision: 426
Added:
cdl/trunk/docs/docbook/gettingstartedguide/
cdl/trunk/docs/docbook/gettingstartedguide/pom.xml
cdl/trunk/docs/docbook/gettingstartedguide/src/
cdl/trunk/docs/docbook/gettingstartedguide/src/main/
cdl/trunk/docs/docbook/gettingstartedguide/src/main/images/
cdl/trunk/docs/docbook/gettingstartedguide/src/main/master.xml
cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/
cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/author_group.xml
cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/conversation-aware-esb.xml
cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/conversation-validation-with-cdl.xml
cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml
cdl/trunk/docs/docbook/gettingstartedguide/src/main/xslt/
cdl/trunk/docs/docbook/gettingstartedguide/src/main/xslt/pdf.xsl
cdl/trunk/docs/docbook/userguide/src/main/module/installation.xml
Removed:
cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml
Modified:
cdl/trunk/docs/docbook/pom.xml
cdl/trunk/docs/docbook/userguide/src/main/master.xml
Log:
Separated getting started section of UserGuide into a separate document, which will be
elaborated over the next couple of days.
Added: cdl/trunk/docs/docbook/gettingstartedguide/pom.xml
===================================================================
--- cdl/trunk/docs/docbook/gettingstartedguide/pom.xml (rev 0)
+++ cdl/trunk/docs/docbook/gettingstartedguide/pom.xml 2008-11-10 14:46:06 UTC (rev 426)
@@ -0,0 +1,87 @@
+<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>gettingstartedguide</artifactId>
+ <version>1.0-M1</version>
+ <packaging>jdocbook</packaging>
+ <name>Overlord::CDL::Docs::gettingstartedguide</name>
+
+ <parent>
+ <groupId>org.jboss.soa.overlord.cdl</groupId>
+ <artifactId>docs</artifactId>
+ <version>1.0-M1</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>file:///${basedir}/src/main/xslt/pdf.xsl</stylesheetResource>
+ <finalName>GettingStartedGuide.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>
+ </formats>
+ <options>
+ <xincludeSupported>true</xincludeSupported>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <docbookVersion>1.72.0</docbookVersion>
+ </options>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+
+</project>
Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/master.xml
===================================================================
--- cdl/trunk/docs/docbook/gettingstartedguide/src/main/master.xml
(rev 0)
+++ cdl/trunk/docs/docbook/gettingstartedguide/src/main/master.xml 2008-11-10 14:46:06 UTC
(rev 426)
@@ -0,0 +1,18 @@
+<?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-M1</title>
+ <subtitle>Getting Started 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/soagwithcdl.xml"/>
+ <xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="module/conversation-validation-with-cdl.xml"/>
+ <xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="module/conversation-aware-esb.xml"/>
+
+</book>
Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/author_group.xml
===================================================================
--- cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/author_group.xml
(rev 0)
+++ cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/author_group.xml 2008-11-10
14:46:06 UTC (rev 426)
@@ -0,0 +1,7 @@
+<?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>
+ <corpauthor>Jeff Yu</corpauthor>
+</authorgroup>
Added:
cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/conversation-aware-esb.xml
===================================================================
--- cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/conversation-aware-esb.xml
(rev 0)
+++
cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/conversation-aware-esb.xml 2008-11-10
14:46:06 UTC (rev 426)
@@ -0,0 +1,8 @@
+<?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="conversationawareesb">
+ <title>Conversation Aware ESB</title>
+
+</chapter>
+
Added:
cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/conversation-validation-with-cdl.xml
===================================================================
---
cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/conversation-validation-with-cdl.xml
(rev 0)
+++
cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/conversation-validation-with-cdl.xml 2008-11-10
14:46:06 UTC (rev 426)
@@ -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="conversationvalidationwithcdl">
+ <title>Conversation Validation with CDL</title>
+
+</chapter>
Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml
===================================================================
--- cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml
(rev 0)
+++ cdl/trunk/docs/docbook/gettingstartedguide/src/main/module/soagwithcdl.xml 2008-11-10
14:46:06 UTC (rev 426)
@@ -0,0 +1,210 @@
+<?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="soagwithcdl">
+ <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>WS-CDL</title>
+
+ <para>
+WS-CDL, or Web Service Choreography Description Language, is a candidate recommendation
from W3C. Although associated with W3C and Web Services, it is important to begin by
stating that the Choreography Description Language (CDL) is <emphasis
role="bold">not</emphasis> web service specific.
+ </para>
+ <para>
+The purpose of CDL is to enable the interactions between a collection of peer to peer
services to be described from a neutral (or global) perspective. This is different to
other standards, such as WS-BPEL, that describe interactions from a service specific
viewpoint.
+ </para>
+ <para>
+In essence a choreography description declares roles which will pass messages between
each other, called interactions. The interactions are ordered based on a number of
structuring mechanism which enables loops, conditional, choices and parallelism to be
described. In CDL variables used for messages and for conditionals are all situated at
roles. There is no shared state rather there is a precise description of the state at each
role and a precise description of how these roles interact in order to reach some notion
of common state in which information is exchanged and processed between them.
+ </para>
+ <para>
+In CDL we use interactions and these structuring mechanisms to describe the observable
behaviour, the messages exchanges and the rules for those exchanges and any supporting
observable state on which they depend, of a system.
+ </para>
+ </section>
+
+ <section>
+ <title>pi4soa</title>
+ <para>
+<emphasis>pi4soa</emphasis> is an open source project established to
demonstrate the potential benefits that a global model (as described using CDL) can
provide when building an SOA. The open source project is managed by the Pi4 Technologies
Foundation, which is a collaboration between industry and academia.
+ </para>
+ <para>
+Building complex distributed systems, without introducing unintended consequences, is a
real challenge. Although the Choreography Description Language provides a means of
describing complex systems at a higher level, and therefore help to reduce such
complexity, it does not necessarily guarantee that erronous situations cannot occur due to
inappropriately specified interactions. The research, being carried out by members of the
Pi4 Technologies Foundation, into the global model and endpoint projection is targeted at
identifying potential unintended consequences, to ensure that a global description of a
system can be reliably executed and can be free from unintended consequences.
+ </para>
+ <para>
+The tool suite currently offers the ability to:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ Define a choreography description
+ </listitem>
+ <listitem>
+ Export the description to a range of other formats, such as BPMN, UML
activity/state/sequence models, and HTML
+ </listitem>
+ <listitem>
+ Define scenarios (equivalent to sequence diagrams), with example messages, which can
then be simulated against an associated choreography
+ </listitem>
+ <listitem>
+ Generate template endpoint implementations:
+ <para>
+ <itemizedlist>
+ <listitem>
+ WS-BPEL for deployment in ActiveBPEL
+ </listitem>
+ <listitem>
+ Java stubs for execution with the pi4soa state machine, with deployment options for
Apache Axis, J2EE (JBoss, Glassfish) and JBoss ESB
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </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>
+
+</chapter>
Added: cdl/trunk/docs/docbook/gettingstartedguide/src/main/xslt/pdf.xsl
===================================================================
--- cdl/trunk/docs/docbook/gettingstartedguide/src/main/xslt/pdf.xsl
(rev 0)
+++ cdl/trunk/docs/docbook/gettingstartedguide/src/main/xslt/pdf.xsl 2008-11-10 14:46:06
UTC (rev 426)
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+
xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ version="1.0">
+
+ <xsl:import
href="http://docbook.sourceforge.net/release/xsl/1.72.0/fo/docbook.x... />
+ <xsl:import href="classpath:/xslt/org/jboss/pdf.xsl" />
+
+ <!-- Override the default font settings -->
+ <xsl:param name="body.font.family" select="'Times New Roman,
serif'" />
+ <xsl:param name="monospace.font.family" select="'DejaVu Sans
Mono, monospace'" />
+ <xsl:param name="sans.font.family" select="'Arial,
sans-serif'" />
+ <xsl:param name="title.font.family" select="$body.font.family"
/>
+ <xsl:param name="programlisting.font"
select="$monospace.font.family" />
+ <xsl:param name="programlisting.font.size"
select="'75%'" />
+
+ <!-- Remove the blank pages between the chapters -->
+ <xsl:param name="double.sided" select="0" />
+
+ <!-- Use SVG for callout images instead of PNG -->
+ <xsl:param name="callout.graphics" select="1" />
+ <xsl:param name="callout.graphics.extension"
select="'.svg'" />
+
+ <!-- Hide URL -->
+ <xsl:param name="ulink.show" select="0"/>
+
+ <!-- Don't use italic font for links -->
+ <xsl:attribute-set name="xref.properties">
+ <xsl:attribute name="font-style">normal</xsl:attribute>
+ </xsl:attribute-set>
+
+ <!-- Decrease the link font size in the program listing -->
+ <xsl:attribute-set name="monospace.properties">
+ <xsl:attribute name="font-size">1em</xsl:attribute>
+ <xsl:attribute name="font-family">
+ <xsl:value-of select="$monospace.font.family"/>
+ </xsl:attribute>
+ </xsl:attribute-set>
+
+ <!-- Add some spacing between callout listing items -->
+ <xsl:template match="callout">
+ <xsl:variable name="id"><xsl:call-template
name="object.id"/></xsl:variable>
+ <fo:list-item id="{$id}" space-before="1em">
+ <fo:list-item-label end-indent="label-end()">
+ <fo:block>
+ <xsl:call-template name="callout.arearefs">
+ <xsl:with-param name="arearefs"
select="@arearefs"/>
+ </xsl:call-template>
+ </fo:block>
+ </fo:list-item-label>
+ <fo:list-item-body start-indent="body-start()">
+ <fo:block padding-top="0.2em">
+ <xsl:apply-templates/>
+ </fo:block>
+ </fo:list-item-body>
+ </fo:list-item>
+ </xsl:template>
+
+ <!-- Slight baseline-shift for callouts in the program listing -->
+ <xsl:template name="callout-bug">
+ <xsl:param name="conum" select='1'/>
+ <xsl:choose>
+ <xsl:when test="$conum <= $callout.graphics.number.limit">
+ <xsl:variable name="filename"
+ select="concat($callout.graphics.path, $conum,
+ $callout.graphics.extension)"/>
+
+ <fo:external-graphic content-width="{$callout.icon.size}"
+ width="{$callout.icon.size}"
+ padding="0.0em" margin="0.0em"
+ baseline-shift="-0.375em">
+ <xsl:attribute name="src">
+ <xsl:choose>
+ <xsl:when test="$passivetex.extensions != 0
+ or $fop.extensions != 0
+ or $arbortext.extensions != 0">
+ <xsl:value-of select="$filename"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:text>url(</xsl:text>
+ <xsl:value-of select="$filename"/>
+ <xsl:text>)</xsl:text>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:attribute>
+ </fo:external-graphic>
+ </xsl:when>
+ </xsl:choose>
+ </xsl:template>
+</xsl:stylesheet>
+
Modified: cdl/trunk/docs/docbook/pom.xml
===================================================================
--- cdl/trunk/docs/docbook/pom.xml 2008-11-10 14:18:24 UTC (rev 425)
+++ cdl/trunk/docs/docbook/pom.xml 2008-11-10 14:46:06 UTC (rev 426)
@@ -1,40 +1,41 @@
-<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</groupId>
- <artifactId>docs</artifactId>
- <version>1.0-M1</version>
- <packaging>pom</packaging>
- <name>Overlord::CDL::Docs</name>
-
- <modules>
- <module>userguide</module>
- <module>samplesguide</module>
- </modules>
-
- <repositories>
- <repository>
- <snapshots>
- <enabled>false</enabled>
- </snapshots>
- <id>jboss.release</id>
- <name>JBoss releases</name>
- <
url>http://repository.jboss.org/maven2</url>
- </repository>
- </repositories>
-
- <pluginRepositories>
- <pluginRepository>
- <snapshots>
- <enabled>false</enabled>
- </snapshots>
- <id>jboss.release</id>
- <name>JBoss releases</name>
- <
url>http://repository.jboss.org/maven2</url>
- </pluginRepository>
- </pluginRepositories>
-
-</project>
+<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</groupId>
+ <artifactId>docs</artifactId>
+ <version>1.0-M1</version>
+ <packaging>pom</packaging>
+ <name>Overlord::CDL::Docs</name>
+
+ <modules>
+ <module>userguide</module>
+ <module>samplesguide</module>
+ <module>gettingstartedguide</module>
+ </modules>
+
+ <repositories>
+ <repository>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ <id>jboss.release</id>
+ <name>JBoss releases</name>
+ <
url>http://repository.jboss.org/maven2</url>
+ </repository>
+ </repositories>
+
+ <pluginRepositories>
+ <pluginRepository>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ <id>jboss.release</id>
+ <name>JBoss releases</name>
+ <
url>http://repository.jboss.org/maven2</url>
+ </pluginRepository>
+ </pluginRepositories>
+
+</project>
Modified: cdl/trunk/docs/docbook/userguide/src/main/master.xml
===================================================================
--- cdl/trunk/docs/docbook/userguide/src/main/master.xml 2008-11-10 14:18:24 UTC (rev
425)
+++ cdl/trunk/docs/docbook/userguide/src/main/master.xml 2008-11-10 14:46:06 UTC (rev
426)
@@ -11,7 +11,7 @@
</bookinfo>
<toc/>
- <xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="module/getting_started.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/conversation-validation-with-cdl.xml"/>
<xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="module/conversation-aware-esb.xml"/>
Deleted: cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml
===================================================================
--- cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml 2008-11-10
14:18:24 UTC (rev 425)
+++ cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml 2008-11-10
14:46:06 UTC (rev 426)
@@ -1,326 +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="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>WS-CDL</title>
-
- <para>
-WS-CDL, or Web Service Choreography Description Language, is a candidate recommendation
from W3C. Although associated with W3C and Web Services, it is important to begin by
stating that the Choreography Description Language (CDL) is <emphasis
role="bold">not</emphasis> web service specific.
- </para>
- <para>
-The purpose of CDL is to enable the interactions between a collection of peer to peer
services to be described from a neutral (or global) perspective. This is different to
other standards, such as WS-BPEL, that describe interactions from a service specific
viewpoint.
- </para>
- <para>
-In essence a choreography description declares roles which will pass messages between
each other, called interactions. The interactions are ordered based on a number of
structuring mechanism which enables loops, conditional, choices and parallelism to be
described. In CDL variables used for messages and for conditionals are all situated at
roles. There is no shared state rather there is a precise description of the state at each
role and a precise description of how these roles interact in order to reach some notion
of common state in which information is exchanged and processed between them.
- </para>
- <para>
-In CDL we use interactions and these structuring mechanisms to describe the observable
behaviour, the messages exchanges and the rules for those exchanges and any supporting
observable state on which they depend, of a system.
- </para>
- </section>
-
- <section>
- <title>pi4soa</title>
- <para>
-<emphasis>pi4soa</emphasis> is an open source project established to
demonstrate the potential benefits that a global model (as described using CDL) can
provide when building an SOA. The open source project is managed by the Pi4 Technologies
Foundation, which is a collaboration between industry and academia.
- </para>
- <para>
-Building complex distributed systems, without introducing unintended consequences, is a
real challenge. Although the Choreography Description Language provides a means of
describing complex systems at a higher level, and therefore help to reduce such
complexity, it does not necessarily guarantee that erronous situations cannot occur due to
inappropriately specified interactions. The research, being carried out by members of the
Pi4 Technologies Foundation, into the global model and endpoint projection is targeted at
identifying potential unintended consequences, to ensure that a global description of a
system can be reliably executed and can be free from unintended consequences.
- </para>
- <para>
-The tool suite currently offers the ability to:
- </para>
- <para>
- <itemizedlist>
- <listitem>
- Define a choreography description
- </listitem>
- <listitem>
- Export the description to a range of other formats, such as BPMN, UML
activity/state/sequence models, and HTML
- </listitem>
- <listitem>
- Define scenarios (equivalent to sequence diagrams), with example messages, which can
then be simulated against an associated choreography
- </listitem>
- <listitem>
- Generate template endpoint implementations:
- <para>
- <itemizedlist>
- <listitem>
- WS-BPEL for deployment in ActiveBPEL
- </listitem>
- <listitem>
- Java stubs for execution with the pi4soa state machine, with deployment options for
Apache Axis, J2EE (JBoss, Glassfish) and JBoss ESB
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
- </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.2.GA or higher), available from <ulink
url="http://www.jboss.org/jbossas">http://www.jboss.org/jbos...
- <listitem>JBossESB (version 4.4.GA or higher), should download the
<emphasis role="bold">jbossesb-4.4.GA.zip</emphasis>, available from
<ulink
url="http://www.jboss.org/jbossesb">http://www.jboss.org/jbo...
- <listitem>Overlord CDL (version 1.0-SNAPSHOT or higher)
</listitem>
- <listitem>
- pi4soa (version 2.0.0 or higher), available from <ulink
url="http://pi4soa.wiki.sourceforge.net/download">http://pi4...
- <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 <ulink
url="http://www.pi4soa.org">http://www.pi4soa.org</ulink> download
wiki.
- </para>
- </note>
- </listitem>
- <listitem>
- Ant, available from <ulink
url="http://ant.apache.org/">http://ant.apache.org</ulink...
- </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>
-
- <listitem>
- Install the Overlord CDL distribution
- <para>
- Unpack the Overlord CDL distribution into a location alongside the JBossAS
installation.
- </para>
- <para>
- <itemizedlist>
- <listitem>
- Edit the <emphasis
role="bold">install/deployment.properties</emphasis> file to update the
JBossAS and JBossESB location settings.
- </listitem>
- <listitem>
- From the install folder, run: <command> ant deploy</command>to
deploy both the Overlord CDL conversational ESB actions and service validation
capabilities.
- Or <command>ant deploy-overlord-cdl-runtime</command> to deploy just
the conversational ESB actions support, or <command>ant
deploy-overlord-cdl-validator</command> to deploy just the service validation
capability.
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
-
- <listitem>
- Install pi4soa
- <para>
- Unpack the pi4soa pre-packaged Eclipse version into a location alongside the
JBossAS installation, or install the relevant plugins (as described on the pi4soa wiki)
into an existing Eclipse environment.
- </para>
- <para>
- If just the service validation capabilities are being used, then no further
configuration of the Eclipse environment is necessary.
- However if the conversational ESB actions, with conformance checking against a
Choreography Description, will be used, then the following additional steps will be
required:
- </para>
- <para>
- <itemizedlist>
- <listitem>
- Start the Eclipse environment
- </listitem>
- <listitem>
- Select the “Help - > Software Updates...” menu item
- </listitem>
- <listitem>
- From the <emphasis role="bold"> Available
Software</emphasis> tab, press the “Add Site...” button
- </listitem>
- <listitem>
- Press the <emphasis role="bold">“Local”</emphasis> button,
browse to locate the <emphasis role="bold">tools</emphasis> folder
in the Overlord CDL distribution,
- and then press the OK button. This will cause the local Eclipse update site,
bundled with the Overlord CDL distribution, to be add to the <emphasis
role="bold"> Available Software </emphasis> tab.
- </listitem>
- <listitem>
- Select the root node of the newly added local update site, and then press the
<emphasis role="bold">“Install”</emphasis> button and follow the
instructions to install the plugins.
-
- <note>
- <para>
- An eclipse issue occasionally causes the nodes under the checked root node
- to become unchecked, resulting in the software update manager indicating
- that no plugins need to be installed. If this happens, simply uncheck the
- root node, and then re-check the root node and press the
- <emphasis role="bold">“Install”</emphasis> button again.
- </para>
- </note>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
-
- </orderedlist>
- </section>
-
-</section>
-
-</chapter>
Added: cdl/trunk/docs/docbook/userguide/src/main/module/installation.xml
===================================================================
--- cdl/trunk/docs/docbook/userguide/src/main/module/installation.xml
(rev 0)
+++ cdl/trunk/docs/docbook/userguide/src/main/module/installation.xml 2008-11-10 14:46:06
UTC (rev 426)
@@ -0,0 +1,115 @@
+<?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="installation">
+ <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.2.GA or higher), available from <ulink
url="http://www.jboss.org/jbossas">http://www.jboss.org/jbos...
+ <listitem>JBossESB (version 4.4.GA or higher), should download the
<emphasis role="bold">jbossesb-4.4.GA.zip</emphasis>, available from
<ulink
url="http://www.jboss.org/jbossesb">http://www.jboss.org/jbo...
+ <listitem>Overlord CDL (version 1.0-SNAPSHOT or higher)
</listitem>
+ <listitem>
+ pi4soa (version 2.0.0 or higher), available from <ulink
url="http://pi4soa.wiki.sourceforge.net/download">http://pi4...
+ <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 <ulink
url="http://www.pi4soa.org">http://www.pi4soa.org</ulink> download
wiki.
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ Ant, available from <ulink
url="http://ant.apache.org/">http://ant.apache.org</ulink...
+ </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>
+
+ <listitem>
+ Install the Overlord CDL distribution
+ <para>
+ Unpack the Overlord CDL distribution into a location alongside the JBossAS
installation.
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ Edit the <emphasis
role="bold">install/deployment.properties</emphasis> file to update the
JBossAS and JBossESB location settings.
+ </listitem>
+ <listitem>
+ From the install folder, run: <command> ant deploy</command>to
deploy both the Overlord CDL conversational ESB actions and service validation
capabilities.
+ Or <command>ant deploy-overlord-cdl-runtime</command> to deploy just
the conversational ESB actions support, or <command>ant
deploy-overlord-cdl-validator</command> to deploy just the service validation
capability.
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ <listitem>
+ Install pi4soa
+ <para>
+ Unpack the pi4soa pre-packaged Eclipse version into a location alongside the
JBossAS installation, or install the relevant plugins (as described on the pi4soa wiki)
into an existing Eclipse environment.
+ </para>
+ <para>
+ If just the service validation capabilities are being used, then no further
configuration of the Eclipse environment is necessary.
+ However if the conversational ESB actions, with conformance checking against a
Choreography Description, will be used, then the following additional steps will be
required:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ Start the Eclipse environment
+ </listitem>
+ <listitem>
+ Select the “Help - > Software Updates...” menu item
+ </listitem>
+ <listitem>
+ From the <emphasis role="bold"> Available
Software</emphasis> tab, press the “Add Site...” button
+ </listitem>
+ <listitem>
+ Press the <emphasis role="bold">“Local”</emphasis> button,
browse to locate the <emphasis role="bold">tools</emphasis> folder
in the Overlord CDL distribution,
+ and then press the OK button. This will cause the local Eclipse update site,
bundled with the Overlord CDL distribution, to be add to the <emphasis
role="bold"> Available Software </emphasis> tab.
+ </listitem>
+ <listitem>
+ Select the root node of the newly added local update site, and then press the
<emphasis role="bold">“Install”</emphasis> button and follow the
instructions to install the plugins.
+
+ <note>
+ <para>
+ An eclipse issue occasionally causes the nodes under the checked root node
+ to become unchecked, resulting in the software update manager indicating
+ that no plugins need to be installed. If this happens, simply uncheck the
+ root node, and then re-check the root node and press the
+ <emphasis role="bold">“Install”</emphasis> button again.
+ </para>
+ </note>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ </orderedlist>
+ </section>
+
+</chapter>