Level: Introductory Kane Scarlett (kane@us.ibm.com), developerWorks Editor, IBM
19 Sep 2006 Meet the WS-ResourceTransfer 1.0 initial draft specification (WS-RT), a proposed open standard that extends certain operations by allowing fragments of XML code in a single resource to be addressed instead of having to affect the entire resource. This introduction provides an overview of the specification, examines its heritage, and starts climbing the learning curve by uncovering the definition of fragments and discovering the three expression dialects employed in WS-RT.
This series of Meet the specs articles focuses on various components of the WS-ResourceTransfer 1.0 initial draft specification. This article includes excerpted and paraphrased text from the original specification. To view the specification in its entirety, see Resources.
The WS-ResourceTransfer 1.0 initial draft specification defines extensions to WS-Transfer, a general SOAP-based protocol for accessing XML representations of Web service-based resources. The family of Web services specifications, the "WS-" group, is designed to interoperate with other members of the family to deliver a set of tools for the Web services environment. As such, this specification relies on other WS specifications for such functions as message delivery and to express WS metadata.
WS-RT is an essential core component of a unified resource access protocol for Web services. The WS-RT extensions deal mostly with fragment-based access to resources to satisfy the common requirements of WS-ResourceFramework and WS-Management specifications. The specification goals are to fulfill these requirements:
- Define a standardized technique for accessing resources using semantics (
get, put, create, and delete) familiar to system-management professionals.
- Define WS-I BP 1.1-compliant WSDL 1.1 portTypes for the Web service methods described in the specification.
- Define minimum requirements for compliance without constraining richer implementations.
- Compose with other Web service specifications for secure, reliable, transacted message delivery.
- Provide extensibility for more sophisticated or currently unanticipated scenarios.
- Support a variety of encoding formats including SOAP 1.1 and SOAP 1.2 Envelopes.
This specification is not attempting discovery of resources.
Before examining the parts of this specification, take a look at its progenitor, WS-Transfer.
 |
