47.2. JAX-RS API 사용

RESTful 웹 서비스를 설계하는 모범 사례 중 하나는 각 리소스에 고유한 URI가 있어야 한다는 것입니다. 개발자는 이 원칙을 사용하여 기본 리소스 구현에 많은 정보를 제공할 수 있습니다. 리소스에 대한 URI 템플릿을 설계할 때 개발자는 리소스 구현에 삽입할 수 있는 매개 변수 정보를 포함하도록 템플릿을 빌드할 수 있습니다. 개발자는 리소스 구현에 정보를 제공하는 데 쿼리 및 매트릭스 매개 변수를 활용할 수도 있습니다.

리소스에 대한 정보를 얻는 가장 일반적인 메커니즘 중 하나는 리소스에 대한 URI 템플릿을 생성하는 데 사용되는 변수를 사용하는 것입니다. 이 작업은 javax.ws.rs.PathParam 주석을 사용하여 수행됩니다. @PathParam 주석에는 데이터가 삽입될 URI 템플릿 변수를 식별하는 단일 매개 변수가 있습니다.

예 47.1. “URI 템플릿 변수에서 데이터 삽입” 에서 @PathParam 주석은 URI 템플릿 변수 색상 의 값이 itemColor 필드에 삽입되도록 지정합니다.

import javax.ws.rs.Path;
import javax.ws.rs.PathParam
...

@Path("/boxes/{shape}/{color}")
class Box
{
  ...

  @PathParam("color")
  String itemColor;

  ...
}

@PathParam 주석에서 지원하는 데이터 유형은 “지원되는 데이터 유형” 에 설명된 것과 다릅니다. @PathParam 주석을 삽입하는 엔터티는 다음 유형 중 하나여야 합니다.

웹에서 정보를 전달하는 일반적인 방법은 URI에 쿼리 매개 변수 를 사용하는 것입니다. 쿼리 매개 변수는 URI 끝에 표시되며, 물음표(?)로 URI의 리소스 위치 부분과 구분됩니다. 이름과 값이 등호(=)로 구분된 하나 이상의 이름 값으로 구성됩니다. 두 개 이상의 쿼리 매개 변수를 지정하면 쌍은 세미콜론( ; ) 또는 앰퍼샌드(&amp;)로 서로 구분됩니다. 예 47.2. “쿼리 문자열이 있는 URI” 쿼리 매개 변수가 있는 URI 구문을 보여줍니다.

http://fusesource.org?name=value;name2=value2;...

javax.ws.rs.QueryParam 주석은 쿼리 매개 변수의 값을 추출하여 JAX-RS 리소스에 삽입합니다. 주석은 값이 추출되고 지정된 필드, 빈 속성 또는 매개변수에 삽입되는 쿼리 매개변수의 이름을 식별하는 단일 매개 변수를 사용합니다. @QueryParam 주석은 “지원되는 데이터 유형” 에 설명된 유형을 지원합니다.

예 47.3. “쿼리 매개변수의 데이터를 사용하는 리소스 메서드” 메서드의 id 매개 변수에 쿼리 매개 변수 id 값을 삽입하는 리소스 메서드를 보여줍니다.

import javax.ws.rs.QueryParam;
import javax.ws.rs.PathParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...

@Path("/monstersforhire/")
public class MonsterService
{
  ...
  @POST
  @Path("/{type}")
  public void updateMonster(@PathParam("type") String type,
                            @QueryParam("id") String id)
  {
    ...
  }
  ...
}

HTTP POST 를 /monstersforhire/daikaiju?id=jonas updateMonster() 메서드의 유형 은 daikaiju 로 설정하고 id 는 jonas 로 설정됩니다.

URI 쿼리 매개변수와 같은 URI 매트릭스 매개 변수는 리소스를 선택하는 추가 정보를 제공할 수 있는 이름/값 쌍입니다. 쿼리 매개 변수와는 달리 매트릭스 매개 변수는 URI의 아무 곳에나 나타날 수 있으며 세미콜론(;)을 사용하여 URI의 계층적 경로 세그먼트와 분리됩니다. /mostersforhire/daikaiju;id=jonas 에는 id 및 /monstersforhire/japan;type=daikaiju/flying;wingspan=40 이라는 두 개의 매트릭스 매개변수가 있습니다.wingspan=40에는 type 및 wingspan 이라는 두 개의 매트릭스 매개변수가 있습니다.

matrix 매개변수 값은 javax.ws.rs.MatrixParam 주석을 사용하여 필드, 매개 변수 또는 빈 속성에 삽입됩니다. 주석은 값이 추출되고 지정된 필드, 빈 속성 또는 매개변수에 삽입되는 matrix 매개변수의 이름을 식별하는 단일 매개 변수를 사용합니다. @MatrixParam 주석은 “지원되는 데이터 유형” 에 설명된 유형을 지원합니다.

