Skip Headers
Oracle® Application Server Web Services Developer's Guide
10g Release 3 (10.1.3)
B14434-01
  Go To Documentation Library
Home		 Go To Product List
Solution Area		 Go To Table Of Contents
Contents		 Go To Index
Index
Previous
Previous		 Next
Next		  

15 Understanding JAX-RPC Handlers

This chapter provides an overview of working with JAX-RPC message handlers.

Message Handler Overview

SOAP message handlers are used to process messages to and from a Web service. There are two kinds of handlers: client and server.

Because handlers gain privileged access to the entire SOAP envelope, they are commonly used for SOAP header processing. Some other common uses for handlers are:

Much of this functionality is provided by the OracleAS Web Services management infrastructure. In many cases, a user-written handler might not be necessary.

For any given Web service or Web service client, there can be zero or more handlers. A collection of handlers constitutes a handler chain. The handler chain is maintained by the JAX-RPC runtime implementation. The default behavior of the runtime implementation is to call each handler in order from the chain. However, a handler can change this processing model based on its implementation of the javax.xml.rpc.handler.Handler interface. For example, returning false in the handleRequest message will halt the runtime from proceeding to the next handler in the chain. Throwing an exception will have a similar effect. For more information on handlers and the handler model, see the JAX-RPC 1.1 specification.

http://java.sun.com/webservices/jaxrpc/index.jsp

Writing a JAX-RPC Handler

To build a JAX-RPC handler, implement the javax.xml.rpc.handler.Handler interface.

package javax.xml.rpc.handler;
public interface Handler{
    public boolean handleRequest(javax.xml.rpc.handler.MessageContext context);
    public boolean handleResponse(javax.xml.rpc.handler.MessageContext context);
    public boolean handleFault(javax.xml.rpc.handler.MessageContext context);
    public void destroy();
    public void init(javax.xml.rpc.handler.HandlerInfo config);
    public javax.xml.namespace.QName[] getHeaders();
}

For more information on the Handler interface, see the output of the Javadoc tool at the following Web address.

http://java.sun.com/j2ee/1.4/docs/api/javax/xml/rpc/handler/Handler.html

As an alternative to implementing the Handler interface, you can extend the javax.xml.rpc.handler.GenericHandler class. This class provides default implementations for all of the interface's methods so there is no need to redefine them in your handler implementation.

Configuring a Server-Side JAX-RPC Handler

Handlers are ultimately configured and registered in the Web services deployment descriptor (webservices.xml). However, instead of editing the file yourself, you can have WebServicesAssembler generate the proper configuration by specifying the handler classes, that is, classes that implement the Handler interface, at development time.


Note:

WebServicesAssembler provides Ant tasks that let you configure JAX-RPC message handlers. Handlers cannot be configured by using the WebServicesAssembler command line.

For example, to add server handlers for a Web service described by the WSDL in Example 16-1, you could use the following Ant task. The server handler appears in bold:

<oracle:topDownAssemble appName="hello-service"
                   wsdl="Hello.wsdl"
                   input="./classes"
                   output="build"
                   ear="dist/hello-service.ear"
                   packageName="oracle.demo"
                   >
                    <oracle:porttype className="oracle.demo.HelloImpl" />
                    <oracle:handler name="ServerHandler" 
                             handlerClass="oracle.demo.ServerHelloHandler"/>
</oracle:topDownAssemble>

In this example, the server handler oracle.demo.ServerHelloHandler will be configured for the hello-service Web service. Any number of handlers can be added by adding <handler> tags, each with unique names. The order in which the handler elements are listed is the order in which they will be added to the handler chain. Although this example is for top down development, handlers can also be added to other Ant tasks using the same <handler> tag. The following is a list of Ant tasks that can include the <handler> tag. "Configuring Handlers in an Ant Task" provides more information on configuring handlers.

To add client-side handlers, the configuration is almost identical. For more information, see "Client-Side JAX-RPC Handlers".

Registering JAX-RPC Handlers with webservices.xml

If you use Ant tasks to add handlers while generating your Web service, there should be no need to add handlers to the webservices.xml file. If you use the command line or are manually creating a Web service deployment, you can add handlers to webservices.xml by adding child elements to the <port-component> element. Example 15-1 illustrates a <port-component> element with multiple handlers.

Example 15-1 Sample JAX-RPC Handlers in webservices.xml

<port-component>
    ...
<handler>
    <handler-name>First Handler</handler-name>
    <handler-class>oracle.xx.AccountTransactionHandler</handler-class>
    <init-param>
       <param-name>test</param-name>
       <param-value>testValue</param-value>
    </init-param>
</handler>
<handler>
    <handler-name>Second Handler</handler-name>
    <handler-class>oracle.xx.NewAccountHandler</handler-class>
