chukwa 学习———— JAX-RS

JAX-RS

简介： JAX-RS (JSR-311) 是一种 Java™ API，可使 Java Restful 服务的开发变得迅速而轻松。这个 API 提供了一种基于注释的模型来描述分布式资源。注释被用来提供资源的位置、资源的表示和可移植的（pluggable）数据绑定架构。基于Hadoop的日志收集系统哦chukwa在里面很好的应用了该服务。

一   JAX-RS: Java API for RESTful Web Services是一个Java编程语言的应用程序接口,支持按照 表象化状态转变 (REST)架构风格创建Web服务Web服务^[1]. JAX-RS使用了Java SE 5引入的Java 标注来简化Web服务客户端和服务端的开发和部署。

二  规范内容

 JAX-RS提供了一些标注将一个资源类，一个POJOJava类，封装为Web资源。标注包括：

• @Path，注释被用来描述根资源、子资源方法或子资源的位置。value 值可以包含文本字符、变量或具有定制正则表达式的变量。清单 6 的例子展示了 @Path 注释的主要应用。
• @GET，@PUT，@POST，@DELETE，标注方法是用的HTTP请求的类型.您可以使用它们来绑定根资源或子资源内的 Java 方法与 HTTP 请求方法。HTTP GET 请求被映射到由 @GET 注释的方法；HTTP POST 请求被映射到由 @POST 注释的方法，以此类推。用户可能还需要通过使用 @HttpMethod 注释定义其自己的定制 HTTP 请求方法指示符。
• @Produces，注释代表的是一个资源可以返回的 MIME 类型。这些注释均可在资源、资源方法、子资源方法、子资源定位器或子资源内找到。

  JAX-RS 提供程序是一些应用程序组件，允许在三个关键领域进行运行时行为的定制：数据绑定、异常映射以及上下文解析（比如，向运行时提供 JAXBContext 实例）。每个 JAX-RS 提供程序类必须由 @Provider 注释。如下的例子讨论了两个数据绑定提供程序MessageBodyWriter 和 MessageBodyReader。

• @Consumes，注释代表的是一个资源可以接受的 MIME 类型。
• @PathParam，@QueryParam，@HeaderParam，@CookieParam，@MatrixParam，@FormParam,分别标注方法的参数来自于HTTP请求的不同位置，例如@PathParam来自于URL的路径，@QueryParam来自于URL的查询参数，@HeaderParam来自于HTTP请求的头信息，@CookieParam来自于HTTP请求的Cookie。

三   用JAX-RS 控制器来处理所有对于Agent处理adaptors的时候的HTTP请求

返回所有的适配器

 *   GET /rest/v1/adaptor

 *   Optional QS params: viewType=text|xml (default=xml)

返回单个适配器

 *   GET /rest/v1/adaptor/[adaptorId]

 *   Optional QS params: viewType=text|xml (default=xml)

移除一个适配器

 *   DELETE /rest/v1/adaptor/[adaptorId]

 *

添加一个适配器

 *   POST /rest/v1/adaptor

 *   Content-Type: application/json

 *   Optional QS params: viewType=text|xml (default=xml)

 *

 *   { "DataType" : "foo",

 *     "AdaptorClass" : "FooAdaptor",

 *     "AdaptorParams" : "params",

 *     "Offset"     : "0" }

 *   The first 3 params above are the only required ones.

  

四   与传统的 servlet 模型相比，JAX-RS 提供了一种可行的、更为简便、移植性更好的方式来在 Java 内实现 RESTful 服务。使用注释让您能够轻松提供 Java 资源的路径位置并将 Java 方法绑定到 HTTP 请求方法。一种可移植的数据绑定架构提供了一些本机的 Java 类型支持并允许进行序列化/反序列化处理的完全定制。javax.ws.rs.core. Application 子类的扩展以及 web.xml 内的相应清单表明了用最少的部署描述符配置就能进行轻松部署。

参考资料

 1.   http://www.mkyong.com/tutorials/jax-rs-tutorials/

 2.   http://www.ibm.com/developerworks/cn/web/wa-jaxrs/index.html

 3.   http://zh.wikipedia.org/zh/JAX-RS