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 - Modeling Resource Properties (Page 2 of 7 )
As part of the WS-Resource Framework's model of stateful resources, the WS-Resource Properties specification outlines how elements of a WS-Resource's state are modeled in XML and accessed through Web services.
What Is a Resource Property?
The idea is that a WS-Resource represents state in a Web services context. This state has components, called resource property elements, which represent atomic elements of state that can be read and written. A set of resource property elements are gathered together into a resource property document: an XML document that can be queried by client applications using XPath or other query languages. Note that in many cases, a designer chooses to expose only a portion of the resource's state as resource properties.
The metaphor presented to the client application is that the WS-Resource's state is accessed by manipulating an XML document through some operations standardized by WS-ResourceProperties and provided by a Web service. Of course, the actual implementation doesn't have to store the values of the WS-Resource's state as XML. It's valid for a Web service implementation that is compatible with WS-ResourceProperties to use EJBs, simple Java classes, JDBC to a row in a database table, JNI to a physical resource, and so on. SkatesTown, for example, may choose to implement the PurchaseOrder WS-Resource as an Entity EJB. Regardless of the physical representation of the WS-Resource's state, the work to be done is to transform that state into an XML representation so that it can participate in the WS-ResourceProperties façade expected by client applications.
Resource Property Documents
Since WS-Resources are accessed through Web services, it makes sense to describe the resource property document and the operations that read and write resource properties through a WSDL portType. WS-ResourceProperties defines an XML attribute named ResourceProperties, which designers include on their WSDL 1.1 portTypes to declare the XML definition of a WS-Resource's state and that the design is following the WS-ResourceProperties standard. Using this approach, SkatesTown declares that the format of the PurchaseOrder resource properties document is an XML element of type poResourceProperties. The following snippet shows the updated WSDL portType for the POPortTypeportType, adding the ResourceProperties attribute:
xmlns:wsrp= URI of the WS-ResourceProperties
<!-- Port type definitions -->
The inclusion of the ResourceProperties attribute on the portType indicates a couple of important things about the POPortType. First, this attribute indicates that any Web service that implements the POPortType will support any WS-Resource whose state is modeled by the XML schema element named poResourceProperties. Second, the portType will include one or more operations as defined in the WS-ResourceProperties specification (we'll examine these operations in more detail later in the chapter). Because SkatesTown is using WSDL 1.1, and WSDL 1.1 doesn't have a mechanism to build portTypes by extending other portTypes, operations from WS-ResourceProperties are included in the POPortType by copying the operation elements from the WS-ResourceProperties WSDL.
A closer examination of the poResourceProperties shows the following definition:
The actual definition of the poResourceProperties element appears at the bottom of the listing. The resource properties document was designed to contain the following five important resource properties associated with a purchase order WS-Resource:
po:po—The original PO element submitted by the customer that initiated the creation of the purchase order resource property.
poRP:dateReceived—The date and time when the original PO was submitted by the customer.
poRP:status—The current processing status of the purchase order, which has one of the following values: received, posted, pending, invoiced, or completed.
poRP:statusDate—The date and time when the purchase order resource was placed into the status indicated by the poRP:status resource property element.
poRP:contactPerson—The name of the current person in SkatesTown to be contacted for further information about the purchase order resource. There can be multiple contact person elements associated with a resource.
The complete definition of the resource properties document has a few more elements, but we'll introduce these later in this chapter.
The construction of the resource property document schema definition is important. The child elements of the document must be declared using the xsd:ref attribute as shown. This allows each resource property element to be referred to by QName. You'll see how we use this facility in the next section.
Finally, Listing 8.1 shows an example resource property document.
This resource property document represents the resource properties (and their values) of a WS-Resource created when a customer (The Skateboard Warehouse) invoked the doSubmission operation on SkatesTown's POSubmission service.
The notion of a WS-Resource factory is defined within the WS-Resource Framework. This factory pattern is well understood in computer science: the notion of an entity that is capable of creating new instances of some component. This pattern is called out in the WS-Resource Framework and illustrated by the relationship between the POSubmissionportType and the POPortType. In WS-Resource Framework, a WS-Resource factory is any service that is capable of creating a new WS-Resource, assigning it an identity, and creating a WS-Resource qualified endpoint reference to point to it. In the example illustrated in the previous section, the POSubmission service acts as a factory, creating new PurchaseOrder WS-Resources.