用 Java 技术创建 RESTful Web 服务（3）注释

look_w

本节将会探讨一些重要的注释及其使用。对于由 JAX-RS 规范提供的注释的完整列表，可以参考本文的  部分给出的 JSR-311 链接。                         
@Path@Path 注释被用来描述根资源、子资源方法或子资源的位置。value 值可以包含文本字符、变量或具有定制正则表达式的变量。清单 6 的例子展示了                                    @Path 注释的主要应用。
清单 6. @Path 的使用

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

package com.ibm.jaxrs.sample.organization; import java.util.List; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.PathParam; @Path(value="/contacts") public class ContactsResource {               @GET     @Path(value="/{emailAddress:.+@.+\\.[a-z]+}")     public ContactInfo getByEmailAddress(@PathParam(value="emailAddress")         String emailAddress) {         ...     }           @GET     @Path(value="/{lastName}")     public ContactInfo getByLastName(@PathParam(value="lastName") String lastName) {         ...     } }

ContactsResource 类上的注释表明对                                            /contacts 路径的所有请求都将由 ContactsResource 根资源处理。getByEmailAddress 上的 @Path 注释则表明任何发送到 /contacts/{emailAddress} 的请求（其中 emailAddress 代表的是正则表达式 .+@.+\\.[a-z]+）都将由 getByEmailAddress 处理。
getByLastName 方法上的 @Path 注释指定了发送到                                        /contacts/{lastName} 路径的所有请求（其中 lastName 代表的是一个与 getByEmailAddress 内的正则表达式不匹配的有效的 URL 部分）都将由 getByLastName 方法处理。
@GET、@POST、@PUT、@DELETE、@HEAD @GET、@POST、@PUT、@DELETE 以及 @HEAD 均是 HTTP 请求方法指示符注释。您可以使用它们来绑定根资源或子资源内的                        Java 方法与 HTTP 请求方法。HTTP GET 请求被映射到由 @GET 注释的方法；HTTP POST 请求被映射到由                        @POST 注释的方法，以此类推。用户可能还需要通过使用 @HttpMethod 注释定义其自己的定制 HTTP 请求方法指示符。
清单 7. 定制的 HTTP 请求方法指示符注释

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

package com.ibm.jaxrs.sample.organization; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; import javax.ws.rs.HttpMethod; @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @HttpMethod("GET") public @interface CustomGET { }

上述的声明定义了 @CustomGET 注释。此注释将具有与 @GET 注释相同的语义值并可用在其位置上。
@Conumes 和 @Produces@Consumes 注释代表的是一个资源可以接受的 MIME 类型。@Produces 注释代表的是一个资源可以返回的 MIME 类型。这些注释均可在资源、资源方法、子资源方法、子资源定位器或子资源内找到。
清单 8. @Consumes/@Produces

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

package com.ibm.jaxrs.sample.organization; import java.util.List; import javax.ws.rs.Consumes; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.Produces; @Path(value="/contacts") public class ContactsResource {               @GET     @Path(value="/{emailAddress:.+@.+\\.[a-z]+}")     @Produces(value={"text/xml", "application/json"})     public ContactInfo getByEmailAddress(@PathParam(value="emailAddress")         String emailAddress) {         ...     }           @GET     @Path(value="/{lastName}")     @Produces(value="text/xml")     public ContactInfo getByLastName(@PathParam(value="lastName") String lastName) {         ...     }           @POST     @Consumes(value={"text/xml", "application/json"})     public void addContactInfo(ContactInfo contactInfo) {         ...     } }

对于上述的 getByEmailAddress 和 addContactInfo 方法，它们均能处理 text/xml 和                                        application/json。被接受或返回的资源表示将依赖于客户机设置的 HTTP 请求头。@Consumes 注释针对 Content-Type 请求头进行匹配，以决定方法是否能接受给定请求的内容。
    在清单 9 中，application/json 的 Content-Type 头再加上对路径 /contacts 的 POST，表明我们的 ContactsResource 类内的 addContactInfo 方法将会被调用以处理请求。
清单 9. Content-Type 头部的使用

1 2 3

POST /contacts HTTP/1.1 Content-Type: application/json Content-Length: 32

相反地，@Produces 注释被针对 Accept 请求头进行匹配以决定客户机是否能够处理由给定方法返回的表示。
清单 10. Accept 头部的使用

1 2	GET /contacts/johndoe@us.ibm.com HTTP/1.1 Accept: application/json

    在清单 10 中，对                    /contacts/johndoe@us.ibm.com 的 GET 请求表明了 getByEmailAddress 方法将会被调用并且返回的格式将会是 application/json，而非 text/xml。