47.2.2. 요청 URI에서 데이터 삽입

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 로 설정되어 있습니다.