Types of SOAP Handlers

It is important to understand how each type of handler is processed in the Agent in order to select the best handler for your needs. Figure 8 illustrates how handlers are invoked in a client application and in the Agent. How each handler is affected by this invocation is discussed in the following sections.

NOTE >> This diagram is based on a request-response message pattern. For a one-way request, the client sends the request but the Agent does not send a return message, so the response handlers are not invoked; conversely, for a notification pattern, the request originates in the Agent and the client does not send back a response. For solicit-response, the Agent sends the request, and the client does respond, so the order is simply reversed.

The transport handlers are those closest to the actual transport, hence the name.

On the client side, during a remote function invocation, they are the last handlers run before the request is sent. If there is a response from the server, the same transport handlers are invoked in reverse order, to process and transform the response message.

On the server side, transport handlers are the first handlers invoked after an incoming request is received. If a response is needed, the transport handlers are invoked in reverse order before the response message is sent back to the calling client

The HydraExpress framework guarantees that the transport handlers are invoked on both incoming and outgoing messages (whether the message is a request or response). This is true even when message handling is interrupted, as described in “Aborting Handler Processing.”

Since the SOAP message is treated as a simple string payload when a transport handler is run, transport handlers are most suitable for tasks that have to be performed on the entire message. This includes tasks such as encryption/decryption, compression/decompression, etc. For tasks that need to access specific parts of a SOAP message, it is better to create a request or a response handler.

On the server, request handlers are invoked on incoming requests immediately after all of the transport handlers have been invoked; on the client, they are invoked immediately before the transport handlers are invoked. See Figure 8.

On the server, the first request handler to get invoked is always the SOAP message handler generated by HydraExpress. This handler parses the SOAP message and makes parts of the message available through methods of the rwsf::CallInfo object associated with the request. You can create additional handlers, as described later in this chapter.

On the server, response handlers are invoked on outgoing responses immediately before the transport handlers are invoked; on the client, they are invoked immediately after the transport handlers have been invoked. See Figure 8.

On the server, the SOAP message handler generated by HydraExpress is always invoked on the outgoing message as the last response handler before the transport handlers. This is true even though it does not appear in the <response-handlers> element of the handlers configuration file, <servicecontextname>_handlers.xml (used to configure server-side handlers and discussed in “Chaining Handlers on the Server”).

A single SOAP message handler can function either as a request message handler, a response message handler, or both. The rwsf::CallInfo interface provides methods for determining whether the message is a request or response.

The rwsf::CallInfo::isRequest() method returns true for a request message, causing the SOAP message handler to parse the message as an incoming request. This method returns false for a response message, causing the SOAP message handler to construct the SOAP response message. You, too, can use this method to create a handler that serves as both a request and a response handler, but note that such custom handlers must be configured in both the <request-handlers> and <response-handlers> elements of <servicecontextname>_handlers.xml, discussed in “Chaining Handlers on the Server”.

In fact, rwsf::CallInfo also has an isClient() method that returns true on the client side and false on the server side. With this method, a single handler could be used for both request and response handling on both the client and the server.

Fault handlers are invoked in cases where an exception is thrown during message processing. They can be used to provide custom message handling in such cases. The exception message is stored in the rwsf::CallInfo object as a string property named rwsf:FaultMessage, and can be accessed by invoking getStringProperty("rwsf:FaultMessage") on the rwsf::CallInfo object.

Fault handlers behave differently on the client and server sides.

• On the server side, before the fault handler is invoked the response is set to a rwsf::ServerFault, which contains the exception message. Then the fault handler is invoked, giving you the option of changing the response as needed. After the fault handler completes processing, no other handlers, including transport handlers, are invoked before the response is sent back to the client.