예 47.4. “매트릭스 매개변수의 데이터를 사용하는 리소스 메서드” 메서드의 매개 변수에 매트릭스 매개 변수 유형 및 id 값을 삽입하는 리소스 메서드를 보여줍니다.

import javax.ws.rs.MatrixParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...

@Path("/monstersforhire/")
public class MonsterService
{
  ...
  @POST
  public void updateMonster(@MatrixParam("type") String type,
                            @MatrixParam("id") String id)
  {
    ...
  }
  ...
}

HTTP POST 를 /monstersforhire;type=daikaiju;id=whale the updateMonster() 메서드의 유형 은 daikaiju 로 설정하고 id 는 whale 으로 설정됩니다.

기본적으로 모든 요청 URI가 디코딩됩니다. 따라서 URI /monster/night%20stalker 와 URI /monster/night stalker 는 동일합니다. 자동 URI 디코딩을 사용하면 ASCII 문자 집합 이외의 문자를 매개 변수로 쉽게 보낼 수 있습니다.

URI를 자동으로 디코딩하지 않으려면 javax.ws.rs.Encoded 주석을 사용하여 URI 디코딩을 비활성화할 수 있습니다. 주석은 다음 수준에서 URI 디코딩을 비활성화하는 데 사용할 수 있습니다.

예 47.5. “URI 디코딩 비활성화” getMonster() 메서드가 URI 디코딩을 사용하지 않는 리소스를 보여줍니다. addMonster() 메서드는 type 매개 변수에 대한 URI 디코딩만 비활성화합니다.

@Path("/monstersforhire/")
public class MonsterService
{
  ...

  @GET
  @Encoded
  @Path("/{type}")
  public Monster getMonster(@PathParam("type") String type,
                            @QueryParam("id") String id)
  {
    ...
  }

  @PUT
  @Path("/{id}")
  public void addMonster(@Encoded @PathParam("type") String type,
                         @QueryParam("id") String id)
  {
    ...
  }
  ...
}

URI 주입 주석 중 하나를 사용하여 데이터를 삽입하려고 할 때 오류가 발생하면 WebApplicationException 예외를 래핑하는 원래 예외가 생성됩니다. WebApplicationException 예외 상태가 404 로 설정되어 있습니다.

일반적으로 요청 메시지의 HTTP 헤더는 메시지에 대한 일반 정보, 전송 중 처리 방법, 예상 응답에 대한 세부 정보를 전달합니다. 일반적으로 몇 가지 표준 헤더가 인식되고 사용되는 반면 HTTP 사양에서는 이름/값 쌍을 HTTP 헤더로 사용할 수 있습니다. JAX-RS API는 HTTP 헤더 정보를 리소스 구현에 삽입하는 쉬운 메커니즘을 제공합니다.

가장 일반적으로 사용되는 HTTP 헤더 중 하나는 쿠키입니다. 쿠키를 통해 HTTP 클라이언트 및 서버는 여러 요청/응답 시퀀스에서 정적 정보를 공유할 수 있습니다. JAX-RS API는 리소스에서 리소스 구현에 직접 데이터를 삽입하는 주석을 제공합니다.

javax.ws.rs.HeaderParam 주석은 HTTP 헤더 필드의 데이터를 매개 변수, 필드 또는 빈 속성에 삽입하는 데 사용됩니다. 값을 추출하여 리소스 구현에 삽입되는 HTTP 헤더 필드의 이름을 지정하는 단일 매개 변수가 있습니다. 관련 매개변수, 필드 또는 빈 속성은 “지원되는 데이터 유형” 에 설명된 데이터 유형을 준수해야 합니다.

If-Modified-Since 헤더 삽입 HTTP If-Modified-Since 헤더의 값을 클래스의 oldestDate 필드에 삽입하는 코드를 표시합니다.

import javax.ws.rs.HeaderParam;
...
class RecordKeeper
{
  ...
  @HeaderParam("If-Modified-Since")
  String oldestDate;
  ...
}

쿠키는 특별한 유형의 HTTP 헤더입니다. 첫 번째 요청의 리소스 구현에 전달되는 하나 이상의 이름/값 쌍으로 구성됩니다. 첫 번째 요청 후 쿠키는 공급자와 각 메시지 간에 소비자 간에 전달됩니다. 요청을 생성하므로 소비자만 쿠키를 변경할 수 있습니다. 쿠키는 일반적으로 여러 요청/응답 시퀀스에서 세션을 유지하고, 사용자 설정 및 유지할 수 있는 기타 데이터를 저장하는 데 사용됩니다.

