47.2. Cryostat-RS API 사용

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

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

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

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의 리소스 위치 부분과 구분됩니다. 이름과 값이 등호(=)로 구분된 이름 값 쌍으로 구성됩니다. 쿼리 매개 변수가 두 개 이상 지정되면 쌍이 together(; ) 또는 앰퍼샌드(&amp;)로 구분됩니다. 예 47.2. “쿼리 문자열이 포함된 URI” 쿼리 매개 변수가 있는 URI의 구문을 표시합니다.

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

javax.ws.rs.QueryParam 주석은 쿼리 매개 변수의 값을 추출하여 Cryostat-RS 리소스에 삽입합니다. 이 주석은 값을 추출하여 지정된 필드, Cryostat 속성 또는 매개 변수에 삽입하는 쿼리 매개변수의 이름을 식별하는 단일 매개 변수를 사용합니다. @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)
  {
    ...
  }
  ...
}

/monstersforhire/da Cryostatiju?id=jonas 에 대한 HTTP POST 를 처리하려면 updateMonster() 메서드 유형이 da Cryostati ju 로 설정되고 id 는 jonas 로 설정됩니다.

URI 매트릭스 매개 변수(예: URI 쿼리 매개변수)는 리소스를 선택하는 추가 정보를 제공할 수 있는 이름/값 쌍입니다. 쿼리 매개변수와 달리 매트릭스 매개 변수는 URI의 아무 곳에나 표시될 수 있으며, URI의 계층 경로 세그먼트와 분리되어 있습니다. /mostersforhire/da Cryostatiju;id=jonas 에는 id 및 /monstersforhire/japan;type=da Cryostatiju/flying;wingspan=40 이라는 하나의 매트릭스 매개변수가 있으며 유형 및 wingspan 이라는 두 개의 매트릭스 매개변수가 있습니다.

매트릭스 매개변수 값은 javax.ws.rs.MatrixParam 주석을 사용하여 필드, 매개변수 또는 8080 속성에 삽입됩니다. 이 주석은 값을 추출하여 지정된 필드, Cryostat 속성 또는 매개 변수에 삽입하는 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)
  {
    ...
  }
  ...
}

/monstersforhire;type=da Cryostatiju;id=whale 에 HTTP POST 를 처리하려면 updateMonster() 메서드 유형이 da Cryostati ju 로 설정되고 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 헤더로 사용할 수 있습니다. Cryostat-RS API는 HTTP 헤더 정보를 리소스 구현에 삽입하기 위한 간편한 메커니즘을 제공합니다.

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

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

If- Cryostat-Since 헤더 삽입 클래스의 가장 오래된Date 필드에 HTTP If- Cryostat- since 헤더의 값을 삽입하는 코드를 표시합니다.

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

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

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

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

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

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

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

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

리소스 메서드 매개변수에 데이터 삽입 양식 데이터를 매개 변수에 삽입하는 리소스 메서드를 표시합니다. 이 메서드는 클라이언트의 폼에 문자열 데이터를 포함하는 세 가지 필드제목,태그 및 본문을포함하는 것으로 가정합니다.

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, ... )
  ...

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

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

주석이 달린 매개 변수 유형인 Quarkus 또는 필드가 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 로 전송될 때 호출됩니다. 이 메서드에는 URI에 추가되는 두 개의 쿼리 매개 변수 id 및 type 이 필요합니다. 따라서 URI baseURI/monster?id=1&type=fom Cryostatiri 를 사용하는 GET 요청은 ID가 1인 Fom Cryostatiri를 반환합니다.

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

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

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

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

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

// 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 접근 방식을 사용하는 경우 form 매개변수를 빈 클래스인 TableOrder 의 필드에 직접 삽입할 수 있습니다. 사실, @PathParam,@QueryParam,@FormParam,@MatrixParam,@CookieParam, @HeaderParam , @HeaderParam 을 포함하여, 8080 클래스의 표준 Cryostat-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 리소스 메서드에 게시되면, Cryostat-RS 런타임은 TableOrder 인스턴스인 orderBean 을 자동으로 생성하고, Cryostat 클래스의 매개 변수 주석으로 지정된 모든 데이터를 삽입합니다.