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:
- 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.
- 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
In this example, the handlers are executed in the
following sequence:- In the request phase
- Handler 1
- Handler 2
- Handler 3
- In the response phase
- Handler 3
- Handler 2
- 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 wish 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
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.