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

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

06 Mar 2007

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

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 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. The second article looked at the nuts-and-bolts level to see how WS-RT extends the get operation; in the third article, you examined how the create operation is extended with this spec. Now for a change of pace (before you discover how WS-RT extends the put), take a look at how the specification handles faults. But first, a refresher on fragments and dialects.

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, which uses a slash for the root directory as well as the separator between hierarchies.

Specification contributors HP, IBM®, Intel, and Microsoft® collaborated to publish the 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 that 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 faults.

Defining faults

In WS-Transfer, the definitions of faults use the following properties:

• [Code], the fault code.
• [Subcode], the fault subcode.
• [Reason], the English language reason element.
• [Detail], the detail element. If absent, no detail element is defined for the fault.

For SOAP 1.2, the [Code] property has to be either Sender or Receiver. These properties are serialized into text XML like this:

The faults defined in this article are targeted at a destination endpoint according to the fault handling rules defined in WS-Addressing. WS-ResourceTransfer faults must include as the [Action] property the following fault action URI: http://schemas.xmlsoap.org/ws/2006/08/resourceTransfer/fault.

The properties -- [Code], [Subcode], [Reason], and [Detail] -- bind to a SOAP 1.2 fault as shown in Listing 1:

<s12:Envelope> 
 <s12:Header> 
   <wsa:Action> 
      http://schemas.xmlsoap.org/ws/2006/08/resourceTransfer/fault 
   </wsa:Action> 
   <!-- Headers elided for clarity. --> 
 </s12:Header> 
 <s12:Body> 
  <s12:Fault> 
   <s12:Code> 
     <s12:Value>[Code]</s12:Value> 
     <s12:Subcode> 
      <s12:Value>[Subcode]</s12:Value> 
     </s12:Subcode> 
   </s12:Code> 
   <s12:Reason> 
    <s12:Text xml:lang="en">[Reason]</s12:Text> 
   </s12:Reason> 
   <s12:Detail> 
     [Detail] 
        ... 
   </s12:Detail> 
  </s12:Fault> 
 </s12:Body> 
</s12:Envelope>

They bind to a SOAP 1.1 fault like shown in Listing 2:

<s11:Envelope> 
 <s11:Body> 
  <s11:Fault> 
   <faultcode>[Subcode]</faultcode> 
   <faultstring xml:lang="en">[Reason]</faultstring> 
   <detail> 
     [Detail] 
        ... 
   </detail> 
  </s11:Fault> 
 </s11:Body> 
</s11:Envelope>

Now let's look at a list of faults and their definitions.

List of faults

Let's take a look at these 14 faults (and what defines them):

• wsa:DestinationUnreachable
• wsa:EndpointUnavailable
• ConcurrencyFault
• UnsupportedDialectFault
• InvalidExpressionFault
• GetFault
• ResourceValidityFault
• FragmentAlreadyExistsFault
• PutFault
• PutModeUnsupportedFault
• CreateFault
• InvalidMetadataFault
• MultipartLimitExceededFault
• InvalidPutSyntaxFault

wsa:DestinationUnreachable

This fault is sent in response to a message that is targeted at a resource that can't be found and is deemed not to exist, possibly because the resource was never created or because the resource has been destroyed. There is no distinction between these two cases. The SOAP bindings for this fault are defined in WS-Addressing.

wsa:EndpointUnavailable

The resource is unable to process the message at this time due to some transient issue (the endpoint may optionally include a wsa:RetryAfter parameter in the detail). The source shouldn't retransmit the message until this duration has passed. The SOAP bindings for this fault are also defined in WS-Addressing.

ConcurrencyFault

This fault is generated by a resource to indicate that it was unable to process a message due to concurrent access. A requester might choose to handle this condition by retrying the operation that caused it.

UnsupportedDialectFault

This fault is generated by a resource to indicate that the expression dialect used to ID a resource fragment isn't supported by the resource for the current operation. The fault detail should contain the Dialect values that the resource supports for the operation.

InvalidExpressionFault

This fault is sent by a resource if a <wsrt:Expression> element has a syntax that is invalid according to the definition of the expression dialect. If the expression syntax is not valid with respect to the dialect, then a resource should specify a fault detail of InvalidExpressionSyntax, indicating which expression this detail applies to.

If the expression is not valid for the resource type, then the resource should specify a fault detail of InvalidExpressionValue, indicating which expression this detail applies to.

<wsrt:InvalidExpressionSyntax>
  <wsrt:Expression>xs:any</wsrt:Expression> +
</wsrt:InvalidExpressionSyntax>
|
<wsrt:InvalidExpressionValue>
  <wsrt:Expression>xs:any</wsrt:Expression> +
</wsrt:InvalidExpressionValue>

GetFault

When a resource is unable to process a valid Get message, this fault is generated.

ResourceValidityFault

If the result of a resource processing a Put message would cause the resource representation to become invalid, this fault is created. The fault detail can include the wsrt:Fragment element in the Put message that caused this fault to be generated.

FragmentAlreadyExistsFault

This fault is generated by a resource if a Put message specifies the Insert mode and identifies a non-repeated fragment element (maxOccurrs = 1) that already exists. The fault detail may include the wsrt:Fragment that failed to be processed.

PutFault

This fault is generated by a resource if it is unable to process a valid Put message. The fault detail may include the wsrt:Fragment that failed to be processed. The fault detail should include a wsrt:SideAffects element in the fault detail to indicate whether any changes occurred. A value of true indicates some changes occurred; false means no changes occurred. Absence of the element indicates that changes may have occurred.

<wsrt:Fragment>fragment</wsrt:Fragment> ?
<wsrt:SideEffects>xs:boolean</wsrt:SideEffects> ?

PutModeUnsupportedFault

If a Put message specifies a mode that is not supported by the resource, this fault is generated by the resource.

CreateFault

If a resource is unable to process a valid Create message, this fault is generated. It may include the wsrt:Fragment that failed to be processed.

InvalidMetadataFault

This fault is generated by a resource factory if a Create message contains a wsmex:Dialect that is not supported or if the resource metadata contains values that are not supported for the resource.

MultipartLimitExceededFault

This fault is generated by a resource if a request message exceeds the limit of wsrt:Expression or wsrt:Fragment elements supported for the dialect. The fault detail must contain the maximum number of wsrt:Expression or wsrt:Fragment elements supported for the dialect.

InvalidPutSyntaxFault

This fault is generated by a resource if a Put request specifying a mode Remove contains a wsrt:Value element or if a Put request specifying a mode Insert or Modify does not contain a wsrt:Value element.

But wait! There's more!

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

• The create and delete operations
• Terminology and notation
• Security (how this WS works with WS-Security)

Resources

• The other articles in this series includes the intro to WS-RT 1.0 (developerWorks, September 2006), extending the Get operation (developerWorks, November 2006), and extending the Create operation (developerWorks, February 2007).
  
  
• 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.

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

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

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Back to top