[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]