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 POPortType portType, adding the ResourceProperties attribute:
...
xmlns:wsrp= URI of the WS-ResourceProperties
specification namespace
xmlns:poRP="http://www.skatestown.com/ns/poResourceProperties"
...
<!-- Port type definitions -->
<wsdl:portType name="POPortType"
wsrp:ResourceProperties="poRP:poResourceProperties">
<wsdl:operation name="getInvoice">
...
</wsdl:portType>
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:
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.skatestown.com/ns/poResourceProperties"
xmlns:po="http://www.skatestown.com/ns/po"
xmlns:poRP="http://www.skatestown.com/ns/poResourceProperties">
<xsd:import namespace="http://www.skatestown.com/ns/po"
schemaLocation="./po.xsd"/>
<xsd:element name="dateReceived" type="xsd:dateTime" />
<xsd:element name="status" >
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="received" />
<xsd:enumeration value="posted" />
<xsd:enumeration value="pending" />
<xsd:enumeration value="invoiced" />
<xsd:enumeration value="completed" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="statusDate" type="xsd:dateTime" />
<xsd:element name="contactPerson" type="xsd:string" />
<xsd:element name="poResourceProperties">
<xsd:complexType>
<xsd:sequence>
...
<!-- ========= Purchase Order specific Resource
Properties ======== -->
<xsd:element ref="po:po" minOccurs="1" maxOccurs="1"/>
<xsd:element ref="poRP:dateReceived" minOccurs="1" maxOccurs="1"/>
<xsd:element ref="poRP:status" minOccurs="1" maxOccurs="1"/>
<xsd:element ref="poRP:statusDate" minOccurs="1" maxOccurs="1"/>
<xsd:element ref="poRP:contactPerson" minOccurs="0"
maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
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.
Listing 8.1 Example Resource Properties Document
<?xml version="1.0" encoding="UTF-8"?>
<poRP:poResourceProperties
xmlns:po="http://www.skatestown.com/ns/po"
xmlns:poRP="http://www.skatestown.com/ns/
poResourceProperties"
xmlns:xsi="http://www.w3.org/2001/
XMLSchema-instance"
xsi:schemaLocation=
"http://www.skatestown.com/ns/
poResourceProperties POResourceProperties.xsd
http://www.skatestown.com/ns/po ./po.xsd ">
<po:po id="43871" submitted="2004-01-05"
customerId="73852">
...
<billTo>
<company>The Skateboard Warehouse</company>
<street>One Warehouse Park</street>
<street>Building 17</street>
<city>Boston</city>
<state>MA</state>
<postalCode>01775</postalCode>
</billTo>
<shipTo>
<company>The Skateboard Warehouse</company>
<street>One Warehouse Park</street>
<street>Building 17</street>
<city>Boston</city>
<state>MA</state>
<postalCode>01775</postalCode>
</shipTo>
<order>
<item sku="318-BP" quantity="5">
<description>Skateboard backpack;
five pockets</description>
</item>
<item sku="947-TI" quantity="12">
<description>Street-style titanium
skateboard</description>
</item>
<item sku="008-PR" quantity="1000"/>
</order>
</po:po>
...
<poRP:dateReceived>2003-12-31T12:00:00</poRP:
dateReceived>
<poRP:status>received</poRP:status>
<poRP:statusDate>2003-12-31T12:00:00</poRP:
statusDate>
<poRP:contactPerson>Jane Smith</poRP:contactPerson>
<poRP:contactPerson>Alex Jones</poRP:contactPerson>
</poRP:poResourceProperties>
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.
WS-Resource Factory
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 POSubmission portType 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.
Next: Resource Property Operations >>
More Web Services Articles
More By Sams Publishing
|
 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.
|
|