</handler>
   ...
</port-component>

Table 15-1 describes the <handler> subelements that can be used to specify a server-side handler:

Table 15-1 <handler> Subelements for a Server-Side Handler

Subelement Description

<handler-name>

A unique name that identifies the handler.

<handler-class>

The fully-qualified name of the class to which the handler belongs. The class must implement: javax.xml.rpc.handler.Handler.

<init-param>

A subelement containing one param-name, param-value pair.

The param-name, param-value pair represents a single parameter and value that will be passed to the handler's init method. There is no limit on the number of init-param subelements that can be used in a <handler> element.

For more information on the contents of webservices.xml, see its schema at the following Web address:

http://java.sun.com/xml/ns/j2ee/j2ee_web_services_1_1.xsd

Client-Side JAX-RPC Handlers

On the Web service client, JAX-RPC handlers can intercept and process messages sent from a client application and the corresponding message returned by the service. These handlers can, for example, process the SOAP message. The following sections describe how to register the handlers for use in Web service clients:

Registering JAX-RPC Handlers for J2EE Web Service Clients

For J2EE Web service clients, JAX-RPC handler information appears within the <service-ref> element in the deployment descriptor for a given J2EE client. The <service-ref> element captures all of the service's J2EE client-related information, such as the location of the WSDL and mapping file, the service interface, the ports the service will run on and their related service endpoint interfaces, and so on.

Unlike server-side handlers, client-side handlers are associated with service references (<service-ref>) instead of port component references (<port-component>). Client-side handlers have a configurable <port-name> parameter that associates a handler with the port of the invoked service. When a service endpoint (WSDL port) is invoked, the value of <port-name> determines which handler is run.

To register a handler for a J2EE Web service client, enter the handler information in the <service-ref> section of its deployment descriptor. The following list identifies the J2EE deployment descriptors for each J2EE component that can act as a Web service client.

  • WEB-INF/web.xml for a JSP or servlet

  • META-INF/application-client.xml for an application client

  • META-INF/ejb-jar.xml for an EJB

Using the handler Element in a J2EE Web Service Client

The <handler> element encapsulates the handler information for a J2EE Web service client. Table 15-2 describes the sub-elements that it can use:

Table 15-2 <handler> Subelements for a J2EE Web Service Client Handler

Subelement Description

<handler-name>

The unique name that identifies the handler.

<handler-class>

The fully-qualified name of the class to which the handler belongs. The class must implement javax.xml.rpc.handler.Handler.

<port-name>

The name of the port on which the handler will operate.

Enter the handler information at the end of the <service-ref> section, after any port component information. Example 15-2 illustrates a <service-ref> tag with two defined handlers. In this example, First Handler is associated with the class oracle.xx.AccountTransactionHandler and runs on portA. Second Handler is associated with the class oracle.xx.NewAccountHandler and runs on portB. First Handler runs only if PortA is invoked and Second Handler runs only if PortB is invoked.

Example 15-2 Sample JAX-RPC Handler for a J2EE Client

<service-ref>
    <service-ref-name>service/MyHelloServiceRef</service-ref-name>
    ....
    <port-component-ref>
        ....
    </port-component-ref>
 <handler>
         <handler-name>First Handler</handler-name>
         <handler-class>oracle.xx.AccountTransactionHandler</handler-class>
         <port-name>portA</port-name>
 </handler>
 <handler>
         <handler-name>Second Handler </handler-name>
         <handler-class>oracle.xx.NewAccountHandler</handler-class>
         <port-name>portB</port-name>
      </handler>
</service-ref>

For more information on the contents of <service-ref> element, see the service-ref (J2EE client) schema.

http://java.sun.com/xml/ns/j2ee/j2ee_web_services_client_1_1.xsd

Registering JAX-RPC Handlers for J2SE Web Service Clients

Client-side JAX-RPC handlers for J2SE clients can be registered using the genProxy Ant task for WebServicesAssembler. In Example 15-3, the handler oracle.demo.ClientHelloHandler will be available to the J2SE client. Unlike J2EE Web service clients, J2SE clients do not use a deployment descriptor.

Example 15-3 Registering a Handler for a J2SE Web Service Client

<oracle:genProxy
            wsdl="http://localhost:8888/hello-service/hello-service?WSDL"
            output="build/src/client"
            packageName="oracle.demo">
            <oracle:handler
                  name="ClientHelloHandler"
                  handlerClass="oracle.demo.ClientHelloHandler" />
      </oracle:genProxy>

Limitations

See "Understanding JAX-RPC Handlers".

Additional Information

For more information on:

  Previous
Previous		 Next
Next
  Go To Documentation Library
Home		 Go To Product List
Solution Area		 Go To Table Of Contents
Contents		 Go To Index
Index