9
Creating and Using SOAP Message Handlers 9-1
9
Creating and Using SOAP Message Handlers
The following sections provide information about creating and using SOAP message handlers:
■
Section 9.1, Overview of SOAP Message Handlers
■
Section 9.2, Adding SOAP Message Handlers to a Web Service: Main Steps
■
Section 9.3, Designing the SOAP Message Handlers and Handler Chains
■
Section 9.4, Creating the GenericHandler Class
■
Section 9.5, Configuring Handlers in the JWS File
■
Section 9.6, Creating the Handler Chain Configuration File
■
Section 9.7, Compiling and Rebuilding the Web Service
■
Section 9.8, Creating and Using Client-Side SOAP Message Handlers
9.1 Overview of SOAP Message Handlers
Some Web services need access to the SOAP message, for which you can create SOAP message handlers.
A SOAP message handler provides a mechanism for intercepting the SOAP message in both the request and response of the Web service. You can create handlers in both
the Web service itself and the client applications that invoke the Web service.
A simple example of using handlers is to access information in the header part of the SOAP message. You can use the SOAP header to store Web service specific
information and then use handlers to manipulate it.
You can also use SOAP message handlers to improve the performance of your Web service. After your Web service has been deployed for a while, you might discover
that many consumers invoke it with the same parameters. You could improve the performance of your Web service by caching the results of popular invokes of the Web
service assuming the results are static and immediately returning these results when appropriate, without ever invoking the back-end components that implement the Web
service. You implement this performance improvement by using handlers to check the request SOAP message to see if it contains the popular parameters.
The following table lists the standard JWS annotations that you can use in your JWS file to specify that a Web service has a handler chain configured; later sections discuss
how to use the annotations in more detail. For additional information, see the Web services MetaData for the Java Platform JSR-181 specification at
http:www.jcp.orgenjsrdetail?id=181 .
9-2 Programming Advanced Features of JAX-RPC Web Services for Oracle WebLogic Server
The following table describes the main classes and interfaces of the javax.xml.rpc.handler
API, some of which you use when creating the handler itself. These APIs are discussed in detail in a later section. For additional information
about these APIs, see the JAX-RPC 1.1 specification at http:java.netprojectsjax-rpc
.
Table 9–1 JWS Annotations Used To Configure SOAP Message Handler Chains
JWS Annotation Description
javax.jws.HandlerChain Associates the Web service with an externally defined
handler chain. Use this annotation when multiple Web services need to share the same handler
configuration, or if the handler chain consists of handlers for multiple transports.
javax.jws.soap.SOAPMessageHandler s
Specifies a list of SOAP handlers that run before and after the invocation of each Web service operation.
Use this annotation rather than HandlerChain if embedding handler configuration information in the
JWS file itself is preferred, rather than having an external configuration file.
The SOAPMessageHandler annotation is an array of SOAPMessageHandlers. The handlers are
executed in the order they are listed in this array.
Note;
This annotation works with JAX-RPC Web services only.
javax.jws.soap.SOAPMessageHandler Specifies a single SOAP message handler in the
SOAPMessageHandlers array.
Table 9–2 JAX-RPC Handler Interfaces and Classes
javax.xml.rpc.handler Classes and Interfaces
Description
Handler Main interface that is implemented when creating a
handler. Contains methods to handle the SOAP request, response, and faults.
GenericHandler Abstract class that implements the Handler interface.
User should extend this class when creating a handler, rather than implement Handler directly.
The GenericHandler class is a convenience abstract class that makes writing handlers easy. This class
provides default implementations of the life cycle 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.
HandlerChain Interface that represents a list of handlers. An
implementation class for the HandlerChain interface abstracts the policy and mechanism for the invocation of
the registered handlers.
HandlerRegistry Interface that provides support for the programmatic
configuration of handlers in a HandlerRegistry. HandlerInfo
Class that contains information about the handler in a handler chain. A HandlerInfo instance is passed in the
Handler.init method to initialize a Handler
instance.
Creating and Using SOAP Message Handlers 9-3
9.2 Adding SOAP Message Handlers to a Web Service: Main Steps
