Configure JAX-RPC handlers

Creating Web service handlers

Handlers allow you to process SOAP messages before and after the message is sent through the network. They are typically used to process SOAP header contents. Header specifications are defined by JAX-RPC and JSR 109. You can configure handlers for Web services and Web service clients.

For deployed Web services, the handler may be added to the webservice.xml deployment descriptor file. For J2EE 1.4 Web service clients, the handler may be added to the respective client deployment descriptor; WEB-INF/web.xml for servlets and JSPs, META-INF/ejb-jar.xml for EJBs, and META-INF/application-client.xml for application-clients. The handler wizard is applicable to Web services using the WebSphere runtime environment only.

Once you have created a Web service or client, configure the handlers as follows:

  1. Right-click on the appropriate Web service deployment descriptor file and select Web Services > Configure handlers.

    Configure handlers

  2. To add a new handler, click Add under Handler configuration.

    1. Enter a class name or browse the available classes. The name will be filled in automatically. If you enter the name of a class that does not yet exist, the wizard will create it for you if you have selected Generate skeleton classes for new handlers.

      Class name

    2. If you have more than one available port to which you can apply a handler, select the correct port.

    3. Click OK.

  3. When you have added all the required handlers to the list, you can change their processing order by changing the order in which they are listed in the wizard. Click Finish.

    Class name

When the wizard creates a skeleton handler, the handler implementation will be opened automatically in the Java Editor. If you have created multiple handlers using the wizard, only the first handler will be opened in the Java Editor.

Once a new handler is added, its configuration can be edited with the Deployment Descriptor Editor or Web Services Editor. To do this, double-click the Web service or client deployment descriptor, and select the WS Handler or Handlers tab. You can also edit the handler implementation itself using the Java Editor.

Handlers tab

Server side handler in webservices.xml:

<?xml version="1.0" encoding="UTF-8"?>
<webservices xmlns="" ...>
            <wsdl-port xmlns:pfx="">pfx:SayHello</wsdl-port>

Adding Web service references (on the client)

Starting with the J2EE 1.3 specification, application components (application clients, Web modules, EJB modules) can define references to external Web services by using "logical" names called Web service references. Beginning with J2EE 1.4, the reference is included in the deployment descriptor.

At deployment, the Web service references are bound to the Web service interfaces in the target operational environment.

For each Web service reference that you define, a service-ref element is added to that application component. Web service references are scoped to the application component or enterprise bean where they are defined, so they are not accessible to other application components or beans during run time. Other components can define Web service references with the same name without causing a name conflict.

NOTE: For project levels previous to the J2EE 1.4 specification level, the workbench allows you to define Web service references, but the service-ref elements are not added to the deployment descriptors (the application-client.xml, web.xml, or ejb-jar.xml). Rather, the Web service references are declared in a webservicesclient.xml file in the META-INF folder of the module. For example, if you add a Web service reference to a J2EE 1.3 application client, the reference is added to webservicesclient.xml. If you add a Web service reference to a J2EE 1.4 application client, the reference is added to application-client.xml.

TIP: The EJB specification recommends that you organize all Web service references in the service sub-context of the bean's environment, the java:comp/env/service JNDI context.

To define a Web service reference:

  1. Open the Add Reference wizard from the deployment descriptor editor (WEB-INF/web.xml) for your J2EE module (Chapter3ClientWeb).

  2. Select Service reference and click Next.

  3. From the list of Web services in your workspace, select the Web service that you want to reference.

  4. In the Name field, specify a name for the reference, or accept the default name provided by the wizard (recommended). The value entered in the Name field is used in the service-ref-name entry in the deployment descriptor. The value for the name is the environment entry name used in the enterprise bean code.

  5. Click Next.

  6. In the Description text area, enter a description for the reference.

  7. In the Namespace URI field, enter a new namespace URI or accept the value entered by the wizard. The value entered in this field is used as the xmlns:prefix attribute in the service-qname entry in the deployment descriptor.

  8. In the Local part field, indicate whether the message destination consumes or produces messages. The value entered in this field is used as the value in the service-qname entry in the deployment descriptor:

  9. Click Finish.

    References tab


	<description>WSDL Service SayHelloService</description>
	<service-qname xmlns:pfx="">

