Meet the specs: WS-RT 1.0 operations, Part One

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 (WS-RT) 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 in order to deliver a set of tools for the Web services environment. As such, this specification relies on other WSs 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

In the first Meet the specs column on WS-RT, I provided a quick look at the four operations. Now let's dig a little deeper into how WS-RT extends the first of these operations -- get. But first, let's do a little glossary review.

Fragments, dialects, QName, and XPath

WS-ResourceTransfer extends these four operations so they can operate on fragments of the resource representations. So what's a fragment? A piece of XML code that is part of the resource. WS-RT imparts the power of fragment access, the ability to access a part of the resource's XML code.

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.)

Dialects include

• QName: 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 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 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® that uses a slash for the root directory as well as the separator between hierarchies.

• XPath Level 1: A dialect that 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, which do not need to support returning values computed from their resource representation. It can define references to any element, attribute, or value in the resource representation; 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.
• XPath 1.0: This 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. It 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. Implementations that support the full XPath 1.0 dialect must also support the XPath Level 1 dialect.

Now let's move on to the get operation.

Extending the get operation

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:

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

There are some constraints on this outline:

• [Header]/wsrt:ResourceTransfer -- If present and understood, a resource must process the [Body] in its entirety and comply with its content. If not present then a resource must treat this request as described in WS-Transfer Get.
• [Body]/wsrt:Get -- An element that controls the retrieval of the resource fragment. This element must be present if the wsrt:ResourceTransfer header is present.
• [Body]/wsrt:Get/@Dialect -- This URI indicates which dialect expression will be used to identify and retrieve the fragments. This attribute must be present when the message contains a wsrt:Expression element. A resource must generate an UnsupportedDialectFault if it does not support the specified dialect.
• [Body]/wsrt:Get/wsrt:Expression -- When present, this optional element identifies a fragment in the resource to be sent in the response. Absence of this element is equivalent to an expression that identifies the entire resource representation. The value of this element must conform to the dialect specified in the [Body]/wsrt:Get/@Dialect attribute. A resource must generate an InvalidExpressionFault if the expression is invalid. If the expression syntax is not valid with respect to the dialect a resource ought to specify a fault detail of InvalidExpressionSyntax. If the expression value isn't valid for the resource type, the resource should specify a fault detail of InvalidExpressionValue.

If a resource can't return a value for a requested fragment, it must generate a GetFault. If the request contains more expression elements than the resource can support, the resource has to return a fault, which should be wsrt:MultipartLimitExceededFault.

When your resource accepts a wsrt:Get request and processes it successfully, it will reply with a response like shown in Listing 2:

[Headers]
<wsrt:ResourceTransfer/>
[Action] 
http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse 
[Body] 
<wsrt:GetResponse> 
  <wsrt:Result...>xs:any</wsrt:Result> + 
</wsrt:GetResponse> 

This response is constrained by these elements:

• [Headers]/wsrt:ResourceTransfer -- This header indicates that the response contains body content defined in WS-ResourceTransfer.
• [Body]/wsrt:GetResponse -- An element that wraps the packaging of the fragments in the response and which must be present if the request body contained a wsrt:Get element.
• [Body]/wsrt:GetResponse/wsrt:Result -- This element encompasses a single fragment response corresponding to a wsrt:Expression in the original request and must contain the fragment of the resource representation identified by the wsrt:Expression; if it doesn't, this element needs to contain the whole resource representation. Also:
  • For each wsrt:Expression element in the request there has to be one wsrt:Result element in the response even if the wsrt:Result is empty of content.
  • The wsrt:Result elements must appear in the same order in the response as the corresponding wsrt:Expression elements in the request.
  • A wsrt:Result needs to have empty content in the case when a wsrt:Expression resolves to nothing.

Examples for XPath Level 1

Listing 3 and Listing 4 are examples of a Get and a GetResponse message (respectively) using the XPath Level 1 dialect.