javax.ws.rs.CookieParam 주석은 쿠키 필드에서 값을 추출하여 리소스 구현에 삽입합니다. 값을 추출할 쿠키 필드의 이름을 지정하는 단일 매개 변수를 사용합니다. “지원되는 데이터 유형” 에 나열된 데이터 유형 외에도 @ Cookie Param 로 장식되는 엔티티도 쿠키 객체가 될 수 있습니다.

예 47.6. “쿠키 삽입” 처리 쿠키의 값을 CB 클래스의 필드에 삽입하는 코드를 표시합니다.

import javax.ws.rs.CookieParam;
...
class CB
{
  ...
  @CookieParam("handle")
  String handle;
  ...
}

HTTP 메시지 삽입 주석 중 하나를 사용하여 데이터를 삽입하려고 할 때 오류가 발생하면 WebApplicationException 예외를 래핑하는 원래 예외가 생성됩니다. WebApplicationException 예외 상태가 400 으로 설정되어 있습니다.

HTML 양식은 사용자로부터 정보를 얻는 쉬운 수단이며, 또한 쉽게 만들 수 있습니다. 양식 데이터는 HTTP GET 요청 및 HTTP POST 요청에 사용할 수 있습니다.

javax.ws.rs.FormParam 주석은 양식 데이터에서 필드 값을 추출하고 값을 리소스 메서드 매개 변수에 삽입합니다. 주석은 값을 추출하는 필드의 키를 지정하는 단일 매개 변수를 사용합니다. 관련 매개변수는 “지원되는 데이터 유형” 에 설명된 데이터 유형을 준수해야 합니다.

리소스 메서드 매개 변수에 양식 데이터 삽입 폼 데이터를 해당 매개 변수에 삽입하는 리소스 메서드를 표시합니다.Shows a resource method that injects form data into its parameters. 이 메서드는 클라이언트 양식에 문자열 데이터가 포함된 세 개의 필드이름,태그 및 본문이 포함되어 있다고 가정합니다.

import javax.ws.rs.FormParam;
import javax.ws.rs.POST;

...
@POST
public boolean updatePost(@FormParam("title") String title,
                          @FormParam("tags") String tags,
                          @FormParam("body") String post)
{
  ...
}

보다 강력한 서비스 구현을 제공하기 위해 선택적 매개 변수를 기본값으로 설정할 수 있습니다. 특히 긴 URI 문자열을 입력하는 경우 오류가 발생하기 때문에 쿼리 매개 변수 및 매트릭스 매개 변수에서 가져온 값에 특히 유용할 수 있습니다. 또한 쿠키에서 추출된 매개 변수의 기본값을 설정하는 것이 좋습니다. 요청 시스템에 모든 값으로 쿠키를 구성하는 적절한 정보가 없기 때문입니다.

javax.ws.rs.DefaultValue 주석은 다음 삽입 주석과 함께 사용할 수 있습니다.

@DefaultValue 주석은 삽입 주석에 해당하는 데이터가 요청에 없는 경우 사용할 기본값을 지정합니다.

매개변수의 기본값을 설정하는 구문 @DefaultValue 주석 사용에 대한 구문을 보여줍니다.

