Jersey
本文从以下两个方面对jersey进行介绍:(内容主要来源于jersey官网)
一、jersey简单介绍
二、jersey的实现基础:JAX-RS程序接口核心。
三、应用程序部署和运行时环境
一、jersey简单介绍
前言:
如果没有一套好的工具或框架,要开发一套能以多种媒体类型显示数据、并且屏蔽client-server底层通信细节 的restful风格的web service ,将是一件耗时耗力的事情。为了简化restful web 服务的开发成本、提高效率,JAVA EE6 引入的一个新技术:JAX-RS。
JAX-RS(即Java API for RESTful Web Services),是一个Java 编程语言的应用程序接口,支持按照表述性状态转移(REST)架构风格创建Web服务。JAX-RS和所有JAVA EE的技术一样,只提供了技术标准,允许各个厂家有自己的实现版本,实现版本有:RESTEasy(JBoss), Jersey(Sun提供的参考实现), Apache CXF, Restlet(最早的REST框架,先于JAX-RS出现), Apache Wink。JAX-RS基于JavaEE的Servlet。
Jersey
jersey是一套restful风格的开源框架,jersey提供了JAX-RS接口,并且作为JAX-RS的一种参考实现。
jersey不仅仅是对JAX-RS接口的实现,在此之外,还通过扩展JAX-RS实现了自己的一些接口,这些扩展接口可以进一步的去简化restful服务的开发,提升效率。
与JAVA SE 的版本兼容
jersey2.6 及之前版本 基于 JAVA SE 6
2.25. 系列 基于JAVA SE 7
2.26 基于JAVA SE 8
Jerset依赖
对于使用MAVEN进行项目构建的开发者来说,添加jersey依赖十分方便。mvn中心仓库包含了所有jersey的稳定版本。如果有需要可以在https://maven.java.net上main获取jersey的最新版本(开发测试版本)。
详情可参考官方教程:https://jersey.github.io/documentation/latest/modules-and-dependencies.html
二、jersey实现的基础:AX-RS程序接口核心概念:资源和子资源
1、root resource classes
根资源类,是一种由@path注解、并且包含至少一个由@path或@GET、@POST等资源方法指示符 注解的方法 的JAVA类。
资源方法,是带有资源方法指示符的资源类的方法。
@Path 注解的值是URI的相对路径。 我们可以在URI中加入变量, 在资源方法中使用@PathParam 来获取参数:
@Path("/users/{username}") public class UserResource { @GET @Produces("text/xml") public String getUser(@PathParam("username") String userName) { ... } }
也是使用正则表达式对前端的查询参数进行过滤,如: @Path
(
"users/{username: [a-zA-Z][a-zA-Z_0-9]*}"
)
1)HTTP 相应注解
@GET, @PUT, @POST, @DELETE and @HEAD 是由 JAX-RS 定义的资源方法标志符注解。其名称与HTTP方法相对应,用于处理HTTP的相关请求。
2)@Produces 注解
@Produces 注解用于指定 表示一个资源的枚举媒体类型。可以用在资源类,也可以用在资源方法上(具有更高的优先权)。如下所示:
@Path("/myResource") @Produces("text/plain") public class SomeResource {
//返回纯文本 @GET public String doGetAsPlainText() { ... }
//返回html @GET @Produces("text/html") public String doGetAsHtml() { ... } }
另外,也可以同时使用多种媒体输出类型。
3)@Consumes注解
用于指定资源方法可以消费的媒体类型,用法与@produces类似。(用于输入信息的过滤,而@Produces用于输出信息的过滤)。@Consumers也可以使用在类或者方法上。
4)参数注解
@QueryParam用于从请求的URL上获取查询参数。而上文提及的@PathParam用于获取 由@Path注解中定义的路径参数。
@DefaultValue注解用于设置查询参数的默认值,注解用例如下:
@Path("smooth") @GET public Response smooth( @DefaultValue("2") @QueryParam("step") int step, @DefaultValue("true") @QueryParam("min-m") boolean hasMin, @DefaultValue("true") @QueryParam("max-m") boolean hasMax, @DefaultValue("true") @QueryParam("last-m") boolean hasLast, @DefaultValue("blue") @QueryParam("min-color") ColorParam minColor, @DefaultValue("green") @QueryParam("max-color") ColorParam maxColor, @DefaultValue("red") @QueryParam("last-color") ColorParam lastColor) { ... }
@PathParam注解 和其他 :@MatrixParam, @HeaderParam, @CookieParam, @FormParam等基于参数的注解,都遵循和@QueryParam注解一样的使用规则。
其中,@ MatrixParam提取URL路径段的信息。@ HeaderParam提取HTTP头信息。@ CookieParam提取cookie相关的HTTP标头声明。
@FormParam获取来自表达的数据,并且媒体类型必须为“application/x-www-form-urlencoded”。如下:
@POST @Consumes("application/x-www-form-urlencoded") public void post(@FormParam("name") String name) { // Store the message }
如果想获取参数名到参数值得映射,使用如下方法:
@GET public String get(@Context UriInfo ui) { MultivaluedMap<String, String> queryParams = ui.getQueryParameters(); MultivaluedMap<String, String> pathParams = ui.getPathParameters(); }
获取cookie或者header:
@GET public String get(@Context HttpHeaders hh) { MultivaluedMap<String, String> headerParams = hh.getRequestHeaders(); Map<String, Cookie> pathParams = hh.getCookies(); }
通常情况下,@Context注解可以用于获取所有request、response相关的环境上下文java类型数据。
2.sub-resources
root resource class 中被@Path注解的方法就是 sub-resources(子资源)。
1)根据request URL对@Path标识的子资源进行分层匹配。如下(不同的请求路径会向不同层级下的资源进行匹配):
@Singleton @Path("/printers") public class PrintersResource { @GET @Produces({"application/json", "application/xml"}) public WebResourceList getMyResources() { ... } @GET @Path("/list") @Produces({"application/json", "application/xml"}) public WebResourceList getListOfPrinters() { ... } @GET @Path("/jMakiTable") @Produces("application/json") public PrinterTableModel getTable() { ... } @GET @Path("/jMakiTree") @Produces("application/json") public TreeModel getTree() { ... } @GET @Path("/ids/{printerid}") @Produces({"application/json", "application/xml"}) public Printer getPrinter(@PathParam("printerid") String printerId) { ... } @PUT @Path("/ids/{printerid}") @Consumes({"application/json", "application/xml"}) public void putPrinter(@PathParam("printerid") String printerId, Printer printer) { ... } @DELETE @Path("/ids/{printerid}") public void deletePrinter(@PathParam("printerid") String printerId) { ... } }
3.life-cycle of root resource classes
默认情况,在执行每个request url 的时候,被匹配到的root resource classes都会新建一个实例。
以下是对生命周期进行管理的三个注解:
@RequestScoped (默认注解) 每个新的request都会创建一个新实例用于处理请求(同一个请求的实例不会被重复创建)。
@PerLookup 每次请求都会创建新实例。(即使处理的是同一个请求)
@Singleton 每一个jax-rs实例将会只产生一个实例资源。
4.注入规则
以下例子使用了多种注入值的使用方法(属性、方法、构造函数等注入值)
@Path("{id:\\d+}") public class InjectedResource { // Injection onto field @DefaultValue("q") @QueryParam("p") private String p; // Injection onto constructor parameter public InjectedResource(@PathParam("id") int id) { ... } // Injection onto resource method parameter @GET public String get(@Context UriInfo ui) { ... } // Injection onto sub-resource resource method parameter @Path("sub-id") @GET public String get(@PathParam("sub-id") String id) { ... } // Injection onto sub-resource locator method parameter @Path("sub-id") public SubResource getSubResource(@PathParam("sub-id") String id) { ... } // Injection using bean setter method @HeaderParam("X-header") public void setHeader(String header) { ... } }
三、应用程序部署和运行时环境