<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsa="http://www.w3.org/2005/08/addressing" 
    xmlns:wsrt= 
       "http://schemas.xmlsoap.org/ws/2006/08/resourceTransfer"> 
 <s:Header> 
    <wsa:To>http://www.example.org/disk</wsa:To> 
    <wsa:Action s:mustUnderstand="true"> 
      http://schemas.xmlsoap.org/ws/2004/09/transfer/Get 
    </wsa:Action> 
    <wsrt:ResourceTransfer s:mustUnderstand="true"/> 
    ... 
 </s:Header> 
  <s:Body> 
     <wsrt:Get 
       Dialect="http://schemas.xmlsoap.org/ws/2006/08/ 
                  resourceTransfer/Dialect/XPath-Level-1" 
             xmlns:d="http://example.org/sample"> 
        <wsrt:Expression> 
            d:Volume[1]/d:Label 
        </wsrt:Expression> 
        <wsrt:Expression> 
            d:DiskCapacity 
        </wsrt:Expression> 
        <wsrt:Expression> 
            d:SerialNumber/text() 
        </wsrt:Expression> 
     </wsrt:Get> 
  </s:Body> 
 </s:Envelope>

 <s:Envelope 
     xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
     xmlns:wsa="http://www.w3.org/2005/08/addressing" 
     xmlns:wsrt= 
        "http://schemas.xmlsoap.org/ws/2006/08/resourceTransfer"> 
  <s:Header> 
     <wsa:To> 
   http://www.w3.org/2005/08/addressing/anonymous 
     </wsa:To> 
     <wsa:Action s:mustUnderstand="true"> 
  http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse 
     </wsa:Action> 
     <wsrt:ResourceTransfer/> 
     ... 
  </s:Header> 
  <s:Body> 
   <wsrt:GetResponse xmlns:d="http://example.org/sample"> 
     <wsrt:Result> 
       <d:Label>MyDrive-C</d:Label> 
     </wsrt:Result> 
     <wsrt:Result> 
       <d:DiskCapacity>62500000000</d:DiskCapacity> 
     </wsrt:Result> 
     <wsrt:Result> 
       <wsrt:TextNode>123-F2560</wsrt:TextNode> 
     </wsrt:Result> 
   </wsrt:GetResponse> 
  </s:Body> 
 </s:Envelope>

Examples for QName

Listing 5 demonstrates a sample Get message using the QName dialect.

<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsa="http://www.w3.org/2005/08/addressing" 
    xmlns:wsrt= 
       "http://schemas.xmlsoap.org/ws/2006/08/resourceTransfer"> 
 <s:Header> 
    <wsa:To>http://www.example.org/disk</wsa:To> 
    <wsa:Action s:mustUnderstand="true"> 
      http://schemas.xmlsoap.org/ws/2004/09/transfer/Get 
    </wsa:Action> 
    <wsrt:ResourceTransfer s:mustUnderstand="true"/> 
    ... 
 </s:Header> 
 <s:Body> 
    <wsrt:Get Dialect="http://schemas.xmlsoap.org/ws/2006/08/ 
                       resourceTransfer/Dialect/QName" 
      xmlns:d="http://example.org/sample"> 
       <wsrt:Expression> 
           d:Volume 
       </wsrt:Expression> 
       <wsrt:Expression> 
           d:DiskCapacity 
       </wsrt:Expression> 
    </wsrt:Get> 
 </s:Body> 
</s:Envelope> 

The fragments of the resource representation are identified by the wsrt:Expression contents in these lines:

           d:Volume 
       </wsrt:Expression> 

Notice that the d:Volume QName in the example resolves to three elements in the resource representation. Listing 6 shows the response to this message.

<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsa="http://www.w3.org/2005/08/addressing" 
    xmlns:wsrt= 
       "http://schemas.xmlsoap.org/ws/2006/08/resourceTransfer"> 
 <s:Header> 
    <wsa:To> 
  http://www.w3.org/2005/08/addressing/anonymous 
    </wsa:To> 
    <wsa:Action s:mustUnderstand="true"> 
  http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse 
    </wsa:Action> 
    <wsrt:ResourceTransfer/> 
    ... 
 </s:Header> 
 <s:Body> 
  <wsrt:GetResponse xmlns:d="http://example.org/sample"> 
     <wsrt:Result> 
       <d:Volume> 
          <d:Drive>C:</d:Drive> 
          <d:Label>MyDrive-C</d:Label> 
          <d:TotalCapacity>10000000000</d:TotalCapacity> 
          <d:FreeSpace>6234794528</d:FreeSpace> 
       </d:Volume> 
       <d:Volume> 
          <d:Drive>D:</d:Drive> 
          <d:Label>MyDrive-D</d:Label> 
          <d:TotalCapacity>30000000000</d:TotalCapacity> 
          <d:FreeSpace>26462809800</d:FreeSpace> 
       </d:Volume> 
       <d:Volume> 
          <d:Drive>E:</d:Drive> 
          <d:Label>MyDrive-E</d:Label> 
          <d:TotalCapacity>22500000000</d:TotalCapacity> 
          <d:FreeSpace>16056784170</d:FreeSpace> 
       </d:Volume> 
     </wsrt:Result> 
     <wsrt:Result> 
       <d:DiskCapacity>62500000000</d:DiskCapacity> 
     </wsrt:Result> 
  </wsrt:GetResponse> 
 </s:Body> 
</s:Envelope> 