Defining Web service handlers (on the client)

For J2EE 1.4 modules that include Web service references, you can use the deployment descriptor editor to define and configure Web service handlers for each Web service reference. Handlers allow you to process SOAP message header traffic for the remote call to the Web service. The SOAP header is defined by the SOAP specification. Handlers are defined by JAX-RPC and the Web Services for J2EE specification.

In order to define Web service handlers, you MUST first define a Web service reference.

Web Service Reference

When you define a handler for a Web service reference, the handler element is added to the related service reference (the service-ref element). For J2EE 1.4, it is in the deployment descriptor.

To define a Web service handler for a Web service reference:

  1. In the Project Explorer of the J2EE perspective, expand the project tree and select the Deployment Descriptor node for your project where you want to define a Web service handler. You can define Web service handlers for Web service references in EJB projects, application client projects, and dynamic Web projects (Chapter3ClientWeb).

  2. Right-click the Deployment Descriptor node and select Open With > Deployment Descriptor Editor from the pop-up menu. The appropriate deployment descriptor for your module type opens. For example, an Web module opens in the Web deployment descriptor editor.

  3. Click the WS Handler tab to go to the Handlers page of the deployment descriptor editor.

  4. In the Service references drop-down list, select the Web service reference that you want to define the handler for.

    Service reference

  5. Click Add to open the New Handler dialog box and define the handler:

    • In the Display name field, type a value for the display-name element in the deployment descriptor - ClientHandler.

    • In the Description field, type a value for the description element for the handler - This is a client side handler.

    • In the Handler name field, type a value for the handler-name element - ClientHandler.

    • In the Handler class field, enter the fully-qualified name of the Java class for the handler. This value is used in the handler-class element - by.iba.rad257.ClientHandler.


  6. Click Finish. The handler is added to the list of handlers defined for the selected reference. If you select the handler, you can see and modify the properties.

    New handler

  7. Optional: In the Icons section, you can specify small and large GIF or JPEG images to help identify the Web service handler at run time. The images must first be imported into the project.

  8. Optional: In the Initial parameters section, click the Add button to define a name and value for an initialization parameter for the selected handler.

  9. Optional: In the SOAP headers section, click the Add button to define the namespace URL and local part for a new SOAP header for the handler.

Client side handler WEB-INF/web.xml:

	<description>WSDL Service SayHelloService</description>
		<description>This is a client side handler</description>

Now add new handler class to Chapter3ClientWeb project:

package by.iba.rad257;

import java.util.Date;

import javax.xml.namespace.QName;
import javax.xml.rpc.handler.GenericHandler;
import javax.xml.rpc.handler.MessageContext;

public class ClientHandler extends GenericHandler {

