Example: Creating a Web service that uses the Web Services Addressing API to access a Web Services Resource (WS-Resource) instance

This example extends the example "Creating a Web service that uses the Web Services Addressing API to access a generic Web service resource instance", to use a WS-Resource instance. A WS-Resource, by definition, is a combination of a resource and a Web service through which the resource is accessed.

Creating a resource properties schema document for the WS-Resource

As described in the WS-Resource specification, which is part of the Web Services Resource Framework (WSRF) specification, a WS-Resource is accessed through a WS-Addressing endpoint reference, and a view on the state of its resource is maintained in a resources properties XML document. Use of a WS-Resource, for representing stateful resources, provides an interoperable means to interact with the state representation of resources using standardized web service messages. A WS-Resource must have a resource properties XML document, described by XML schema, which describes a particular view of the state of the WS-Resource. The printer WS-Resource schema document is illustrated in the following example.

<?xml version="1.0"?>
<xsd:schema ...
   xmlns:pr="http://example.org/printer.xsd" 
   targetNamespace="http://example.org/printer.xsd" >
 <xsd:element name="printer_properties">
   <xsd:complexType>
     <xsd:sequence>
        <xsd:element ref="pr:printer_reference" />
        <xsd:element ref="pr:printer_name" />
        <xsd:element ref="pr:printer_state" />
        <xsd:element ref="pr:printer_accepting_jobs" />
        <xsd:element ref="pr:queued_job_count" />
        <xsd:element ref="pr:operations_supported" />
        <xsd:element ref="pr:document_format_supported" />
        <xsd:element ref="pr:job_hold_until_default" 
                     minOccurs="0" />
        <xsd:element ref="pr:job_hold_until_supported" 
                     minOccurs="0" 
                     maxOccurs="unbounded" />
        <xsd:element ref="wsrf-rp:QueryExpressionDialect" 
                     maxOccurs="unbounded" />
        <xsd:element ref="pr:job_properties" minOccurs="0" 
                     maxOccurs="unbounded" />
     </xsd:sequence>
   </xsd:complexType>
 </xsd:element>
 ...
</schema>

Creating and editing the WSDL definition for the Web service component of the WS-Resource

<wsdl:definitions targetNamespace="http://example.org/printer" ...
             xmlns:wsrf-rp="http://docs.oasis-open.org/wsrf/rp-2" 
             xmlns:wsrf-rpw="http://docs.oasis-open.org/wsrf/rpw-2"
             xmlns:wsa="http://www.w3.org/2005/08/addressing"
             xmlns:pr="http://example.org/printer">
  <wsdl:types>
    ...
    <xsd:schema...>
      <xsd:element name="CreatePrinterRequest"/>
      <xsd:element name="CreatePrinterResponse" 
                   type="wsa:EndpointReferenceType"/>
     <xsd:import namespace="http://www.w3.org/2005/08/addressing" 
                  schemaLocation="http://www.w3.org/2005/08/addressing/ws-addr.xsd"/>
     <xsd:import namespace=http://docs.oasis-open.org/wsrf/rp-2
                  schemaLocation="http://docs.oasis-open.org/wsrf/rp-2.xsd"/>
    </xsd:schema>

    <!-- Import WSDL definitions for GetResourceProperties -->
   <wsdl:import namespace="http://docs.oasis-open.org/wsrf/rpw-2" 
                 location="http://docs.oasis-open.org/wsrf/rpw-2.wsdl" />

  </wsdl:types>
  <wsdl:message name="CreatePrinterRequest">
    <wsdl:part name="CreatePrinterRequest" 
               element="pr:CreatePrinterRequest" />
  </wsdl:message>
  <wsdl:message name="CreatePrinterResponse">
    <wsdl:part name="CreatePrinterResponse" 
               element="pr:CreatePrinterResponse" />
  </wsdl:message>

  <!-- The port type has a ResourceProperties attribute that references the resource 
  properties document -->
  <wsdl:portType name="Printer" wsrf-rp:ResourceProperties="pr:printer_properties">
    <wsdl:operation name="createPrinter">
      <wsdl:input name="CreatePrinterRequest" 
                  message="pr:CreatePrinterRequest" />
      <wsdl:output name="CreatePrinterResponse"
                   message="pr:CreatePrinterResponse" />
    </wsdl:operation>

    <!-- The GetResourceProperty operation is required by the WS-ResourceProperties specification -->
    <wsdl:operation name="GetResourceProperty" 
        <wsdl:input name="GetResourcePropertyRequest" 
                    message="wsrf-rpw:GetResourcePropertyRequest" 
                    wsa:Action="http://docs.oasis-open.org/wsrf/rpw-2/GetResourceProperty/
                                                                        GetResourcePropertyRequest"/>
        <wsdl:output name="GetResourcePropertyResponse"
                     message="wsrf-rpw:GetResourcePropertyResponse" 
                     wsa:Action="http://docs.oasis-open.org/wsrf/rpw-2/GetResourceProperty/
                                                                       GetResourcePropertyResponse"/>
        <wsdl:fault name="ResourceUnknownFault"
                    message="wsrf-rw:ResourceUnknownFault"/>
        <wsdl:fault name="InvalidResourcePropertyQNameFault"
                    message="wsrf-rpw:InvalidResourcePropertyQNameFault" />     
    </wsdl:operation>
  </wsdl:portType>
</wsdl:definitions>

Implementing the Web service component of the WS-Resource

You implement the Web service in the same way as a normal Web service, as described in Example: Creating a Web service that uses the Web Services Addressing API to access a generic Web service resource instance. This example discusses the use of endpoint references that refer to generic Web service resource instances. A WS-Resource instance is a specific type of such a resource instance, that supports the standardized message exchanges defined in the WSRF specification.

Related concepts

Related tasks

Related Reference

Reference topic