v0.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, or components
of a Web service’s data and/or meta-data, in WSDL.
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.
This syntactic convention is
associated with a very flexible mechanism to associate access mechanisms with
the attribute declaration.
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
means by which a requestor accesses attributes is determined by the access
mechanism(s) specified in 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 could 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.
There is no guarantee that the
list of attributes provided in the interface is the complete list of attributes
available, it is only a minimum, required
list. Attribute access mechanisms (see below) are free to define operations to
access attributes not defined in the interface, for example by providing a way
to retrieve a list of attributes at runtime.
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. 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 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.
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:
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 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.