[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: WSDL annotation proposal
All:
Here is a reviewed version of Anish WSDL annotation (inspired from F & P) initial proposal for WS-Reliability.
(Anish agreed with my review, after a few iterations between us...)
It has been now focused more narrowly to the use of Reliable features and capabilities.
I think each feature in it has proved useful for our purpose, and does not define more than what we need.
The mechanism is indeed quite flexible (I have more use cases to show this).
Jacques
<<ws-reliability-wsdl-annotations-final.txt>>
WS-Reliability Features, Properties and Compositor Proposal
-----------------------------------------------------------
I. Introduction
Users of a Web Service will need to be aware of the reliability capabilities
(RM capabilities)that are supported/required by the service. One practical location to
advertise these capabilities is in the service description (WSDL document),
which allows for publishing both abstract service definitions as well as
concrete protocol details (bindings). This allows clients (or other Web
services) to easily obtain information about specific capabilities such as
guaranteed delivery, duplicate elimination, message ordering, and various
reply patterns of a specific Web service, before calling the service. While
bundling reliability capabilities with the service description may not be
desirable in all cases, it is expected that this convenient approach will
often be appropriate. The WSDL annotation mechanism described here is a
flexible way to add such capability assertions.
WS-Reliability uses the WSDL 1.1 extensibility points to define an extensible
framework consisting of features, properties and compositors to address
the needs of a reliable Web service to advertise its capabilities, and
composibility of those capabilities.
The following extensibility elements relevant to RM capabilities are used:
* feature - abstract RM capability or assertion associated with WSDL elements.
* property - an assertion or constraint on an atomic RM capability and its value(s)
associated with WSDL elements.
* compositor - specify how features and properties are combined.
An annotation composed with the above extensibility elements will specify the
reliability features and properties associated with specific WSDL constructs.
Features and properties represent reliability capabilities and compositors
specify how these capabilities are composed.
This would allow, for example, a Web service description to advertise the fact
that clients invoking the service must use duplicate elimination or message
ordering.
I.A Notational Convention
This specification uses the following namespace prefixes:
Prefix Namespace
------ ---------
xs "http://www.w3.org/2001/XMLSchema";
wsdl11 "http://schemas.xmlsoap.org/wsdl/";
fnp "http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/";
wsrm "http://www.oasis-open.org/committees/wsrm/schema/1.1/feature/rel/";
The choice of any namespace prefix is arbitrary and not semantically
significant.
I.B Conformance
Implementations of WS-Reliability are expected, though not required, to
understand the WSDL extensibility points defined in this section.
Understanding of these extensibility points promotes interoperability. When a
WSDL document contains these extensibility points, it is through these
extensibility points that a service advertises its supported and required
features. Therefore it is RECOMMENDED that implementations recognize,
understand and support these extensibility points.
It is also possible for services to advertise features through other channels
(such as UDDI) in addition to these extensibility point.
II. WSDL Extensibility Elements
II.A Compositor
The compositor semantics describe how features and properties are
composed for the enclosing component (or WSDL 1.1 element).
The compositor's semantics determine whether the usage of composed elements
by a client to the service, is required or optional.
The RM capabilities represented by these elements must all be supported by the Service.
A compositor element can occur as a child element of wsdl11:portType,
wsdl11:operation (which may itself be a child of wsdl11:portType or
wsdl11:binding), wsdl11:binding, wsdl11:service and wsdl11:port. The
compositor element utilizes the extensibility defined by WSDL 1.1. A
compositor element specifies the semantics for combining its children
elements. These children elements can be additional compositor, features,
properties, or extensibility element(s).
A compositor element is expressed by the following pseudo-syntax:
<fnp:compositor uri="..." name="NCName"?>
[fnp:feature/> | <fnp:property/> | <fnp:compositor/> |
<extensibility-element/>]+
</fnp:compositor>
The uri attribute of the compositor specifies its semantics. Four different
compositors (URIs) and their capability-related semantics are described
below. It is possible to provide additional compositors by using
other URIs. The ability to define additional compositors and the existence of
extensibility points (represented by "<extensibility-element>") make the
framework extensible. The optional name attribute identifies the compositor. An
element built with such compositors represents an RM capability.
1. all: this compositor specifies that a service invocation MUST comply with
all the children elements (representing RM capability assertions).
This compositor is identified by using the URI:
"http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositors/all";
2. choice: this compositor specifies that a service invocation MUST comply with
exactly one of the possibly many children elements (representing RM capability assertions).
This compositor is identified by using the URI:
"http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositors/choice";
3. one-or-more: this compositor specifies that a service invocation MUST comply with
at least one of the possibly many children elements (representing RM capability assertions).
This compositor is identified by using the URI:
"http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositors/one-or-more";
4. zero-or-more: this compositor specifies that a service invocation MAY comply with
one or more of the children elements (representing RM capability assertions).
This compositor is identified by using the URI:
"http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositors/zero-or-more";
Examples for each compositor are provided in Section VII below.
Compositors specified at different WSDL components are implicitly aggregated
using the 'all' compositor at the dependent WSDL component. Consider the example
below,
<wsdl11:definitions>
...
<wsdl11:portType name="myPortType">
<fnp:compositor uri="..." name="A">
...
</fnp:compositor>
...
</wsdl11:portType>
<wsdl11:binding name="myBinding" type="myPortType">
<fnp:compositor uri="..." name="B">
...
</fnp:compositor>
...
<wsdl11:binding>
<wsdl11:service name="myService">
<wsdl11:port name="myPort" binding="myBinding>
...
</wsdl11:port>
</wsdl11:service>
<wsdl11:definitions>
Compositor specified at the wsdl11:portType "myPortType" and compositor
specified at wsdl11:binding "myBinding" are aggregated at the dependent
wsdl11:port "myPort" using the 'all' compositor. I.e., the equivalent
compositor at "myPort" is,
<fnp:compositor
uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositor/all";>
<fnp:compositor uri="..." name="A">
</fnp:compositor>
<fnp:compositor uri="..." name="B">
...
</fnp:compositor>
</fnp:compositor>
II.B Feature
A feature describes an abstract RM capability or assertion associated with a WSDL
element. A feature can occur only as a child of a compositor.
Whether the usage of a
feature is required or not is defined by the enclosing compositor(s). A
feature is identified by a URI. Recognizing the URI of a feature is considered
to be equivalent to understanding the feature identified by that URI.
A feature element is expressed by the following pseudo-syntax:
<fnp:feature uri="...">
[<fnp:compositor/> | <extensibility-element/>]*
</fnp:feature>
II.C Property
A property is identified by a QName. A property is an assertion or constraint on
a specific RM capability and its value(s) associated with WSDL elements.
Typically properties are associated
with a feature (but are not required to) and are described in a feature
specification. The QName identifier of a property uniquely identifies the
property. Recognizing the property QName identifier is considered to be
equivalent to understanding the semantics associated with that property. The
property QName identifier typically points a global XML Schema element
declaration. A property specification typically specifies the schema that
contains this global element declaration. A constraint on the set of values
that a property can have is specified by a QName that identifies a XML Schema
type.
<fnp:property name="xs:QName">
[<fnp:value>xs:anyType</fnp:value> |
<fnp:constraint>xs:QName</fnp:constraint>]
[<extensibility-element/>]*
</fnp:property>
III. WS-Reliability Feature
The WS-Reliability feature is identified by the URI
"http://www.oasis-open.org/committees/wsrm/schema/1.1/feature/rel/";
This feature URI identifies the WS-Reliability specification. Understanding
this URI implies understanding the WS-Reliability specification.
IV. WS-Reliability Properties
This section identifies properties for the WS-Reliability specification.
Typically these properties would be scoped within the feature identified by the
URI "http://www.oasis-open.org/committees/wsrm/schema/1.1/feature/rel/";
IV.A. Guaranteed Delivery Property
This property is identified by the QName "wsrm:GuaranteedDelivery" and
corresponds to the semantics specified by the WS-Reliability guaranteed
delivery semantics. The type of this property is "xs:boolean".
IV.B. Duplicate Elimination Property
This property is identified by the QName "wsrm:NoDuplicateDelivery" and
corresponds to the semantics specified by the WS-Reliability duplicate
elimination semantics. The type of this property is "xs:boolean".
IV.C. Message Ordering Property
This property is identified by the QName "wsrm:OrderedDelivery" and
corresponds to the semantics specified by the WS-Reliability message
ordering semantics. The type of this property is "xs:boolean".
IV.D. Reply Pattern Property
This property is identified by the QName "wsrm:ReplyPattern" and
corresponds to the semantics specified by the WS-Reliability reply
pattern options. The type of this property is "xs:String".
(values: Response, Poll, Callback)
V. Other Reliability Properties
In addition to the properties defined in section III, there are
WS-Reliability properties that are used on the Sender side (usually the client side
and therefore do not occur in the WSDL document).
This section identifies such properties. These properties MUST NOT be specified
in the WSDL document. How the properties are specified and/or represented does
not affect interoperability as these properties are client-side only
properties. They are defined here for convenience only.
V.A. Group Expiry Time
This property is identified by the QName "wsrm:GroupExpiryTime" and
corresponds to the semantics specified by the WS-Reliability group expiration
time. The type of this property is xs:duration.
Note: The expiry time is calculated at the time a message is sent, but adding
this duration to the time the message is sent.
V.B. Group Maximum Idle Duration
This property is identified by the QName "wsrm:GroupMaxIdleDuration" and
corresponds to the semantics specified by the WS-Reliability group maximum idle
duration. The type of this property is xs:duration.
V.C. Message Expiration Time
This property is identified by the QName "wsrm:ExpiryTime" and
corresponds to the semantics specified by the WS-Reliability message expiration
time. The type of this property is xs:duration.
Note: The expiry time is calculated at the time a message is sent, but adding
this duration to the time the message is sent.
V.D. Retry Maximum Time
This property is identified by the QName "wsrm:RetryMaxTimes" and
corresponds to the semantics specified by the WS-Reliability maximum retry
times. The type of this property is xs:int.
V.E. Retry Time Interval
This property is identified by the QName "wsrm:RetryTimeInterval" and
corresponds to the semantics specified by the WS-Reliability retry time
interval. The type of this property is xs:duration.
V.F. ReplyTo URI
This property is identified by the QName "wsrm:ReplyTo" and
corresponds to the semantics specified by the WS-Reliability reply-to.
The type of this property is xs:anyURI.
VI. Schema
<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema";
xmlns:wsrm="http://www.oasis-open.org/committees/wsrm/schema/1.1/feature/rel/";
targetNamespace="http://www.oasis-open.org/committees/wsrm/schema/1.1/feature/rel/";
elementFormDefault="qualified" >
<!-- properties to be used in WSDL -->
<xs:element name="GuaranteedDelivery" type="xs:boolean"/>
<xs:element name="NoDuplicateDelivery" type="xs:boolean"/>
<xs:element name="OrderedDelivery" type="xs:boolean"/>
<xs:element name="ReplyPattern" type="xs:string"/>
<!-- properties to be used on the client side -->
<xs:element name="GroupExpiryTime" type="xs:duration"/>
<xs:element name="GroupMaxIdleDuration" type="xs:duration"/>
<xs:element name="ExpiryTime" type="xs:duration"/>
<xs:element name="RetryMaxTimes" type="xs:int"/>
<xs:element name="RetryTimeInterval" type="xs:duration"/>
<xs:element name="ReplyTo" type="xs:anyURI"/>
</xs:schema>
VII. Examples
VII.A Example for the "all" compositor
<wsdl11:portType name="Example-1">
<fnp:compositor uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositor/all";>
<fnp:feature uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/feature/rel/";
<fnp:compositor uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositor/all";>
<fnp:property name="wsrm:DuplicateElimination">
<fnp:value>true</fnp:value>
</fnp:property>
<fnp:property name="wsrm:OrderedDelivery">
<fnp:value>true</fnp:value>
</fnp:property>
<fnp:property name="wsrm:GuaranteedDelivery">
<fnp:value>true</fnp:value>
</fnp:property>
</fnp:compositor>
</fnp:feature>
</fnp:compositor>
...
</wsdl11:portType>
In the example above, the reliability feature identified by URI
"http://www.oasis-open.org/committees/wsrm/schema/1.1/feature/rel/"; is
required by the portType. This feature consists of three properties, all of
which are required because of the semantics of the 'all' compositor that
composes the three properties.
VII.B Example for the "choice" compositor:
<wsdl11:binding name="Example-2">
<fnp:compositor uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositor/all";>
<fnp:feature uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/feature/rel/";
<fnp:compositor uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositors/choice";>
<fnp:property name="wsrm:ReplyPattern">
<value>Response</value>
</fnp:property>
<fnp:property name="wsrm:ReplyPattern">
<value>Callback</value>
</fnp:property>
<fnp:property name="wsrm:ReplyPattern">
<value>Poll</value>
</fnp:property>
</fnp:compositor>
</fnp:feature>
</fnp:compositor>
...
</wsdl11:binding>
In the example above, the reliability feature identified by URI
"http://www.oasis-open.org/committees/wsrm/schema/1.1/feature/rel/"; is
required by the portType. This feature consists of three properties, of which
the client must choose one.
VII.C Example for the "one-or-more" compositor:
<wsdl11:portType name="Example-3">
<fnp:compositor uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositor/all";>
<fnp:feature uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/feature/rel/";
<fnp:compositor uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositor/one-or-more";>
<fnp:property name="wsrm:DuplicateElimination">
<fnp:value>true</fnp:value>
</fnp:property>
<fnp:property name="wsrm:OrderedDelivery">
<fnp:value>true</fnp:value>
</fnp:property>
<fnp:property name="wsrm:GuaranteedDelivery">
<fnp:value>true</fnp:value>
</fnp:property>
</fnp:compositor>
</fnp:feature>
</fnp:compositor>
...
</wsdl11:portType>
VII.D Example for the "zero-or-more" compositor:
<wsdl11:portType name="Example-4">
<fnp:compositor uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositor/all";>
<fnp:feature uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/feature/rel/";
<fnp:compositor uri="http://www.oasis-open.org/committees/wsrm/schema/1.1/fnp/compositor/zero-or-more";>
<fnp:property name="wsrm:DuplicateElimination">
<fnp:value>true</fnp:value>
</fnp:property>
<fnp:property name="wsrm:OrderedDelivery">
<fnp:value>true</fnp:value>
</fnp:property>
<fnp:property name="wsrm:GuaranteedDelivery">
<fnp:value>true</fnp:value>
</fnp:property>
</fnp:compositor>
</fnp:feature>
</fnp:compositor>
...
</wsdl11:portType>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]