The value of each of the wsrt:Expression fragments in the request message is returned in a unique wsrt:Result wrapper in the response message. The order of the elements in the response matches the order of the corresponding wsrt:Expression elements in the request. The result of getting the <d:Volume> fragment is illustrated in Listing 7:

  <wsrt:GetResponse xmlns:d="http://example.org/sample"> 
     <wsrt:Result> 
       <d:Volume> 
          <d:Drive>C:</d:Drive> 
          <d:Label>MyDrive-C</d:Label> 
          <d:TotalCapacity>10000000000</d:TotalCapacity> 
          <d:FreeSpace>6234794528</d:FreeSpace> 
       </d:Volume> 
       <d:Volume> 
          <d:Drive>D:</d:Drive> 
          <d:Label>MyDrive-D</d:Label> 
          <d:TotalCapacity>30000000000</d:TotalCapacity> 
          <d:FreeSpace>26462809800</d:FreeSpace> 
       </d:Volume> 
       <d:Volume> 
          <d:Drive>E:</d:Drive> 
          <d:Label>MyDrive-E</d:Label> 
          <d:TotalCapacity>22500000000</d:TotalCapacity> 
          <d:FreeSpace>16056784170</d:FreeSpace> 
       </d:Volume> 
     </wsrt:Result> 

Examples for XPath 1.0

So what does the Get operation look like using the full XPath 1.0 dialect? Listing 8 demonstrates the use of a query expression to return the result of the quantity of the <d:Volume> elements with a capacity of greater than 20000000000 (only the message body is displayed here).

<s:Body> 
  <wsrt:Get Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116" 
   xmlns:d="http://example.org/sample"> 
      <wsrt:Expression> 
             count( d:Volume[d:TotalCapacity > 20000000000] ) 
      </wsrt:Expression> 
  </wsrt:Get> 
</s:Body> 

When the expression on this line (count( d:Volume[d:TotalCapacity > 20000000000] )) is applied to the resource representation (a physical disk which has a number of logical volumes) shown in Listing 9:

 <Disk xmlns="http://example.org/sample"> 
    <DiskCapacity>62500000000</DiskCapacity> 
    <DiskFreeSpace>524182841</DiskFreeSpace> 
    <SerialNumber>123-F2560</SerialNumber> 
    <LastAuditDate>1998-05-25T13:30:15</LastAuditDate> 
    <Volume> 
       <Drive>C:</Drive> 
       <Label>MyDrive-C</Label> 
       <TotalCapacity>10000000000</TotalCapacity> 
       <FreeSpace>6234794528</FreeSpace> 
    </Volume> 
    <Volume> 
       <Drive>D:</Drive> 
       <Label>MyDrive-D</Label> 
       <TotalCapacity>30000000000</TotalCapacity> 
       <FreeSpace>26462809800</FreeSpace> 
    </Volume> 
    <Volume> 
       <Drive>E:</Drive> 
       <Label>MyDrive-E</Label> 
       <TotalCapacity>22500000000</TotalCapacity> 
       <FreeSpace>16056784170</FreeSpace> 
    </Volume> 
 </Disk> 

it evaluates to a result of "2." Listing 10 shows the corresponding GetResponse message.

<s:Body> 
   <wsrt:GetResponse> 
     <wsrt:Result>2</wsrt:Result> 
   </wsrt:GetResponse> 
</s:Body> 

The result of the query expression is a number that is converted to an xs:double and returned as the value of the wsrt:Result element in this line: <wsrt:Result>2</wsrt:Result>.

But wait! There's more!

In upcoming Meet the specs columns on WS-RT 1.0, I'll take a closer look at how the WS-ResourceTransfer 1.0 specification extends the put operation, then I'll detail:

• The create and delete operations
• The fault-handling rules of WS-Addressing
• Terminology and notation
• Security (how this WS works with WS-Security)

Resources

Learn

• Get information on the technologies discussed in this article: A working definition of QName and the XML Path Language (XPath) 1.0.
  
  
• WSDM/WS-Man Reconciliation: An Overview and Migration Guide: This whitepaper covers much of the current thinking on the immediate direction of the Web services management strategies.
  
  
• Autonomic computing standards page: Get more information on the WS family of specifications.
  
  
• Autonomic computing zone: Visit the developerWorks Autonomic computing zone to stay on the cutting edge of autonomic computing features and technologies.
  
  
• You might visit other developerWorks zones mentioned in this article: The SOA and Web services zone for the resources you need to understand and get started with SOA; the XML zone on how to manage, work with, and think in XML; the Open source zone to find resources for open source development and implementation.
  
  
• developerWorks technical events and webcasts: Stay current with the latest technology.
  
  

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

• Participate in the discussion forum.
  
  
• developerWorks blogs: Get involved in the developerWorks community.
  
  

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.

Comments

Back to top

Trademarks

Table of contents

• Fragments, dialects, QName, and XPath
• Extending the get operation
• But wait! There's more!
• Resources
• About the author
• Comments