[overlord-commits] Overlord SVN: r355 - in cdl/trunk/docs/docbook/userguide/src/main: module and 1 other directory.

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> + &lt;properties name="filters"> + ... + &lt;property name="org.jboss.soa.esb.filter.10" + value="org.pi4soa.jbossesb.validator.ValidatorFilter"/> + &lt;/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> + &lt;validator active="true" > + &lt;service cdmFilePath="models/TrailBlazer.cdm" + participantType="LoanBrokerParticipant" > + &lt;output epr="jms:queue/esb-tb-creditAgencyQueue" /> + &lt;input epr="jms:queue/esb-tb-creditAgencyQueue_reply" /> + &lt;output epr="jms:queue/esb-tb-jmsBankRequestQueue" /> + &lt;output epr="jms:queue/esb-tb-fileBankRequestQueue" /> + &lt;input epr="jms:queue/esb-tb-jmsBankResponseQueue" /> + &lt;output epr="jms:queue/esb-tb-customerNotifier" /> + &lt;input epr="jms:queue/esb-tb-fileBankResponseQueue" /> + &lt;/service> + &lt;service cdmFilePath="models/TrailBlazer.cdm" + participantType="CreditAgencyParticipant" > + &lt;input epr="jms:queue/esb-tb-creditAgencyQueue" /> + &lt;output epr="jms:queue/esb-tb-creditAgencyQueue_reply" /> + &lt;/service> + &lt;service cdmFilePath="models/TrailBlazer.cdm" + participantType="BankParticipant" > + &lt;input epr="jms:queue/esb-tb-jmsBankRequestQueue" /> + &lt;input epr="jms:queue/esb-tb-fileBankRequestQueue" /> + &lt;output epr="jms:queue/esb-tb-jmsBankResponseQueue" /> + &lt;output epr="jms:queue/esb-tb-fileBankResponseQueue" /> + &lt;/service> + &lt;service cdmFilePath="models/TrailBlazer.cdm" + participantType="NotifierParticipant" > + &lt;input epr="jms:queue/esb-tb-customerNotifier" /> + &lt;/service> + &lt;/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> + &lt;action name="LoanBrokerValidatorAction1" + class="org.pi4soa.jbossesb.validator.ValidationAction" + process="processMessage" > + &lt;property name="cdmFilePath" value="models/TrailBlazer.cdm" /> + &lt;property name="participantType" value="LoanBrokerParticipant" /> + &lt;property name="inbound" value="true" /> + &lt;property name="request" value="true" /> + &lt;/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>