Various adjustments can be made to affect the message sent in the Web service. Two mechanisms exist for making such adjustments: handlers and interceptors.
Messages in SOAP are divided into a body and any number of optional headers. The latter contain application-specific meta-data (such as security-related data).
Handlers provide mechanisms used to get, insert and/or remove headers from a SOAP message. However, handlers have access to the whole SOAP message, including the SOAP body, so that handlers can be used, for example, to encrypt and decrypt data in the body of a SOAP message.
To make WSO2 SOA Enablement Server aware of a handler (for details on handlers see SOAP Message Handlers), the Handlers interface is used. This interface is accessible from both ServiceEndpoint and ServiceClient.
Handlers are organized into chains. Every handler in a chain gets access to the SOAP message that represents either a Web service request or a response. A handler can by used by both a Web service and the client applications that invoke the Web service.
For more details, see the Javadoc for the org.systinet.wasp.webservice.Handlers interface.
Handlers are added to a chain with one of the getHandlers().insert(...) methods. These methods differ according to their parameters. All of them include either an instance of Handler or handler info.
int insert(Handler handler);
int insert(Handler handler, int position) throws IndexOutOfBoundsException;
int insert(Handler handler, QName[] understands);
int insert(Handler handler, QName[] understands, int position) throws IndexOutOfBoundsException;
int insert(WASPHandlerInfo handlerInfo);
int insert(WASPHandlerInfo handlerInfo, int position) throws IndexOutOfBoundsException;
Method 1 inserts a given handler instance at the end of the handler chain being processed.
Method 2 is identical to Method 1 but includes the position of the new handler among the handlers already in the chain.
In additional to the parameters of methods 1 and 2, methods 3 and 4 include the array of header QNames that this handler understands.
In methods 5 and 6 there is an instance of WASPHandlerInfo, an extension of JAX-RPC HandlerInfo, instead of a handler instance. It provides a richer API for defining how a handler understands headers and contains methods dealing with custom configuration created by the WSO2 SOA Enablement Server Configuration framework.
Remove a single instance of a given handler from a chain with the void remove(int position); method.
Remove all instances of a given handler from a chain with the boolean remove(WaspHandlerInfo handlerInfo); method.
WaspHandlerInfo get(int position);
Returns the instance of the WaspHandlerInfo at the specified position in the chain.
int size();
Returns the number of handlers in the chain.
Example 54 shows how to insert a handler to the client-side processing.
Example 54. Inserting a Handler to the Client-Side
// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.basics.publishing.runtime;
import example.basics.invocation.HelloService;
import org.systinet.wasp.webservice.ServiceClient;
import javax.xml.namespace.QName;
import javax.xml.rpc.handler.Handler;
import javax.xml.rpc.handler.HandlerInfo;
import javax.xml.rpc.handler.MessageContext;
import javax.xml.rpc.handler.soap.SOAPMessageContext;
import javax.xml.rpc.soap.SOAPFaultException;
import javax.xml.soap.SOAPMessage;
public class ClientWithHandlers {
public static void main(String[] args) throws Exception {
String wsdlURL = "http://localhost:6060/HelloWorld/wsdl";
// creates service client
ServiceClient serviceClient = ServiceClient.create(wsdlURL);
// inserts handler
serviceClient.getHandlers()
.insert(new MyHandler());
// create proxy
HelloService helloService =
(HelloService) serviceClient.createProxy(HelloService.class);
// presumably some invocations of helloService follow
helloService.hello("world");
}
// this is the header processor registered in this example
public static class MyHandler implements Handler {
public boolean handleRequest(MessageContext context)
throws SOAPFaultException {
SOAPMessage message = ((SOAPMessageContext) context).getMessage();
// do something
return true;
}
public boolean handleResponse(MessageContext context) {
SOAPMessage message = ((SOAPMessageContext) context).getMessage();
// do something
return true;
}
public boolean handleFault(MessageContext context) {
return true;
}
public void init(HandlerInfo config) {
}
public void destroy() {
}
public QName[] getHeaders() {
return new QName[0];
}
}
}
Interceptors accept transport messages as their input, modify them and return new transport messages as output. They are at the lowest level of message processing. This level has no notion about XML or higher level protocols, so it is able to do things like converting non-XML protocols into XML protocols and vice versa. For instance, you can use interceptors for dumping messages into the console, performing authentication, transforming the incoming message via XSLT, etc.
To make WSO2 SOA Enablement Server aware of an interceptor (for details on interceptors see Interceptors), the Interceptors interface is used. This interface is accessible from both ServiceEndpoint and ServiceClient.
To use an interceptor, it may be added to a service endpoint or service client. It can be active in one or both of the directions IN and OUT. As with header processors, this direction is relative to the point of view of the service endpoint or service client.
See also the Javadoc for org.systinet.wasp.webservice.Interceptors.
Transport interceptors are added to a chain with one of two getInterceptors().insert(...) methods. Both of them include the instance of the interceptor and its direction. The second method includes the name of the interceptor and its position within the chain.
void insert(Interceptor instance, int direction);
void insert(int position, Interceptor instance, int direction) throws IndexOutOfBoundsException;
Remove a single instance of a given interceptor from a chain with the void remove(int position); method.
Remove all instances of a given interceptor from a chain with the boolean remove(Interceptor instance); method.
Interceptor get(int position)
Returns the instance of the interceptor at the specified position within the chain.
int getDirection(int position)
Returns the communication direction of the interceptor at the specified position.
void setDirection(int position, int direction)
Changes the communication direction of the interceptor at the specified position and with the specified direction.
int size();
Returns the number of transport interceptors in the chain.
Example 55 shows how to insert a transport interceptor to a service client processing.
Example 55. Transport Interceptor Configuration
// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.basics.publishing.runtime;
import example.basics.invocation.HelloService;
import org.idoox.config.Configurable;
import org.idoox.transport.Connection;
import org.idoox.wasp.interceptor.InterceptorChain;
import org.systinet.wasp.webservice.Interceptors;
import org.systinet.wasp.webservice.ServiceClient;
public class ClientWithInterceptor {
public static void main(String[] args) throws Exception {
String wsdlURL = "http://localhost:6060/HelloWorld/wsdl";
ServiceClient serviceClient = ServiceClient.create(wsdlURL);
HelloService helloService =
(HelloService) serviceClient.createProxy(HelloService.class);
serviceClient.getInterceptors()
.insert(
new Interceptor(),
Interceptors.DIRECTION_INOUT);
// presumably some invocations of helloService follow
helloService.hello("world");
}
// this is the transport interceptor registered in this example
public static class Interceptor
implements org.idoox.wasp.interceptor.TransportInterceptor {
public void load(Configurable c) {
}
public void destroy() {
}
public void intercept(
Connection connection,
InterceptorChain chain,
int position) {
// do something with the connection
}
}
}