Skip Headers
Oracle® Application Server Web Services Developer's Guide
10g (10.1.3.5.0)
Part Number E13982-01
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

16 Using JAX-RPC Handlers

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

Understanding Message Handlers

SOAP message handlers can be 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.

See Also:

The JAX-RPC 1.1 specification provides more information on handlers and the handler model:

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

How to Write a JAX-RPC Handler

To write 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();
}

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.

See Also:

The API at the following Web site provides more information on the Handler interface and GenericHandler class.

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

How to Configure and Register a Server-Side Handler with Ant Tasks

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. These tasks are listed in "Ant Tasks that can Configure and Register 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 17-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 is configured for the hello-service Web service. Any number of handlers can be added by adding <handler> elements, each with unique names. Handlers are added to the chain in the same order in which the handler elements are listed. Although this example is for top down development, handlers can also be added to other Ant tasks using the same <handler> element.

The process for adding client-side handlers is almost identical.

See Also:

Ant Tasks that can Configure and Register Handlers

The following is a list of Ant tasks that can include the <handler> element. For more information on these commands, see Chapter 18, "Using WebServicesAssembler".

How to Edit webservices.xml to Register a Server-Side Handler

If you use Ant tasks to add handlers while generating your Web service, then the appropriate configuration will be added to the webservices.xml file for you. There should be no need to add any additional information to this file.

However, if you use the command line, or manually create a Web service deployment descriptor, then you must edit the webservices.xml file. You can add handlers to the file by adding <handler> subelements to the <port-component> element. Example 16-1 illustrates a <port-component> element with multiple handlers.

Example 16-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 16-1 describes the <handler> subelements that can be used to specify a server-side handler.

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

Subelement Description

<handler-class>

The fully-qualified name of the handler's class. The class must implement: javax.xml.rpc.handler.Handler.

<handler-name>

A unique name that identifies the 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:

How to Register a JAX-RPC Handler for J2EE Web Service Client

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

The contents of <service-ref> element are described by the service-ref (J2EE client) schema, available at the following Web site.

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

Using the handler Element in a J2EE Web Service Client

The <handler> element encapsulates the handler information for a J2EE Web service client. Table 16-2 describes the subelements that it can use.

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

Subelement Description

<handler-class>

The fully-qualified name of the handler's class. The class must implement javax.xml.rpc.handler.Handler.

<handler-name>

The unique name that identifies the 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.

<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 16-2 illustrates a <service-ref> element 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 16-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>

How to Register a JAX-RPC Handler for a J2SE Web Service Client

Client-side JAX-RPC handlers for J2SE clients can be registered using the genProxy Ant task for WebServicesAssembler. In Example 16-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 16-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:

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us