Network Deployment (Distributed operating systems), v8.0 > End-to-end paths > Web services - Resource framework (WSRF)


Create stateful web services by using the Web Services Resource Framework

We can implement a stateful web service as a WS-Resource, and reference it by using a WS-Addressing endpoint reference. You develop WS-Resources in the same way as ordinary web services, and by using the same tools. However, complete some additional tasks, as described in this topic.

Complete this task when to create a WS-Resource, which is a combination of a stateful resource and a web service through which the resource is accessed.

To complete this task have knowledge of standard web services development tasks, and the Web Services Resource Framework (WSRF) specifications. For an introduction to the WSRF specifications, read the OASIS WSRF Primer document.


Procedure

  1. Identify or create the resource component for which the WS-Resource provides access. This resource component can either be an existing system or entity, or a new component. You have no constraints on how you implement the resource; it can be a simple Java class, a stateless session enterprise bean, an entity bean backed by a relational database, a Service Data Object (SDO), a Java connector, or any other component.

  2. Identify or create a resource properties schema file for the WS-Resource. Use IBM Rational Application Developer for WebSphere, or any XML schema authoring tool, to create an XML schema. The schema defines the XML complexType element for the root element of the resource properties document.

  3. Create or generate a WSDL document for the web service component of the WS-Resource. See Develop a WSDL file for JAX-RPC applications for information about creating WSDL files.
  4. Edit the WSDL file to add a ResourceProperties attribute to the portType element. This attribute identifies the root element of the resource properties document that you created earlier. For example, if a Printer service has a resource properties document with a root element <printer_properties> in the namespace as follows:
    <wsdl:portType xmlns:pr="http://example.org/printer"
                   xmlns:wsrf-rp="http://docs.oasis-open.org/wsrf/rp-2"
                   name="Printer" wsrf-rp:ResourceProperties="pr:printer_properties">
    
  5. Provide a means to obtain an EndpointReference that points to the WS-Resource. You might define a wsdl:operation element called Create that returns a wsdl:output message of type EndpointReferenceType. See for an example of a CreatePrinter operation that returns an EndpointReference object for a Printer WS-Resource.
  6. Define each WSRF-defined operation that the WS-Resource supports as a child element of the wsdl:portType element. For each WSRF-defined operation that is supported by the port type, specify the WS-Addressing action attribute on each wsdl:message element. For example, the GetResourceProperty operation is defined in the WSDL as follows:
    <wsdl:operation name="GetResourceProperty"
                    xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
                    xmlns:wsrf-rpw="http://docs.oasis-open.org/wsrf/rpw-2">
    <wsdl:input name="GetResourcePropertyRequest" message="wsrf-rpw:GetResourcePropertyRequest"
        wsaw:Action="http://docs.oasis-open.org/wsrf/rpw-2/GetResourceProperty/GetResourcePropertyRequest"/>
    <wsdl:output name="GetResourcePropertyResponse" message="wsrf-rpw:GetResourcePropertyResponse"
        wsaw:Action="http://docs.oasis-open.org/wsrf/rpw-2/GetResourceProperty/GetResourcePropertyResponse"/>   ...
    
    </wsdl:operation>
    
    The wsaw:Action attribute ensures that the WSRF-defined wsaw:Action URIs are used for the WSRF-defined messages, rather than default URI values.

    The WS-ResourceProperties specification requires the presence of the GetResourceProperty operation if the ResourceProperties attribute is present on the PortType element.

  7. Follow the instructions from step 2 in Create a JAX-RPC web service application that uses Web Services Addressing to create the implementation of the WS-Resource, enable the client to access the WS-Resource by using an endpoint reference, and deploy the application.


Example

The following examples correspond to steps 2 to 4 in the procedure. The examples show how an IT organization might use a WS-Resource instance to manage a network of printers. A WS-Resource is a combination of a resource and a web service through which the resource is accessed. The examples assume that the organization is currently using web services to manage its printer network, as set out in the examples in Create a JAX-RPC web service application that uses Web Services Addressing.

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 by 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 file 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>

The WSDL definition for the Printer WS-Resource server is the same as in the WS-Addressing example, 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>


Related


Web Services Resource Framework support
Web Services Addressing support
Web Services Resource Framework resource property and lifecycle operations
Create a JAX-RPC web service application that uses Web Services Addressing
Task overview: Implementing web services applications


Related


WSDL2Java command for JAX-RPC applications
Java2WSDL command for JAX-RPC applications
Web Services Addressing application programming model
OASIS WSRF primer

+

Search Tips   |   Advanced Search