JAX-RS规范基础

1：概念与常用注解

JAX-RS是一套用java实现REST服务的规范，提供了一些标注将一个资源类，一个POJOJava类，封装为Web资源。标注包括：

• @Path，标注资源类或方法的相对路径
• @GET，@PUT，@POST，@DELETE，标注方法是用的HTTP请求的类型
• @Produces，标注返回的MIME媒体类型
• @Consumes，标注可接受请求的MIME媒体类型
• @PathParam，@QueryParam，@HeaderParam，@CookieParam，@MatrixParam，@FormParam,分别标注方法的参数来自于HTTP请求的不同位置，例如@PathParam来自于URL的路径，@QueryParam来自于URL的查询参数，@HeaderParam来自于HTTP请求的头信息，@CookieParam来自于HTTP请求的Cookie。

2：JAX-RS的几种实现

    目前JAX-RS的实现包括：

• Apache CXF，开源的Web服务框架。
• Jersey， 由Sun提供的JAX-RS的参考实现。
• RESTEasy，JBoss的实现。
• Restlet，由Jerome Louvel和Dave Pawson开发，是最早的REST框架，先于JAX-RS出现。
• Apache Wink，一个Apache软件基金会孵化器中的项目，其服务模块实现JAX-RS规范

3：常用注解范例

（1）PathParam

Java代码  

1. public class CustomerResource {  
2.     ...  
3.     @Path("{id}")  
4.     @GET  
5.     @Produces("application/xml")  
6.     public StreamingOutput getCustomer(@PathParam("id") int id) {  
7.         ...  
8.     }  
9. }  

 

此处，取得{id}的值，并试图转换成一个int型的值。

可以同时使用多个PathParam:

Java代码  

1. @Path("/customers")  
2. public class CustomerResource {  
3.     ...  
4.     @Path("{first}-{last}")  
5.     @GET  
6.     @Produces("application/xml")  
7.     public StreamingOutput getCustomer(@PathParam("first") String firstName,  
8.         @PathParam("last") String lastName) {  
9.         ...  
10.     }  
11. }  

（2）@QueryParam

很显然，QueryParam用来获取查询参数，对于 GET /customers?start=0&size=10 ，例如：

Java代码  

1. @Path("/customers")  
2. public class CustomerResource {  
3.     @GET  
4.     @Produces("application/xml")  
5.     public String getCustomers(@QueryParam("start") int start,  
6.         @QueryParam("size") int size) {  
7.         ...  
8.     }  
9. }  

这里start为0，size为10.

同上面的PathParam，也可以用UriInfo去获取QueryParam，例如：

Java代码  

1. @Path("/customers")  
2. public class CustomerResource {  
3.     @GET  
4.     @Produces("application/xml")  
5.     public String getCustomers(@Context UriInfo info) {  
6.         String start = info.getQueryParameters().getFirst("start");  
7.         String size = info.getQueryParameters().getFirst("size");  
8.         ...  
9.     }  
10. }  

（3） @FormParam

很自然，FormParam用于提取POST请求中的Form参数，其中Content-Type被假设为application/x-www-formurlencoded。例如有以下Form请求

 

Html代码  

1. <FORM action="http://example.com/customers" method="post">  
2.     <P>  
3.         First name: <INPUT type="text" name="firstname"><BR>  
4.         Last name: <INPUT type="text" name="lastname"><BR>  
5.         <INPUT type="submit" value="Send">  
6.     </P>  
7. </FORM>  

可以如下取值：

Java代码  

1. @Path("/customers")  
2. public class CustomerResource {  
3.     @POST  
4.     public void createCustomer(@FormParam("firstname") String first,  
5.         @FormParam("lastname") String last) {  
6.             ...  
7.     }  
8. }  

（4） HeaderParam

    很直接，用来提取HTTP Header值的。例如：

Java代码  

1. @Path("/myservice")  
2. public class MyService {  
3.     @GET  
4.     @Produces("text/html")  
5.     public String get(@HeaderParam("Referer") String referer) {  
6.         ...  
7.     }  
8. }  

（5）@CookieParam

提取cookie信息，例如：

Java代码  

1. @Path("/myservice")  
2. public class MyService {  
3.     @GET  
4.     @Produces("text/html")  
5.     public String get(@CookieParam("customerId") int custId) {  
6.         ...  
7.     }  
8. }  

这里注入了的是一个cookie的值，如果想取得更多的信息，而不仅仅是基本值，则可以直接注入javax.ws.rs.core.Cookie对象，例如：

Java代码  

1. @Path("/myservice")  
2. public class MyService {  
3.     @GET  
4.     @Produces("text/html")  
5.     public String get(@CookieParam("customerId") Cookie custId) {  
6.         ...  
7.     }  
8. }