JBoss.orgCommunity Documentation

Eclipse User Guide

Testable Architecture

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 (or BPMN process model) 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 design and/or implementation for each service.

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 not web service specific.

More recently the BPMN standard, under the guidance of the OMG, has introduced its own Choreography Model to complement the previous Process and Collaboration Models.

The purpose of a Choreography 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.

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, choices and parallelism to be described. In WS-CDL and BPMN2 Choreography, 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.

In Choreography 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.

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.

An interaction represents the exchanging of a message from one role to another role(s).

This is achieve by dragging a link between the 'originating' (or 'source') role to the 'destination' (or 'target') role. This will cause 'send' and 'receive' message events to be added to the source and target roles, with a link between drawn between them.

While the link is selected, go to the Properties view to set the relevant properties for the message.

The "Error Expected" property is a checkbox that can be used to indicate that this message is expected to be incorrect when used for simulating or testing against other artifacts.

The "Operation" field represents the name of the operation being performed. In cases where the target architecture is message oriented, this may not seem necessary, however it can be useful to clarify the purpose of the interaction.

The optional "Fault" field is used to provide a fault name for the interaction, in situations where the message exchange represents a fault response.

The "Parameters" list represents the one or more pieces of information that should be exchanged with the message. Pressing the 'Add' button will show another dialog window:

The "Type" field represents a fully qualified type name. The value within the curly braces defines the namespace, and the remaining text is the 'local part'.

The "Value" field represents a path to the file containing the example message value. The path can define a relative path, as in the image above, from the scenarios location. So this example indicates that the message value file ( BuyRequest.xml ) is in the same folder as the scenario file that is referencing it.

Once the parameter has been defined, it will be displayed in the parameters list as above and the text associated with the message link will be updated to summarize the information.

It is also possible to select the individual send and/or receive message events from the palette and attach them to the appropriate roles, with or without a link to connect them. For example, if a 'send message event' is placed on a Role, with the associated message information, this will indicate that the role sends a message but the intended recipient does not get it for some reason.

This is an example of where we want to represent an invalid (or negative) use case. Although this may seem counter intuitive, it can be useful to be able to specify anti use cases, as a way to document situations that we don't want to be implemented. Through the use of the 'Error Expected' field (associated with the Message Link properties) it is also possible to identify which parts of these negative scenarios should observe errors, and therefore can be used for automated testing.

The scenario simulation is triggered either using the button on the toolbar, or the "Scenario->Simulate" menu item on the context menu associated with the diagram background:

This will display a dialog window to capture information used to simulate each of the roles defined in the scenario, e.g.

The next step is to associate a model with one of the roles. This is achieved by selecting the "..." button next to the model field, which allows the user to select the model file. A model file can be anything - if the file is a supported representation, then its selection will result in the "Model Role" and "Simulator" combo boxes being populated with valid values.

The "Model Role" field displays a list of roles that are derived from the selected model. This enables the role name defined in the scenario (shown in blue associated with the border), to be associated with the role within the model.

The "Simulator" field displays the list of simulators that can be used to validate the scenario against the model. Some model types may have more than one simulator implementation - this will be discussed more in subsequent sections. When a new simulator is selected, then the "Model Role" list will be updated based on the list of model roles determined by that simulator.

Once the first model has been selected, the user will be prompted to ask whether the same model should be used for all roles in the scenario.

If the model that was selected was specific to the role (i.e. it represented an implementation just relevant to the particular role), then press the No button. However if the model is associated with more than one role in the scenario (i.e. a choreography), then pressing the 'Yes' button populates the simulation dialog, using the "best guess" to select the model role relevant for the scenario role.

When the "Simulate" button is pressed, then message events (associated with the specific roles) in the scenario are simulated against the models specified in the dialog. If the message event is valid, its node will be displayed in green. If however the event is unexpected, then it will be displayed in red. When this occurs, either select the message link or particular red node, and then pick the "Simulation Log" tab at the bottom, to see log information returned from the simulator regarding the erroneous events.

NOTE: If a scenario 'message event' has been marked as 'Error Expected', then it will be displayed with a red border - but when simulated, the color within the message event node will be green if the node failed as expected, but red if the event did not generated an error.

Finally the simulation can be reset,

When a Choreography Diagram is initially created, it will create a default Choreography Task. It is possible to simply change this information as the starting point for your diagram, but for the purposes of this article we will create a choreography task from scratch – so select this default choreography task and delete it.

Components to be included in the Choreography Diagram are provided in the palette on the right hand side of the canvas. We initially want to start the diagram with a “Start Event”, a “Choreography Task” and a “Sequence Flow” to connect the two. This should then look like this....

The Properties view will show the details for the newly create Choreography Task, allowing you to change its name to something that reflects what it represents, e.g. “Submit Purchase Order”.

The next step is to establish the Participants that will be performing the interaction associated with the Choreography Task. As shown in the diagram, the Choreography Task has a short cut button (also available via its context menu) to add a participant.

