Using JAXRPC Handlers

With WS4EE you can have client and server side handlers.

A JAX-RPC handler is required to implement the javax.xml.rpc.handler.Handler

interface. The following code snippet shows the Handler interface.

package javax.xml.rpc.handler;
public interface Handler 
{
   boolean handleRequest(MessageContext context);

   boolean handleResponse(MessageContext context);

   boolean handleFault(MessageContext context);
}

A handler implementation class is required to provide a default constructor.

The methods handleRequest and handleResponse perform the actual processing work

for a handler. The method handleRequest processes the request SOAP message, while

the method handleResponse processes the response SOAP message. The method

handleFault performs the SOAP fault processing.

The MessageContext parameter provides access to the message context (for example: a

SOAP message that carries an RPC request or response) that is processed by a handler.

Generic Handler

The javax.xml.rpc.handler.GenericHandler class is an abstract class that

implements the Handler interface. Handler developers should typically subclass the

generic handler class unless the handler implementation class needs another class as

its superclass.

The GenericHandler class is a convenience abstract class that makes writing handlers

easy. This class provides default implementations of the lifecycle methods init and

destroy and also different handle methods. A handler developer should only override

methods that it needs to specialize as part of the derived handler implementation class.

Configuration

A JAX-RPC handler may be configured and used on the service client as follows:

• On the service client side, a request handler is invoked before an RPC request is communicated to the target service endpoint.

• On the service client side, a response or fault handler is invoked before an RPC response is returned to the service client from the target service endpoint.

A JAX-RPC handler may configured and used on a service endpoint as follows:

• On the service endpoint side, a request handler is invoked before an RPC request is dispatched to the target service endpoint.

• On the service endpoint side, a response or fault handler is invoked before communication back to the service client from the target service endpoint.

Configuring a client side handler

Client side JAXRPC handlers are configures as part of the <service-ref> element

  <service-ref>
    <service-ref-name>service/OrganizationServiceEJB</service-ref-name>
    <service-interface>javax.xml.rpc.Service</service-interface>
    <wsdl-file>USE_JBOSS_XML_OVERRIDE</wsdl-file>
    <jaxrpc-mapping-file>META-INF/jaxrpc-mapping.xml</jaxrpc-mapping-file>
    <handler>
      <handler-name>TestHandler</handler-name>
      <handler-class>org.jboss.test.webservice.samples.ClientSideHandler</handler-class>
    </handler>
  </service-ref>

Configuring a server side handler

Server side JAXRPC handlers are configures as part of the <port-component> element

  <webservice-description>
    <webservice-description-name>OrganizationServiceJSE</webservice-description-name>
    <wsdl-file>WEB-INF/wsdl/OrganizationService.wsdl</wsdl-file>
    <jaxrpc-mapping-file>WEB-INF/jaxrpc-mapping.xml</jaxrpc-mapping-file>
    <port-component>
      <port-component-name>PortComponent</port-component-name>
      <wsdl-port>impl:OrganizationPort</wsdl-port>
      <service-endpoint-interface>org.jboss.test.webservice.samples.Organization</service-endpoint-interface>
      <service-impl-bean>
        <servlet-link>Organization</servlet-link>
      </service-impl-bean>
      <handler>
        <handler-name>TestHandler</handler-name>
        <handler-class>org.jboss.test.webservice.samples.ServerSideHandler</handler-class>
      </handler>
    </port-component>
  </webservice-description>

Sample code and handler tests

The samples attached to the main wiki use client/server side handlers. You can also run the handler flow test from the testsuite. It shows how a handler can examine/modify the incomming and outgoing message and return the message if necessary.

tdiesler@satellite /cygdrive/d/projects/jboss-branch/jboss-4.0.x/testsuite
$ ant -Dtest=org.jboss.test.webservice.handlerflow.HandlerFlowTestCase one-test

one-test:
    [junit] Running org.jboss.test.webservice.handlerflow.HandlerFlowTestCase
    [junit] Tests run: 3, Failures: 0, Errors: 0, Time elapsed: 4.126 sec