Author: objectiser
Date: 2008-09-30 11:53:47 -0400 (Tue, 30 Sep 2008)
New Revision: 355
Added:
cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml
cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml
Modified:
cdl/trunk/docs/docbook/userguide/src/main/master.xml
Log:
Started migration of other docs into docbook UserGuide. Conversation-validation-with-cdl -
converted two sections, but remaining sections will not be converted - one relates to
installation which is now handled in the 'getting started' part, and the other
describes running the Trailblazer example, which is covered in the samples guide. Possible
that some of the images may be useful in the samples guide - and also may want to
'docbook' the samples guide.
Modified: cdl/trunk/docs/docbook/userguide/src/main/master.xml
===================================================================
--- cdl/trunk/docs/docbook/userguide/src/main/master.xml 2008-09-30 13:34:41 UTC (rev
354)
+++ cdl/trunk/docs/docbook/userguide/src/main/master.xml 2008-09-30 15:53:47 UTC (rev
355)
@@ -1,16 +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</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>
+<?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"/>
+ <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/userguide/src/main/module/conversation-aware-esb.xml
===================================================================
--- cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml
(rev 0)
+++ cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml 2008-09-30
15:53:47 UTC (rev 355)
@@ -0,0 +1,14 @@
+<?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>
+ <section>
+ <title></title>
+ <section>
+ <title></title>
+ <para>
+ </para>
+ </section>
+ </section>
+</chapter>
Added:
cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml
===================================================================
--- cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml
(rev 0)
+++
cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml 2008-09-30
15:53:47 UTC (rev 355)
@@ -0,0 +1,186 @@
+<?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>
+ <section>
+ <title>Conversation Validation</title>
+ <section>
+ <title>Overview</title>
+ <para>
+ Conversation validation is a form of runtime governance concerned with the dynamic
behaviour of a system.
+ </para>
+ <para>
+When coupled with a choreography description model of a system, this means having the
ability to ensure that the way a collection of services interact correctly adheres to a
description of the business process being enacted.
+ </para>
+ <para>
+This section introduces the choreography description language (CDL) defined by W3C, and
the <emphasis>pi4soa</emphasis> open source project which provides an editor
for creating choreography descriptions, as well as utilizing these descriptions for
runtime validation and execution purposes.
+
+ </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>
+
+ <section>
+ <title>Configuration of Conversation Validation</title>
+
+ <section>
+ <title>Central Configuration</title>
+ <para>
+The principle mechanism used for validating conversations within an ESB is through the
use of a global filter registered with the
<emphasis>jbossesb-properties.xml</emphasis>. This file is located in the
<emphasis>$JBossESB/server/default/deploy/jbossesb.sar</emphasis> folder.
+ </para>
+ <informalexample>
+ <programlisting>
+ <properties name="filters">
+ ...
+ <property name="org.jboss.soa.esb.filter.10"
+ value="org.pi4soa.jbossesb.validator.ValidatorFilter"/>
+ </properties>
+ </programlisting>
+ </informalexample>
+
+ <para>
+This filter is installed as part of the installation process for the Overlord-CDL
distribution.
+ </para>
+ <para>
+The information concerning what destinations will be validated, and to which
choreography/participant they relate, are contained within the
<emphasis>validator-config.xml</emphasis> file, contained within the
<emphasis>overlord-cdl-validator.esb</emphasis> bundle.
+ </para>
+ <para>
+An example of the contents of this file, as used by the TrailBlazer example, is:
+ </para>
+ <informalexample>
+ <programlisting>
+ <validator active="true" >
+ <service cdmFilePath="models/TrailBlazer.cdm"
+ participantType="LoanBrokerParticipant" >
+ <output epr="jms:queue/esb-tb-creditAgencyQueue" />
+ <input epr="jms:queue/esb-tb-creditAgencyQueue_reply" />
+ <output epr="jms:queue/esb-tb-jmsBankRequestQueue" />
+ <output epr="jms:queue/esb-tb-fileBankRequestQueue" />
+ <input epr="jms:queue/esb-tb-jmsBankResponseQueue" />
+ <output epr="jms:queue/esb-tb-customerNotifier" />
+ <input epr="jms:queue/esb-tb-fileBankResponseQueue" />
+ </service>
+ <service cdmFilePath="models/TrailBlazer.cdm"
+ participantType="CreditAgencyParticipant" >
+ <input epr="jms:queue/esb-tb-creditAgencyQueue" />
+ <output epr="jms:queue/esb-tb-creditAgencyQueue_reply" />
+ </service>
+ <service cdmFilePath="models/TrailBlazer.cdm"
+ participantType="BankParticipant" >
+ <input epr="jms:queue/esb-tb-jmsBankRequestQueue" />
+ <input epr="jms:queue/esb-tb-fileBankRequestQueue" />
+ <output epr="jms:queue/esb-tb-jmsBankResponseQueue" />
+ <output epr="jms:queue/esb-tb-fileBankResponseQueue" />
+ </service>
+ <service cdmFilePath="models/TrailBlazer.cdm"
+ participantType="NotifierParticipant" >
+ <input epr="jms:queue/esb-tb-customerNotifier" />
+ </service>
+ </validator>
+ </programlisting>
+ </informalexample>
+
+ <para>
+The 'validator' element has a single boolean attribute called 'active',
which determines whether active or passive validation is used. Active validation means
that any erronous messages, that conflict with the behaviour as described in the
choreography, should be prevented from being received or sent. Passive validation means
that the message will continue to be received or sent, and errors will only be reported
for information purposes.
+ </para>
+ <note>
+ <para>
+ It is important to note that if 'active' validation is used, then the
validation mechanism will be an integral part of the message flow. This may have a slight
performance impact on the delivery of messages between services.
+ </para>
+ </note>
+ <para>
+Within the 'validator' element is a list of 'service' elements, one per
service being validated. The behaviour of the service being validated is identified by
specifying the choreography model and the participant type within the choreography model.
Therefore, within the above configuration, the first set of destinations (eprs) are
associated with the <emphasis>LoanBrokerParticipant</emphasis> defined within
the choreography description model found in the file
<filename>model/TrailBlazer.cdm</filename>, which will be located within the
<emphasis>overlord-cdl-validator.esb</emphasis> bundle.
+ </para>
+ <para>
+The elements contained within the 'service' element define the
<emphasis>input</emphasis> and <emphasis>output</emphasis> eprs
(Endpoint References) that are associated with the service. The
<emphasis>input</emphasis> eprs are the destinations on which messages will be
received and the <emphasis>output</emphasis> eprs are the destinations on
which messages will be sent by the service.
+ </para>
+ <para>
+The format of the 'epr' attribute will be specific to the type of transport used
for the ESB aware destination. Currently only JMS is supported, and can be identified by
the protocol prefix 'jms:'.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Local Configuration using
<emphasis>ValidationAction</emphasis></title>
+ <para>
+Although it is preferrable to validate an .esb bundle using the central configuration,
there are times when it is not possible to know the specific destination used to send a
message to or from a service. In these situations, it will be necessary to explicitly
insert an action into a service descriptor's action pipeline, to observe the message.
+ </para>
+ <para>
+This can be achieved using the
<emphasis>org.pi4soa.jbossesb.validator.ValidationAction</emphasis>, which can
be configured with the following properties:
+ </para>
+
+ <informalexample>
+ <programlisting>
+ <action name="LoanBrokerValidatorAction1"
+ class="org.pi4soa.jbossesb.validator.ValidationAction"
+ process="processMessage" >
+ <property name="cdmFilePath" value="models/TrailBlazer.cdm"
/>
+ <property name="participantType"
value="LoanBrokerParticipant" />
+ <property name="inbound" value="true" />
+ <property name="request" value="true" />
+ </action>
+ </programlisting>
+ </informalexample>
+
+ <para>
+The <emphasis>cdmFilePath</emphasis> references the choreography description
model, which will usually be a relative path within the
<emphasis>overlord-cdl-validator.esb</emphasis> bundle. The
<emphasis>participantType</emphasis> property defines which participant the
validator action is representing. The optional <emphasis>inbound</emphasis>
property indicates whether the message on the action pipeline is being received (true) or
sent (false). The optional <emphasis>request</emphasis> property can be used
to determine whether the message on the action pipeline represents a request (true) or
response/notification (false).
+ </para>
+ </section>
+ </section>
+</chapter>