RESTEasy注解及使用

RESTEasy簡介

接上一篇《JAX-RS規範的版本.實作.jar對應關系》，我們已經知道RESTEasy是JAX-RS規範的實作，本篇内容告訴我們該怎樣去使用它。

常用注解

RESTEasy以jaxrs-api.jar包為基礎對JAX-RS進行實作，該包中包含了JAX-RS規範所聲明的注解。

注解清單

這裡我們根據3.0.7.Final這一版本對一些常用注解進行說明，以下是注解清單，請進行參考閱讀：

注解	描述	參數
@ApplicationPath	标注資源的root路徑，加載子資源檔案	value
@Path	标注普通資源路徑	value
@GET	擷取
@POST	添加
@PUT	整體更新
@PATCH	部分更新(resteasy中并沒有)
@DELETE	删除
@PathParam	資源路徑參數	value
@QueryParam	資源請求參數	value
@MatrixParam	标注請求資源key-value類型的參數	value
@FormParam	标注表單參數	value
@Encoded	标注需要UrlEncode的元素
@Context	在參數清單注入系統級别參數javax.ws.rs.core.HttpHeaders, javax.ws.rs.core.UriInfo, javax.ws.rs.core.Request, javax.servlet.HttpServletRequest, javax.servlet.HttpServletResponse, javax.servlet.ServletConfig, javax.servlet.ServletContext, and javax.ws.rs.core.SecurityContext objects
@CookieParam	标注需要擷取的cookie參數	value
@Consumes	指定client請求資料類型，與client的Content-Type比對	value[]
@Produces	指定client接收資料類型，與client的Accept比對	value[]
@HeaderParam	标注需要擷取的header參數	value
@DefaultValue	标注預設值	value
@Form	标注表單對象，對象中的表單屬性需要@FormParam進行标注

使用方法

@ApplicationPath

@ApplicationPath("operations")
        public class OperationApplication extends Application {

        private Set<Object> singletons=new HashSet<Object>();

        public OperationApplication(){
            singletons.add(new Library());
            singletons.add(new BookStoreImpl());
        }

        @Override
        public Set<Object> getSingletons(){
            return singletons;
        }
    }
           

在使用RESTEasy進行應用啟動的時候，需要指明其請求根路徑，這裡既需要用到

@ApplicationPath

注解。

建立一個資源處理類OperationApplication繼承Application，

标注類級别注解

@ApplicationPath

，用以聲明根路徑，

重寫getSingletons()方法，用以擷取資源容器

在構造器中加載Library和BookStoreImpl兩份資源，隻有在此添加的資源才能被通路

@Path,@GET,@PUT,@DELETE,@POST

@Path("/library")
    public class Library {

        @GET
        //@PUT,@POST,@DELETE
        @Path("/books")
        public String getBooks(){
            return "book list";
        }
     }
           

@Path是類與方法級别

使用

@Path

注解辨別通路路徑，該路徑基于

@ApplicationPath

提供的根路徑

@GET,@PUT,@DELETE,@POST為方法級别

這四個注解是http rest注解，用在實際動作上

@PathParam,@QueryParam

···

@PUT
@Path("/book/{isbn}")
public void addBook(@PathParam("isbn") String isbn, @QueryParam("name") String name){

    System.out.println("add the book with name : "+name+", isbn : "+isbn);
}

@DELETE
@Path("/book/{var: .*}/{isbn}")
public void removeBook(@PathParam("isbn") String isbn,@PathParam("var") String var){
        System.out.println(var);
        System.out.println("the book with isbn : "+isbn+" has been removed");
    }
           

···

通過聲明

@Pathparam

參數名可以更友善的擷取路徑上的參數，

路徑參數可以直接聲明，也可以聲明後通過正則進行限制，如

@Path("/book/{var: .*}/{isbn}")

，這裡聲明了var和isbn兩個路徑參數，var參數會捕獲輸入路徑中滿足冒号後正則的部分作為value

@POST
    @Path("/book{multi}")
    public void postBook(@PathParam("multi") PathSegment multi){
        MultivaluedMap<String,String> paramMap =multi.getMatrixParameters();
        Set<String> set=paramMap.keySet();

        for (String key:set){
            System.out.println(key+" : "+paramMap.get(key));
        }
    }
           

上一片段對應的請求為：

POST http://localhost:8080/operations/library/book==;name=EJB ;title=Bill Burke
           

通過PathSegment類的使用可以将路徑參數進行map映射，按照上面的請求寫法，會将參數name和title進行鍵值映射

@MatrixParam

@PUT
    @Path("/books")
    public void updateBook(@MatrixParam("name") String name,@MatrixParam("title") String title){
        System.out.println("name :"+name+" ,title :"+title);
    }
           

使用@MatrixParam可以擷取下面這種資源寫法的請求參數：

GET http://host.com/library/book;name=EJB 3.0;author=Bill Burke

           

@FormParam,@DefaultValue

@POST
    @Path("/books-form1")
    public void addBookByForm(@FormParam("name") @DefaultValue("yimmm") String name,@FormParam("title") String title){
        System.out.println("name :"+name+" ,title :"+title);
    }
           

作為form送出的參數

@FormParam

可以根據名稱進行擷取，

@DefaultValue

在未傳入相應參數時可以賦予其預設值

@Consumes

@POST
    @Path("/books-form2")
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    public void addBookByForm(MultivaluedMap<String,String> form){
        Set<String> set=form.keySet();

        for (String key:set){
            System.out.println(key+" : "+form.get(key));
        }
    }
           

@Consumes

對請求參數格式進行限制

在進行form送出時，MultivaluedMap

@Form

@POST
    @Path("/books-form3")
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    public void addBookByForm(@Form Book book){
        System.out.println(book.getAuthor());
        System.out.println(book.getTitle());
    }
           

使用

@Form

可以将form參數直接映射為對象 但是該對象需要進行相關标注。

建立Book.java，用

@FormParam對其進行參數标注

，在資源中即可運用

@Form

在參數清單中對

Book book

進行标注，請求中的符合Book屬性的參數會作為Book執行個體的屬性被接收

public class Book {
    @FormParam("author")
    private String author;

    @FormParam("title")
    private String title;
           

@Context,@Encoded

@GET
    @Path("encodeTest/{name}")
    public String testEncode(@Context javax.ws.rs.core.HttpHeaders headers,@PathParam("name") @Encoded String name){

        return name;
    }
           

@Context在參數清單注入系統級别參數，如上，将javax.ws.rs.core.HttpHeaders進行嵌入。

@Encoded對目前的pathparam name進行urlencode，接收後的name參數是encode後的字元串

@Produces

@GET
    @Path("/books")
    @Produces({MediaType.APPLICATION_JSON,MediaType.TEXT_PLAIN})
    public String getBooks(){
        return "book list";
    }
           

@Produces與@Consumes用法相同，隻不過是進行傳回資料格式的比對，它們的參數為字元串數組

注：暫且說到這裡，後續補充