The Message Handler API

HydraExpress provides an API for creating your own handlers. The classes in this API are implemented in the Web Services Library and are described in the HydraExpress C++ API Reference Guide. Table 9 describes the classes that are the most important for creating custom message handlers.

Table 9 – The Message Handler Classes for Creating Custom Handlers
Class Name	Description
rwsf::CallInfo	This class acts as a container for all of the data associated with a particular service request. It holds the request and response SOAP messages, and provides access methods for metadata such as SOAP headers, transport headers, and session information.
rwsf::MessageProperties	This is the base class for rwsf::CallInfo. This class is important because rwsf::CallInfo inherits a number of important methods from it, such as the isRequest() and isClient() methods described above.
rwsf::MessageHandlerImp	This class provides the interface for processing messages. This is the class your custom message handlers should derive from. As implied by the Imp at the end of the class name, message handlers conform to the handle/body design pattern.

Figure 9 shows the relationship between message handlers and the generated classes. Note that all of Web service-related classes generated by HydraExpress are essentially message handlers. The handler that appear by default in <servicecontextname>_handlers.xml, MyServiceSkeleton, derives (through intermediaries) from rwsf::MessageHandlerImp, as will your custom message handlers.

Figure 9 – Message Handler Generated Classes Architecture

The file <servicecontextname>_handlers.xml is generated and initially contains a service-endpoint that points to the service implementation. “Chaining Handlers” discusses using this file to configure and chain handlers. The file client-handlers.xml is also generated. In the request-response and one-way message patterns, only the logger handler is initially present. For the notification and solicit-response message patterns, the client-handlers.xml file is used to configure the handlers for incoming requests and outgoing responses instead of the <servicecontextname>_handlers.xml file. For information on the notification pattern, see Chapter 9 . For information on the solicit-response pattern, see “The Solicit-Response Pattern.”

To create your own handler, just derive directly from rwsf::MessageHandlerImp and add information identifying your handler classes to <servicecontextname>_handlers.xml. For more information, see “Creating Your Own Handlers.”