Oracle® Application Server Web Services Developer's Guide 10g (10.1.3.1.0) Part Number B28974-01 |
|
|
View PDF |
This chapter provides an overview of working with JAX-RPC message handlers.
How to Configure and Register a Server-Side Handler with Ant Tasks
How to Edit webservices.xml to Register a Server-Side Handler
SOAP message handlers can be used to process messages to and from a Web service. There are two kinds of handlers: client and server.
Client side handlers can intercept messages sent from a client application, the "request", and the corresponding message returned from the service to the client, the "response".
Server side handlers can intercept messages received by a Web service, the "request", and the corresponding message returned by the service, the "response".
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:
logging
auditing
encryption/decryption
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: |
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
|
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:
|
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".
genProxy (for client-side generation only)
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 |
---|---|
The fully-qualified name of the handler's class. The class must implement: |
|
A unique name that identifies the handler. |
|
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 |
For more information on the contents of webservices.xml
, see its schema at the following Web address:
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
How to Register a JAX-RPC Handler for a J2SE 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.
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
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 |
---|---|
The fully-qualified name of the handler's class. The class must implement |
|
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 |
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>
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>
For more information on:
processing messages directly, see the SAAJ APIs available from:
OracleAS Web Services extensions to the SAAJ APIs that allow you to work with SOAP 1.2 messages, see "Working with SOAP Messages".
assembling Web services from a WSDL, see Chapter 6, "Assembling a Web Service from WSDL".
assembling stateful Web services, see Chapter 7, "Assembling a Web Service with Java Classes".
assembling Web services from EJBs, see Chapter 8, "Assembling a Web Service with EJBs".
assembling Web services from a JMS queue or topic, see Chapter 9, "Assembling Web Services with JMS Destinations".
assembling Web services from database resources, see Chapter 10, "Assembling Database Web Services".
assembling Web services with J2SE 5.0 Annotations, see Chapter 11, "Assembling Web Services with Annotations".