Introducing the Implied Resource Pattern - Combining the SetResourceProperties Components

The operations we've discussed can be used separately, with individual request/response message exchanges; or they can be combined, for efficiency reasons, into a single request/response. Let's apply the following SetResourceProperties request to the original resource properties document (shown in Listing 8.1):

<soap:Envelope>
...
 <poRP:POResourceID>43871</poRP:POResourceID>

</soap:Header>
<soap:Body>
<wsrp:SetResourceProperties 
<wsrp:Update>
<poRP:status>posted</poRP:status>
</wsrp:Update>
<wsrp:Delete

ResourceProperty="poRP:contactPerson">
</wsrp:Delete>
<wsrp:Insert>
<poRP:contactPerson>Laura

Tang</poRP:contactPerson>
</wsrp:Insert>
<wsrp:Update>
<poRP:statusDate>2004-1-05T1:35:27</poRP:

statusDate>
</wsrp:Update>
</wsrp:SetResourceProperties>
</soap:Body>
</soap:Envelope>

Note the order of operations:

1. The value of the status resource property is updated.

2. The values of the poRP:contactPerson resource property are deleted.

3. A new value for contactPerson is inserted.

4. The value of the statusDate is updated.

It's important to understand that the components of the SetResourceProperties request are processed in the order they appear in the message. Furthermore, the results of processing a component are visible to the processing of subsequent components.

The resulting resource properties document looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<poRP:poResourceProperties

xmlns:po="http://www.skatestown.com/ns/po" 
...
<po:po id="43871" submitted="2004-01-05"

customerId="73852">
...
</po:po>
...
<poRP:dateReceived>2003-12-31T12:00:00</poRP:

dateReceived>
<poRP:status>posted</poRP:status>
<poRP:statusDate>2004-1-05T1:35:27</poRP:

statusDate>
<poRP:contactPerson>Laura

Tang</poRP:contactPerson>
</poRP:poResourceProperties>

Rounding Out SetResourceProperties

We need to add a few more comments about the SetResourceProperties operation. Errors are handled in a normal Web services way. Faults are listed on the SetResourceProperties operation definition in the WSDL. Errors flow back to the requestor's application instead of a normal SetResourcePropertiesResponse message. The sorts of errors that can occur include:

• "The resource identified by the request was unknown to the Web service" (you see this sort of error message with most of the WS-Resource Framework operations).

• "The request was rejected because it would render the resource properties document no longer able to validate."

• "The resource property could not be modified because it's read-only."

• "The resource property identified was unknown to the resource."

• "The request failed for some reason."

So, much of the error-checking is done to make sure the resource properties document remains validatable with respect to its schema. Of course, other errors, which are application specific, can be detected. Many aspects of a resource property element, such as whether it's read-only, or whether there is some sort of complicated, algorithmic constraint on its value, can't be expressed in XML Schema.

The actual failure recovery is implementation dependent. Some implementations may restore the resource property values to where they were prior to the attempt to process the failed component; some may restore the entire resource property document to the state prior to processing any component in the entire SetResourceProperties request. Outside of an application-specific WS-Policy assertion, there is no way for the requestor to determine the expected failure semantic. However, if the SetResourceProperties request is executed under a transaction semantic (such as we'll discuss in Chapter 11, "Web Services Transactions"), the failure semantics of the entire SetResourceProperties request will be clear to the requestor.

You may have noticed the granularity of all the WS-ResourceProperties operations: Things work only at the resource property level. If an application needs finer-grained update capability, it needs to use other means. For example, if The Skateboard Warehouse wants to make a change to the shipTo part of the po:PO resource property of its PurchaseOrder WS-Resource, it could do an update, replacing the entire value of the po:PO with a new one that differs only in the shipTo element. More sophisticated mechanisms, such as an update language associated with XQuery, aren't currently well specified. At this point, XQuery is still read-only.

Of course, security is an important consideration with WS-ResourceProperties. However, WS-ResourceProperties, like most WS-* specifications, doesn't define a separate, domain-specific security mechanism. Rather, WS-ResourceProperties exploits the feature of Web services known as composability—that is, WS-* specifications are designed to be composed together to create an overall solution. WS-ResourceProperties, like the rest of the WS-Resource Framework, relies on WS-Security (see Chapter 9, "Securing Web Services") for its security needs.

Rounding Out the POPortType

The POPortType includes one additional operation that we haven't discussed to this point. The getInvoice operation provides a simple mechanism for the requestor to retrieve an invoice (if it exists) that corresponds to the PurchaseOrder WS-Resource. This is an example of an application-specific operation that is composed with the operations from other WS-Resource Framework specifications. It also illustrates the notion that not all pieces of information associated with a WS-Resource are modeled as resource properties. It would have been perfectly valid for the designer of the POPortType to make invoice a resource property. There could have been application-specific or implementation issues that drove the designer to make retrieval of an invoice an operation as opposed to modeling an invoice as a resource property.

Deciding what is a resource property boils down to application design. If in doubt about whether to make something a resource property, consider the following reasoning by analogy. If you were designing a Java class to model the resource, would you choose an instance variable (public or private) to model the property? Or would it be better to build an application-specific method to access the property? Of course, sometimes you do neither; some aspects of a business object aren't modeled by software.

Please check back next week for the continuation of this article.

Comments On: Introducing the Implied Resource Pattern

· This article is an excerpt from the book "Building Web Services with Java: Making...   >>> Post your comment now!

Buy this book...

This article is excerpted from chapter 8 of the book Building Web Services with Java: Making sense of XML, SOAP, WSDL, and UDDI, written by Steve Graham et al. (Sams; ISBN: 0672326418). Check it out today at your favorite bookstore. Buy this book now.