14.5 Chaining Handlers
Once a handler is created, it can be used on both the client and the server. To create and chain handlers on the client side, use the client API classes. To configure handlers and chain them on the server side, use the <servicecontextname>_handlers.xml file. These processes are discussed in more detail in this section.
14.5.1 Chaining Handlers on the Client
To chain handlers on the client, simply add them to the <serviceName>Client.cpp file, for example:
MyProxy proxy = MyProxy::make(location); proxy.addTransportHandler(new StringReverseHandler); proxy.addRequestHandler(new AuthenticationHandler); |
The order in which client-side handlers are processed is important when choosing the types of handlers to use. Please see Section 14.4.3, "Add the Handlers to the Proxy."
14.5.2 Chaining Handlers on the Server
To chain handlers on the server, add them to the handlers configuration file, <servicecontextname>_handlers.xml.
14.5.2.1 The handlers.xml Configuration File
The handlers configuration file specifies several parts of the service, including the name of service and the various chains. You may add additional handlers at any point in the flow without changing the generated code, or having to regenerate code.
A sample handlers configuration file is generated for each service and contains one required element, the service, which defines the handler chains. Multiple chains can be configured, and each chain is processed in the order in which it appears.
Here is an example of the <servicecontextname>_handlers.xml file.
<configuration>
<service name="FaultService"> <!-- 1 -->
<request-handlers> <!-- 2 -->
<handler name="http://localhost:8080/fault/FaultSkeleton">
<property name="SomeParameter" value="Some value"/>
</handler>
</request-handlers>
<transport-handlers/> <!-- 3 -->
<service-endpoint name="http://localhost:8080/fault/Fault"/> <!-- 4 -->
<response-handlers/> <!-- 5 -->
<fault-handlers/> <!-- 6 -->
</service>
</configuration>
|
| //1 | The service element contains all the chains for this service. Its name attribute defines the service's name. Note that this name is an initialization parameter in web.xml so when the servlet has a message to dispatch, it knows to send it to this FaultService for processing. |
| //2 | The request-handlers perform any special processing to the request as it arrives, and then pass the request to the skeleton. To add special request-handlers, insert them before the skeleton, which is the only required request-handler. Extra configuration information can be passed to the handlers by using the property elements. Each handler can have a set of property elements that are automatically passed to the handler when the handler is constructed. These properties are defined in servicecontextname_handlers.xml. |
| //3 | The transport-handlers element contains any special handlers on the transport, such as encryption or compression handlers. |
| //4 | The service-endpoint element points to the service implementation. |
| //5 | The response-handlers element would include any special handlers for sending the response back to the client. In this case, the element is empty, so this chain is ignored. |
| //6 | The fault-handlers element includes specific fault handlers. |
14.5.2.2 Editing the handlers.xml File
In the example above, the configuration file handlers_handlers.xml is code generated. If a file named handlers_handlers.xml already exists, the generator appends sample to the name of the generated file so as not to overwrite changes to a previously-generated sample handlers configuration file.
If you create a new handlers configuration file, or change its name, you must also change its name in the handlers_web.xml service descriptor file. For more information on the web.xml deployment descriptor, see Section 23.4, "About the Servlet Used by the Service."
At deployment, your handlers configuration file is copied to your servlet context directory as <installdir>\apps\servlets\<context>\handlers.xml (note the file name change to remove the context name) where it is overwritten each time the service is deployed, so be careful when making changes to it. It is recommended that you edit the <servicecontextname>_handlers.xml in your project and re-run the deploy target if changes to the configuration are required. The servlet context directory derives its name from the SOAP address in the WSDL. For instance, for
<soap:address location="http://localhost:8090/handlers/Handlers"/> |
the context directory is handlers, and the servlet is Handlers. For this URL, <servicecontextname>_handlers.xml would be copied to:
RWSF_HOME
\apps\servlets
\handlers
\handlers.xml
|
Copyright © Rogue Wave Software, Inc. All Rights Reserved.
The Rogue Wave name and logo are registered trademarks of Rogue Wave Software, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.