Working with Handlers

When working with web services on Integration Server, the SOAP body portion of the SOAP message contains the data representing the input and output signatures of the underlying SOAP operation. In typical processing, Integration Server converts the SOAP body between its XML representation in the SOAP message and the Document (IData) representation used within Integration Server automatically.

In addition to the data contained in the SOAP body, a SOAP message might contain data in the SOAP headers. The best way to access the SOAP headers is to use handlers. A handler, sometimes called a header handler, provides access to the entire SOAP message.

Handlers can be used to perform various types of processing, including processing SOAP headers, adding SOAP headers, removing SOAP headers, passing data from the header to the endpoint service or vice versa.

In Integration Server, a handler is a set of up to three handler services. The handler can contain one of each of the following handler services:

  • Request handler service
  • Response handler service
  • Fault handler service

For detailed information about request, response, or fault handler services, see Web Services Developer’s Guide .

Any IS service can be used as a handler service. However, handler services must use a specific service signature. Integration Server defines the service handler signature in the pub.soap.handler:handlerSpec specification. Integration Server also provides several services that you can use when creating handler services. These services are located in the pub.soap.handler folder in the WmPublic package.

When you register a handler, you name the handler, identify the services that function as the request, response or fault handler services, and indicate whether the handler is for use with provider web service descriptors or consumer web service descriptors.

You can assign multiple handlers to a web service descriptor. Designer displays the handlers on the Handlers tab. The collection of handlers assigned to a web service descriptor is called a handler chain. For a consumer web service descriptor, Integration Server executes the handler chain for output SOAP requests and inbound SOAP responses. For a provider web service descriptor, Integration Server executes the handler chain for inbound SOAP requests and outbound SOAP responses.

When executing the handler chain, Integration Server executes request handler services by working through the handler chain from top to bottom. However, Integration Server executes response handler services and fault handler services from bottom to top.

The order of handlers in the handler chain may be important, depending on what processing the handlers are performing.

Setting Up a Header Handler

To create and implement a header handler, you need to:

  • Build the services for handling a request, handling a response, and handling a fault. Use the pub.soap.handler:handlerSpec specification as the signature for a service that acts as a header handler.
  • Register the combination of those services as a header handler.
  • Assign the header handler to the web service descriptor.

Registering a Header Handler

Register the handler as either a consumer or provider using pub.soap.handler:registerWmConsumer or pub.soap.handler:registerWmProvider, respectively. During registration:

  • You provide a logical name for the handler.
  • You specify the services for handling a request, a response, and a fault as input.
  • You optionally specify the list of QNames on which the handler operates.

    Specify QNames only if you want to associate with handler with one or more QNames. Registering QNames with a handler provides the following benefits:

    • Integration Server can perform mustUnderstand checking for the header with the QName at run time. If a service receives a SOAP message in which a header requires mustUnderstand processing by the recipient, Integration Server uses the header QName to locate the handler that processes the header. Note that the handler must be part of the handler chain for the WSD that contains the service.
    • When adding headers to a WSD, Designer populates the list of IS document types that can be used as headers in the WSD with the IS document types whose QNames were registered with the handlers already added to the WSD. If you add a IS document type as a header to a WSD and the QName of that IS document type is not associated with a handler, Designer adds the header but display a warning stating that there is not an associated handler.
    • When consuming WSDL to create a provider or consumer WSD, Integration Server automatically adds a handler to the resulting WSD if the WSDL contains a QName supported by the handler.
Note: Integration Server stores information about registered header handlers in memory. Integration Server does not persist registered header handler information across restarts. Consequently, you must register header handlers each time Integration Server starts. To accomplish this, create a service that registers a header handler and make that service a start up service for the package that contains the services that act as header handlers.

Adding a Handler to a Web Service Descriptor

About this task

To add a handler to a web service descriptor

Procedure

  1. In Package Navigator view, open and lock the web service descriptor to which you want to add handlers.
  2. In the Handlers tab, click on the web service descriptor toolbar. Or right-click and select Add Handler.
  3. Select the registered handler that you want to add to the web service descriptor.
  4. Click File > Save.
  5. Once a handler is added to a web service descriptor, you may optionally add any headers associated with the handler to the request or response elements of operations within the web service descriptor.
    Note: You must set up a package dependency if the web service descriptor uses a handler from a different package.

Deleting a Handler from a Web Service Descriptor

About this task

To delete a handler from a web service descriptor

Procedure

  1. In Package Navigator view, open and lock the web service descriptor from which you want to remove handlers.
  2. Click the Handlers tab.
  3. Select the handler that you want to delete.
  4. Click on the web service descriptor toolbar or right-click and select Delete.

    Designer removes the selected handler is deleted from the Handlers tab and from the web service descriptor. If the web service descriptor still contains a header associated with the deleted handler, Designer displays a warning.