JAX-RS(JSR-311):RESTful 웹서비스 개발시 Annotation 정리

어노테이션

이 섹션에서는 일부 중요한 어노테이션들과 그 사용에 대해 살펴본다. JAX-RS 스펙으로 제공되는 어노테이션들의 전체 목록은 참고자료 섹션의 JSR-311 링크를 참조하자.

@Path

@Path 어노테이션은 루트 리소스, 하위 리소스 메소드 또는 하위 리소스의 위치를 설명하는 데 사용된다. value 속성은 리터럴 문자, 변수 및 사용자 정의 정규식이 있는 변수를 포함할 수 있다. 목록 6의 예제는 @Path 어노테이션의 기본적인 사용을 보여준다.

목록 6. @Path의 사용

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}로 전송되는 어느 요청이나 getByEmailAddress로 처리될 것임을 의미한다. 여기에서 emailAddress는 정규식 .+@.+\\.[a-z]+를 표현한다.

getByLastName 메소드의 @Path 어노테이션은 /contacts/{lastName} 경로로 전송된 모든 요청들이 getByLastName 메소드로 처리될 것을 지정한다. 여기에서 lastName은 getByEmailAddress에서 정규식에 일치하지 않는 유효한 URL 부분을 표현한다.

@GET, @POST, @PUT, @DELETE, @HEAD

@GET, @POST, @PUT, @DELETE 및 @HEAD는 HTTP 요청 메소드 지정자 어노테이션들이다. 이들을 사용하여 루트 리소스 또는 하위 리소스에서 Java 메소드를 HTTP 요청 메소드로 바인드할 수 있다. HTTP GET 요청들은 @GET으로 어노테이션을 작성한 메소드들로 맵핑되고, HTTP POST 요청들은 @POST로 어노테이션을 작성한 메소드들로 맵핑되는 등의 작업이 수행된다. 사용자들은@HttpMethod 어노테이션을 사용하여 자체적인 사용자 정의 HTTP 요청 메소드 지정자 어노테이션들을 정의할 수도 있다.

목록 7. 사용자 정의 HTTP 요청 메소드 지정자 어노테이션

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 어노테이션과 동일한 시맨틱 값을 보유하며, 제 자리에서 사용할 수 있다.

@Consumes 및 @Produces

@Consumes 어노테이션은 리소스가 승인하는 MIME 유형을 표현한다. @Produces 어노테이션은 리소스가 리턴하는 MIME 유형을 표현한다. 이러한 어노테이션들은 리소스, 리소스 메소드, 하위 리소스 메소드, 하위 리소스 로케이터 또는 하위 리소스에서 찾을 수 있다.

목록 8. @Consumes/@Produces

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 헤더의 사용

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

반대로, @Produces 어노테이션은 Accept 요청 헤더에 일치하여, 클라이언트에서 주어진 메소드가 리턴하는 표현을 처리할 수 있는지 여부를 결정한다.

목록 10. Accept 헤더의 사용

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

목록 10에서 /contacts/johndoe@us.ibm.com으로의 GET 요청은 getByEmailAddress 메소드가 호출될 것이며, 리턴 형식이 text/xml이 아니라 application/json이 될 것임을 의미한다.

출처 :  

http://www.ibm.com/developerworks/kr/library/wa-jaxrs/index.html#N10191