When this button is pressed, it will add a new participant to the task, or if available, also present a list of existing participants that can be selected. The first participant added to the choreography task will be considered the 'initiating participant', which means it will send the message. If two messages are associated with the same choreography task (e.g. representing a request/response pattern), then the initiator sends the request, and the other participant would return the response. In general, only associate two messages with a choreography task if the associated 'operation' will only have the single response type. If it has multiple response types (e.g. one normal and one or more faults), then separate choreography tasks should be used – as will be seen later in the purchasing example.

When the participant band has been added to the choreography task, it can be selected to focus the Properties view on its properties. The name can then be changed to something more meaningful, for example Buyer. The following image shows the task after both participants have been added and their names changed.

Now that we have defined the choreography task to represent an interaction from the Buyer to the Seller, we now need to describe the message that will be passed between them.

As with adding participants, there is a short cut button (and context menu item) for adding a message, associated with the participant band that is sending the message. So in the image above, adding a message to the Buyer would define the request, as the Buyer is the initiator for this task (denoted by its white background).

As with the 'Add Participant' action, if there are existing message definitions, then these will be presented to the user to enable them to select a previously defined message. Otherwise a message icon will simply be added.

The user can now select this message 'envelope' to view its properties and set its name, e.g. “BuyRequest”.

However the BuyRequest name is only a logical name, it does not define the details of the message structure. This is ok when we are simply sketching the high level representation of a choreography, but to enable the choreography to represent concrete details, we need to associate the message with an item definition.

In the Properties view associated with the selected message there is an 'Item' field. This allows the user to select a previously defined message type (e.g. from an imported XSD schema), or if an appropriate entry does not exist, then we can press the 'Create New' button.

The 'Item Kind' field will always be 'Information', unless defining some abstract choreography describing how physical items are exchanged. The 'Data Type' field references the detailed message schema type. To set the field, press the 'Edit...' button and set the value:

NOTE: Currently this only enables a free format string value to be defined – but should bring up the import dialog and enable the user to select a specific type, creating the import entry on the fly if necessary.

Now that the message details have been provided, the diagram displays that information in place of the logical message name.

NOTE: Currently does not actively update after this information is set – or when the message name is changed (when no item definition set).

Although the choreography diagram (and underling model) now shows how messages are exchanged by participants in the choreography, these exchanges have not been defined in an SOA context, based on service interfaces. Therefore we also need to define (within the model) how these message exchanges are grouped into message exchange patterns (MEP) on interfaces associated with the participants.

Although this can be achieved by adding Interface and Operation components within the model, and establishing the appropriate associations from the participants to the interfaces, there is a short cut that will derive this information from the interactions in the model.

However before invoking this utility, we have one final step that needs to be done. In the preceding sections you have seen how to create messages and exchange them between participants as part of a Choreography Task. Although this is adequate information from a message passing perspective, as it defines a reference to the specific message schema that is used, it does not indicate whether the message exchange represents a fault associated with a preceding request.

Therefore it is necessary to distinguish whether a particular message type is actually a fault (or error), to enable the service interface derivation to correctly distinguish between normal and fault responses in a service operation.

For each message type that needs to be highlighted as a fault, we need to create an Error component that references the same item definition. This Error component will essentially define the fault code for the fault, which will be used when constructing the RPC operation signature.

Select the Data Items tab, from the Properties associated with the diagram canvas, and expand the Error List :

Using the 'Add' button, create a new entry and configure its details to reference the required item definition (representing the message schema) and error code:

Once all of the required Error components have been created and configured, then select the " Savara->BPMN2->Add Service Interfaces " menu item, associated with the BPMN2 choreography file, to create the appropriate interfaces and establish the necessary relationships.

The Savara Eclipse tooling includes the ability to generate services from source models. These models can vary, including (currently) choreographies and BPEL process definitions.

Select the "Savara->Generate->Service" menu item associated with the context menu of the source model. For example,

This will display a dialog window to allow the user to select how each role, identified within the source model, should be generated as a service design or implementation:

The "Service Role" check box is used to indicate whether that role, within the source model, should result in a service being created.

The "Project Name" field is used to enter the name of the project that will be generated. The project name is constructed from a combination of the model name and the role. If the project already exists, then the background of this field will be red, and the OK button will be disabled until either the service role checkbox for that role is unchecked, or the project name changed.

The "Service Type" field displays a list of service generation types. This list will be dependent upon the source model type, and so will not be discussed in detail here. The particular structure of each generated project will be dependent upon the service type selected. Some of these service types will relate to implementation technologies (e.g. SCA Java and BPEL), while others may be used to represent a service design (e.g. BPMN2 Process - although a BPMN2 Process can also evolve into an executable implementation).

When the OK button is pressed, each of the projects for the enabled roles will be created with their relevant artifacts.

NOTE: The list of target 'service types' is not related to the source model type. So (for example) if the source model is a BPEL process definition, then it is still possible that BPEL will be offered as a target service type. Although this may seem redundant, it can offer the opportunity to generate a abstract skeleton (observable behavior) version of a fully implemented executable BPEL process.

Revision History
Revision 2-0Feb 9th 2012Gary Brown
Initial version