使用CXF Interceptor特性

jopen 11年前

     在Web Service中,客户端和服务端通过交换信息来互相通信。信息在客户端组装,在服务端解组。在Web Service术语中,组装表示将JAVA对象转换为XML文件,这些XML文档将被传输到网络中;反而言之,解组就是将XML文档转换为JAVA对象。

     当客户端向服务端发送请求,请求中的数据将被组装并传输到服务器。服务器获取该数据,解组,最后调用服务方法。当服务器发送响应给客户端时,将重复该过程。组装和解组是客户端和服务端提供的核心功能。CXF通过Interceptor来提供这些功能。
     Interceptor通过监听传输过来的信息来提供核心功能。这些功能包括:组装、解组、操纵消息头、执行认证检查、验证消息数据等。CXF提供内置的Interceptor来实现这些功能。用户也可以自定义Interceptor。Interceptor以phases组织起来,以链的形式调用, 

理解interceptor phase 和chain

    Phase可以被当作分类框,将类似功能的Interceptor组织起来。
    有两种Interceptor链,inbound链和outbound链。两种都有一系列的Phase。例如,在inbound链中有UNMARSHAL Phase,用来解组信息数据,并将其转化为JAVA对象。
     对于每个请求来讲,在服务端创建inbound Interceptor;对于每个响应来讲,将创建outbound Interceptor。
消息传输到链中,按特定的顺序在Phase中的Interceptor执行。
在信息传输到服务端之前,inbound Interceptor操作信息。
在信息传输到客户端之前,outbound Interceptor操作信息。
如果出现错误,Interceptor链释放自己,不去调用应用。

interceptor API概览

PhaseInterceptor继承自Interceptor接口。AbstractPhaseInterceptor实现了PhaseInterceptor。

Interceptor接口

     如果要自定义Interceptor,就必须直接或间接实现Interceptor接口。Interceptor接口定义了两个方法。handleMessage和handleFault。
package org.apache.cxf.interceptor;
public interface Interceptor<T extends Message> {
   void handleMessage(T message) throws Fault;
   void handleFault(T message);
}
    handleMessage方法需要org.apache.cxf.message.Message对象。这是执行信息的核心方法。为了自定义Interceptor就必须实习该方法,并提供执行信息的逻辑。
    handleFault方法同样需要org.apache.cxf.message.Message对象。在执行Interceptor过程中出现错误时将会调用该方法。

PhaseInterceptor接口

    大多数核心Interceptor都是实现继承自Interceptor接口的PhaseInterceptor。
PhaseInterceptor定义了4个方法。
getAfter将返回一个Set,包含了在这个Interceptor之前执行Interceptor的IDs。
getBefore将返回一个Set,包含了在这个Interceptor之后执行Interceptor的IDs。
getId返回ID
getPhase返回这个Interceptor所在的phase。
为了自定义Interceptor,开发者必须继承AbstractPhaseInterceptor抽象类。

AbstractPhaseInterceptor抽象类

   AbstractPhaseInterceptor定义了构造器,可以为自定义的Interceptor指定特定的phase。当你指定了phase,自定义的Interceptor将会安排在链中Phase。AbstractPhaseInterceptor提供了空实现的handleFault。开发者可以覆盖这个方法。开发者必须实现handleMessage方法。
   查看AbstractPhaseInterceptor抽象类,它已实现PhaseInterceptor接口的方法。Phase的顺序由PhaseInterceptorChain类决定

开发自定义的interceptor

      为了演示interceptor的功能,假定一个用例:只有经过认证的用户才能调用Web Service,用户认证需要获取SOAP头的信息。
      为了实现这些需求,创建两个interceptor,一个客户端,一个服务端。客户端interceptor负责拦截即将发出的SOAP信息,并在SOAP头中添加用户验证。服务端interceptor负责拦截收到的SOAP信息,从SOAP信息获取用户认证信息并验证该用户。如果用户验证失败,将抛出异常,在这种情况下阻止Web Service的运行。
开发自定义的interceptor分为如下几个步骤:
       开发服务端的interceptor。
       在Web Service服务类添加服务端interceptor。
       开发客户端interceptor。
       在客户端添加客户端interceptor。
       开发发布Web Service的服务器。
