5
SOAP Handlers

Oracle SOAP supports handlers for the SOAP Request Handler Servlet (SOAP Server) that are configured in handler chains. Handlers are invoked at specific times for each SOAP request.

This chapter covers the following topics:

Handler Overview

A handler is a class that implements the oracle.soap.server.Handler interface. A handler can be configured as part of a chain in one of three contexts: request, response, or error. Note that handlers in a chain are invoked in the order they are specified in the configuration file.

See Also:

"Configuring Handlers"

Request Handlers

Handlers in the request chain are invoked on every request that arrives, immediately after the SOAP Request Handler Servlet reads the SOAP Envelope and before performing the service lookup. If any handler in the request chain throws an exception, the processing of the chain is immediately terminated and the service is not invoked.

The error chain is invoked if any exception occurs during request chain invocation.

Response Handlers

Handlers in the response chain are invoked on every request immediately after the service completes. If any handler in the response chain throws an exception, processing of the chain is immediately terminated. The error chain is invoked if any exception occurs during response chain invocation.

Error Handlers

When an exception occurs during either request-chain invocation, service invocation, or response chain invocation, the SOAP Request Handler Servlet invokes the handlers in the error chain. In contrast to the request and response chains, an exception from an error handler is logged and processing of the error chain continues. All handlers in the error chain are invoked, regardless of whether one of error handler throws an exception.

Configuring Handlers

Configure handlers and handler chains in the SOAP configuration file. Handlers can be invoked for each service request or response, or when an error occurs. Handlers are global in the sense that they apply to every SOAP request and cannot be configured on a subset of requests, such as all requests for a particular service.

Configure a handler by setting parameters in the SOAP configuration file, soapConfig.xml. Example 5-1 shows a sample segment from a SOAP configuration file showing the configuration for a handler.

Example 5-1 Handler Configuration

<osc:handlers>
   <osc:handler name="auditor"
      class="oracle.soap.handlers.audit.AuditLogger">
      <osc:option name="auditLogDirectory"
           value="/private1/oracle/app/product/tv02/soap/webapps/soap/WEB-INF"/>
      <osc:option name="filter" value="(!(host=localhost))"/>
   </osc:handler>
</osc:handlers>
  
<osc:requestHandlers names="auditor"/>
<osc:responseHandlers names="auditor"/>
<osc:errorHandlers names="auditor"/>

5 SOAP Handlers