This article continues our discussion of the WS-Resource Framework, a set of proposed standards that formalizes the relationship between Web services and state. In this part, the second of a multi-part series, we start with the implied resource pattern. It 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).
Introducing the Implied Resource Pattern - SetResourceProperties (Page 6 of 7 )
So far, we've examined the operations defined by WS-ResourceProperties to retrieve or get values of resource properties. WS-ResourceProperties also defines an additional operation, SetResourceProperties, which allows a requestor to insert, update, and delete values of resource properties. The SetResourceProperties message request consists of a collection of components (Insert, Update, or Delete components); so, you can think of this operation as a simple script that can be executed against the WS-Resource, making multiple change operations happen with a single Web service invocation. Many uses of SetResourceProperties involve a single change, like "change the value of ResourceProperty tns:XYZ to 7." Other applications, such as in a systems-management domain, may involve a sophisticated collection of inserts, updates, and deletes in a single SetResourceProperties invocation.
Let's examine each type of set component (Insert, Update, and Delete) individually. Then we'll summarize their use with an example that combines all three components.
SetResourceProperties Insert Component
The Insert component can be used to insert new values for a resource property. For example, if The Skateboard Warehouse wishes to add another contact person to its PurchaseOrder WS-Resource, it sends the following message:
This causes the resource properties document to include a new value for the poRP:contactPerson resource property. The exact resource property that is modified is identified by the tag of the child of the Insert element. In this case, it's poRP:contactPerson, indicating that the poRP:contactPerson resource property is the target of this modification.
After this request is successfully executed, the response message is returned:
The response message isn't terribly interesting. Essentially, it appears to indicate that no error was detected when processing the SetResourcePropertiesRequest. We won't repeat the response message again in the rest of our discussion of SetResourceProperties.
As a result of the successful insertion of the new contact person, the resource properties document now looks like this:
Note that it's up to the implementation to determine where the new contact person is inserted. It could appear at the beginning, in the middle, or at the end of the list of existing contact person elements. The only requirement is that the insertion allow the resource properties document to still be validatable against its schema. So, had the implementation inserted the contact person before the status element, the document would not be valid with respect to its schema, and we would consider the implementation to be not in compliance with WS-ResourceProperties.
It's important to be careful with any of these components. It's easy to issue a SetResourceProperties request that would render the resource properties document unable to validate. You need to pay close attention to the definition of the resource properties elements and make sure that the minOccurs and maxOccurs cardinality properties aren't violated. For example, for the status resource property, the maxOccurs is equal to 1, meaning it can have at most one value. Given that there is already a value for the status resource property in our example's resource properties document, the following insertion request would fail:
It isn't valid for there to be two values of poRP:status in the resource properties document (because maxOccurs is set to 1).
SetResourceProperties Update Component
The Update component is similar to the Insert component, in that new values are added to the resource properties document. However, unlike the Insert component, which only inserts new values in addition to the existing values of a resource property, the update operation replaces all existing values with the contents of the request. So, to change the value of the status resource property to posted, the following update operation is used:
The effect of an update operation is that all the values for the resource property identified by the ResourceProperty attribute of the Update component are deleted, and then the contents of the Update component are inserted in their place. Note that the QName of the child element must match the value of the ResourceProperty attribute (in this case, they're both poRP:status).
SetResourceProperties Delete Component
The last type of component in a SetResourceProperties element is the Delete component. With the Delete component, all the values associated with the resource property identified (by QName) in the Delete component are removed from the resource properties document. Again, you need to be aware of the resource property's minOccurs attribute. If the value of minOccurs isn't 0, the Delete component will fail.
Because most of the resource properties associated with our PurchaseOrder WS-Resource example have minOccurs greater than 0, the only possible legal delete operation involves the contact person resource property. Here's a request that deletes all the values of the contact person resource property: