v0.4.4
Editors:
Steve Graham (Chair), David Snelling, William Vambenepe, Sanjiva Weerawarana, Umit Yalcinalp
Members of the Attributes Task
Force would like to acknowledge the contributions of the following people. This
document is a synthesis of contributions made by these people:
Philippe
Le Hegaret, Savas Parastatides, Krishna Sankar, Jim
Webber
Jim Amsden,
Jeff Michinsky (invited experts).
The Attributes Task Force was
chartered to consider the requirements for modeling attributes. Attributes can
be considered as a mechanism to describe a pattern of operations, or message
sets. This short hand or convenience mechanism can be used in a variety of
ways, including: describing data or meta data properties of a service,
describing elements of a service’s state (if, in fact that service has state).
This specification does not mandate a particular use pattern for Attributes.
We have gathered requirements
and explored various alternatives and precedents in the industry, including: WebDAV, CORBA IDL attributes and OGSI ServiceData.
This document summarizes our
analysis and a recommendation to the W3C Web Service Description Working Group.
The following are the
requirements gathered by the Attributes Task Force[1].
The solution must allow or support. Note: many of the requirements are not met
directly by the task force’s proposal; the proposal has been designed to permit
others to build solutions using, for example, open content.
1.
The user to know a (potentially partial)
list of attributes at design time. This implies that additional attributes may
appear at runtime. OGSI calls this facility “dynamic serviceData”.
2.
Ability for the user to know type of
attributes ahead of time
3.
Ability to restrict read vs. write
access
4.
Attributes inheritance through WSDL 1.2
interface inheritance
5.
Metadata on attributes (creation date,
type, description...)
6.
Attributes can be of any schema type
(simple or complex)
The attributes task force
proposes the inclusion of attribute declarations to WSDL interfaces as
presented in this document. Declaring attributes in the WSDL interface provides
a uniform way of declaring information items constituting the Web service’s
data and/or meta-data that can be accessed or modified by Web service requestors.
Based on the experience gained
in OGSI and in systems management, we assert that providing a syntactic
convention for declaring attributes in the interface with accessibility options
is useful for tools to build systems.
The proposed solution has two
components:
1. A mechanism to define
Attributes as part of an interface definition;
2. A mechanism to describe how
Attributes and their values can be manipulated.
A
designer uses the attribute element to identify the types of attributes
associated with an interface. These elements may be read or written. The exact set
of messages by which a requestor accesses attributes is determined by the the
binding.
<definitions>
<interface>
<attribute
element="xs:QName"
access= “read” | “write” | “read-write”? >
<documentation />
</attribute>*
</interface>
</definitions>
We propose to add an additional component,
named attribute, as child of the
interface element.
The
properties of the Attribute Component are as follows:
·
{element} A reference, by QName to a
Global XML element.[2]
·
{access} A fixed enumeration of strings
(“read” or “write” or “read-write”).
An
interface MAY have zero or more attribute element children. Each element
defines a single attribute. Constraints on the values of element property are
the same as constraints on the operation name property. For example, an
interface MUST not have two attribute elements that have the same value of
their @element attribute. The rules related to attribute uniqueness in light of
interface extension are the same as for operations.
Just as the binding element
defines the transport and encoding details of how operations are invoked, so
too does the binding element define how attributes are accessed.
For attribute access, the
binding type defines the set of messages that are to be used to read or write
values of a Web services’ attributes.
WSDL 1.2 will define the message
sets associated with attribute access for each binding it defines. Any service
that implements interfaces that have attribute child information items are
expected to understand the messages defined by the pattern specified in this
section. Binding types defined elsewhere will be required to indicate how
attributes can be read and written using that binding.
Additional attribute access
(such as XPath expression-based access) may be specified (by others) by
defining operations in an interface.
In the case of SOAP binding, the
value of an attribute can be read by sending the following message to an
endpoint associated with a SOAP binding:
<soap:envelope>
<soap:body><wsdl:get-attribute
name=xsd:QName/></soap:body>
</soap:envelope>
Note the introduction of the wsdl:get-attribute element that contains one attribute, the
QName of an attribute.
If the value of the QName attribute corresponds to an attribute of the Web
service, then the following response can be expected by the requestor:
<soap:envelope>
<soap:body ...>
<xsd:QName> current value </xsd:QName>
</soap:body>
</soap:envelope>
Where the current value of the
attribute is contained in the body of the SOAP response.
If the value of the QName attribute does not correspond to an attribute of the
Web service, then the following fault message can be expected by the requestor:
<soap:envelope>
<soap:body ...>
<soap:Fault>
<soap:Code>
<soap:Value>soap:Sender</soap:Value>
<soap:Subcode>
<soap:Value>wsdl:UnknownAttribute</soap:Value>
</soap:Subcode>
</soap:Code>
<soap:Reason>
<soap:Text
xml:lang="en">Unknown Attribute</env:Text>
…
</soap:Reason>
</soap:Fault>
</soap:body>
</soap:envelope>
Where the wsdl:UnknownAttribute
is also defined by WSDL.
If attribute does not support
read access, then the following fault message can be expected by the requestor:
<soap:envelope>
<soap:body ...>
<soap:Fault>
<soap:Code>
<soap:Value>soap:Sender</soap:Value>
<soap:Subcode>
<soap:Value>wsdl:WriteOnlyAttribute</soap:Value>
</soap:Subcode>
</soap:Code>
<soap:Reason>
<soap:Text
xml:lang="en">Attribute cannot be read</env:Text>
…
</soap:Reason>
</soap:Fault>
</soap:body>
</soap:envelope>
Where the wsdl:WriteOnlyAttribute
is also defined by WSDL.
Other application specific fault
messages may appear.
The value of an attribute can be
written to by sending the following message to an endpoint associated with a
SOAP binding:
<soap:envelope>
<soap:body>
<xsd:QName>
new value </xsd:QName>
</soap:body>
</soap:envelope>
The requestor should expect no
response from this message. It is up to the requestor to use other means to
determine this message accomplished a change in the value of the attribute.
Note: the similarity between
response of get message and the set message request. Because WSDL defines only
request/response over HTTP, this ambiguity does not appear in actuality. For
asynchronous bindings, it is the responsibility of the binding to describe the
correlation mechanism by which these messages can be disambiguated.
In the case of an http binding
to the Web service, the current value of an attribute can be retrieved by
issuing the following get verb to the service’s endpoint url:
url?attribute-ns="xsd:anyURI"&attribute-localname="localName"
If the combination of the
attribute-ns and the attribute-localname identify a QName of an attribute associated with the Web service, then
the current value of the attribute is returned in the body of http response
message.
If the attribute identified by
the parameters of the get is not associated with the Web service, or the
attribute is write-only, then an error message is returned in the body of the
http response message.
The value of an attribute can be
written by sending an http POST message to the service’s endpoint associated
with a HTTP binding. The body of the POST message would contain the new value
of the attribute.
<xsd:QName> new
value </xsd:QName>
The requestor should expect no
response from this message. It is up to the requestor to use other means to
determine this message accomplished a change in the value of the attribute.