Jersey

本文從如下兩個方面對jersey進行介紹：（內容主要來源於jersey官網）

1、jersey簡單介紹

2、jersey的實現基礎：JAX-RS程序接口核心。

3、應用程序部署和運行時環境

 

1、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

 

2、jersey實現的基礎：AX-RS程序接口核心概念：資源和子資源

一、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) { ... }
}

 

3、應用程序部署和運行時環境