WS Choreography, Ideas for Implementing Choreography Templates

1 Introduction

This note presents ideas for how Choreography Templates might be implemented as a follow on from the WS Choreography F2F on May 11-13, 2004 at Oracle.

The purpose of the note is to seek agreement on how templates could work. Once (if) agreement is reached then necessary changes to the CDL spec can be worked out.

"Choreography Templates" are choreography definitions where all the parts of the choreography definition are identified, but some have not been specified. This means that, in order to fully define a choreography based on a template, it is necessary to:

• First define the choreography template, identifying the "parameters" to the template, and
• Second, define the choreography, based on the template, specifying the values of the parameters to be used

2 Requirements

At a high level, the requirements are as follows:

1. Enable choreography re-use. Provide a mechanism for substituting parts of a choreography definition. This is to include:
1. Choreography End Point definitions
2. Message Definitions
3. Guard Conditions
4. etc.
2. Complete choreography definitions. This means that only substitution is allowed. Additional parts of the choreography cannot be omitted as in the original "Package Binding" proposal.
3. Use of templates is optional. This means that it should be possible to fully define a choreography without using a template
4. The scope of templates can be controlled. This means that the choreography designer can define a template with differing degrees of parameterization
5. Multiple sources for template parameters. Parameters to substitute in a template can come from multiple sources, specifically: the original choreography designer and each of the participants in the choreography. For example, the Buyer and Seller in a purchasing choreography would each specify their own WSDL interface(s) for the messages they each receive.

3 How it could be implemented …

This covers:

• How to define a choreography template, and
• How to use a choreography template to define a choreography
• How to combine both.

3.1 Defining a Choreography Template

The basic idea is to build on the package definition in the existing spec but add a templateParameterDefinitions element after the package element that enables substitution of values based on ncNames. For example:

<package name="ConsumerRetailerChoreoTemplate" version="1.0">
  <templateParameterDefinitions>
    <parameter ncName="tns:OrderMsg"/>
    <parameter ncName="tns:OrderAckMsg" default="pons:PurchaseOrderAckMsg"/>
    ...
  </templateParameterDefinitions>
  ...
  <informationType name="purchaseOrderType" type="tns:OrderMsg"/>
  <informationType name="purchaseOrderAckType" type="tns:OrderAckMsg"/>
  ...
</package>

The basic idea is that:

• The existence of a templateParameterDefinitions element indicates that this package definition is a template
• Each parameter element within the templateParameters specifies:
• A ncName within the package definition, and
• An optional default value for the name.

Note that use of the optional default values for template parameters should make it simpler to use.

3.2 Using a Choreography Template

A package definition that is based on a template includes a templateParameterValues element that:

• Contains a templateParameterValues element that references the template package to use, and
• Contains a combination of one or more of either:
• parameterValue elements that specify actual values to use, and/or
• parameterRef elements that reference a file or resource that contains parameter values.

For example:

<package name="MyConsumerRetailerChoreo" version="1.0">
  <templateParameterValues template="ConsumerRetailerChoreoTemplate" templateVersion="1.0">
    <parameterValue ncName="tns:OrderMsg" value="pons:PurchaseOrderMsg">
    ...
    <parameterRef URI="some location">
    ...
  </templateParameterValues>
  ...
</package>

The file referenced by the parameterRef element must resolve to an XML document containing a single templateParameterValues element as its root element, for example …

<templateParameterValues>
...
</templateParameterValues>

The resulting templateParameterValues element can contain a combination of parameterValue and/or parameterRef elements. This allows nesting of references.

3.3 Combining Both

A Package definition may contain both templateParameterDefinitions and templateParameterValues elements. For example:

<package name="ConsumerRetailerChoreoTemplate" version="1.0">
  <templateParameterDefinitions>
    ...
  </templateParameterDefinitions>
  <templateParameterValues template="ConsumerRetailerChoreoTemplate" templateVersion="1.0">
    ...
  </templateParameterValues>
  ...
</package>

In this case:

• The templateParameterValues element provides values to be used by the variable and choreography definitions contained within the package, and
• The templateParameterDefinitions element provides parameters to be used when the package is referenced by another package.

4 Notes

Note that:

• Parameter values in a templateParameterValues element are applied in the sequence in which they occur. This means that one parameter value can be overridden by a value that occurs later.
• Circular references where a parameterRef references a templateParameterValues element contains references that had previously been read, causes an error
• A package element can define one of:
• A "package" as currently defined – i.e. without a templateParameterDefinitions or templateParameterValues elements
• A "choreography template" which contains just a templateParameterDefinitions element, followed by all the other elements in the existing package definition, or
• A "template based choreography" which is a package that contains just a templateParameterValues element
• A "choreography template" that references some previously defined template based choreography. i.e. it contains both a templateParameterDefinitions and a templateParameterValues element

David Burdett
Commerce One
June 18, 2004