This section presents the different components that can be found in the Choreography Description. Although most of the concepts are very similar to their WS-CDL counterparts, some of the concepts are not directly related. Therefore, where necessary, the mapping between a Choreography Description component and its equivalent WS-CDL syntax will be explained.
The type definitions are primarily defined on the Base Types tab of the Choreography Description Designer. However the Role Type, Behavior and Relationship Type components can also be created using the Roles and Relationships tab.
Each of the different types will be discussed further in the following sub-sections.
The Participant Type represents an organizational unit that can assume one or more role types. This can be considered equivalent to a class implementing more than one interface.
It is important to understand that a participant will be responsible for maintaining the state information associated with each of the role types that it assumes. If two or more of those role types have a variable with the same name, then they each actually refer to the same piece of information.
The Role Type element defines a role that a participant may assume within the choreography. Interactions within a choreography are performed between role types, specifying a 'from role type' and a 'to role type'.
In version 1.0 of the WS-CDL specification, each Role Type can belong to only one Participant Type, so this effectively means that an interaction is being performed between the participants that are associated with the role types specified in the interaction.
However the pi4soa tools include an extension to the standard, to overcome this limitation. Therefore it is possible to treat the Role Type in the same manner as a Java interface, and have more than one participant (i.e. equivalent to a Java class) implement the same role type. The benefit of this is interactions defined within sub-choreographies can be re-used in conjunction with multiple participant types.
A Role Type element has only two properties, a unique name which will be used to reference it from the Relationship Type and Channel Type elements, and a description.
The Role Type must contain at least one Behavior element. This element associates an interface definition (generally WSDL) with the role type. The behavior element also has a unique name and description properties.
Multiple Behavior elements may be defined for a Role Type associating multiple service interface definitions with the same Role Type.
The Relationship Type element provides a static association between two Role Types. A relationship must exist between two Role Types to enable them to interact.
The properties for the Relationship Type are simply, the name, a description and then references to two Role Types. Each of the referenced role types can also optionally provide a subset of the behaviors it supports. If no behaviors are defined, then it is assumed that all behaviors for the role type are applicable.
As mentioned above, the Relationship Type represents a static association between two Role Types. The Channel Type represents a more dynamic concept. If a channel is thought of as a connection between a client and server, then the Channel Type only defines the Role Type associated with the server.
This enables the structure of the communication channels between the related participants to be dynamically changed during the course of a transaction. For example, a channel can be established from Role A to Role B, and then the participant acting as Role A could send its 'client' end of the channel to another participant (e.g. Role C). From this point, Role C can continue to communicate with Role A using the same channel instance. In this example, there would also need to be two Relationship Types, one from Role A to Role B, and another from Role C to Role B, to declare from a static perspective that these roles can communicate.
Therefore Channel Types are defined to support a more dynamic re-configuration of the communication paths between the participants in a conversation.
A Channel Type can define a set of restrictions on the use of its channel instances. These restrictions can include defining the types of communications that can be conducted over the channels, or limiting which other channels can be passed across an instance of this Channel Type. These restrictions can be statically checked to ensure that the choreography has used the instances of the channel type correctly.
The properties of the channel type are:
| Property | Description |
|---|---|
| Name | The name of the channel type |
| Description | Longer descriptive text to explain the purpose of the type within the choreography |
| Action | This property defines whether the channel type supports "request/response" or just "request" or just "response" messages |
| Role Type | This property identifies the destination role type associated with the channel type - this role type is effectively the provider of the service |
| Behavior | This field defines the optional behavior, within the identified role, that this channel type is associated with |
| Reference Token | This field identifies the type of the service endpoint reference |
| Usage | This field identifies the permitted usage pattern for the instances of this channel type - "once" means that only a single interaction can be performed on a channel instance, "unlimited" means that it can be used any number of times |
Within a complex choreography, that has multiple channel instances (whether the same or different channel type), it is necessary to ensure they each have their own identity. It is also important to understand how these many channel instances relate to each other within a particular choreography session instance.
The information required to derive the identity of a channel instance is defined using the 'Identity' element(s) under the channel type. This mechanism is described further in another section.
The Channel Type can declare restrictions on the channels that are passed (within an interaction) across an instance of this channel type. These restrictions are defined by creating a 'Passed Channel Details' element under the channel type. The properties for this element are:
| Property | Description |
|---|---|
| Name | The name of the channel type |
| Description | Longer descriptive text to explain the purpose of the passed channel restrictions |
| Action | This property defines whether the channel type can be passed within both a request/response, or only in either a request or a response |
| Channel | The channel type being passed |
| New | Whether the passed channel is being created, and the 'client' end of this new channel is being passed to enable the other end of the current channel instance to be able to 'callback' the participant sending the passed (newly created) channel instance |
The Information Type component is used to provide abstract data types that can be used by other elements of the choreography. Some examples being the declaration of variables, used to store messages being exchanged or state that is evaluated by expressions, and defining the type of tokens used for correlating messages to a choreography instance. The properties of this component are:
| Property | Description |
|---|---|
| Name | The name of the information type |
| Description | Longer descriptive text to explain the purpose of the type within the choreography |
| Element Name | Refers to an XML Schema element |
| Type Name | Refers to an XML schema simple type, or a WSDL1.1 message type |
A Token is simply an alias for a piece of information of a particular type.
A Token Locator is a means of extracting a piece of information (aliased by a token), from a complex data type (e.g. a message).
We may have two or more data types that all contain a particular piece of information (such as an id). If we wish to refer to the piece of information in a consistent manner, regardless of the different data types, then we need a way to reference this field using an appropriate alias.
Therefore, the first step is to declare a token to represent the generic piece of information we are interested in. The Token element has a name property to uniquely identify the token, a description property and finally a reference to the Information Type appropriate for the Token.
The next step is to define a Token Locator to describe how the information related to the token can be extracted from an Information Type (representing the complex data type) that contains this field. One token locator would be required for each combination of token and data type that contains the token field. The locator has properties:
| Property | Description |
|---|---|
| Description | Longer descriptive text to explain the purpose of the token locator |
| Information Type | The information type that is being examined to retrieve the information associated with the token |
| Part | If the information being examined to extract the token field is a WSDL1.1 message, then this optional part name can identify the appropriate part of a multipart message |
| Query | The XPath expression used to extract the field from the source information |
| Token | The token representing the data to be extracted |
The list of activities within the choreography description are described in this section.
The Assign activity provides the mechanism for assigning values to one or more variables, within an atomic unit. This means that if a failure should occur during this assignment activity, then the activity will undo any work it has already done, leaving the state as it was prior to the activity commencing.
The result of an assignment, where the source information is unavailable (see isVariableAvailable function), is undefined. A Conditional or When activity, used in conjunction with the isVariableAvailable function,can be used to ensure this does not happen.
The Assign activity requires an associated role type. This role type indicates at which role the assignments are being performed. The role type can be selected from a dropdown list, which will contain any role types that have been defined within the Choreography Description:
The next step is to define the information associated with each variable that is being assigned. This is achieved by creating a new 'Copy Details' element, under the assign component, for each variable being assigned:
The properties for this 'Copy Details' element are described in the table below:
| Property | Description |
|---|---|
| Name | Short name for this component |
| Description | Longer descriptive text to explain the purpose of the activity within the choreography |
| Source Expression | The XPath expression used to derive the value that will be copied into the target variable - if a source expression is defined, then the following source variable field should not be specified (i.e. these fields are mutually exclusive) |
| Source Variable | The source variable whose value will be copied into the target variable - if a source variable is defined, then the source expression field should not be specified (i.e. these fields are mutually exclusive) |
| Source Variable Part | If a source variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name |
| Target Variable | The target variable into which the copied value will be assigned |
| Target Variable Part | If a target variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name |
| Cause Exception | If this field is specified, then this copy statement is intended to cause an exception (of the type defined by the value within this field) to be raised |
The Choice activity provides the mechanism to enable a choreography to define two or more mutually exclusive paths. The path is selected based on the outcome of observable or non-observable situations. These situations may be related to the evaluation of observable expressions that operate on the state managed by the choreography (i.e. variables). They may relate to events (e.g. messages) that are being sent and received by the participants.
For example, a Choice construct is typically used to represent the alternate paths that may be enacted based on whether a normal or fault response is received following a request being sent. Therefore two paths may be declared, one with the interaction defined to exchange the normal response, and then other defined to exchange the fault response. From the perspective of the participant that is sending the normal or fault response, it could have a non-observable condition which may be internally evaluated (and therefore not defined within the choreography), to determine which path to take. The receiving participant equally does not have any observable expression to determine which path to take. It will use the type of the received message to determine which path is appropriate.
The Conditional component within the Choreography Description is used to represent a decision point, where the path taken through a choreography is dependent upon the evaluation of an expression.
| Property | Description |
|---|---|
| Name | Short name for this component |
| Description | Longer descriptive text to explain the purpose of the activity within the choreography |
| Expression | The XPath expression representing the predicate |
The Conditional component is mapped onto the WS-CDL workunit activity. The syntax of a workunit is:
<workunit name="ncname"
guard="xsd:boolean XPath-expression"?
repeat="xsd:boolean XPath-expression"?
block="true|false"? >
Activity-Notation
</workunit>
The expression field of the Conditional component is mapped onto the guard attribute of the workunit. The semantics of the Conditional activity does not support repetition, and so the repeat attribute in the workunit is not set.
The block attribute on the workunit will be set to 'false', as the semantics for the Conditional activity does not support blocking.
The Finalize activity is used to initiate the finalization handling for a choreography that has previously been performed (using the Perform activity).
The finalization details are defined with the following properties:
| Property | Description |
|---|---|
| Name | Short name to identify the finalize activity |
| Description | Longer descriptive text to explain the purpose of the activity within the choreography |
| Choreography | This property defines a reference to the enclosed choreography that is being finalized - and can be selected from a dropdown list |
| Choreography Instance Id | This property is an optional XPath expression, and can be used to identify a specific instance of the choreography to be finalized, in cases where multiple instances of this choreography have been performed |
| Finalizer | This property references the finalization handler that is to be used within the enclosing choreography |
The Interaction activity is the main activity that represents the communication between the various participants and roles defined within a choreography.
Unlike most business process specifications, which identify the act of communication from a particular endpoint's perspective using a send or receive primitive, the choreography is defined from the global perspective. Therefore the Interaction activity encapsulates both the sending of messages and the subsequent receiving of these messages as a single concept. This ensures that both endpoints nvolved in a communication are correctly synchronized.
The Interaction defines the following properties:
| Property | Description |
|---|---|
| Name | A short name used to describe the interaction |
| Description | Longer descriptive text to explain the purpose of the activity within the choreography |
| Align | This is a boolean property that indicates whether the result of this interaction should be aligned at the communicating endpoints - i.e. they both agree that they have the same resulting state before the interaction completes |
| Channel Variable | This is the reference to the variable that represents the channel instance on which to communicate |
| Initiate | This is a boolean property that indicates whether this interaction is responsible for initiating the choreography |
| Operation | The operation name, which should be valid for the receiving role type's behavior |
| Relationship | The relationship type associated with this interaction |
| Timeout "From" Role Type Record Details | Whenever a timeout occurs, the record details associated with this list will be performed at the 'from' role type |
| Timeout "To" Role Type Record Details | Whenever a timeout occurs, the record details associated with this list will be performed at the 'to' role type |
| Time To Complete | This field identifies the duration to wait for the interaction to complete, and if it does not complete during the specified time interval, then a timeout should occur |
Associated with the interaction is one or more exchange elements. These elements provide the details of the messages that will be exchanged between the two roles involved in the interaction. The properties associated with an 'Exchange Details' element are:
| Property | Description |
|---|---|
| Name | A short name used to describe the exchange |
| Description | Longer descriptive text to explain the purpose of the activity within the choreography |
| Action | This field identifies the direction of the message, whether it is a 'request' from the 'from role' to the 'to role', or a 'respond' message in the opposite direction, which may be a normal message or a fault |
| Fault Name | This optional field identifies the name of the fault associated with this exchange |
| Receive Cause Exception | This optional field is used to indicate the type associated with an exception that is raised at the receiving role, related to the direction of this exchange |
| Receive Record Details | This field provides a list of 'Record Details', associated with the same interaction, that are triggered in the receiving role |
| Receive Variable | This field identifies the optional variable that will contain the information received as part of the exchange |
| Receive Variable Part | If a receive variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name |
| Send Cause Exception | This optional field is used to indicate the type associated with an exception that is raised at the sending role, related to the direction of this exchange |
| Send Record Details | This field provides a list of 'Record Details', associated with the same interaction, that are triggered in the sending role |
| Send Variable | This field identifies the optional variable that contains the information being sent as part of the exchange |
| Send Variable Part | If a send variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name |
| Type | This field identifies the information type for the information being exchanged |
The 'Record Details' define information that must be assigned to variables as a result of an exchange occurring. The properties associated with this element are:
| Property | Description |
|---|---|
| Name | A short name used to describe the exchange |
| Description | Longer descriptive text to explain the purpose of the activity within the choreography |
| Cause Exception | This optional property indicates the type of exception that will be raised on the occurance of this record |
| Source Expression | This property defines the source XPath expression that will identify the value to be recorded. This field is mutually exclusive with the source variable field |
| Source Variable | The source variable whose value will be copied into the target variable. If a source variable is defined, then the source expression field should not be specified (i.e. these fields are mutually exclusive) |
| Source Variable Part | If a source variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name |
| Target Variable | The target variable into which the copied value will be assigned |
| Target Variable Part | If a target variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name |
| When | This property identifies at what point the record statement should be performed in relation to the exchange it is associated with. It can have three values: before record before the exchange occurs, after record after the exchange occurs, or timeout record if a timeout occurs |
The NoAction activity defines that the participants involved within a choreography should not perform any internal tasks that would modify the observable behavior exhibited by those participants.
This means that the participant would not be able to perform any interactions, or modify state information that is defined within the choreography.
The primary purpose of this activity is to represent a NOP (no operation), to fill slots where an activity is mandatory, but where we don't actually wish to do anything. An example would be that we may wish to indicate that a choice construct should have an option to 'not do anything' and therefore be optional.
| Property | Description |
|---|---|
| Description | Longer descriptive text to explain the purpose of the activity within the choreography |
| Role Type | This field is optional - if specified, identifies the role at which this 'no action' should be handled |
The Parallel activity defines that the activities that it contains will all be performed concurrently.
The parallel activity will only complete once all of the contained activities have all completed.
The Perform activity is used to indicate that the activities within a referenced choreography should occur at this point.
This mechanism supports the modularization of choreographies into reusable entities. The perform activity can refer to choreographies that are either directly defined within the performing choreography, or that are defined at the top level of the Choreography Description.
To provide the greatest reuse of choreographies, the Perform activity provides the optionally capability to bind variables within the performing choreography with variables in the performed choreography. To achieve this binding, the variable in the performed choreography must be defined as a 'free' variable. This means that it has no direct storage of its own, but instead maps onto the storage of a variable contained within an enclosing choreography.
The properties associated with the Perform activity are:
| Property | Description |
|---|---|
| Description | Descriptive text to explain the purpose of the activity within the choreography |
| Choreography | This property defines a reference to the choreography that is being performed - and can be selected from a dropdown list |
| Choreography Instance Id | This property is an optional XPath expression, and can be used to identify a specific instance of the choreography to be performed, in cases where multiple instances of this choreography will be performed and later finalized |
| Wait For Completion | This property determines whether the performing choreography should wait for the performed choreography to complete, before preceding to the next activity |
The variable binding information is specified in an element contained within the Perform activity, called the 'Bind Details', with the following properties:
| Property | Description |
|---|---|
| Name | Short name for this component |
| Description | Longer descriptive text to explain the purpose of the activity within the choreography |
| 'This' Variable | This property defines the variable, within the performing choreography, that will be bound |
| 'Free' Variable | This property defines the variable, within the performed choreography, that will be bound |
The Sequence activity specifies that the set of activities that are defined within the sequence construct should be performed one by one, in the order that they are specified.
The subsequent activity in the list can only be performed once its proceeding activity has completed. The sequence only completes when the final activity in its list has completed.
The SilentAction activity is similar in nature to the NoAction activity, with the difference that it indicates that the internal implementation of a participant (and role) should carry out some non-observable implementation specific tasks.
These internal tasks may modify the state information associated with the particular participant and role. However it will not be entitled to perform interactions, as this would interfere with the externally observable behavior of the role.
Properties associated with this component
| Property | Description |
|---|---|
| Description | Longer descriptive text to explain the purpose of the activity within the choreography - could be used to define the requirements for the implementation of the 'silent' action |
| Role Type | This field is optional - if specified, identifies the role at which this silent action should be handled |
The When component within the Choreography Description is used to describe a synchronization point where the choreography is dependent upon a predicate (condition) being true. If the information referenced within the condition is not available, then the condition will block until the information becomes available. At this point the predicate will be evaluated to determine if it is true, and if not the activity will continue to block until the predicate becomes true.
The When component has an optional 're-evaluation' condition, which is evaluated after all of the activities within the 'when' component have completed, to determine whether the conditional expression (associated with the 'when' component) should be evaluated again. This provides the ability for the When component to be repeated multiple times - each time being synchronized based on the expression associated with the 'when' component.
The semantics of the when component can be written as:
when (C) {
activities
} [ until (!R) ]
where C represents the condition and R represents the optional 're-evaluation' expression. The activities in the body of the When component are only performed if the condition C evaluates to true. Then the condition is only re-evaluated if R is either not specified, or evaluates to true.
Properties associated with this component:
| Property | Description |
|---|---|
| Name | Short name for this component |
| Description | Longer descriptive text to explain the purpose of the activity within the choreography |
| Expression | The XPath expression representing the predicate on which this 'when' component is synchronized |
| Re-Evaluate Condition | The XPath expression to determine if the 'when' condition should be re-evaluated after the iteraction has completed |
The When component is mapped onto the WS-CDL workunit activity. The syntax of a workunit is:
<workunit name="ncname"
guard="xsd:boolean XPath-expression"?
repeat="xsd:boolean XPath-expression"?
block="true|false"? >
Activity-Notation
</workunit>
The expression field of the When component is mapped onto the guard attribute of the workunit, and the re-evaluation condition is mapped onto the repeat attribute.
The block attribute on the workunit will be set to 'true', as the When semantics require the condition to block until all of its information is available, and the predicate evaluates to true. The non-blocking semantics are described by the While activity.
The While component within the Choreography Description is used to describe a repetition that is dependent upon a condition being true. The condition is evaluated prior to performing each iteration of the activities contained within the scope of the While component.
What makes the semantics of the while component slightly different from a normal 'while' construct in a programming language, is that after an iteration has been performed, an optional 're-evaluation' condition can also be specified, to determine whether the conditional expression (associated with the while component) should be evaluated again. This provides the ability to break out of the repetition without unnecessarily complicating the while condition.
The semantics of the while component can be represented using the following:
while (C) {
activities
} [ until (!R) ]
where C represents the condition and R represents the optional 're-evaluation' expression. Each iteration only proceeds if the condition C evaluates to true, and the condition is only re-evaluated if R is not specified or also evaluates to true.
Properties associated with this component:
| Property | Description |
|---|---|
| Name | Short name for this component |
| Description | Longer descriptive text to explain the purpose of the activity within the choreography |
| Expression | The XPath expression to determine if the repetition should occur |
| Re-Evaluate Condition | The XPath expression to determine if the repetition condition should be re-evaluated after the iteraction has completed |
The While component is mapped onto the WS-CDL workunit activity. The syntax of a workunit is:
<workunit name="ncname"
guard="xsd:boolean XPath-expression"?
repeat="xsd:boolean XPath-expression"?
block="true|false"? >
Activity-Notation
</workunit>
The expression field of the While component is mapped onto the guard attribute of the workunit, and the re-evaluation condition is mapped onto the repeat attribute.
The block attribute on the workunit will be set to 'false', as the While semantics do not wait for information to be available, or require the condition to be true before proceeding. The blocking semantics are described by the When activity.
Within expressions defined in a choreography, it is possible to make use of a set of pre-defined functions which are prefixed with the letters "cdl:". The list of these choreography description language functions are:
any getChannelIdentity(string varName)
The function can be used to return the identity information associated with a channel instance.
any getChannelReference(string varName)
The function can be used to return the endpoint reference information associated with a
channel instance.
date getCurrentDate(QName roleName)
The function can be used to retrieve the current date. This function will be performed
locally at the role identified by the roleName parameter.
dateTime getCurrentDateTime(QName roleName)
The function can be used to retrieve the current date and time. This function will be
performed locally at the role identified by the roleName parameter.
time getCurrentTime(QName roleName)
function can be used to retrieve the current time. This function will be performed locally
at the role identified by the roleName parameter.
any getVariable(string varName, string part, string documentPath, QName roleName?)
The function can be used to obtain the information associated with a named variable. If the
variable is a WSDL1.1 message, then it will also be necessary to identify the part of the message
that should be retrieved.
boolean globalizedTrigger(string expression, string roleName, string expression2, string roleName2, ...)
function provides a mechanism to describe, within a single activity expression, a list
of distinct sub-expressions that should be projected to different roles associated with
the activity. This enables the choreography designer to determine what relevant expression
is required at the different roles, to ensure that those roles take the same path within
the global choreography.
boolean hasDeadlinePassed(dateTime deadlineTime, QName roleName)
The function can be used to determine whether a particular deadline time has passed.
Generally this function will be used within the When activity as part of the blocking
condition, to cause the choreography to wait for the impending deadline. It may also be
used within the 'complete' condition for a choreography, to ensure that the choreography
finishes before the specified time.
boolean hasDurationPassed(duration elapsedTime, QName roleName)
The function can be used to determine whether a particular time interval has passed.
Generally this function will be used within the When activity as part of the blocking
condition, to cause the choreography to wait for the duration. It may also be used
within the 'complete' condition for a choreography, to ensure that the choreography
finishes within the specified duration.
boolean isVariableAvailable(string varName, QName roleName)
The function is used to test whether a variable has been populated with some information.
This is required to guard against the use of an unset variable in an invalid situation.
If an unset variable is used within the When activity, the activity will block until the
variable is set. However, in other cases the use of such a variable is undefined.
boolean variablesAligned(string varName, string withVarName, QName relationshipName)
The function is used to determine whether two variables, at different roles (associated
with a relationship), have 'aligned' values. Alignment means that there has been agreement
that the two variables have the same value.
boolean hasExceptionOccurred(QName exceptionType)
The function returns "true" if an exception of the type identified by the parameter
exceptionType has occurred. Otherwise it returns "false".
boolean hasChoreographyCompleted(string choreoName, string choreoInstanceId?)
The function returns true if the performed choreography associated with the parameter
'choreoName' and OPTIONAL choreoInstanceId has a status of completed (whether successfully
or not). If choreoInstanceId is not specified, the function will evaluate whether all
performed choreographies, with the supplied name, have completed. If the named choreography
has not been performed, prior to this function being called, it will return false.
string getChoreographyStatus(string choreoName, string choreoInstanceId?)
The function returns the current status associated with the identified choreography and
OPTIONAL choreoInstanceId . If choreoInstanceId is not specified, then there MUST only be
a single instance of that performed choreography in the scope of the current choreography
that is checking the status, otherwise a status of 'ambiguous' MUST be returned. The values
of the status can be 'enabled', 'completed-successfully', 'completed-unsuccessfully',
'closed', 'ambiguous', or 'instance-unknown'. The 'instance-unknown' status is encountered
when this function is invoked and when the choreography has not been enabled.
XPath is a standard notation for querying information in an XML document. Although XPath defines many constructs for accessing this information, we have introduced the most useful features below.
If you would like to read more information about XPath, then the specification can be found at: http://www.w3.org/TR/xpath.
Functions are simply invoked by expressing the function name (including the namespace) and the set of comma separated parameters within the following brackets.
For example,
cdl:getVariable('myVar','','/order/@id','myRole')
In this example, the parameters are supplied as a set of text strings.
The list of boolean operators, in precedence order, is:
or
and
= !=
<= < >= >
For example,
cdl:isVariableAvailable('myVar') and cdl:getVariable('myVar','','') > 5
XPath also supports some boolean functions:
boolean not(boolean)
The not function returns true if its argument is false, and false otherwise
boolean true()
The true function returns true
boolean false()
The false function returns false
The list of Arithmetic operators is:
+
-
*
div
mod
For example,
cdl:getAvailable('myVar','','') + 1
Text strings can be defined within an XPath expression as literals within single or double quotes (depending on the context).
XPath provides a set of built-in functions for manipulating strings, which include:
string string(object?)
Converts the supplied value to a string representation
string concat(string, string, string*)
The concat function returns the concatenation of its arguments
boolean starts-with(string, string)
The starts-with function returns true if the first argument string starts
with the second argument string, and otherwise returns false
boolean contains(string, string)
The contains function returns true if the first argument string contains
the second argument string, and otherwise returns false
string substring(string, number, number?)
The substring function returns the substring of the first argument
starting at the position specified in the second argument with length
specified in the third argument. For example, substring("12345",2,3)
returns "234". If the third argument is not specified, it returns the
substring starting at the position specified in the second argument and
continuing to the end of the string. For example, substring("12345",2)
returns "2345"
Primarily, XPath is an expression language for locating information within an XML document. Therefore the language provides a way to describe how to navigate the hierarchical nodes and determine which attribute, text field or node-set should be returned. The following table provides a subset of the possible accessors that can be used - refer to the XPath specification for more details. This table describes the abbreviated form of the locators, as this form is more compact:
para
Selects the para element children of the context node,
e.g. /order/item, would select all 'item' nodes that were contained
within the 'order' node
\*
Selects all child nodes of the current context, e.g. /order/*,
would select all nodes contained under the 'order' node
text()
Selects all text nodes under the current context, e.g. /order/text(),
would return any text nodes contained by the 'order' node
@name
Selects the name attribute of the context node, e.g. /order/@id would
return the id attribute from the 'order' element
para[1]
Selects the first para child of the context node, e.g. /doc/chapter[5]/section[2]
selects the second section of the fifth chapter of the doc node
para[@type="warning"]
Selects all para children of the context node that have a type attribute
with value 'warning'
chapter[title]
Selects the chapter children of the context node that have one or more
title children
employee[@secretary and @assistant]
Selects all the employee children of the context node that have both a
secretary attribute and an assistant attribute
This section discusses how channel instances are identified within the context of a choreography session.
This is important, as it enables messages to be correctly associated with the appropriate choreography session and channel instance, and it also enables an association to be established between multiple independent channel instances, to correlate them to the same session.
The Identity element is created as a child element of a Channel Type. The identity consists of one or more Token elements, which locate the specific parts of the composite identity information from a particular message (using Token Locators where appropriate).
The identity element has an associated type, which indicates its purpose in relating instances of the channel type to the choreography session. These types are:
-
Primary
This identity provides the primary key for the channel type. Only one instances of a channel type can have the same value for a particular identity. Only one primary identity can be associated with a channel type.
-
Alternate
As each message exchanged on an instance of a channel type will generally not have the same (primary) key value as part of its data, we need to provide alternative identity fields that can be used in place of the primary identity. To ensure that an alternate identity is associated with the appropriate channel instance, it must first occur in a message that is associated with the channel instance due to the fact that it contains either the channel instance's primary identity, or another one of its alternate identities that had previously been associated with the channel instance.
-
Derived
The previous two identity types were concerned with correlating messages to a particular instance of the channel type. The derived identity type concerns establishing a correlation between channel instances, to ensure that are bound to the same choreography session. When the derived identity is specified on a channel type, it means that if a message is exchanged on an instance of that channel type, that contains the appropriate information for the derived identity, then the identity will be associated with the choreography session. It is then possible to define another Channel Type that has the same identity information, but being classified as the primary identity for this other Channel Type. When a new instance of this Channel Type is created, based on the identity value previously derived from the other channel instance, then this will automatically correlate the new channel instance to the same choreography session as the previous channel instance.
-
Association
The association identity type is similar in purpose to the previous derived identity type, in that it is used to correlate channel instances to a choreography session. However the difference between these two identity types is that the derived identity type can be considered equivalent to a forward reference, and the association identity type can be considered equivalent to a backward reference. With an association identity, the initial channel type only defines its own identity information, and the subsequent channel type (that needs to be correlated to the initial channel type) provides the association identity element with the information necessary to map onto one of the primary or alternate identity values in the initial channel type.
The choreography is the main construct that groups a set of interactions into a meaningful business transaction. Choreographies represent a module that can be reused by other choreographies, using the Perform activity, enabling more comprehensive business protocols to be assembled from simplier protocol units.
The choreography has the following properties:
| Property | Description |
|---|---|
| Name | Short name for the choreography |
| Description | Longer descriptive text to explain the purpose of the choreography |
| Completion Condition | The optional XPath expression used to determine when this choreography can be prematurely completed in a successful state |
| Coordinated | When set to true, this property indicates that all participants involved in the choreography will be coordinated so that they all complete at the same time, and with the same status |
| Isolation | When this boolean property is set to true, it means that modifications made within the scope of this choreography, to bound variables in the performing choreography, will not be made visible until this choreography has successfully been completed - it also means that the enclosing and sibling choreographies will block when accessing those variables, until the isolated choreography has completed |
| Relationships | The optional list of relationship types that are associated with the choreography - if not defined, then the choreography will be implicitly associated with all relationship types |
| Root | This boolean property identifies whether this is the root choreography - only one top level choreography can be declared as root, which identifies it as the entry point into the set of choreographies included in the CDL package |
Variables are used by a choreography to represent state information and channel instances. A choreography may require state information to be explicitly modeled and recorded in order to make a decision as to which path to take. A choreography that models only the observable interactions, without making any internal state visible, still needs to represent the channel instances on which interactions are performed.
The properties associated with a variable declaration are:
| Property | Description |
|---|---|
| Name | The variable name |
| Description | Longer descriptive text to explain the purpose of the activity within the choreography |
| Free | When set to "true", specifies that the Variable must be bound to an equivalent (i.e. same type) variable within an enclosing choreography - this variable cannot be used in its own right without being bound |
| Mutable | When set to "false", specifies that the Variable information cannot change once initialized |
| Role Types | This property represents the optional list of role types associated with the variable - if no list is provided, then the variable will be declared at all roles associated with the choreography |
| Silent | This property, if set to "true", indicates that the manipulation of the value associated with this variable is non-observable, i.e. it is modified within the internal implementation of the respective choreography participants |
| Type | This property identifies the type of the variable - either an information type or channel type |
Free variables can simply be thought of as links to real variables that have been declared in an enclosing (performing) choreography. This link is established when the enclosing choreography performs the current choreography and provides the necessary binding details to link the concrete variable with the free variable. These bound variables must be compatible in terms of type.
Silent variables can be used to define an expression in the choreography description that is based on information whose value is only known to the implemented endpoints. These variables will have their values modified by the internal implementation of an endpoint, and therefore it cannot be expressed in observable activities within the choreography.
Exception handling provides a mechanism to enable a choreography to terminate based on the occurence of a situation. The exception is raised based on a piece of information, of a particular type, being recorded in a participant.
Some of the choreography activites have a property, called cause exception, to indicate that when the activity is performed, then an exception of the type associated with the activity should be raised. If a choreography is coordinated, then all of the participants within the choreography should enter the same exception handler. For non-coordinated choreographies, the interactions will need to be defined in such a way to cause the same exception to be raised at each participant.
To define an exception handler, press the 'add exception handler' button at the top of the choreography flow page, as show here:
This will create a new exception handler within the sub-choreography:
The exception handler (i.e. Exception Work Unit) element has properties to define the name and description of the exception handling activity. It also has a property to select the information type associated with the exception to be handled. If an exception information type is not specified, then the associated exception workunit will become the default exception handler to catch any exception information type that has no explicit handler - only one default exception work unit can be defined for a choreography.
To create a new Choreography Description, the first step is to locate the folder in which the file will be created. Once this folder has been found (or created), the user should select the 'New...' menu item (on the context menu), as follows:
The user should select the 'Other...' menu item from this menu, which will cause a wizard to be displayed with the various items that can be created. Within the list, there is a sub group with the title 'SOA'. This group contains an entry called 'Choreography Description' that should be selected:
The user should then press the 'Next' button to see the following form:
This form enables the user to select both the folder, within which the new Choreography Description should be created (defaults to the folder previously chosen when invoking the context menu), and the name of the choreography description (by default this is My.cdm).
From version 1.7.0, the new choreography description wizard also enables the main details associated with the top level choreography package to be preconfigured. When the filename is changed, the portion of the name without the .cdm is used to automatically update the Description, Choreography Name and Target Namespace fields. The initial portion of the target namespace can be changed within the preferences for the choreography designer.
When the 'Finish' button is pressed, a new Choreography Description file (with the specified name) will be created in the nominated folder. The Eclipse workbench will then switch into the Choreography perspective (a configurable layout with the appropriate windows required for the pi4soa tools) and an editor will automatically be opened for the newly created Choreography Description.
Monitoring a choreography requires the configuration of the project, in which the choreography to be monitored is located, to enable the monitor to receive service tracker information from the relevant target platform.
Due to the specific configuration details required for each target platform, this section will provide the information required for a specific platform (JBoss) as an example.
The configuration information for the monitor is contained within the pi4soa.xml file, located in the project's classpath. If this file does not already exist, then one needs to be created. The contents for a JBoss/JBossESB based project would be:
<pi4soa> <container> <clientMessageHandlers class="org.pi4soa.jbossesb.container.ESBClientMessageHandler"> </clientMessageHandlers> <serviceTracker class="org.pi4soa.service.tracker.jms.JMSServiceTracker" > <jmsConnectionFactory>ConnectionFactory</jmsConnectionFactory> <jndiFactoryURLPackages>org.jboss.naming:org.jnp.interfaces</jndiFactoryURLPackages> <jmsDestination>topic/tracker</jmsDestination> <jndiInitialContextFactory>org.jnp.interfaces.NamingContextFactory</jndiInitialContextFactory> <jndiProviderURL>jnp://localhost:1099</jndiProviderURL> <recordMessagePayload>true</recordMessagePayload> </serviceTracker> </container> <tracker> <jndi> <initialContextFactory>org.jnp.interfaces.NamingContextFactory</initialContextFactory> <providerURL>jnp://localhost:1099</providerURL> <factoryURLPackages>org.jboss.naming:org.jnp.interfaces</factoryURLPackages> </jndi> <jms> <connectionFactory>ConnectionFactory</connectionFactory> <connectionFactoryAlternate>ConnectionFactory</connectionFactoryAlternate> <destination>topic/tracker</destination> </jms> </tracker> </pi4soa>
The information under the container node represents the configuration of the execution runtime within the Eclipse environment, showing that the client (launched when performing a service test) will report information to the service tracker.
The information of interest to the monitor is defined within the tracker node. This defines the JNDI and JMS configuration properties required by the monitor to listen for service tracker events on a JMS bus.
To monitor a choreography, select the Choreography->Monitor menu item from the context menu associated with the choreography file. This will launch the monitor GUI, and proceed to load the choreography description. If the monitor is unable to load the choreography, or has problems establishing a connection to the service tracker (i.e. JMS topic in the example configuration above), then an error will be reported.
The choreography monitor has three main display areas.
-
The left hand panel is the tree showing:
- Issues - these show the entries related to 'unexpected messages', 'errors' and 'warnings'. The errors and warnings can be system or user generated using the 'error' or 'warning' methods on the ExtensionContext (see developer documentation). Selecting one of these transactions will focus the monitor on the issues in that category.
- Sessions - the list of choreography sessions being monitored. Selecting a session from the list focuses the monitor on that session.
- Channels - the list of channels associated with the choreography. Selecting a channel from the list, focuses the monitor on all events associated with that channel.
- The top right panel shows the list of service tracker events associated with the current focus (as selected in the left hand tree). If no specific entry is selected, then all service tracker events (for all sessions) will be displayed.
- The bottom right panel shows the details related to a service tracker event selected from the top right hand panel.
Semantic annotations are a means of associating additional structured or freeform semantic information with a component in the choreography description model.
When a component is selected within the choreography description designer, if you select the context menu (using the righthand mouse button) you will see the menu item 'Edit Annotations'. If you select this menu item a dialog box will be displayed.
In the lefthand panel will be presented a list of existing semantic annotations that have been defined for the component. To edit any one of these existing values, simply select the relevant annotation from the list. This will cause the details associated with the annotation to be displayed in the righthand panel.
If the annotation is a freeform annotation, then the raw annotation details will be displayed for editing in the righthand panel (Annotation tab).
If the annotation is a structured annotation, then a form will be presented in the righthand panel (Parameters tab) detailing the fields that can be modified.
When a structured annotation is selected and values entered into the form, it is also possible to see a formatted version of the annotation (if a presentation style sheet has been configured) in the Annotation tab.
To create a new semantic annotation, simply select the context menu on the lefthand panel and select either the "Add Defined Annotation" or "Add Free Form Annotation".
It is possible to customize the templates and presentation style sheets associated with the pi4soa tool suite. The set of available annotation templates and presentation details are defined within a file called 'annotations.xml', located in the annotations folder of the org.pi4soa.common plugin.
An example of the contents of this file is:
<annotations>
<annotation type="State" component="org.pi4soa.cdl.StructuralType" >
<template url="cdl/State.template"
processor="org.pi4soa.common.annotations.impl.DefaultTemplateProcessor" />
<presentation url="cdl/State.presentation"
processor="org.pi4soa.common.annotations.impl.XSLTPresentationProcessor" />
</annotation>
</annotations>
The 'type' attribute on the annotation element defines the name that can be selected from the 'defined annotation' list by the user. The component attribute represents the Java class or interface to which the annotation can be applied. In this case, the 'org.pi4soa.cdl.StructuralType' represents all of the grouping constructs in the Choreography Description Model.
The 'template' element defines the location of the template file, and an implementation of the "org.pi4soa.common.annotations.TemplateProcessor" interface which can be used to handle the processing of the template. The default implementation used above enables the template to contain entries that will be presented in the form to the user.
The structure of these elements are as follows:
{{<Field Name>;<Description>;<Field Type>;<Optional Enumeration Values>;<Optional Default Value>}}
where and are template parameter delimiters, the ';' is used to separate the definition fields, and if the field type is an enumeration, then the ',' is used as a separator between enumeration field types.
The value field types are: string, integer, enum or boolean.
An example of the template file would be:
<state name="{{State Name;The name of the state;string;;}}"
participantInstance="{{Participant Instance;The name of the participant instance;string;;}}" />
These fields do not have the enumeration values defined, as they are strings, and also have no default value.
The optional 'presentation' element defines the location of the presentation file, and an implementation of the "org.pi4soa.common.annotations.PresentationProcessor" interface which can be used to handle the processing of the presentation of the template. The implementation used above enables the instantiated template to be presented using an XSLT style sheet.
An example of the presentation file would be:
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
The state <xsl:if test="state/@participantInstance != ''" >of participant instance
'<xsl:value-of select="state/@participantInstance" />' </xsl:if>is: <xsl:value-of select="state/@name"/>
</xsl:template>
</xsl:stylesheet>
The W3C Web Service Choreography Description Language, or WS-CDL for short, provides a standard notation for describing the collaborative peer-to-peer interactions between a set of cooperating services. These services could be actual 'web services', or any form of SOA based service - i.e. WS-CDL is not bound to web services, although generally WSDL will be used to describe the abstract interface of a service.
As with most XML based notations, WS-CDL is not very easy to read or modify, without a detailed understand of the syntax and semantics of the specification. Therefore the pi4soa project provides a set of higher level tools which aim to make it easier for a user to understand business protocols, specified in WS-CDL, as well as modify and enhance them.
To enable the pi4soa tools to provide these usability benefits, it is necessary to convert the detailed XML representation associated with a WS-CDL document, into a higher level object model on which the pi4soa tools can effectively operate. Therefore it is necessary to import WS-CDL documents into the internal object model representation used by pi4soa tools.
First step is to decide which folder should be used to store the imported CDL model. Once selected (or created), then select the 'Import...' menu item (available on the context menu for the folder).
This will show an import wizard that will offer a list of possible items that can be imported. From the list, select the entry 'Import Choreography Description from WS-CDL' and press the 'Next' button. This will cause the wizard to present a form as shown in the following image:
The fully qualified name of the file containing the CDL document should be entered into the text field. A 'Browse' button is provided to enable the user to search the file system for the appropriate file.
Once the file name has been entered, press the 'Next' button to import the CDL. This will cause the CDL document to be validated. If there are any errors that prevent the CDL being imported, these will be displayed in the subsequent form:
If this window shows any errors, then the 'Finish' button will remain disabled and the user will only be able to cancel the task. However, if no errors have been detected, then the 'Finish' button can be pressed to cause the imported CDL document to be saved within the selected folder. The name of the imported CDL package will be used to name the file within the folder, followed by a '.cdm' extension.
First step is to decide which CDL file will be exported. Once chosen, then select the 'Export...' menu item (available on the context menu for the file).
This will show an export wizard that will offer a list of possible items (and formats) that can be exported. From the list, select the entry 'Other -> WS-CDL' and press the 'Next' button. This will cause the wizard to present a form as shown in the following image:
This form contains a text field that should be used to enter the fully qualified name of the file into which the exported CDL XML document should be stored. The user can press the 'Browse' button to search the file system, or enter the name directly.
If the selected file already exists then the user will be asked if they wish to overwrite the current contents within the file. If they select 'No', or if there is anything invalid about the file name that has been entered, then an error message will be shown at the top of the window.
When a valid file name has been entered, where permission has been given to overwrite the file (if it already exists), then the 'Finish' button will be enabled for the user to press. Once pressed, then the CDL will be exported to its XML representation.
First step is to decide which CDL file will be exported. Once chosen, then select the 'Export...' menu item (available on the context menu for the file).
This will show an export wizard that will offer a list of possible items (and formats) that can be exported. From the list, select the entry 'Other -> HTML' and press the 'Next' button. This will cause the wizard to present a form. This form contains a text field that should be used to enter the fully qualified name of the file into which the exported Choreography Description (html) should be stored. The user can press the 'Browse' button to search the file system, or enter the name directly.
If the selected file already exists (as shown in the image above) then the user will be asked if they wish to overwrite the current contents within the file. If they select 'No', then an error message will be shown at the top of the window.
When a valid file name has been entered, where permission has been given to overwrite the file (if it already exists), then the 'Finish' button will be enabled for the user to press. Once pressed, then the Choreography Description will be exported to its HTML representation.
The template used during the export of the choreography to HTML can be found in the org.pi4soa.cdl plugin installation directory, under the "templates/html" directory. The templating technology used is Apache Velocity. These templates can be customized by the user to change the contents or format of the exported documents. Other formats may be supported in the future.
First step is to decide which CDL file will be exported. Once chosen, then select the 'Export...' menu item (available on the context menu for the file).
This will show an export wizard that will offer a list of possible items (and formats) that can be exported. From the list, select the entry 'Service Endpoint Descriptions' and press the 'Next' button. The next page contains a text field that should be used to enter the fully qualified name of the directory into which the exported service endpoint projections should be stored. The user can press the 'Browse' button to search the file system, or enter the name directly.
When a valid directory path has been entered, then the 'Finish' button will be enabled for the user to press. Once pressed, then the service endpoint projections will be exported in an XMI representation. There will be one Service Description Model (SDM) file per participant type associated with the choreography description.
The preferences for the Choreography Designer can be found on the Window->Preferences... menu item. The Choreography item has a Designer child node, that presents the following options:
The namespace prefix is used to prefix the target namespace associated with any newly created choreography descriptions (i.e. shown within the new choreography description wizard). This value, along with the name of the choreography, will also be used to define the value of the 'tns' prefixed org.pi4soa.cdl.NameSpace component within any new choreography descriptions.
The 'Include XML Schema' checkbox determines if newly created choreography descriptions should include a org.pi4soa.cdl.NameSpace component for the 'xsd' prefix, referencing the XML schema URI. This checkbox indicates the default value, which will be used by the new choreography description wizard, enabling the decision on whether the XML schema should be included to be choreography description specific.
The 'Enable Inference' checkbox determines if inference rules should be applied by the choreography designer. These rules aim to speed up creation and modification of choreography descriptions. However, if these rules are not desired, then they can be disabled.