14.2 Types of SOAP Handlers
HydraExpress supports four categories of handlers:
transport handlers
request handlers
response handlers
fault handlers
14.2.1 Transport Handlers
The transport handlers are those closest to the actual transport, hence the name.
On the client side, they are invoked after the SOAP message is built and right before it is sent. The message is then sent to the server. In cases where there is a response from the server, the same transport handlers are invoked again, in reverse order, when the response from the server is received. Thus there is symmetry to the order in which the transport handlers are invoked.
On the server side, transport handlers are invoked right after a message is received. If there is a response, the transport handlers are invoked again just before the response is sent, again in the reverse order. So handlers are invoked symmetrically on the server as well.
The HydraExpress framework guarantees that the transport handlers are invoked both on the way in and on the way out. This is true even when message handling is interrupted, as described in Section 14.4.2.3, "Aborting Handler Processing."
At the time when transport handlers are invoked, the message processing layer has not started parsing the SOAP message. So transport handlers are most suitable for tasks that have to be performed on the entire message, such as encryption/decryption or compression/decompression. For tasks that need to access parts of the SOAP message, it is better to create a request handler.
14.2.2 Request Handlers
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.
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 and configure them in <serviceName>handlers.xml, as described later in this chapter.
14.2.3 Response Handlers
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.
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 <serviceName>handlers.xml.
The SOAP message handler can function as both a request and a response message handler because of the rwsf::CallInfo method rwsf::CallInfo::isRequest(). This method returns true for the incoming message, causing the SOAP message handler to parse the incoming message. This method returns false for the outgoing 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 <serviceName>handlers.xml.
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.
14.2.4 Fault Handlers
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 client side, after the fault handler is invoked the exception is rethrown.
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 no transport handlers, are invoked before the response is sent back to the client.
© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.