Message handlers and pipelines

A message handler is a program in which you can perform your own processing of web service requests and responses. A pipeline is a set of message handlers that are executed in sequence.

There are two distinct phases in the operation of a pipeline:
  1. The request phase, during which CICS® invokes each handler in the pipeline in turn. Each message handler can process the request before returning control to CICS.
  2. This is followed by the response phase, during which CICS again invokes each handler in turn, but with the sequence reversed. That is, the message handler that is invoked first in the request phase, is invoked last in the response phase. Each message handler can process the response during this phase.

    Not every request is succeeded by a response; some applications use a one-way message flow from service requester to provider. In this case, although there is no message to be processed, each handler is invoked in turn during the response phase.

Figure 1 shows a pipeline of three message handlers:
Figure 1. A generic CICS pipeline
A pipeline containing three handlers: handler 1, handler 2 and handler 3
In this example, the handlers are executed in the following sequence:
In the request phase
  1. Handler 1
  2. Handler 2
  3. Handler 3
In the response phase
  1. Handler 3
  2. Handler 2
  3. Handler 1
In a service provider, the transition between the phases normally occurs in the last handler in the pipeline (known as the terminal handler) which absorbs the request, and generates a response; in a service requester, the transition occurs when the request is processed in the service provider. However, a message handler in the request phase can force an immediate transition to the response phase, and an immediate transition can also occur if CICS detects an error.
A message handler can modify the message, or can leave it unchanged. For example:
  • A message handler that performs encryption and decryption will receive an encrypted message on input, and pass the decrypted message to the next handler. On output, it will do the opposite: receive a plain text message, and pass an encrypted version to the following handler.
  • A message handler that performs logging will examine a message, and copy the relevant information from that message to the log. The message that is passed to the next handler is unchanged.
Important: If you are familiar with the SOAP feature for CICS TS, you should be aware that the structure of the pipeline in this release of CICS is not the same as that used in the feature.

Transport-related handlers

CICS supports the use of two transport mechanisms between the web service requester and the provider. In some cases, you might require different message handlers to be invoked, depending upon which transport mechanism is in use. For example, you might want to include message handlers that perform encryption of parts of your messages when you are using the HTTP transport to communicate on an external network. But encryption might not be required when you are using the MQ transport on a secure internal network.

To support this, you can configure your pipeline to specify handlers that are invoked only when a particular transport (HTTP or MQ) is in use. For a service provider, you can be even more specific, and specify handlers that are invoked only when a particular named resource (a TCPIPSERVICE for the HTTP transport, a QUEUE for the MQ transport) is in use.

This is illustrated in Figure 2:
Figure 2. Pipeline with transport-related handlers
A pipeline containing alternate paths. Handler 4 and Handler 5 are common to both paths. The WebSphere MQ path contains handler 1 followed by the common handlers (handler 4 and handler 5). The HTTP path contains handler 2 and handler 3 followed by the common handlers.
In this example, which applies to a service provider:
  • Handler 1 is invoked for messages that use the MQ transport.
  • Handlers 2 and 3 are invoked for messages that use the HTTP transport.
  • Handlers 4 and 5 are invoked for all messages.
  • Handler 5 is the terminal handler.

Interrupting the flow

During processing of a request, a message handler can decide not to pass a message to the next handler, but can, instead, generate a response. Normal processing of the message is interrupted, and some handlers in the pipeline are not invoked. For example, suppose that handler 2 in Figure 3 is responsible for performing security checks.
Figure 3. Interrupting the pipeline flow
A pipeline containing three handlers: handler 1, handler 2 and handler 3. Processing of the request terminates at handler 2, which sends the response to handler 1. Handler 3 does not get invoked.
If the request does not bear the correct security credentials, then, instead of passing the request to handler 3, handler 2 suppresses the request and constructs a suitable response. The pipeline is now in the response phase, and when handler 2 returns control to CICS, the next handler invoked is handler 1, and handler 3 is bypassed altogether.

A handler that interrupts the normal message flow in this way must only do so if the originator of the message expects a response; for example, a handler should not generate a response when an application uses a one-way message flow from service requester to provider.