v0.3
Editors:
Steve Graham (Chair), David Snelling, William Vambenepe, 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, Sanjiva Weerawarana,
(frequent mailing list participation)
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 should be able to know what their permissions
are on attributes before trying to access the attribute.
2.
Query across attributes (in one
service) by some query language.
3.
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”.
4.
Ability for the user to know type of
attributes ahead of time
5.
Input/output messages that manipulate
attributes can be validated against WSDL
6.
Static attributes
7.
Ability to restrict access on a per attribute
basis.
8.
Ability to restrict read vs. write
access
9.
Attributes inheritance through WSDL 1.2
interface inheritance
10. Metadata on attributes (creation date, type, description...)
11. Bulk retrieval of several attributes in one operation
12. 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.
<definitions>
<binding>
<attribute
element="xs:QName"?
style="xs:AnyURI"
>
<documentation />?
</attribute>*
</binding>
</definitions>
The
set of operations or messages that allow requestors to read and/or write
elements of a service’s data and/or meta-data is specified by the attribute
element child of a binding.
The
properties of the Attribute Component are as follows:
·
{element} A reference, by Qname, to an
attribute declared in an interface.
·
{style} A URI, which defines the access
mechanism by which attributes can be manipulated by a requestor.
If an attribute element is
defined without a value for the name attribute, it is considered to define a “generic”
access mechanism available for all attributes associated with the interface. It
is legal to define zero or more such generic access mechanisms.
If an attribute element is
defined with a name value, then the access mechanism applies only to the named
attribute. The access mechanism described in this manner is in addition to the
set of “generic” access mechanisms that may be associated with the binding. It
is legal to define zero or more access mechanisms for a specific attribute.
Through a combination of generic
and named attribute bindings, all attributes defined in the interface MUST be
associated with at least one access mechanism.
Because the set of attributes
for an interface may be a superset of the attributes defined in the interface,
it is legal to include an attribute element in the binding that refers to (by
name) an attribute that does not appear in the attributes listed in the
interface. Although this is a deviation from how bindings refer to operations
in interfaces, it is required for attributes to support the notion of “dynamic
attributes” as suggested from the OGSI work. Attributes not listed in the
interface can also be accessed through a generic access mechanism if there is
some means by which the requestor can discover the list of attributes available
at runtime.
The access mechanism identified
by the URI value of the style attribute defines the semantic of how the
attributes declared at the interface level can be accessed. The designer of the
attribute binding chooses access mechanisms from one of possibly many different
choices.
The creator of an access mechanism
is free to use any approach he or she chooses to define the access mechanism,
be it pure English or a mix of WSDL constructs and English, RDF, etc.
Nevertheless, the description of the access mechanism must provide enough
information for the requestor to derive a set of named operations (and their
signatures) as well as the QName of an interface containing
all the operations in the access mechanism.
The creator of an access
mechanism is not required to provide an actual WSDL interface when specifying
an attribute access mechanism; for example operation names might depend on the
attributes available in the interface and this list may not be known when describing
the attribute access mechanism. It is legal for an access mechanism to reference
a QName indicating the interface definition that describes
the attribute access operations.
The remainder of the binding(s)
associated with the interface can define binding information for the operations
mandated by the access mechanism, just as if the interface corresponding to the
binding extended the interface defined by the access mechanism. Note that the interface
associated with binding is not required to extend the interface mandated by the
access mechanism[4][sgg1].
Note that an access mechanism is
not limited to specifying how to read and write attribute values; it could
provide other functions, such retrieving a list of attributes.
Attribute inheritance is distinct
from the binding choices made to associate access mechanism. So, interface extension
can redefine the semantic of attributes in a fashion similar to operations.
With regards the relationship
between attributes and their access mechanism, the only thing that matters is the
access mechanism(s) identified in the binding for the interface. Consider the
following situation.
·
Interface I1 defines attribute A1 and there is a binding B1 for
this interface which mandates access operation AM1.
·
Interface I2 extends interface I1 and there is a binding B2 for
this interace.
Access to attribute A1 of
interface I2 (or any other attribute or operation in interface I2) is governed
by binding B2 for interface I2. The access methods available to retrieve
attribute A1 of interface I2 are those supported in binding B2. The fact that
binding B1 provides an access method AM1 is immaterial.
In summary, operations
associated with the access mechanism are not part of the interface and are not
affected by interface inheritance.
We propose that WSDL define the
following three access mechanisms:
(defining
URIs associated with the WSDL 1.2 namespace):
This is a simple access mechanism
that mandates a get and/or a set method for
each attribute (based on the value of the access
attribute) with a simple naming
algorithm. For each attribute, with QName tns:XXX,
define:
tns:getXXX and tns:setXXX for each attribute,
where XXX is the local name of the attribute. The namespace of the operations
is the same as the namespace of the attribute name.
getXXX (defined if read access is available on
the attribute) returns an element of the type specified by the attribute
declaration
setXXX (defined if write access is available on
the attribute) takes an element of the type specified by the attribute
declaration and returns an empty message.
This mechanism does not define a
way to retrieve the list of attributes and could therefore only provide access
to the attributes listed in the interface; dynamic attributes could not be
accessed using this mechanism.
This access mechanism mandates a
single pair of untyped
operations: get and set that take as input the name (and, in the case of
"set", value). The namespace of the operations is the same namespace
of the wsdl definitions element containing the
binding element.
This access mechanism also
provides a getAttributeNames operation as a way to determine
the list of attributes supported by a Web service. This operation also has the
same namespace as the wsdl definitions element.
This access mechanism is a
powerful and flexible one that supports the most sophisticated requirements
collected by the task force. This access mechanism mandates a single pair of untyped operations: get and set, both of which take an
expression as parameter.
This access mechanism also
provides a getAttributeNames operation as a way to determine
the list of attributes supported by a Web service. The namespace of the
operation is the same namespace as the wsdl
definitions element.
This access mechanism would
support expressions for getting and setting attributes including:
-
read of multiple attributes
-
bulk modification of multiple attributes
-
queries (such as XPath) across multiple
attributes.
-
and
support for metadata on attributes.
This mechanism would be based on
query languages such as XPath or XQuery and would
build upon the work done in OGSI.
Note:
other access mechanisms can be created by other designers. It is the
responsibility of these other designers to make the URI of their access
mechanism well known and widely supported.
Note:
it is possible to accommodate WebDAV-based datastores by some organization
defining a “WebDAV” attribute access mechanism that mandates propfind and
proppatch operations.
We considered several possible
approaches:
a) CORBA IDL-like convention
b) similar
to a) but single operation, no strong typing
c) JavaBeans pattern
d) a
“base” Web services interface that defines the attribute operations.
The task force concluded that
none of these approaches could be chosen as the ONLY access mechanism. As a
result of this conclusion, we developed an extensible mechanism for attribute
access as embodied in our proposal.
Consider the following interface:
<wsdl:interface name=”somePT”
…>
<attribute element=”tns:sd1”>
<attribute element=”tns:sd2” access=”read”>
…
</wsdl:interface>
What can the requestor conclude
about how to read/write values of sd1 or sd2?
A CORBA IDL like approach would suggest that the requestor could invoke
operation(s):
-
getsd1(), with no input message and that would
return a message containing a single tns:sd1 element.
-
getsd2(), with no input message and that would
return a message containing a single tns:sd2 element.
-
setsd2(), with an input message with a single tns:sd2
element and that returns an output message that is empty.
If we go with an implicit
operation approach, there is no reason why a designer should be bound to only a
strongly typed get/set pair. An
alternative on this would be a single get() and single
set() operation that takes the qname of the attribute
as parameter (only parm in get() and the first of two
parms in the set()). The get returns xsd:any and the set still returns
empty message, but its second input parm is also an xsd:any. This is
something like:
xsd:any
get(qname)
void
set(qname, xsd:any)
This way the binding does not
have to specify separate construct for each attribute, but rather, there needs
to be a single binding for a single implicit get operation and a single implicit
set operation.
This also gives tooling the
freedom to *choose* if it wants to generate a type strong getXXX
and setXXX method at the language level or *choose*
to accept the weakly typed get() and set()
operation. There is enough information
in the interface’s attribute elements to define the strongly typed operations,
if the tooling chooses to do so.
Languages like Smalltalk don’t have strong typing.
This model will also allow OGSI
to extend the concept for findServicedata and setServiceData more conveniently.
If we go with a CORBA IDL like
approach, we are challenged to answer the question, why define attributes at
all, just do getXXX and setXXX
and therein imply that an attribute called XXX exists and infer the type from
the input and output messages.
This argument was raised on the
email list and addressed quite deftly[5].
There appears to be non-trivial
opposition to this approach within W3C.
This section discusses how our
proposal addresses the requirements gathered by the task force:
1.
The user should be able to know what their
permissions are on attributes before trying to access the attribute.
-
This can be accomodated by the open
content model on attribute declaration. In general security is beyond the scope
of WSDL 1.2.
2.
Query across attributes (in one
service) by some query language.
-
This can be accomodated by the powerful
access mechanism Expression
Based Access Mechanism
3.
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”.
-
This can be accomodated by the access
mechanisms Expression Based
Access Mechanism and Untyped Get/Set
Operations.
4.
Ability for the user to know type of
attributes ahead of time
-
This is accomodated by type information
element of the attribute component.
5.
Input/output messages that manipulate
attributes can be validated against WSDL
-
Operations to access attributes are
defined by various access mechanisms. Access mechanisms MAY be associated with
WSDL interface definitions, and thereby be validatable. For those access
mechanisms that do not explicitly identify WSDL interface, they MUST provide
enough information for the requestor to construct such and interface.
6.
Static attributes
-
This can be accomodated by the open
content model on attribute declaration. WSDL 1.2 will not define the means by
which static values are associated with the attribute definition.
7.
Ability to restrict access on a per
attribute basis.
-
This can be accomodated by the open
content model on attribute declaration. In general security is beyond the scope
of WSDL 1.2.
8.
Ability to restrict read vs. write
access
-
This can be accomodated by the access
information element on the attribute component.
9.
Attributes inheritance through WSDL 1.2
interface inheritance
-
Attributes, like operations can be
inherited.
10. Metadata on attributes (creation date, type, description...)
-
This can be accomodated by the open
content model on attribute declaration. WSDL will not describe any particular
meta data information elements.
11. Bulk retrieval of several attributes in one operation
-
This can be accomodated by the powerful
access mechanism Expression
Based Access Mechanism
12. Attributes can be of any schema type (simple or complex)
-
This is accomodated by type information
element of the attribute component.
[1] http://lists.w3.org/Archives/Public/public-ws-desc-state/2003Jun/0013.html
[2] Note: this could be either element or complexType. We need to align this with whatever the message removal proposal implies for how operation defines the types of its parts
[3] Note: this section is subject to change, reflecting continuing discussions regarding changes to the binding element by the WSDL WG.
[4] Note: There is a potential operation name collision that we may need to resolve. If the interface designer creates a getFoo operation and chooses an access mechanism that also defines a getFoo operation (but with different parameters). This is a problem only if the interface and the access mechanism are in the same namespace. Should the access mechanism explicitly define the namespace of the operations it defines?
[5] http://lists.w3.org/Archives/Public/public-ws-desc-state/2003Jul/0016.html
[sgg1]Are the operations namespace-qualified at the binding level?