CXFgh1.doc

1.Apache CXF 简介Apache CXF提供了一套创建SOA服务的基础设施框架，用户由此可以按照自己喜欢的编程模式，利用Apache CXF提供的简单易用工具（包括Maven插件），创建适合SOA环境的任何WEB服务，包括SOAP/HTTP服务及REST/HTTP服务。Apache CXF可扩展的插拔式架构不但支持XML消息格式和HTTP通信协议，而且还支持基于其他通信协议如IIOP和非XML消息格式如CORBA CDL或JSON。CXF 大大简化了Services 的创建，CXF 继承了Celtix和XFire两大开源项目的精华，一样可以天然地和 Spring 进行无缝集成，提供了对JAX-WS 全面的支持，实现了JCP及Web服务的主要技术标准，大大方便了用户使用不同编程模式进行SOA服务开发，并为企业遗留系统的集成提供了可扩展性。1）Apache CXF支持的主要技术标准及功能包括： 多种技术标准。Apache CXF完全实现了多个JSR标准，包括JAX-WS 2.0(JSR-224) 、Java Web服务元数据（JSR-181）、和SAAJ （JSR-67）。Apache CXF 2.0发布还通过了JAX-WS 2.0 TCK，成为开源社区继JAX-WS RI之后的第一个通过JAX-WS TCK的SOAP堆栈。Apache CXF还实现了多个Web服务标准，为用户实现企业级的Web服务提供了广泛的支持，这些 Web服务标准包括SOAP 1.1、SOAP1.2、MTOM/XOP 、WSDL 1.0、WS-Addressing、WS-ReliableMessaging 、WS-Policy,WS-Security及WS-I Basic Profile等多种编程模式。为方便用户按照自己喜欢的方式创建web服务，Apache CXF提供了多种web服务开发模式。除了完全支持JAX-WS 各种编程模式如client/server、同步、异步 、单程及动态调用接口，Apache CXF还支持JavaScript及ECMAScript 4 XML(E4X) 编程。Spring用户可以很容易地按照 Spring编程方式快速创建并部署web服务。传统的Java开发人员则可以通过注释（Annotation）方便地进行web服务开发，喜欢POJOs 的Java开发人员更可直接配置并部署基于POJOs的web服务。更值得一提的是，通过Apache Yoko，用户不需要任何CORBA编程知识就可以轻松地把现有CORBA 应用转化为web服务，或开发客户端与现有CORBA应用直接交互。 多种通信协议及消息格式。Apache CXF支持多种通信传输协议，包括HTTP/HTTPS、JMS、 Servlet及同一JVM内通信，并提供了SOAP或纯XML通信消息格式(payload) 支持。同时，Apache CXF具有创新意义的REST/HTTP支持也大大方便了用户创建真正符合REST风格的web服务。对于那些需要重用IT遗留系统的用户来说，Apache CXF可扩展的插拔式架构允许定制开发并混合使用任何类型的通信协议及通信消息格式。支持多种容器部署。基于Apache CXF的web服务可以单独运行，也可部署在多种容器里，包括轻量级容器如Tomcat及Spring ，JEE容器如Geronimo, JBOSS, WebLogic等。同时，Apache CXF web服务还可以服务引擎方式部署于JBI容器如ServiceMix或OpenESB 。SCA容器如Apache Tuscany的支持也在计划之中。 多种传输方式、Bindings、Data Bindings 和 Format Bindings：SOAP、REST/HTTP；Data Bndings：目前支持 JAXB 2.0、Aegis两种，默认是JAXB 2.0。XMLBeans、Castor 和JiBX 数据绑定方式将在CXF 2.1 版本中得到支持；格式（Format）：XML、JSON；传输方式：HTTP、Servlet、JMS 和 Jabber；可扩展的API允许为CXF增加其它的Bindings，以能够支持其它的消息格式，比如：CSV和固定记录长度。灵活部署轻量级容器：可在Tomcat或基于Spring的容器中部署Services；集成JBI：可以在如ServiceMix, OpenESB or Petals 等等的 JBI 容器中将它部署为一个服务引擎；集成 SCA：可以部署在如 Tuscany 之类的 SCA 容器中；集成 J2EE：可以在 J2EE 应用服务器中部署Services，比如：Geronimo、JOnAS、JBoss、WebSphere Application Server 和 WebLogic Application Server，以及 Jetty 和 Tomcat；独立的 Java 客户端服务器。支持多种编程语言全面支持 JAX-WS 2.0客户端服务器编程模型；支持 JAX-WS 2.0 synchronous、asynchronous 和 one-way APIs；支持 JAX-WS 2.0 Dynamic Invocation Interface (DII) API；支持 wrapped and non-wrapped 风格；支持 XML messaging API；支持 JavaScript 和 ECMAScript 4 XML (E4X) ，客户端与服务端均支持；通过 Yoko 支持 CORBA；通过 Tuscany 支持 SCA；通过 ServiceMix 支持 JBI ；代码生成Java to WSDL；WSDL to Java；XSD to WSDL；WSDL to XML；WSDL to SOAP；WSDL to Service；CXF 框架支撑环境CXF 框架是一种基于 Servlet 技术的 SOA 应用开发框架，要正常运行基于 CXF 应用框架开发的企业应用，除了 CXF 框架本身之外，还需要 JDK 和 Servlet 容器的支持。2)基础架构 CXF旨在为服务创建必要的基础设施，它的整体架构主要由以下几个部分组成： （1）.Bus 它是CXF架构的主干，为共享资源提供了一个可配置的场所，作用非常类似于Spring的ApplicationContext。这些共享资源包括WSDL管理器、绑定工厂等。通过对Bus进行扩展，可以方便地容纳自己的资源，或替换现有的资源。默认Bus实现是基于Spring的，通过依赖注入，将运行时组件串起来。Bus的创建由BusFactory负责，默认是 SpringBusFactory，对应于默认Bus实现。在构造过程中，SpringBusFactory会搜索META-INF/cxf（就包含在CXF的Jar中）下的所有Bean配置文件，根据它们构建一个ApplicationContext。开发者也可提供自己的配置文件来定制Bus。 2.消息传递和拦截器（Interceptor） CXF建立于一个通用的消息层之上，主要由消息、拦截器和拦截器链（InterceptorChain）组成。CXF是以消息处理为中心的，熟悉 JSP/Servlet的开发者可以将拦截器视为CXF架构中的“Filter”，拦截器链也与“FilterChain”类似。通过拦截器，开发者可以方便地在消息传递、处理的整个过程中对CXF进行扩展。拦截器的方法主要有两个：handleMessage和handleFault，分别对应消息处理和错误处理。每个方法把消息对象类型作为一个参数。handleFault方法实现处理错误环境。拦截器通常以链的方式处理，链上的每个拦截器在消息序列里执行一些处理，这个链向前移。当一个错误条件出现时，handleFault方法在每个拦截器上调用，并且这个链没有展开或者向后退。拦截器经常成组形成状态。拦截器提供了公共的函数能组成一个状态，每个状态执行特定的消息处理。每个状态于是加入拦截器。这个链可以创建成inbound and outbound消息。一个典型的WEB服务端点有三个拦截器链 Inbound messages chain Outbound messages chain Error messages chain拦截器里还有内置的拦截器，如日志，安全等，开发者也可选择创建自定义拦截器。3.前端（Front End） 它为CXF提供了创建服务的编程模型，当前主要的前端就是JAX-WS。 4.服务模型 CXF中的服务通过服务模型来表示。它主要有两部分：ServiceInfo和服务本身。ServiceInfo作用类似WSDL，包含接口信息、绑定、端点（EndPoint）等信息；服务则包含了ServiceInfo、数据绑定、拦截器和服务属性等信息。可使用Java类和WSDL来创建服务。一般是由前端负责服务的创建，它通过ServiceFactory来完成。 5.绑定（Binding） 绑定提供了在传输之上映射具体格式和协议的方法，主要的两个类是Binding和BindingFactory。BindingFactory负责创建Binding。 6.传输（Transport） 为了向绑定和前端屏蔽传输细节，CXF提供了自己的传输抽象。其中主要有两个对象：Conduit和Destination。前者是消息发送的基础，后者则对应消息接收。开发者还可以给Conduit和Destination注册MessageObserver，以便在消息发送和接收时获得通知。 Adding exception handling to RESTful serviceLets take a scenario where a client sends a request to delete or update a category, and the category does not exist, so your implementation needs to return the correct error message back to the client. To deal with exceptions, JAX-RS provides the WebApplicationException, which extends the Java RuntimeException class. The WebApplicationException can take an HTTP status code or javax.ws.rs.core.Response object as part of the constructor. The Response object can be used to set the entity information providing a user readable error message along with the HTTP status code.Typically, exception handling for RESTful service would fall into one of the following categories: The implementation class can throw an unchecked WebApplicationException with the required HTTP Error code. The HTTP specification defines which HTTP response code should be used for unsuccessful requests, which can be interpreted by clients in a standard way. For example, Status code 4xx defines client error, such as Bad request, and 5xx defines the server request where server failed to fulfill a valid request. The implementation class can create a javax.ws.rs.core.Response object and send a custom error message to the client or send the required HTTP status code in the response. The implementation class can throw a checked exception, and you can wire an Exception Resolver implementation to convert the application exception to the Response object. The ExceptionResolver interface provides a contract for a provider that maps Java exception to a Response. For instance, if you are fetching information from the database, and a record does not exist, and your application throws a RecordNotFound exception, then you can map this exception to a Response object using your ExceptionResolver implementation. The Response object can be populated with a custom error message and sent back to the client, as mentioned in the second approach. We will now modify the CategoryService class to add the exception handling capability. We use the first and second approach for exception handling to understand these concepts in detail. The following is the revised CategoryService class, we have only shown the code snippets which have changed.package demo.restful;/JAX-RS Imports /* * CategoryService class - Add/Removes category for books */Path(/categoryservice)Produces(application/xml)public class CategoryService GET Path(/category/id) public Category getCategory(PathParam(id) String id) System.out.println(getCategory called with category id: + id); Category cat = (Category) getCategoryDAO().getCategory(id); if (cat = null) ResponseBuilder builder = Response.status(Status.BAD_REQUEST); builder.type(application/xml); builder.entity(Category Not Found); throw new WebApplicationException(builder.build(); else return cat; POST Path(/category) Consumes(application/xml) public Response addCategory(Category category) System.out.println(addCategory called); Category cat = (Category) getCategoryDAO().getCategory( category.getCategoryId(); if (cat != null) return Response.status(Status.BAD_REQUEST).build(); else getCategoryDAO().addCategory(category); return Response.ok(category).build(); DELETE Path(/category/id) public Response deleteCategory(PathParam(id) String id) System.out.println(deleteCategory with category id : + id); Category cat = (Category) getCategoryDAO().getCategory(id); if (cat = null) return Response.status(Status.BAD_REQUEST).build(); else getCategoryDAO().deleteCategory(id); return Response.ok().build(); PUT Path(/category) public Response updateCategory(Category category) System.out.println(updateCategory with category id : + category.getCategoryId(); Category cat = (Category) getCategoryDAO().getCategory( category.getCategoryId(); if (cat = null) return Response.status(Status.BAD_REQUEST).build(); else getCategoryDAO().updateCategory(category); return Response.ok(category).build(); POST Path(/category/book) Consumes(application/xml) public Response addBooks(Category category) System.out.println(addBooks with category id : + category.getCategoryId(); Category cat = (Category) getCategoryDAO().getCategory( category.getCategoryId(); if (cat = null) return Response.status(Status.NOT_FOUND).build(); else getCategoryDAO().addBook(category); return Response.ok(category).build(); GET Path(/category/id/books) Consumes(application/xml) public Response getBooks(PathParam(id) String id) System.out.println(getBooks called with category id : + id); Category cat = (Category) getCategoryDAO().getCategory(id); if (cat = null) return Response.status(Status.NOT_FOUND).build(); else cat.setBooks(getCategoryDAO().getBooks(id); return Response.ok(cat).build(); The code highlighted in the above code listing is the modification that we have made to add exception handling to the CategoryService implementation. The getCategory method uses the first approach, where we have used a javax.ws.rs.core.Response.ResponseBuilder to create a Response object, set the entity error message as xml Category Not Found and HTTP Status code as BAD_REQUEST. We then build the response and throw a WebApplicationException back to the client, as shown in above code listing. The CXF framework would convert the WebApplicationException into required HTTP format and send the response back to the client. We will look at HTTP response content in detail in the next chapter where we will look at various test scenarios for CategoryService implementation.For the rest of the resource method implementation, we modify the output parameter to the javax.ws.rs.core.Response object. For instance , if you look at the addBooks implementation above, if we do not find a valid category ID in the client request, then we would sent the HTTP STATUS NOT FOUND message back to the client, and if the request is successfully processed, then we build the category response and send it back to the client using the Response.ok(category).build() method To test the exception handling code, follow the build and deploy steps mentioned in the Running the program section to rebuild and deploy the program. Once the Category Service is available over HTTP, type in http:/localhost:9000/categoryservice/category/003 in the browser, and you would get the HTTP 400 BAD Request message on the Internet Explorer browser, as shown in the next screenshot. Internet Explorer doesnt show the custom error message. If you open up the URL in Firefox browser, then you would see the custom error message Category Not Found in the browser. As you can see, depending on your client, the custom error message may not be shown. The standard method is to use HTTP status code for returning the status to the client. If your clients can interpret the error messages, then its best to use a custom error message to give more information about the error.Invoking the Update Category operation with invalid requestWe will now test out exception scenarios for CategoryService. We will send an Update Category request to the CategoryService with a category ID that does not exist in the system. Enter the following information in the Poster screen.1. Enter URL as http:/localhost:8080/restapp/categoryservice/category (Replace 8080 with the port number where the web server is running).2. Enter Content Type as application/xml. 3. Click on the Headers tab, and check if the Name field contains Accept and if Value is application/xml. If not, then add these values. 4. In the Content to Send field, enter the following Category information in an XML format. Note that we specify the categoryId as 003, which does not exist.Microsoft NET0035. In the Actions tab, click the PUT method to issue HTTP PUT request to the CategoryService with the above information.The following updateCategory() method code will be executed as highlighted in bold. As the category ID 003 doesnt exist, we set the Response Status as BAD_REQUEST denoting an error. The CXF JSX RS implementation then creates an HTTP response with status code as 400 (BAD_REQUEST) denoting an error back to the client. Apart from HTTP status code, you can also send a custom error message back to the client. We will look at this scenario in the next invocation request. PUT Path(/category) public Response updateCategory(Category category) System.out.println(updateCategory with category id : + category.getCategoryId(); Category cat = (Category) getCategoryDAO().getCategory( category.getCategoryId(); if (cat = null) return Response.status(Status.BAD_REQUEST).build(); else getCategoryDAO().updateCategory(category); return Response.ok(category).build(); You would receive the following response from the updateCategory() method of the CategoryService. As you see in the following screenshot, the Status is 400 Bad Request, which signifies that the there was an error while processing the request due to a Bad Request message being sent by the client.Invoking the Get Category operation with invalid requestIn this scenario, we will send a Get Catego