import javax.ws.rs.DefaultValue;
  ...
  void resourceMethod(@MatrixParam("matrix")
                      @DefaultValue("value)
                      int someValue, ... )
  ...

주석은 매개변수, 빈 또는 필드 앞에 있어야 합니다. 첨부된 삽입 주석과 관련된 @DefaultValue 주석의 위치는 중요하지 않습니다.

@DefaultValue 주석은 단일 매개변수를 사용합니다. 이 매개변수는 삽입 주석을 기반으로 적절한 데이터를 추출할 수 없는 경우 필드에 삽입되는 값입니다. 값은 모든 문자열 값일 수 있습니다. 값은 연결된 필드의 유형과 호환되어야 합니다. 예를 들어 연결된 필드가 int 이면 기본값으로 파 란색으로 인해 예외가 발생합니다.

주석이 달린 매개 변수 유형, 빈 또는 필드가 List, Set 또는 SortedSet인 경우 결과 컬렉션에는 제공된 기본값에서 매핑된 단일 항목이 있습니다.

기본값 설정 에서는 @DefaultValue 를 사용하여 값이 삽입되는 필드의 기본값을 지정하는 두 가지 예를 보여줍니다.

import javax.ws.rs.DefaultValue;
import javax.ws.rs.PathParam;
import javax.ws.rs.QueryParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("/monster")
public class MonsterService
{

  @Get
  public Monster getMonster(@QueryParam("id") @DefaultValue("42") int id,
                            @QueryParam("type") @DefaultValue("bogeyman") String type)
  {
    ...
  }

  ...
}

기본값 설정 의 getMonster() 메서드는 GET 요청이 baseURI/monster 로 전송될 때 호출됩니다. 이 메서드에는 두 개의 쿼리 매개 변수 id 와 type 가 필요하며 URI에 추가됩니다. URI URI/monster?id=1&type=fomóiri를 사용하는 GET 요청은 Fomóiri 와 함께 Fomóiri를 반환합니다.

@DefaultValue 주석은 두 매개 변수에 모두 배치되므로 쿼리 매개변수를 생략하면 getMonster() 메서드가 작동할 수 있습니다. baseURI/monster로 전송된 GET 요청은 URI baseURI /monster?id=42&type=bogeyman 을 사용하여 GET 요청과 동일합니다.

REST를 통해 HTML 양식을 게시할 때 서버 측의 일반적인 패턴은 양식에서 수신한 모든 데이터를 캡슐화하기 위한 Java 빈(및 다른 매개 변수 및 HTML 헤더에서 데이터일 수 있음)을 생성하는 것입니다. 일반적으로 이 Java 빈을 생성하는 것은 두 단계 프로세스입니다. 리소스 메서드는 주입(예: @FormParam 주석을 메서드 매개 변수에 추가하여) 양식 값을 수신하며, 리소스 메서드는 빈의 생성자를 호출하여 양식 데이터를 전달합니다.

JAX-RS 2.0 @BeanParam 주석을 사용하면 단일 단계에서 이 패턴을 구현할 수 있습니다. 양식 데이터는 빈 클래스 필드에 직접 삽입할 수 있으며, JAX-RS 런타임에서 빈 자체는 자동으로 생성됩니다. 예를 들어 가장 쉽게 설명할 수 있습니다.

@BeanParam 주석은 리소스 메서드 매개 변수, 리소스 필드 또는 빈 속성에 연결할 수 있습니다. 그러나 매개변수 대상은 모든 리소스 클래스 라이프사이클에 사용할 수 있는 유일한 종류의 대상입니다. 다른 종류의 대상은 요청별 라이프사이클로 제한됩니다. 이 상황은 표 47.1. “@BeanParam injection 대상” 에 요약되어 있습니다.

다음 예제에서는 @BeanParam을 사용하지 않고 기존 접근 방식을 사용하여 Java 빈에서 양식 데이터를 캡처하는 방법을 보여줍니다.

// Java
import javax.ws.rs.POST;
import javax.ws.rs.FormParam;
import javax.ws.rs.core.Response;
...
@POST
public Response orderTable(@FormParam("orderId")  String orderId,
                           @FormParam("color")    String color,
                           @FormParam("quantity") String quantity,
                           @FormParam("price")    String price)
{
    ...
    TableOrder bean = new TableOrder(orderId, color, quantity, price);
    ...
    return Response.ok().build();
}

이 예에서 orderTable 방법은 가구 웹 사이트에서 테이블 수량을 주문하는 데 사용되는 양식을 처리합니다. 주문 폼이 게시되면 양식 값이 orderTable 메서드의 매개 변수에 삽입되고 orderTable 메서드는 삽입된 양식 데이터를 사용하여 TableOrder 클래스의 인스턴스를 명시적으로 만듭니다.

위 예제를 리팩터링하여 @BeanParam 주석을 활용할 수 있습니다. @BeanParam 접근법을 사용하는 경우 양식 매개 변수를 빈 클래스의 필드에 직접 삽입할 수 있습니다. 실제로 @PathParam,@QueryParam,@FormParam,@MatrixParam,@CookieParam, @HeaderParam , @HeaderParam 등의 빈 클래스에서 표준 JAX-RS 매개변수 주석을 사용할 수 있습니다. 양식을 처리하는 코드는 다음과 같이 리팩토링될 수 있습니다.

// Java
import javax.ws.rs.POST;
import javax.ws.rs.FormParam;
import javax.ws.rs.core.Response;
...
public class TableOrder {
    @FormParam("orderId")
    private String orderId;

    @FormParam("color")
    private String color;

    @FormParam("quantity")
    private String quantity;

    @FormParam("price")
    private String price;

    // Define public getter/setter methods
    // (Not shown)
    ...
}
...
@POST
public Response orderTable(@BeanParam TableOrder orderBean)
{
    ...
    // Do whatever you like with the 'orderBean' bean
    ...
    return Response.ok().build();
}

이제 양식 주석이 빈 클래스인 TableOrder에 추가되었으므로 리소스 메서드 서명의 모든 @FormParam 주석을 단일 @BeanParam 주석으로 교체할 수 있습니다. 이제 폼이 orderTable 리소스 메서드에 게시되면 JAX-RS 런타임에서 자동으로 TableOrder 인스턴스, orderBean; orderBean 를 만들고, 빈 클래스에 매개변수 주석에 의해 지정된 모든 데이터를 삽입합니다.