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.3 Web service clients, the handler will be added to webservicesclient.xml. 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.
  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.
    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.

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.

Limitations:
  • A problem currently exists in that after adding a Handler in the Handler Configuration wizard, the wizard will generate a new skeletal Handler Java file into the primary source folder of your project unless a Handler Java file already exists at the same exact location and you have not selected "Do not overwrite loadable Java classes." The wizard does not check for existence of a Handler of the same fully qualified name elsewhere in the EAR. As a result, when you use the wizard to add a Handler that already exists somewhere else in the EAR, such as in a different source folder in your project or in a different module in the EAR, the wizard will write a new skeletal Handler, eclipsing your original Handler class. If this occurs, delete the skeletal Handler generated by the wizard.
  • If a J2EE deployment descriptor editor is open with unsaved changes, and you then launch the Handler Configuration wizard to add a Handler to the same descriptor, the wizard will finish correctly, however, you will not be able to save the changes pending in your editor session. If you try to save, the editor will produce the message "The file has been modified." Before using the Handler Configuration wizard to work with Handlers in a J2EE deployment descriptor file (such as webservices.xml, webservicesclient.xml, web-inf.xml, ejb-jar.xml or application-client.xml), close any editors that are open on that descriptor file.

(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.