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

Author: objectiser Date: 2008-10-02 10:56:11 -0400 (Thu, 02 Oct 2008) New Revision: 359 Added: cdl/trunk/docs/docbook/userguide/src/main/images/setconversationtype.png Modified: 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 cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml Log: Converted some of the 'conversation aware' ESB guide into docbook format. Added: cdl/trunk/docs/docbook/userguide/src/main/images/setconversationtype.png =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/setconversationtype.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml 2008-10-02 06:02:08 UTC (rev 358) +++ cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.xml 2008-10-02 14:56:11 UTC (rev 359) @@ -4,11 +4,308 @@ <chapter id="conversationawareesb"> <title>Conversation Aware ESB</title> <section> - <title></title> + <title>Conversation based Conformance</title> <section> - <title></title> + <title>Overview</title> <para> +The term "conversation" represents a structured set of interactions (or message exchanges) between one or more peer to peer services, to conduct a business transaction. The "conversation" is defined from a service neutral (i.e. global) perspective. </para> + <para> +This document explains how such a "conversation" description can be used to ensure conformance of one or more service implementations, within an ESB, during the design and implementation phase of the system. + </para> + <para> +This section introduces the choreography description language (CDL) defined by W3C, which is a standard notation for defining conversations from a global perspective, and the <emphasis>pi4soa</emphasis> open source project which provides an editor for creating choreography descriptions, as well as utilizing these descriptions for conformance checking, monitoring and execution purposes. + </para> + <para> +Finally the section will provide a brief discussion of how CDL can be used to provide conformance checking of an ESB, through the use of 'conversation aware' ESB actions. + </para> </section> + <section> + <title>CDL Conformance Checking</title> + <para> +In general, conformance checking is the procedure for ensuring that a component has been correctly built according to some specification or standard. In terms of CDL, it more specifically ensures that one or more services perform their responsibilities correctly in accordance with the choreography description. + </para> + <para> +The <emphasis>pi4soa</emphasis> tools suite provide the mechanism for producing service endpoint descriptions for each service within a choreography description. The relevant service descriptions can then be compared (for conformance) against their ESB service implementations. + </para> + <para> +However, to make this possible, it is necessary to be able to derive the communication 'type' structure from the ESB implementation, i.e. where messages (of particular types) are sent and received, where decision points are, where actions are performed concurrently, etc. + </para> + <para> +This is why a specific set of 'conversation aware' ESB actions have been defined (discussed in a later section), to make it possible to derive the communication 'type' structure from an ESB service implementation. + </para> + <para> +Once the communication 'type' structure has been obtained from the ESB implementation, it can be compared against the relevant service endpoint description projected from the choreography description, to determine if there are any differences. These can then be reported to the ESB service developer, so that they can fix the problems, before the service is deployed to the runtime environment. + </para> + <para> +This ensures that all of the services will interaction correctly, as they will all have been validated against the choreography, and therefore work together by design. + </para> + </section> </section> + + <section> + <title>JBossESB "Conversation Aware" ESB Actions</title> + <section> + <title>Overview</title> + <para> +This section outlines the various "conversation aware" ESB actions that can be used to make the communication behaviour of a service implementation explicit, thus enabling it to be compared for conformance against a description of the expected behaviour. + </para> + </section> + <section> + <title>Conversational Service</title> + <para> +The top level component is the <emphasis>Service</emphasis>, which will have a single endpoint reference (i.e. service category and name) that will be used by external clients (or other services) that interact with this service. + </para> + <para> +However the service behaviour is stateful, and therefore will need a means of routing the inbound request to the appropriate service descriptor that is (a) capable of handling the request, and (b) the service instance is in an appropriate state where the service descriptor can be executed. + </para> + + <section> + <title>Message Router Action</title> + <para> +The action used to perform routing of the inbound requests is called <emphasis>MessageRouterAction</emphasis>, for example: + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + + <service category="ESBBroker.BrokerParticipant" name="ESBBrokerProcess" description=""> + <listeners> + <jms-listener name="BrokerServiceListener" + busidref="BrokerService" + maxThreads="1"/> + </listeners> + <actions mep="OneWay"> + <action class="org.jboss.soa.overlord.jbossesb.actions.MessageRouterAction" + process="process" name="s0-1"> + <property name="paths"> + <route service-category="ESBBroker.BrokerParticipant" + service-name="ESBBrokerProcess.main" + initiate="true"> + <identity type="primary" > + <token name="id" locator="//@id" /> + </identity> + <message type="enquiry" /> + </route> + <route service-category="ESBBroker.BrokerParticipant" + service-name="ESBBrokerProcess.main.5" > + <identity type="primary" > + <token name="id" locator="//@id" /> + </identity> + <message type="buy" /> + <message type="cancel" /> + </route> + </property> + </action> + </actions> + </service> + ]]></programlisting> + </informalexample> + + <para> +In this example, the 'service' endpoint reference will be associated with the service category "ESBBroker.BrokerParticipant" and name "ESBBrokerProcess". All inbound requests to an instance of this service will be routed via this service descriptor. + </para> + <para> +This service descriptor therefore only has a single action, which represents the message routing capability. The action class is <emphasis>org.jboss.soa.overlord.jbossesb.actions.MessageRouterAction</emphasis>. This action only defines a single property 'path' which defines one or more 'route' elements. The attributes associated with this 'route' element are: + </para> + <para> + <itemizedlist> + <listitem> +service-category and service-name, together identify the service descriptor that should be invoked if this route is selected + </listitem> + <listitem> +an optional 'initiate' boolean attribute. If the attribute is specified, and its value is 'true', then the route can only be selected if the service instance relevant for the inbound message does not yet exist, and this message will result in a <emphasis>CreateSessionAction</emphasis> being invoked to create the service instance. If the attribute value is 'false', or not specified, then a service instance must already exist that is capable of handling the inbound message. + </listitem> + </itemizedlist> + + </para> + <para> +The 'route' element will contain one or more 'identity' elements, and one or more 'messageType' elements. + </para> + <para> +The 'identity' element is used to extract information from the inbound message that can be used to identify the appropriate service instance. The only attribute on the 'identity' element is the type of identity, which can be: + </para> + + + <para> + <itemizedlist> + <listitem> +primary +<para> +the primary identity field, used to associate a message with the session +</para> + </listitem> + <listitem> +alternate +<para> +an alternative primary identity +</para> + </listitem> + <listitem> +association +<para> +link the message to a session based on an identity previously associated with the session (or parent session). However this identity will not be associated with the current session, it is usually only used to link a child session to a parent session +</para> + </listitem> + <listitem> +derived +<para> +the extracted identity will be placed in reserve for use as the primary identity for a subsequent session. It is not directly associated with the session in which it is discovered +</para> + </listitem> + </itemizedlist> + </para> + + + + + <para> +The one or more 'token' definitions contained within the 'identity' element provide the details regarding the structure of the identity. The token has 'name' and 'locator' attributes, the locator being used to provide an expression that locates the identity information within the inbound message. If more than one token is defined, it provides a composite identity (i.e. made up of multiple parts). + </para> + <para> +The one or more 'messageType' elements, contained within the 'route' element, defines the message type(s) that should be routed to the service descriptor associated with the 'route' element. + </para> +<note> +If a route is marked as <emphasis>initiate='true'</emphasis>, with the correct message type for an inbound message, but a service instance already exists for the identity information extracted from the message, then the route will not be selected. The converse is also true. +</note> + +<note> +Similarly, even if a message type match is found, if the service instance is not in an appropriate state to invoke the target service descriptor, then the route will not be selected. +</note> + <para> +If no routes are found for a particular inbound message, then an exception will be reported. + </para> + + </section> + </section> + <section> + <title>Establishing Correspondance between ESB Configuration and Choreography</title> + <para> +All actions (and therefore service descriptors) for a particular service implementation must be defined within the same ESB configuration file. This is a current requirement, to ensure that all of the inter-related service descriptors are available to support the static validation (e.g. conformance checking). + </para> + <para> +The <filename>jboss-esb.xml</filename> file must be defined within either the same Eclipse project as the <emphasis>pi4soa</emphasis> choreography description (.cdm file), or in a project that has a 'project reference' to the project containing the choreography description. + </para> + <para> +To establish the link between the choreography description and the <filename>jboss-esb.xml</filename>, both must 'implement' a common <emphasis>conversation type</emphasis>. + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ + + <action class="org.jboss.soa.overlord.jbossesb.actions.CreateSessionAction" + process="process" name="..."> + .... + <property name="conversationType" + value="jboss.overlord.samples.LoanBroker@Broker" /> + .... + </action> + ]]></programlisting> + </informalexample> + <para> +The <emphasis>conversation type</emphasis> is specified in the <emphasis>CreateSessionAction</emphasis> ESB action, described later in this section, and is associated as a semantic annotation against the relevant Participant Type or Participant Instance within the choreography description. + <para> + </para> +To associate the <emphasis>conversation type</emphasis> with either the Participant Type or Instance, open the choreography description in the <emphasis>pi4soa</emphasis> choreography designer. Then select the "Choreography->Edit Annotations" menu item from the context menu associated with the Participant Type or Instance. In the lefthand panel, select "Add Freeform Annotation" from the context menu, then specify "conversationType" as the annotation type and press 'Ok'. Then select the 'Annotation' tab in the righthand panel, and enter the conversation type, e.g. "jboss.overlord.samples.LoanBroker@Broker". Note the '@' is important, as the following word indicates the 'role' associated with the conversation type which precedes the '@' symbol. + </para> + + <imagedata fileref="images/setconversationtype.png" width="4in" /> + + + </section> + <section> + <title>Managing Sessions</title> + <para> +A "session" represents a specific instantiation of a service definition that is involved in a business transaction (or conversation). The "session" will be distinguished based on unique identity information relevant to the business transaction, that is derived from specific properties within the messages being exchanged by the interacting services. + </para> + <para> +The service description can be composed from other reusable sub-service descriptions, although the service can only define a single 'root' (i.e. top level) definition. + </para> + <section> + <title>Business State and Logic</title> + + <para> +Each top level or sub-service description will be associated with a business state 'pojo' class that contains its business relevant information and logic (i.e. methods). This class is identified by the property 'session', which will be associated with the initial conversation based ESB actions in a service (or sub-service) description, or in any subsequent conversation based ESB actions that require the information to determine the session instance. + </para> + <para> +As well as representing the business state and logic for a session (or sub-session), the pojo can define an annotation that provides information about the session. The annotation type is <classname>org.jboss.soa.overlord.jbossesb.actions.Service</classname>. + </para> + + <informalexample> + <programlisting> + + package org.jboss.soa.overlord.samples.jbossesb.loan.broker; + + import org.jboss.soa.overlord.jbossesb.actions.Service; + + @Service(name="{http://www.jboss.org/overlord/loanBroker}Broker", + conversationType="jboss.overlord.samples.LoanBroker@Broker", + root=true) + public class BrokerMain { + .... + } + </programlisting> + </informalexample> + + <para> +The 'name' attribute represents a name associated with the complete service description, encompassing both top level and composed sub-session behaviour. The 'root' attribute indicates whether this pojo is related to the top level session, or a sub-session. + </para> + <para> +For pojos that represent the 'root', or top level session, for a service description, they should also specify the optional 'conversationType' attribute. This expresses the type that will be checked for conformance, and is comprised of two parts separated by the '@' symbol. The first part is a fully qualified name of the conversation type. The second part represents the role being played within the conversation type. + </para> + <para> +If the <emphasis>Service</emphasis> annotation is not defined on the pojo, then the information (service description name, root and optional conversation type) must be explicitly defined in the relevant conversation based ESB actions. + </para> + + </section> + <section> + <title>Instantiating top level and child sessions</title> + </section> + + <section> + <title>Retrieving an existing session</title> + </section> + + </section> + <section> + <title>Interacting</title> + <para> + </para> + </section> + <section> + <title>Managing Information</title> + <para> + </para> + </section> + <section> + <title>Controlling Flow</title> + <para> + </para> + </section> + </section> + + <section> + <title>Generating a JBossESB Configuration from CDL</title> + <section> + <title>Overview</title> + <para> + </para> + </section> + <section> + <title>Generating the JBossESB Configuration</title> + <para> + </para> + </section> + </section> + + <section> + <title>Dealing with Conformance Issues</title> + <section> + <title>Overview</title> + <para> +<todo>Explain how conformance issues are reported and about the quickfix mechanism - including the standard ways to resolve problems</todo> + </para> + </section> + </section> + </chapter> + Modified: 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 2008-10-02 06:02:08 UTC (rev 358) +++ cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml 2008-10-02 14:56:11 UTC (rev 359) @@ -19,62 +19,7 @@ </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> Modified: cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml 2008-10-02 06:02:08 UTC (rev 358) +++ cdl/trunk/docs/docbook/userguide/src/main/module/getting_started.xml 2008-10-02 14:56:11 UTC (rev 359) @@ -1,260 +1,316 @@ -<?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> - - <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 - &gt; Software Updates...” menu item - </listitem> - <listitem> - From the <emphasis role="bold"> Available Software</emphasis> tab, press the “Add Site...” button - </listitem> - <listitem> - Press the “Local” 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 “Install” button and follow the instructions to install the plugins. - </listitem> - </itemizedlist> - </para> - </listitem> - - </orderedlist> - </section> - -</section> - -</chapter> +<?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.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> + + <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 - &gt; Software Updates...” menu item + </listitem> + <listitem> + From the <emphasis role="bold"> Available Software</emphasis> tab, press the “Add Site...” button + </listitem> + <listitem> + Press the “Local” 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 “Install” button and follow the instructions to install the plugins. + </listitem> + </itemizedlist> + </para> + </listitem> + + </orderedlist> + </section> + +</section> + +</chapter>