开发服务端interceptor  
OrderProcessUserCredentialInterceptor继承自AbstractSoapInterceptor,AbstractSoapInterceptor继承自AbstractPhaseInterceptor。AbstractSoapInterceptor提供了获取SOAP头和版本的信息。
OrderProcessUserCredentialInterceptor默认构造函数中,指定了Phase.PRE_INVOKE,代表着该interceptor将先于Web Service服务类执行。
 
public OrderProcessUserCredentialInterceptor() {          super(Phase.PRE_INVOKE);      }
handleMessage方法中,SoapMessage提供了获取SOAP头的信息。使用message.getHeader获取SOAP头中<OrderCredentials>元素
Header header = message.getHeader(qnameCredentials);
 
<soap:Header>        <OrderCredentials>           <username>John</username>           <password>password</password>        </OrderCredentials>  </soap:Header>
在OrderCredentials节点下,可以获得用户名和密码节点。
Element elementOrderCredential = (Element) header.getObject();  Node nodeUser = elementOrderCredential.getFirstChild();  Node nodePassword = elementOrderCredential.getLastChild();   
package demo.order.server;        import javax.xml.namespace.QName;        import org.apache.cxf.binding.soap.SoapMessage;    import org.apache.cxf.binding.soap.interceptor.AbstractSoapInterceptor;    import org.apache.cxf.headers.Header;    import org.apache.cxf.interceptor.Fault;    import org.apache.cxf.phase.Phase;    import org.w3c.dom.Element;    import org.w3c.dom.Node;        public class OrderProcessUserCredentialInterceptor extends AbstractSoapInterceptor {            private String userName;        private String password;            public OrderProcessUserCredentialInterceptor() {            super(Phase.PRE_INVOKE);        }            public void handleMessage(SoapMessage message) throws Fault {                System.out.println("OrderProcessUserCredentialInterceptor handleMessage invoked");            QName qnameCredentials = new QName("OrderCredentials");                // Get header based on QNAME            if (message.hasHeader(qnameCredentials)) {                Header header = message.getHeader(qnameCredentials);                    Element elementOrderCredential = (Element) header.getObject();                Node nodeUser = elementOrderCredential.getFirstChild();                Node nodePassword = elementOrderCredential.getLastChild();                    if (nodeUser != null) {                    userName = nodeUser.getTextContent();                }                if (nodePassword != null) {                    password = nodePassword.getTextContent();                }            }                System.out.println("userName reterived from SOAP Header is " + userName);            System.out.println("password reterived from SOAP Header is " + password);                // Perform dummy validation for John            if ("John".equalsIgnoreCase(userName) && "password".equalsIgnoreCase(password)) {                System.out.println("Authentication successful for John");            } else {                throw new RuntimeException("Invalid user or password");            }        }            public String getUserName() {            return userName;        }            public void setUserName(String userName) {            this.userName = userName;        }            public String getPassword() {            return password;        }            public void setPassword(String password) {            this.password = password;        }    }  

Web Service业务类添加interceptor

Web Service业务类可以添加配置文件或者定义annotations添加interceptor。
添加InInterceptors注释定义了一个Inbound interceptor,将在Web Service执行之前调用。  
@org.apache.cxf.interceptor.InInterceptors (interceptors ={"demo. order.server.OrderProcessUserCredentialInterceptor" })
package demo.order;        import javax.jws.WebService;        @org.apache.cxf.interceptor.InInterceptors(interceptors = {"demo.order.server.OrderProcessUserCredentialInterceptor"})    @WebService    public class OrderProcessImpl implements OrderProcess {            public String processOrder(Order order) {            System.out.println("Processing order...");            String orderID = validate(order);            return orderID;        }            /**        * Validates the order and returns the order ID       *        */        private String validate(Order order) {            String custID = order.getCustomerID();            String itemID = order.getItemID();            int qty = order.getQty();            double price = order.getPrice();                if (custID != null && itemID != null && qty > 0 && price > 0.0) {                return "ORD1234";            }                return null;        }    }  

开发客户端interceptor

同样的OrderProcessClientHandler继承自AbstractSoapInterceptor。
OrderProcessClientHandler默认构造器,指定了super(Phase.WRITE),还addAfter方法。addAfter指定了OrderProcessClientHandler将在CXF内置SoapPreProtocolOutInterceptor之后添加。OrderProcessClientHandler将在Phase.WRITE并在SoapPreProtocolOutInterceptor之后运行。SoapPreProtocolOutInterceptor负责建立SOAP版本和头,因此任何SOAP头元素的操作都必须在SoapPreProtocolOutInterceptor之后执行。
public OrderProcessClientHandler() {        super(Phase.WRITE);        addAfter(SoapPreProtocolOutInterceptor.class.getName());  }
构造函数new Header(qnameCredentials, elementCredentials);创建了Header对象,并设置了OrderCredentials元素。最后message.getHeaders().add(header)将SOAP头添加到信息中。
package demo.order.client;        import javax.xml.namespace.QName;    import javax.xml.parsers.DocumentBuilder;    import javax.xml.parsers.DocumentBuilderFactory;    import javax.xml.parsers.ParserConfigurationException;        import org.apache.cxf.binding.soap.SoapMessage;    import org.apache.cxf.binding.soap.interceptor.AbstractSoapInterceptor;    import org.apache.cxf.binding.soap.interceptor.SoapPreProtocolOutInterceptor;    import org.apache.cxf.headers.Header;    import org.apache.cxf.interceptor.Fault;    import org.apache.cxf.phase.Phase;    import org.w3c.dom.Document;    import org.w3c.dom.Element;        public class OrderProcessClientHandler extends AbstractSoapInterceptor {            public String userName;        public String password;            public OrderProcessClientHandler() {            super(Phase.WRITE);            addAfter(SoapPreProtocolOutInterceptor.class.getName());        }            public void handleMessage(SoapMessage message) throws Fault {                System.out.println("OrderProcessClientHandler handleMessage invoked");                DocumentBuilder builder = null;            try {                builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();            } catch (ParserConfigurationException e) {                e.printStackTrace();            }            Document doc = builder.newDocument();            Element elementCredentials = doc.createElement("OrderCredentials");            Element elementUser = doc.createElement("username");            elementUser.setTextContent(getUserName());            Element elementPassword = doc.createElement("password");            elementPassword.setTextContent(getPassword());            elementCredentials.appendChild(elementUser);            elementCredentials.appendChild(elementPassword);                // Create Header object            QName qnameCredentials = new QName("OrderCredentials");            Header header = new Header(qnameCredentials, elementCredentials);            message.getHeaders().add(header);        }            public String getPassword() {            return password;        }            public void setPassword(String password) {            this.password = password;        }            public String getUserName() {            return userName;        }            public void setUserName(String userName) {            this.userName = userName;        }    }  

客户端添加interceptor

OrderProcessClientHandler设置了username和password。通过ClientProxy.getClient(client);获取Client对象,并通过cxfClient.getOutInterceptors().add(clientInterceptor)将clientInterceptor作为outbound interceptor。
package demo.order.client;        import demo.order.OrderProcess;    import demo.order.Order;        import org.apache.cxf.frontend.ClientProxy;    import org.apache.cxf.transport.http.gzip.GZIPInInterceptor;    import org.apache.cxf.transport.http.gzip.GZIPOutInterceptor;    import org.springframework.context.support.ClassPathXmlApplicationContext;        public final class Client {            public Client() {        }            public static void main(String args[]) throws Exception {            ClassPathXmlApplicationContext context = new ClassPathXmlApplicationContext(new String[]{"client-beans.xml"});                OrderProcess client = (OrderProcess) context.getBean("orderClient");    //        OrderProcess client = (OrderProcess) context.getBean("orderClient2");            OrderProcessClientHandler clientInterceptor = new OrderProcessClientHandler();            clientInterceptor.setUserName("John");            clientInterceptor.setPassword("password");            org.apache.cxf.endpoint.Client cxfClient = ClientProxy.getClient(client);            cxfClient.getOutInterceptors().add(clientInterceptor);                Order order = new Order();            order.setCustomerID("C001");            order.setItemID("I001");            order.setQty(100);            order.setPrice(200.00);                String orderID = client.processOrder(order);            String message = (orderID == null) ? "Order not approved" : "Order approved; order ID is " + orderID;            System.out.println(message);        }    }  

开发发布Web Service的服务器

package demo.order;        import org.apache.cxf.feature.LoggingFeature;    import org.apache.cxf.interceptor.LoggingInInterceptor;    import org.apache.cxf.interceptor.LoggingOutInterceptor;    import org.apache.cxf.jaxws.JaxWsServerFactoryBean;    import org.apache.cxf.transport.http.gzip.GZIPFeature;    import org.apache.cxf.transport.http.gzip.GZIPInInterceptor;    import org.apache.cxf.transport.http.gzip.GZIPOutInterceptor;        public class OrderProcessServerStart {            public static void main(String[] args) throws Exception {                OrderProcess orderProcess = new OrderProcessImpl();            LoggingFeature log = new LoggingFeature();            GZIPFeature gzip = new GZIPFeature();            gzip.setThreshold(1);            JaxWsServerFactoryBean server = new JaxWsServerFactoryBean();            server.setServiceBean(orderProcess);            server.setAddress("http://localhost:8080/OrderProcess");                server.getFeatures().add(log);            server.getFeatures().add(gzip);            //server.getFeatures().add(log);            //server.getInInterceptors().add(new LoggingInInterceptor());            //server.getOutInterceptors().add(new LoggingOutInterceptor());                    server.create();            System.out.println("Server ready....");                        Thread.sleep(5 * 60 * 1000);            System.out.println("Server exiting");            System.exit(0);        }    }  
 

理解CXF features

Feature其实是interceptors另外一种形式。可以使用feature组件来代替直接使用interceptor。
本例中添加了log和gzip两个feature,正如Interceptor中所描述的phase的概念,添加log和gzip的顺序会影响LoggingFeature显示的内容。
请读者自行尝试OrderProcessServerStart中
        server.getFeatures().add(log);
        server.getFeatures().add(gzip);
        //server.getFeatures().add(log);
和client-beans.xml中
 
   <bean class="org.apache.cxf.feature.LoggingFeature"></bean>     <bean class="org.apache.cxf.transport.http.gzip.GZIPFeature" >       <property name="threshold" value="1" /></bean>     <!--bean class="org.apache.cxf.feature.LoggingFeature"></bean-->
         
安排log和gzip的添加次序。

LoggingFeature

LoggingFeature可以独立于服务端和客户端。也就是说,可以服务端添加LoggingFeature,而客户端不添加,反之亦然。

GZIPFeature

GZIPFeature不同于LoggingFeature,客户端和服务端必须同时实现GZIPFeature,不然会抛出异常javax.xml.ws.soap.SOAPFaultException: Couldn't parse stream.。
查看添加GZIPFeature的服务器需要借助于工具。Tcpmon是其中的一个选择,另外LoggingFeature提供了tcpmon类似的功能。
在client-beans.xml中<http-conf:client>元素指定了AcceptEncoding属性,这个属性暗示客户端应用将会接受gzip的内容。

tcpmon

如何用Apache TCPMon来截获SOAP消息
http://www.blogjava.net/heyang/archive/2010/12/10/340294.html
下载地址http://ws.apache.org/commons/tcpmon/download.cgi
 
server.setAddress("http://localhost:8080/OrderProcess");
在执行CXF过程中,是无法查看到组装和解组的内容。如果希望看到内容,则需要借助工具。外部工具如tcpmon。将client-beans.xml address中的端口修改你希望的端口,如8081。然后在OrderProcessServerStart查看发布的端口 为8080。在tcpmon解压的目录bin中执行tcpmon.bat,出现tcpmon界面。切换到Admin。在Listen Port #处填写8081,在Target Port #填写8080,点击Add。然后切换到Sender。为了方便查看XML,在左下角有个XML Format,将其勾选上,tcpmon会将捕获的内容整理为XML格式。执行Client,便可以再Sender界面查看到XML的具体内容了。

threshold

忽略1 byte并压缩剩下的内容。Threshold若为0值表示全部内容都将压缩。如果Threshold未提供任何值,那么默认将执行全部内容压缩。

来自:http://reymont.iteye.com/blog/1532463