WS Choreography, Ideas for Implementing Choreography Templates - Version 2

0. Update

I (David B) have reviewed the original, June 18, 2004 version of this note with Nick Kavantzas. He raised the following points:

1. Use of parameter References. This should not be necessary as you should only have one way of Import stuff. Need to work out how to use Import for this purpose
2. Overriding parameter values. Overriding one parameter value with another value defined later should not be allowed, and should cause an error instead. This will simplify handling of the parameter values.
3. Replacing Parameter Values. The value in a ParameterValue element cannot be the name of another Parameter Value, as this will complicate the approach.
4. Text as well as name substitution. Currently, parameter values can substitue one ncname for another. This is too simple, you also want to be able substitute element content.

I agree with these points so have updated the rest of the note to reflect these points as well as added further clarification in several places.

David
June 30, 2004

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 and a discussion with Nick Kavantzas on June 30, 2004

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 substituted.

2 Requirements

At a high level, the requirements are as follows:

1. Enable choreography re-use. Provide a text substitution mechanism for replacing various parts of a choreography definition.
2. Control where substitutions are made. This means that the places within a choreography where substitution can occur is limited to a specific list of places. These places need to be fully defined, but include:
1. Choreography End Point definitions
2. Message Definitions
3. Guard Conditions
4. etc.
3. Specify complete choreography definitions only. Only text substitution is allowed. Additional parts of the choreography cannot be omitted, as in the original "Package Binding" proposal, and later "extended". This means that parameters must be defined in a template choreography whenever alternative values may be used.
4. The scope of variation in a template choreography can be controlled. This follows on from the previous requirement as a choreography designer can define a template that specifies exactly where and when the choreography may vary by varying the degree of parameterization.
5. Use of templates is optional. This means that it should be possible to define a choreography fully without using a template
6. 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 in a single definition.

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 name="tns:OrderMsg"/>
    <parameter name="tns:OrderAckMsg">"pons:PurchaseOrderAckMsg"</parameter>
    <parameter name="tns:RetailerInfo">
        ...
  </templateParameterDefinitions>
  ...
  <informationType name="purchaseOrderType" type="tns:OrderMsg"/>
  <informationType name="purchaseOrderAckType" type="tns:OrderAckMsg"/>
  ...
  <someElement>tns:RetailerInfo</someElement>
  ...
</package>

The basic idea is that:

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

Notes.

1. The optional default value for a template parameter must be used if, when the template is referenced, no substitute value is provided.
2. The element someElement is not in the current CDL spec. It has been included here to show how you can substitute any content, including, if necessary XML - see the next topic.

3.2 Using a Choreography Template

A package definition that is based on a template contains:

• One or more templateParameterValues elements that references the template package to use, that each contain ...
• parameterValue elements that specify actual values to substitute in the referenced template package.

For example the template defined in section 3.1 could be used as follows:

<package name="MyConsumerRetailerChoreo" version="1.0">
  <templateParameterValues template="ConsumerRetailerChoreoTemplate" templateVersion="1.0">
    <parameterValue name="tns:OrderMsg>"pons:PurchaseOrderMsg"</parameterValue>
    <parameterValue name="tns:RetailerInfo>"<someXMLorOtherText>...</someXMLorOtherText>"</parameterValue>
    ...
  </templateParameterValues>
  ...
</package>

Notes.

• A package, through use of the import element, can import more than one template where, for each imported template one or more parameterValues elements are required that specify parameter values to be substituted in that template
• More than one templateParameterValues element may be present that references the same template provided that none of the parameterValue names are duplicated.
• Before validating the correctness of a package definition that contains templateParameterValue elements, the parameterValues must be used to substitute values in the referenced  template first
• In the example above:
• A parameterValue for tns:OrderMsg must be present as there is no default value for this parameter in the template definition
• A parameterValue for tns:OrderAckMsg need not be, but could have been, present, as it has a default value in the template definition
• The content of the parameterValue element with the name tns:RetailerInfo is used to substitute the name tns:RetailerInfo in the template definition. This means that <someElement>tns:RetailerInfo</someElement> in the template definition would, after substitution, become  <someElement><someXMLorOtherText>...</someXMLorOtherText></someElement>.

3.3 Combining Both

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

<package name="ConsumerPurchasingChoreoTemplate" version="1.0">
  <templateParameterDefinitions>
    ...
  </templateParameterDefinitions>
  <templateParameterValues template="ConsumerRetailerChoreoTemplate" templateVersion="1.0">
    ...
  </templateParameterValues>
  <templateParameterValues template="RetailerShipperChoreoTemplate" templateVersion="1.0">
    ...
  </templateParameterValues>
  ...
  <importDefinitions>
    <import ... "ConsumerRetailerChoreoTemplate"/>
    <import ... "RetailerShipperChoreoTemplate"/>
  </importDefinitions>
  ...
</package>

Notes.

• The templateParameterValues elements provide 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.
• This example:
• Creates a new choreography package out of two imported choreography templates
• Includes importing separate template definitions using an import element. This has not been specified in detail as the method for doing imports is under review.

4 General Notes

Note that:

• A package element can define one of:
• A "package" as currently defined – i.e. without 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 one or more templateParameterValues elements for each of the template choreographies used
• A "choreography template" that references one or more previously defined "template based choreographies". i.e. it contains both a templateParameterDefinitions and templateParameterValues elements
• Errors occur if:
• "Duplicate" parameterValue statements occur, i.e. the same parameterValue name attribute occurs more than once when specifying the parameter values for a template package
• parameter elements without default values are present in a templateParameterDefinitions element in a template for which no values are provided when that  template is referenced by a templateParameterValues element
• There are circular references, i.e. a templateParameterValues elementreferences a template that contains templateParameterValues elements that reference the first template definition

David Burdett
Commerce One
June 30, 2004