Specification contributors
HP, IBM®, Intel, and Microsoft® collaborated to publish WS-ResourceTransfer (WS-RT), an initial draft that describes an extension to the WS-Transfer specification. WS-Transfer defines standard messages for controlling resources using the familiar paradigms of get, put, create, and delete. The extensions deal primarily with fragment-based access to resources to satisfy the common requirements of WS-ResourceFramework and WS-Management.
|
|
Let's start with WS-Transfer
WS-Transfer defines a mechanism for acquiring XML-based representations of entities using the Web service infrastructure. It defines two types of entities -- resources and resource factories. Resources are Web services that are addressable by an endpoint reference (as defined in WS-Addressing) that provides an XML representation. Resource factories are Web services that can create a new resource from an XML representation. What WS-T specifically defines is two operations for sending and receiving the representation of a given resource and two operations for creating and deleting a resource and its corresponding representation.
WS-Transfer defines operations to the get, put, create, and delete representations of resources. WS-ResourceTransfer extends these operations to add to them the capability to operate on fragments of the resource representations.
The capabilities added by WS-RT
As I just said, WS-ResourceTransfer extends get, put, create, and delete operations so they can operate on fragments of the resource representations. So what's a fragment?
Fragments
The wsa:EndpointReference (or EPR) defined by WS-Addressing is a reference to the resource in its entirety. Operations are normally unconstraining in WS-A except they are assumed to affect the resource as a whole. Fragments are just that -- pieces of XML code that are part of the resource. The capability WS-RT imparts to the previously mentioned operations is the ability to access parts of the XML of a resource; this is known as fragment access.
WS-RT defines an extensible mechanism for designating the expression syntax by which the fragment is addressed; it also defines several such standard expression syntaxes or dialects.
Expression dialects
Expression dialects form an expression that can be evaluated with respect to the XML document that represents the resource -- the de-referenced value of the expression is the part of the XML that is of interest. The expression can create a logical pointer to the fragment of XML that is of interest or it may craft a query that can be applied to the XML document to produce an evaluated result. (Remember: These expression dialects simply ID the appropriate fragment of the resource representation; it's the action that defines what happens to the fragment.)
Each dialect has to clearly specify how the result of evaluating a given expression against a resource representation is serialized to XML. It should specify dialect-specific behavior for operations that access the resource. Dialects include:
- QName.
- XPath Level 1.
- XPath 1.0.
The QName dialect is a simple dialect for expressions that uses a QName to reference the immediate children of the root element of the resource representation. QName is useful for simple resources with no XPath processing capability. The QName dialect must be indicated by using the URI: http://schemas.xmlsoap.org/ws/2006/08/resourceTransfer/Dialect/QName and the expression must evaluate to zero or more entire elements, each including the element name, any attributes, and its entire content. The QName dialect does not support computed values.
|
XPath
XPath is a sublanguage in an XSL style sheet that is used to identify XML elements for processing. It is also used to calculate numbers and manipulate strings. XPath and XSLT expressions are intertwined. For example, although XPath can reference a variable, the variable must be created and given a value in XSLT. XPath syntax is somewhat like the directory addressing in UNIX, which uses a slash for the root directory as well as the separator between hierarchies.
|
|
The XPath Level 1 dialect uses an XPath to reference specific fragments of the resource; it is logically applied to the XML representation of the resource and the resulting node set is the resource fragment that is the subject of the message containing the expression. This dialect is useful for resources with limited XPath processing capability that do not need to support returning values computed from their resource representation. The context of an XPath Level 1 expression follows this path (no pun intended):
- Context node is the root element of the XML representation of the resource.
- Context position is 1.
- Context size is 1.
- There is no variable binding.
- Node tests are NameTest and the text NodeType.
- There are no function libraries.
- Any namespace declarations in-scope where the XPath expression appears.
The XPath Level 1 dialect can define references to any element, attribute, or value in the resource representation; it must be indicated by using the URI: http://schemas.xmlsoap.org/ws/2006/08/resourceTransfer/Dialect/XPath-Level-1 and expressions in this dialect must not evaluate to more than a single node. The dialect does not support computed values, and text and attribute nodes must be serialized using the same serialization as for the XPath 1.0 dialect.
The XPath 1.0 dialect differs from XPath Level 1 in that it supports a wider set of XPath function libraries. This dialect works well for any resource with full XPath processing capability or any resource that needs to support returning values computed from its resource representation. The context for an XPath 1.0 expression is as follows:
- Context node is the root element of the XML representation of the resource.
- Context position is 1.
- Context size is 1.
- There is no variable binding.
- There are core function libraries.
- Any namespace declarations in-scope where the XPath expression appears.
The XPath 1.0 dialect can define references to any element, attribute, or value in the resource representation and can also be used to compute values from the resource representation. It must be indicated by using the URI: http://www.w3.org/TR/1999/REC-xpath-19991116 and implementations that support the full XPath 1.0 dialect must also support the XPath Level 1 dialect.
The expression may evaluate to one of four possible types: a node set, a Boolean, a number, or a string (with the last three types being the results of evaluating a computed expression). They are serialized by performing the following conversions and then by wrapping the result in the wsrt:Result element:
- Boolean: convert to an xs:boolean
- string: convert to an xs:string
- number: convert to an xs:double
A node set is zero or more elements, attributes, or text values of elements. A node set is serialized into XML by concatenating each node and enclosing it in the wsrt:Result wrapper XML element for which schema validation is suppressed. Element nodes in a node set are serialized directly into their XML representation -- for attributes and text nodes in the node set, a wrapper element is used to enclose these values to distinguish them from other such nodes in the serialized result.
The nodes in the node set can be serialized in any order and the WS-RT global element definition wsrt:NodeSet can also be used as the wrapper element when serializing these node sets outside of an WS-RT result. Finally, an XPath 1.0 expression may evaluate to multiple nodes -- this is important to note because this means the XPath 1.0 dialect must not be used with a put or create operation.
Applying extensions to operations
In future Meet the specs columns, I'll dig into more detail on applying these extended capabilities to action operations, but for this installment, let's look at these operations quickly.
get
In WS-Transfer, the get operation is used to retrieve an existing resource representation in its entirety. WS-RT extends get to retrieve fragments of an existing representation. A resource that can return its full representation must also support wxf:Get to return the entire resource representation without using WS-RT extensions.
Listing 1 demonstrates the extended outline for get in WS-RT:
Listing 1. Extended outline for get
[Headers]
<wsrt:ResourceTransfer s:mustUnderstand="true"? />
[Action]
http://schemas.xmlsoap.org/ws/2004/09/transfer/Get
[Body]
<wsrt:Get Dialect="xs:anyURI"?>
<wsrt:Expression ...>xs:any</wsrt:Expression> *
</wsrt:Get>
|
put
The WS-Transfer put operation is used to update an existing resource representation by providing a replacement XML representation. WS-RT extends put to update an existing resource representation by providing fragments of the XML representation. A resource that can update its full representation must also support wxf:Put to update the entire resource representation without using WS-RT extensions.
Listing 2 demonstrates the extended outline for put in WS-RT:
Listing 2. Extended outline for put
[Headers]
<wsrt:ResourceTransfer s:mustUnderstand="true"/>
[Action]
http://schemas.xmlsoap.org/ws/2004/09/transfer/Put
[Body]
<wsrt:Put Dialect="xs:anyURI"?>
<wsrt:Fragment Mode="Modify|Insert|Remove">
<wsrt:Expression>xs:any</wsrt:Expression> ?
<wsrt:Value ...>xs:any</wsrt:Value> ?
</wsrt:Fragment> +
</wsrt:Put>
|
create
In WS-Transfer, the create operation is used for creating a resource using an initial representation. The resource factory that receives a create request allocates a new resource that is initialized from the presented representation. The new resource will be assigned a factory-service-determined endpoint reference that is returned in the response message. Often the information required to create a resource may differ quite a bit from the initial representation; sometimes supplying the initial representation is not a viable option.
WS-RT extends create to generate a resource from zero or more specified fragments of the XML representation; it further extends create so that any resource metadata may be created as part of the creation of the resource.
Listing 3 demonstrates the extended outline for create in WS-RT:
Listing 3. Extended outline for create
[Headers]
<wsrt:ResourceTransfer s:mustUnderstand="true"/>
[Action]
http://schemas.xmlsoap.org/ws/2004/09/transfer/Create
[Body]
<wsrt:Create Dialect="xs:anyURI"?>
<wsmex:Metadata>resource metadata</wsmex:Metadata> ?
<wsrt:Fragment>
<wsrt:Expression>xs:any</wsrt:Expression> ?
<wsrt:Value ...>xs:any</wsrt:Value>
</wsrt:Fragment> *
</wsrt:Create>
|
But wait! There's more!
In upcoming Meet the specs columns on WS-RT 1.0, you'll get closer look at operations and learn about WS-RT 1.0 and:
- Terminology and notation
- Faults (targeted at a destination endpoint according to the fault-handling rules defined in WS-Addressing)
- Security (how this WS works with WS-Security)
Resources Learn
Get products and technologies
-
Grab your own PDF or ZIP version of the WS-RT 1.0 specification draft.
-
IBM trial software: Build your next development project with trial software, available for download directly from developerWorks.
Discuss
About the author | 
| | Kane Scarlett is the editor of the Autonomic computing technology zone for developerWorks. His past publishing work was with such magazines as Unix Review, Advanced Systems, and the -World publications (Java-, Sun-, NC-, Linux-), as well as some little oddball journals like National Geographic Magazine. |
Rate this page
| 
