JBoss.orgCommunity Documentation

SAVARA 1.1

User Guide


The SAVARA project aims to leverage the concept of a choreography (or conversation) description to provide design-time and run-time governance of an SOA.

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.

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.

This document will outline how the Choreography Description is being used as part of SAVARA to provide SOA governance capabilities for each phase of the SOA lifecycle.

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 SAVARA enables a skeleton implementation to be generated as a service implementation (e.g. WS-BPEL process).

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.

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.

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.

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.

When a 'structured' implementation language has been used, such as WS-BPEL, it will be possible to infer the behaviour of the service being implemented, to compare it against the choreography description.

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.

There are two other areas where a choreography description can be used as part of design-time governance, that are not currently implemented in SAVARA:

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.

This section explains how to configure the conversation validation mechanism to validate services against a choreography description. The first sub-section describes how the mechanism is hooked into the JBossESB and JBossWS-Native environments. The following two sub-sections explain two alternate ways that relevant endpoint references can be configured for validation.

The principle mechanism used for validating conversations within the JBossWS Native stack is through the use of a global filter registered in the standard-jaxws-client-config.xml and standard-jaxws-endpoint-config.xml files. These files are located in the $JBossAS/server/default/deployers/jbossws.deployter/META-INF folder.

The standard-jaxws-client-config.xml is updated to include a <emphaiss>pre handler</emphaiss> implemented by a Savara client interceptor.

The standard-jaxws-endpoint-config.xml is updated to include a <emphaiss>pre handler</emphaiss> implemented by a Savara server interceptor.

These interceptors are installed as part of the installation process for the SAVARA distribution.

The information concerning which destinations will be validated, and to which model/role they relate, can be explicitly defined within the validator-config.xml file, contained within the savara-validator-jbossesb.esb bundle.

An example of the contents of this file, that would related to the TrailBlazer example, is:



    <validator mode="monitor" replyToTimeout="10000" >
        <service model="TrailBlazer.cdm" 
                    role="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 model="TrailBlazer.cdm" 
                    role="CreditAgencyParticipant" >
            <input epr="jms:queue/esb-tb-creditAgencyQueue" />
            <output epr="jms:queue/esb-tb-creditAgencyQueue_reply" />
        </service>
        <service model="TrailBlazer.cdm" 
                    role="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 model="TrailBlazer.cdm" 
                    role="NotifierParticipant" >
            <input epr="jms:queue/esb-tb-customerNotifier" />
        </service>
    </validator>
                 

The 'validator' element has an optional attribute called 'mode', with the possible values of 'monitor' or 'manage'. If the mode is 'monitor' (which is the default), then any messages that result in validation errors being detected will continue to be received or sent, with the errors only be reported for information purposes. If the mode is 'manage', then any erronous messages detected during validation, that conflict with the behaviour as described in the choreography, will be prevented from being received or sent.

The optional 'replyToTimeout' (defined in milliseconds) is used to determine how long a dynamic reply-to destination should be monitored for validation purposes. In some message exchanges, the response destination will not always be known in advance. Therefore the configuration can identify such situations, and monitor the reply-to destination for the response. However, if a response is not delivered in a particular time period, we need to be able to discontinue the validation of the dynamic endpoint. If this did not occur, then over time too many endpoints would be monitored, which may result in out-of-memory problems. The default timeout period is 10 seconds.

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 model (e.g. choreography description file) and the role (e.g. participant type) within the model. Therefore, within the above configuration, the first set of destinations (eprs) are associated with the LoanBrokerParticipant defined within the choreography description model found in the file TrailBlazer.cdm, which will be located within the models folder contained within the savara-validator-jboss.sar bundle.

The elements contained within the 'service' element define the input and output eprs (Endpoint References) that are associated with the service. The input eprs are the destinations on which messages will be received and the output eprs are the destinations on which messages will be sent by the service.

The format of the 'epr' attribute will be specific to the type of transport being validated. Currently JMS is supported, and can be identified by the protocol prefix 'jms:', or a Web Service endpoint using a service name with the QName style of '{namespace}localpart'.

Each 'input' and 'output' element can also define an optional 'dynamicReplyTo' boolean attribute. If defined, it will indicate to the Service Validator that the message on the specified endpoint (epr) will contain a dynamically defined 'reply-to' destination that needs to be monitored for a response.

The first step to configuring the validator is to associate the endpoint references (EPRs) against the relevant choreography interactions. This is achieved by defining an annotation for each 'exchange details' component (i.e. each request and response/notification).

When the annotation editor is displayed for the relevant 'exchange details' component, the validator annotation should be added. This is achieved by selecting the popup menu associated with the background of the lefthand panel, and selecting the Add Defined Annotation menu item.

When the list of defined annotations is displayed, select the validator annotation.

After pressing the Ok button, the annotation editor will configure the righthand panel with the parameters associated with this annotation.

To specify the Endpoint Reference (EPR) for a particular message exchange, enter the EPR into the Destination field. The value specified in this field will be dependent upon the technology being validated. For example, if the JBossESB is being monitored, then the value will be a physical address associated with the ESB service endpoint (e.g. jms:queue/esb-quotes). If the technology being validated is a Web Service (or BPEL process), then the field will represent the WSDL service name specified using the QName style (e.g. {namespace}localpart).

The Type field is used to define the style of endpoint being validated. In the image above, the endpoint being validated is a Web Service (or BPEL process), and therefore the type is specified as a 'service name'. However if the technology being validated identifies a different endpoint address, for the request and response (as in the case of JBossESB), then the type should be set to 'endpoint address'.

If the exchange is a request, that will result in a response being sent on a dynamically provided "reply-to" destination, then the Dynamic Reply-To checkbox should be selected. This situation may occur in the case of validating a JBossESB service, where a well-defined endpoint address has not been defined for the response.

Once the annotation has been defined, then press the Save button to save the annotation against the interaction's exchange details.

When all of the relevant 'exchange details' components have been configured with a validator annotation, defining the EPR to be validated, then the choreography description file can be copied into the savara-validator-jboss.sar/models folder. This will cause the validation mechanism to derive the configuration information from the choreography description model, and begin validating the defined destinations against that choreography description model.

As well as validating the interactions between a set of services, against a pre-defined choreography description, it is also possible to use the Service Validators in a non-validating record mode.

This will be useful in situations where a choreography description does not currently exist, and we wish to use the stream of business events being sent and received by each identified service (or participant type) to gain an understanding of the current business process.

An example of this type of configuration, associated with the TrailBlazer example, is:



    <validator>
        <service role="LoanBrokerParticipant" validate="false" >
            <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 role="CreditAgencyParticipant" validate="false" >
            <input epr="jms:queue/esb-tb-creditAgencyQueue" />
            <output epr="jms:queue/esb-tb-creditAgencyQueue_reply" />
        </service>
        <service role="BankParticipant" validate="false" >
            <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 role="NotifierParticipant" validate="false" >
            <input epr="jms:queue/esb-tb-customerNotifier" />
        </service>
    </validator>
                 

To define a Service Validator in record only mode, the model attribute is not specified (because no choreography description exists to be validated against), and the optional validate attribute should be set to false (by default this attribute is true).