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 <serviceName>handlers.xml file. These processes are discussed in more detail in this section.
To chain handlers on the client, simply add them to the client proxy, for example:
MyProxy proxy = MyProxy::make(location); proxy.addTransportHandler(new StringReverseHandler); proxy.addRequestHandler(new AuthenticationHandler);
For more information, see Section 14.4.3, "Add the Handlers to the Proxy."
The order in which handlers are processed on the client side is illustrated in the following figure.
Note that:
Transport handlers are applied symmetrically, with the first handler added being closest to the transport, the second in second position, and so on, in both directions.
Request and response handlers are applied in the order added.
To chain handlers on the server, add them to the handlers configuration file, <serviceName>handlers.xml.
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 <serviceName>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 </transport-handlers> <service-endpoint name="http://localhost:8080/fault/Fault"/> 4 <response-handlers> 5 </response-handlers> <fault-handlers> 6 </fault-handlers> </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. |
//3 | The transport-handlers element contains any special handlers on the transport, such as encryption or compression information. |
//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. |
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, "Configuring the Servlet Used by the Service."
At deployment, your handlers configuration file is copied to your servlet context directory under <installdir>\apps\servlets\<context> where it is overwritten each time the service is deployed, so be careful when making changes to it. 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, <serviceName>handlers.xml would be located at:
RWSF_HOME \apps\servlets \handlers \<serviceName>handlers.xml
The order in which handlers are processed on the server side is illustrated in the following figure.
The server follows basically the same flow as the client, except reversed. The order in which handlers are applied is based on their order in the configuration file. Transport handlers are applied symmetrically at input and output, with the first configured handler being closest to the transport, the second configured handler being second from the transport, and so on. Request and response handlers are applied in configured order in both directions.
© 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.