Implementing a Provider Object

Implementing a `Provider` Object

Overview

The Provider interface is relatively easy to implement. It only has one method, invoke(), that must be implemented. In addition it has three simple requirements:

An implementation must have the @WebServiceProvider annotation.
An implementation must have a default public constructor.
An implementation must implement a typed version of the Provider interface.
In other words, you cannot implement a Provider<T> interface. You must implement a version of the interface that uses a concrete data type as listed in Data Types. For example, you can implement an instance of a Provider<SAXSource>.

The complexity of implementing the Provider interface is in the logic handling the request messages and building the proper responses.

Working with messages

Unlike the higher-level SEI based service implementations, Provider implementations receive requests as raw XML data, and must send responses as raw XML data. This requires that the developer has intimate knowledge of the messages used by the service being implemented. These details can typically be found in the WSDL document describing the service.

WS-I Basic Profile provides guidelines about the messages used by services, including:

The root element of a request is based in the value of the name attribute of the wsdl:operation element that corresponds to the operation that is invoked.

	Warning
	If the service uses doc/literal bare messages, the root element of the request is based on the value of `name` attribute of the `wsdl:part` element referred to by the `wsdl:operation` element.

The root element of all messages is namespace qualified.
If the service uses rpc/literal messages, the top-level elements in the messages are not namespace qualified.
Important
The children of top-level elements might be namespace qualified, but to be certain you will must check their schema definitions.
If the service uses rpc/literal messages, none of the top-level elements can be null.
If the service uses doc/literal messages, then the schema definition of the message determines if any of the elements are namespace qualified.

	Important
The children of top-level elements might be namespace qualified, but to be certain you will must check their schema definitions.

The `@WebServiceProvider` annotation

To be recognized by JAX-WS as a service implementation, a Provider implementation must be decorated with the @WebServiceProvider annotation.

Table 19.2 describes the properties that can be set for the @WebServiceProvider annotation.

Table 19.2. @WebServiceProvider Properties

Property	Description
portName	Specifies the value of the `name` attribute of the `wsdl:port` element that defines the service's endpoint.
serviceName	Specifies the value of the `name` attribute of the `wsdl:service` element that contains the service's endpoint.
targetNamespace	Specifies the targetname space of the service's WSDL definition.
wsdlLocation	Specifies the URI for the WSDL document defining the service.

All of these properties are optional, and are empty by default. If you leave them empty, FUSE Services Framework creates values using information from the implementation class.

Implementing the `invoke()` method

The Provider interface has only one method, invoke(), that must be implemented. The invoke() method receives the incoming request packaged into the type of object declared by the type of Provider interface being implemented, and returns the response message packaged into the same type of object. For example, an implementation of a Provider<SOAPMessage> interface receives the request as a SOAPMessage object and returns the response as a SOAPMessage object.

The messaging mode used by the Provider implementation determines the amount of binding specific information the request and the response messages contain. Implementations using message mode receive all of the binding specific wrappers and headers along with the request. They must also add all of the binding specific wrappers and headers to the response message. Implementations using payload mode only receive the body of the request. The XML document returned by an implementation using payload mode is placed into the body of the request message.

Examples

Example 19.11 shows a Provider implementation that works with SOAPMessage objects in message mode.

Example 19.11. Provider<SOAPMessage> Implementation

import javax.xml.ws.Provider;
import javax.xml.ws.Service;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.WebServiceProvider;

@WebServiceProvider(portName="stockQuoteReporterPort"
                    serviceName="stockQuoteReporter")
@ServiceMode(value="Service.Mode.MESSAGE")
public class  stockQuoteReporterProvider implements Provider<SOAPMessage>
{
public stockQuoteReporterProvider()
  {
  }

public SOAPMessage invoke(SOAPMessage request)
  {
  SOAPBody requestBody = request.getSOAPBody();
  if(requestBody.getElementName.getLocalName.equals("getStockPrice"))
    {
    MessageFactory mf = MessageFactory.newInstance();
      SOAPFactory sf = SOAPFactory.newInstance();

    SOAPMessage response = mf.createMessage();
      SOAPBody respBody = response.getSOAPBody();
      Name bodyName = sf.createName("getStockPriceResponse");
      respBody.addBodyElement(bodyName);
      SOAPElement respContent = respBody.addChildElement("price");
      respContent.setValue("123.00");
      response.saveChanges();
    return response;
    }
    ...
  }
}

The code in Example 19.11 does the following:

	Specifies that the following class implements a `Provider` object that implements the service whose `wsdl:service` element is named `stockQuoteReporter`, and whose `wsdl:port` element is named `stockQuoteReporterPort`.
	Specifies that this `Provider` implementation uses message mode.
	Provides the required default public constructor.
	Provides an implementation of the `invoke()` method that takes a `SOAPMessage` object and returns a `SOAPMessage` object.
	Extracts the request message from the body of the incoming SOAP message.
	Checks the root element of the request message to determine how to process the request.
	Creates the factories required for building the response.
	Builds the SOAP message for the response.
	Returns the response as a `SOAPMessage` object.

Example 19.12 shows an example of a Provider implementation using DOMSource objects in payload mode.

Example 19.12. Provider<DOMSource> Implementation

import javax.xml.ws.Provider;
import javax.xml.ws.Service;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.WebServiceProvider;

@WebServiceProvider(portName="stockQuoteReporterPort" serviceName="stockQuoteReporter")
@ServiceMode(value="Service.Mode.PAYLOAD")
public class  stockQuoteReporterProvider implements Provider<DOMSource>
public stockQuoteReporterProvider()
  {
  }

public DOMSource invoke(DOMSource request)
  {
    DOMSource response = new DOMSource();
    ...
    return response;
  }
}

The code in Example 19.12 does the following:

	Specifies that the class implements a `Provider` object that implements the service whose `wsdl:service` element is named `stockQuoteReporter`, and whose `wsdl:port` element is named `stockQuoteReporterPort`.
	Specifies that this `Provider` implementation uses payload mode.
	Provides the required default public constructor.
	Provides an implementation of the `invoke()` method that takes a `DOMSource` object and returns a `DOMSource` object.