    public QName[] getHeaders() {
        // Fill in method body
        return null;

    public boolean handleRequest(MessageContext context) {
        try {
			Date startTime = new Date();
			context.setProperty("startTime", startTime);
			System.out.println("  => CLIENT SIDE HANDLER: Start time stored.");			
		} catch (Exception x) {
		return true;

    public boolean handleResponse(MessageContext context) {
        try {
			Date startTime = (Date)context.getProperty("startTime");
			Date endTime = new Date();
			long elapsedTime = endTime.getTime() - startTime.getTime();
			System.out.println("  => CLIENT SIDE HANDLER: Elapsed time is " + elapsedTime + ".");
		} catch (Exception x) {
		return true;

Start test client:

Test client

Test the Web Service:

Test client

In the Console View you can see the server side and client side handlers output:

[14.6.07 10.59.55:801 EEST] 00000044 ServletWrappe A   SRVE0242I: [/sampleSayHelloProxy/TestClient.jsp]: Initialization successful.
[14.6.07 10.59.56:738 EEST] 00000045 ServletWrappe A   SRVE0242I: [/sampleSayHelloProxy/Method.jsp]: Initialization successful.
[14.6.07 10.59.57:035 EEST] 00000044 ServletWrappe A   SRVE0242I: [/sampleSayHelloProxy/Input.jsp]: Initialization successful.
[14.6.07 10.59.59:066 EEST] 00000041 ServletWrappe A   SRVE0242I: [/sampleSayHelloProxy/Result.jsp]: Initialization successful.
[14.6.07 11.00.09:582 EEST] 00000041 SystemOut     O   => CLIENT SIDE HANDLER: Start time stored.
[14.6.07 11.00.09:691 EEST] 00000040 SystemOut     O   => SERVER REQUEST :

<soapenv:Envelope ...>
	<soapenv:Header />
		<p462:greet xmlns:p462="">

[14.6.07 11.00.09:691 EEST] 00000040 SystemOut     O   => SERVER RESPONSE:

<soapenv:Envelope ... >
	<soapenv:Header />
		<p462:greetResponse xmlns:p462="">
			<greetReturn>Hello, Mikalai !</greetReturn>

[14.6.07 11.00.09:707 EEST] 00000041 SystemOut     O   => CLIENT SIDE HANDLER: Elapsed time is 125.


The javax.xml.rpc.handler.Handler interface is required to be implemented by a SOAP message handler. The handleRequest, handleResponse and handleFault methods for a SOAP message handler get access to the SOAPMessage from the SOAPMessageContext. The implementation of these methods can modify the SOAPMessage including the headers and body elements.

The SOAPFaultException exception represents a SOAP fault.

The message part in the SOAP fault maps to the contents of faultdetail element accessible through the getDetail method on the SOAPFaultException. The method createDetail on the javax.xml.soap.SOAPFactory creates an instance of the javax.xml.soap.Detail.

The faultstring provides a human-readable description of the SOAP fault. The faultcode element provides an algorithmic mapping of the SOAP fault.

public class SOAPFaultException extends RuntimeException {

Class java.rmi.RemoteException

A RemoteException is the common superclass for a number of communication-related exceptions that may occur during the execution of a remote method call. Each method of a remote interface, an interface that extends java.rmi.Remote, must list RemoteException in its throws clause.

System Exceptions

System exceptions generally involve unanticipated errors - such as a network timeout or an unavailable or unreachable server - that occur when invoking a Web service. Although system exceptions are usually out of the control of the client developer, you should still be aware that these errors may occur, and you should have a strategy for your client application to deal with these situations. For example, with these types of errors, it may be useful to have the client application prompt the user to retry the operation or redirect the user to an alternative service, if possible. Many times the only solution is to display the exception occurrence to the end user. Sometimes it may be appropriate to translate the system exception to an unchecked exception and devise a global way to handle them. The exact solution is particular to each application and situation.

System exceptions, which the client receives as RemoteException, arise from a variety of reasons. Often system exceptions happen because of network failures or server errors. They also may be the result of a SOAP fault. Since a RemoteException usually contains an explanation of the error, the application can use that message to provide its own error message to the user and can prompt the user for an appropriate action to take. If an EJB component client is doing its work on behalf of a Web tier client, the EJB client should throw an exception to the Web tier client. The Web tier client notifies the user, giving the user a chance to retry the action or choose an alternative action.

BOOT.BY - Tech Industry News         Free SCBCD 1.3 Study Guide     Free SCDJWS 1.4 Study Guide     SCDJWS 1.4 Quiz     Free IBM Certified Associate Developer Study Guide     Free SCJP 5.0 (Tiger) Study Guide     Free Mock Exam Engine     Free SCWCD 1.4 Study Guide     IBM Test 000-287. Enterprise Application Development with IBM WebSphere Studio, V5.0 Study Guide     Free SCBCD 5.0 Study Guide