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 (Page 1 of 7 )
Implied Resource Pattern
How is WS-Addressing used to define the relationship between Web services and stateful resources? This is the core of the WS-Resource Framework. The WS-Resource Framework defines the concept of an implied resource pattern. The implied resource pattern is a convention on XML, WSDL, and WS-Addressing that defines how a particular WS-Resource is referred to as a context for processing a Web service message. We use the term implied because the identity of the resource isn't part of the request message, but rather is specified using the reference properties feature of WS-Addressing. The identity of the resource is implied by the context of the message and its association with an endpoint reference, not directly in the signature of the message.
As an example, a purchase order Web service could be created to identify a purchase order by passing the purchase order number as a parameter of each request message. Alternatively, the purchase order number could be used as a reference property of an endpoint reference the Web service creates to point to an individual purchase order WS-Resource. An endpoint reference that identifies not only the Web service target of the request message but also the identity of a stateful resource as context for processing the message is referred to as a WS-Resource qualified endpoint reference.
The key to the entire WS-Resource Framework is the use of the WS-Addressing to identify the stateful resource to be used to process the Web service message. The endpoint reference provides means to point to both the Web service and the stateful resource in one convenient XML element. You can think of a WS-Resource qualified endpoint reference as a pointer to a specific WS-Resource.
There are two approaches to identifying the WS-Resource in an endpoint reference: URI encoding and reference properties. The first approach involves appending some identifying within the address component of the endpoint reference. This approach works well in certain circumstances: for example, when a URI scheme is used and the WS-Resource can be identified by a simple type.
Another approach exploits the reference properties feature of WS-Addressing we described in the previous section. An endpoint reference may include a reference properties element; if it's included, then the contents of that element must appear in a binding-specific manner on any Web services request sent to the Web service referred to by that endpoint reference (for example, in a SOAP binding, the reference property element must appear as a SOAP header). An endpoint reference can be formed that refers to a Web service and specifically identifies that a particular stateful resource (for example, a customer's specific purchase order) must be used as context to processing Web services messages. The types of messages that can be sent to that WS-Resource are defined by the portType of the Web service identified by the Address element of the endpoint reference.
Consider the following example. SkatesTown wishes to model its purchase orders as WS-Resources that maintain the state associated with the processing of a purchase order request sent to SkatesTown. This design approach is somewhat analogous to modeling a purchase order as an Entity EJB. SkatesTown uses the implied resource pattern because the purchase order is a stateful entity; SkatesTown wishes to allow customers to access their purchase orders using Web services technologies; and SkatesTown wishes to use standard, interoperable means of exposing a purchase order as a stateful resource using Web services.
In order to use the implied resource pattern, the POSubmission service needs some changes. First, let's examine the doSubmission operation. From Chapter 4, the doSubmission operation and related messages appear as follows:
With the implied resource pattern, the purchase order can be treated as a WS-Resource. The doSubmission operation then becomes a factory operation to create new purchase order WS-Resources. The response should no longer be an invoice, as you saw in Chapter 4, but rather an endpoint reference pointing to a PurchaseOrder WS-Resource created as a result of the doSubmission request from the customer. This allows us to implement this Web service using the implied resource pattern by changing just the response message:
We'll examine the portType responsible for PurchaseOrder WS-Resources in more detail throughout this chapter. The name of this portType is the POPortType. For now, consider that this POPortType provides operations to allow a customer to query the contents of a purchase order they submitted, make certain modifications on the PurchaseOrder WS-Resource, query status on the processing of the PurchaseOrder, cancel a PurchaseOrder, receive notification when a PurchaseOrder is fully processed, and so on.
Now, the response to a doSubmission operation contains a WS-Resource qualified endpoint reference to a PurchaseOrder WS-Resource:
Let's take a closer look at this response message. The content of the response message is a WS-Resource qualified endpoint reference identifying a PurchaseOrder WS-Resource. The interface of the Web service is described by the POPortType (we'll examine this interface in more detail later). Figure 8.1 outlines the components of the endpoint reference referring to a PurchaseOrder created as a result of processing a doSubmission operation.
Figure 8.1 An endpoint reference to a PurchaseOrderWS-Resource
There are three important components of the endpoint reference to the PurchaseOrder WS-Resource:
The required Address element identifies a URL to a Web service that can perform operations on the PurchaseOrder WS-Resource.
The reference properties element contains the identifier of the PurchaseOrder stateful resource created by the processing of the doSubmission operation. This identifier is meaningful only to the Web service identified by the Address element. The only thing the customer's application should do with this element is include it in any message it sends to the Web service identified by the Address element, following the binding-specific rules defined by WS-Addressing that we discussed previously. The customer's application shouldn't use this identifier for any other reason; it should be treated as an opaque piece of information.
The PortType element indicates that the interface to the Web service identified by the Address element is the POPortTypeportType defined by SkatesTown.