Skip to main content

skip to main content

developerWorks  >  Autonomic computing | SOA and Web services | Open source | XML  >

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

Take a closer look at how the WS-ResourceTransfer 1.0 specification extends the Get operation

developerWorks
Document options

Document options requiring JavaScript are not displayed

Discuss


Rate this page

Help us improve this content


Level: Introductory

Kane Scarlett (kane@us.ibm.com), developerWorks Editor, IBM

29 Nov 2006

Meet the WS-ResourceTransfer 1.0 initial draft specification, 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 article provides a closer look at how the WS-ResourceTransfer 1.0 specification extends the Get operation.

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

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.

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.
  • 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:


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>

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:


Listing 2. Response to wsrt:Get request
[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.


Listing 3. Get message using the XPath Level 1

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


Listing 4. GetResponse message using the XPath Level 1

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


Listing 5. 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.


Listing 6. Sample GetResponse 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.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:


Listing 7. <d:Volume> fragment result
  <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).


Listing 8. Sample Get message using the full XPath 1.0 dialect

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


Listing 9. XML representation of example resource accessed by the protocol operation

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


Listing 10. Sample GetResponse message using the full XPath 1.0 dialect

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


Please take a moment to complete this form to help us better serve you.



YesNoDon't know
 


 


12345
Not
useful		Extremely
useful
 


Back to top