+

Search Tips   |   Advanced Search

 

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

The WSDL definition for the Printer WS-Resource server is the same as in Example: Creating a Web service that uses the Web Services Addressing API to access a generic Web service resource instance, with the addition of a ResourceProperties attribute on the wsdlPortType element. This attribute declares that the port type is implemented by a WS-Resource rather than a generic Web service. Because the interface contains a resource properties document type declaration, the interface must also contain the WSRF-defined GetResourceProperty operation; this operation is required by the WS-ResourceProperties specification.

<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


Web Services Resource Framework support

 

Related tasks


Creating stateful Web services using the Web Services Resource Framework

 

Related Reference


Example: Creating a Web service that uses the Web Services Addressing API to access a generic Web service resource instance
Web Services Addressing APIs
Web Services Addressing SPI

 

Reference topic