JBoss.orgCommunity Documentation

Chapter 2. SOA Governance with CDL

2.1. Design Time Governance
2.1.1. Creating a Choreography
2.1.2. Design Time Governance With WS-BPEL
2.1.3. Design Time Governance With "Conversation Aware" ESB Actions
2.1.4. Summary
2.2. Runtime Governance using Conversation Validation
2.2.1. Service Validator Configuration
2.2.2. Deploy the TrailBlazer Example
2.2.3. Starting the pi4soa Monitor
2.2.4. Running the Example
2.2.5. Detecting a Validation Error

The Choreography Description Language (CDL) provides a means of describing a process, that executes across a distributed set of services, from a global (or service independent) perspective.

SOA Governance, using CDL, is about ensuring a process is correctly implemented (as part of design-time governance), and executes as expected (part of runtime governance).

In this chapter we will take you through a worked example associated with each of these aspects.


Before proceeding, please make sure that the Overlord CDL distribution has been correctly installed and that the samples have been imported into the Eclipse environment.

When designing a system, it is necessary to capture requirements. Various approaches can be used for this, but currently there are no mechanisms that enable the requirements to be documented in such a way to enable an implementation to be validated back against the requirements.

The pi4soa tools provide a means of describing requirements, representing specific use cases for the interactions between a set of cooperating services, using scenarios - which can be considered similar to UML sequence diagrams that have been enhanced to include example messages.

In the purchasing-models Eclipse project, the SuccessfulPurchase.scn scenario looks like this:

The next step in the development process is to specific a Choreography Description to implement the requirements described within the set of scenarios. The choreography for the Purchasing example can be found in purchasing-models/PurchaseGoods.cdm. When the choreography editor has been launched, by double-clicking on this file within the Eclipse environment, then navigate to the Choreography Flows tab to see the definition of the purchasing process:

The pi4soa tools can be used to test the scenarios against the choreography description, to ensure that the choreography correctly implements the requirements. To test the SuccessfulPurchase.scn scenario against the choreography, launch the scenario editor by double-clicking on the scenario file, and then pressing the green play button in the toolbar. When complete, the scenario should look like the following image, indicating that the scenario completed successfully.

To view a scenario that demonstrates a test failure, open the InvalidPurchase.scn scenario by double-clicking on the file, and then initiate the test using the green play button in the toolbar. When complete, the scenario should look like the following image.

You will notice that the Store participant has a red 'send' node, indicating that this action was not expected behaviour when compared with the choreography description. The reason this is considered an error, is that the Store participant should only send a BuyFailed message following an invalid credit check.

When an error is detected in a scenario, the choreography designer can then determine whether the scenario is wrong (i.e. it does not correctly describe a business requirement), or whether the choreography is wrong and needs to be updated to accomodate the scenario.

Once the choreography description has been successfully tested against the scenarios, and therefore is shown to meet the business requirements, the next step is to design and implement each service involved in the choreography. The pi4soa tools provide the means to export BPMN, UML or HTML documentation to aid the implementation phase. However there is special support for a concept called "Conversation Aware" ESB Actions.

Once we have a choreography description, it is possible to generate an ESB Service (with conversation aware ESB actions), for each of the participants defined within the choreography. To try this out, select the Overlord->Generate->JBossESB Services menu item from the popup menu associated with the PurchaseGoods.cdm.

This will display a dialog listing the possible services that can be generated from this choreography, with a proposed Eclipse project name.

To test out this feature, uncheck the Buyer and CreditAgency participants, leave the build system as Ant, select the messaging system appropriate for your target environment and press the 'Ok' button. This will create a single new project for the Store participant.

Depending upon the value of the 'stateless' checkbox, the generated ESB service artefact (jboss-esb.xml) will either use a stateful or stateless approach for encoding the behaviour of the service. The difference relates to whether the Overlord infrastructure explicitly maintains state information about session instances, to help police the behaviour of individual transactions, or whether this is implicitly performed using other capabilities (such as the Conversation Validation mechanism described in the following section, which can be used as an external monitor to ensure the service behaves as expected).

The generated project includes the ESB configuration file (in the src/conf folder) and the relevant Java classes in the src/java folder. The contents of this project represents a template of the service. Before it can be executed, the ESB configuration file will need to be enhanced to include internal implementation details for the service. The contents of this generated project should be compared to the completed version in the purchasing-store project.


When the project is generated, if errors are reported against the jboss-esb.xml, then simply double-click on the error to launch the ESB configuration file. Then make a minor change, such as adding a new line and then removing it, and save the file again (to force re-validation). This should cause the errors to be cleared. This occurs because the Eclipse tasks that validate the jboss-esb.xml file and compiling the new Java classes in the project sometimes gets confused, causing the classes not to be present when the validation rules attempt to access them. This issue is being investigated.

The purchasing example describes the interactions between a Buyer, Store and Credit Agency. The flow for this example would be:

There are two alternate implementations of the services involved in the purchasing example, demonstrating both the stateful and stateless "conversation aware" ESB actions. The $Overlord/samples contains a sub-folder for each variation.

To run the purchasing example, firstly ensure that the JBoss Application Server has been fully configured as described in the Installation chapter, and then do the following:

In this example, the conversation ESB actions will do the validation in the runtime. As we've said, the client send the 'buyRequest' message to the store, firstly the store service will check the received message based on its messageType attribute. and then send another message to the 'credit agency' service it goes through its validation. If the messageType that store service received is not as same as the one defined in the conversational esb actions, it will throw out the exception and ends its flow.

Once services have been deployed, as mentioned in the previous section, we still need to be able to verify that the services continue to conform to the choreography description. The Conversation Validation capability within the Overlord CDL distribution can be used to validate the behaviour of each service.

In this section, we will use the Trailblazer example found in the $Overlord/samples/trailblazer folder and the trailblazer-models Eclipse project.

The JBossESB service validator configuration is defined using jbossesb specific annotations, that are associated with the 'exchange details' components (contained within interactions), within the choreography description.

To view the pre-configured service validator configuration defined for the Trailblazer example, edit the TrailBlazer.cdm file, navigate to the Choreography Flows tab and then select the Choreography->Edit Annotations menu item associated with the first 'exchange details' component (as shown below).

This will display the annotation editor, with the single configured annotation called 'jbossesb'. This annotation defines the information required for the Service Validator to monitor this specific message exchange (i.e. the JMS destination on which the message will be passed).

Once an annotation has been defined, it will also be displayed as part of the tooltip for the associated model component, for example:

One the jbossesb annotations have been defined for all relevant 'exchange details' components in the choreography description, the choreography file can be copied to the $JBossAS/server/default/deploy/overlord-cdl-validator.esb/models folder in the JBossAS environment. The service validator configuration for the trailblazer example has been preconfigured to be deployed as part of the installation procedure.


If the overlord-cdl-validator.esb/validator-config.xml within the JBossAS environment is modified, or choreography description files added, removed or updated within the overlord-cdl-validator.esb/models sub-folder, then the changes will automatically be detected and used to re-configure the service validators without having to restart the JBossESB server.

To run the example, you need to start a browser and select the URL localhost:8080/trailblazer. This will show the following page, if the server has been configured correctly and the TrailBlazer example deployed:

Now you can submit quotes, You will see either a loan request rejected (single email) because the score is less than 4, or two emails (one from JMS bank and one from FileBased bank) with valid quotes. When entering subsequent quotes, make sure that the quote reference is updated, so that each session has a unique id.