RESTful 애플리케이션에서 자원에 대한 미디어 유형 정의

자원은 많은 형식으로 표시될 수 있습니다. XML, JSON(JavaScript Object Notation), Atom, 2진 형식(예: PNG, JPEG, GIF), 일반 텍스트, 독점 형식을 사용하여 자원을 표시합니다. REST(Representational State Transfer)에서는 단일 자원을 다중 형식으로 표시하는 유연성을 제공합니다.

시작하기 전에

JAX-RS 웹 애플리케이션에서 자원을 정의합니다.

이 태스크 정보

자원에는 표시 방식이 있습니다. 자원 표시는 URI를 사용하여 자원에서 리턴하거나 자원으로 전송하는 HTTP 메시지의 컨텐츠입니다. 자원이 지원하는 각 표시에는 대응하는 미디어 유형이 있습니다. 예를 들어, 자원이 XML로 형식화된 컨텐츠를 리턴하려는 경우 HTTP 메시지에서 연관된 미디어 유형으로 application/xml을 사용할 수 있습니다.

애플리케이션의 요구사항에 따라 자원은 선호하는 단일 형식 또는 다중 형식으로 표시를 리턴할 수 있습니다. 예를 들어, JavaScript 클라이언트를 사용하여 액세스하는 자원은 JSON이 이용하기 쉽기 때문에 JSON 표시를 선호할 수 있습니다.

JAX-RS에서는 자원 메소드에서 읽고 쓰는 데 허용되는 미디어 유형을 선언하기 위해 @Consumes 및 @Produces 어노테이션을 제공합니다.

또한 JAX-RS는 엔티티 제공자를 사용하여 자원 표시 사이에서 Java™ 유형을 맵핑합니다. MessageBodyReader 엔티티 제공자는 요청 엔티티를 읽고, Java 유형으로 요청 엔티티를 직렬화 해제합니다. MessageBody쓰기r 엔티티 제공자는 Java 유형에서 응답 엔티티로 직렬화합니다.

표 1. 표준 엔티티 제공자 및 기본 Java 유형. 이 표는 대응하는 지원 컨텐츠 유형과 함께 JAX-RS 런타임 환경에 포함되는 기본적인 Java유형과 표준 엔티티 제공자를 포함합니다.
Java 유형 MessageBodyReader MessageBodyWriter 지원되는 컨텐츠 유형
byte[] X X */*
java.io.InputStream X X */*
java.io.Reader X X */*
java.lang.String X X */*
java.io.File X X */*
javax.activation.DataSource X X */*
javax.xml.transform.Source X X text/xml, application/xml, application/*+xml
javax.ws.rs.core.MultivaluedMap X X application/x-www-form-urlencoded
JAXB 유형 X X text/xml, application/xml, application/*+xml
javax.ws.rs.core.StreamingOutput   X */*

String 값이 요청 엔티티 매개변수로 사용되면 MessageBodyReader 엔티티 제공자는 요청 본문을 새 String으로 직렬화 해제합니다. JAXB 유형이 자원 메소드에서 리턴 유형으로 사용되면, MessageBodyWriter는 JAXB(Java Architecture for XML Binding) 오브젝트를 응답 본문으로 직렬화합니다.

Java 유형에서 특정 표시로 사용자 정의 맵핑이 필요한 경우 애플리케이션에서 정의한 엔티티 제공자 사용에 대한 정보를 참조하십시오.

클라이언트가 다중 형식을 처리할 수 있고 서버에서 리턴할 최상의 자원 표시를 판별하려면 다중 컨텐츠 유형을 지원하도록 JAX-RS 애플리케이션에서 컨텐츠 조정 사용을 참조하십시오.

XML, JSON, Atom에 대한 스펙은 애플리케이션에 대한 자원 표시 형식에 관한 세부사항을 제공합니다. 자원 표시 형식에 대해 자세히 학습하려면 스펙을 참조하십시오.

프로시저

  1. 요청 또는 응답에 사용할 XML, JSON 또는 ATOM과 같은 자원 표시 형식을 판별하십시오.
  2. 자원 메소드에 @Consumes 및 @Produces 어노테이션을 적절히 추가하십시오.
  3. 자원이 요청 컨텐츠를 읽어야 하는 경우 자원 메소드에 요청 엔티티 매개변수를 추가하십시오. 요청 엔티티 매개변수는 어노테이션이 없는 메소드에서 단일 Java 매개변수에 해당합니다.
  4. 자원 메소드가 응답에서 컨텐츠를 리턴하면 JAX-RS 엔티티 제공자가 쓸 수 있는 Java 오브젝트를 리턴하십시오. 이 Java 오브젝트는 HTTP 응답에서 응답 엔티티에 맵핑됩니다. 리턴된 엔티티는 JAX-RS이 지원하는 Java 유형이거나 javax.ws.rs.core.Response 또는 javax.ws.rs.core.GenericEntity 유형으로 랩핑되어야 합니다.

결과

자원 메소드 엔티티 매개변수에 요청 엔티티를 맵핑하며, 리턴되는 응답 오브젝트는 자원 표시를 위해 응답 엔티티에 맵핑됩니다.

다음 예제는 RESTful 서점 스토어 애플리케이션에 대한 자원 표시로 XML을 정의하는 방법을 보여줍니다.

  1. 요청 엔티티를 읽거나 요청 엔티티를 리턴하려는 자원 메소드를 식별하십시오.

    뒤에 나오는 retrieveSpecificBookInformation 메소드 예제에서 읽은 요청 엔티티가 없습니다. 그러나 응답 오브젝트는 리턴됩니다. 이 오브젝트는 엔티티 정보를 포함하는 JAXB 오브젝트를 랩핑합니다. 미디어 유형이 application/xml인 자원 메소드에서 @Produces 어노테이션을 추가하면 자원 메소드가 항상 미디어 유형이 application/xml인 XML 표시를 리턴함을 나타냅니다.

    HTTP 요청 승인 헤더 값이 application/xml 미디어 유형과 호환 가능한 클라이언트는 메소드를 올바르게 호출합니다.

    application/xml 미디어 유형과 호환 가능한 HTTP 승인 헤더 값이 없는 클라이언트는 자동으로 406 Not Acceptable 응답 상태(서버가 허용할 수 있는 응답을 생성할 수 없음을 나타냄)를 수신합니다.

    다음 예제는 요청 엔티티를 읽거나 응답 엔티티를 리턴하는 자원 메소드를 식별합니다.

    /*
     * Book.java
     * This class represents individual books. The @Produces annotation specifies a media type of application/xml.
     */
    @Path(“/bookstore/books/{bookID}”)
    public class Book {
      @GET
      @Produces(“application/xml”)
      public javax.ws.rs.core.Response retrieveSpecificBookInformation(@PathParam(“bookID”) String theBookID,
       @Context javax.ws.rs.core.HttpHeaders headers) {
       /* … */
       return
        Response.ok(/* JAXB object to represent response body entity */).expires(/* Expires response header value*/).header(“CustomHeaderName”, “CustomHeaderValue”).build();
       }
       @PUT
       public String updateBookInformation(@PathParam(“bookID”) String theBookID, String theRequestEntity,
        @javax.ws.rs.HeaderParam(“Content-Length”) String contentLengthHeader) { /* … */ }
    
       @DELETE
       public void removeBook(@PathParam(“bookID”) String theBookID) { /* … */ }
    }
  2. 요청 정보를 이용해야 하는 자원 메소드를 식별하십시오.

    다음 스니펫에서 @Consumes 어노테이션에 정의된 대로, text/plain의 미디어 유형을 전송하면 서적 자원의 PUT 메소드는 요청 엔티티 컨텐츠를 승인합니다. 이 메소드는 @Produces 어노테이션에 지정된 대로, text/plain 표시를 포함하는 컨텐츠를 리턴합니다.

    클라이언트가 text/plain의 Content-Type 값을 포함하는 메시지를 전송하지 않으면, PUT 자원 메소드는 호출되지 않습니다. Content-Type: application/xml이 HTTP 요청 헤더에서 전송되면 updateBookInformation Java 메소드는 호출되지 않습니다.

    DELETE 메소드는 요청 엔티티를 읽거나 응답 엔티티를 리턴하지 않습니다. 따라서 @Consumes 또는 @Produces 어노테이션이 필요하지 않습니다.

    다음 예제는 요청 정보를 이용하는 자원 메소드를 식별합니다.

    /*
     * Book.java
     * This class represents represent individual books with custom headers.
     */
    @Path(“/bookstore/books/{bookID}”)
    public class Book {
      @GET
      @Produces(“application/xml”)
      public javax.ws.rs.core.Response retrieveSpecificBookInformation(@PathParam(“bookID”) String theBookID, @Context javax.ws.rs.core.HttpHeaders headers) {
        /* … */
        return Response.ok(/* JAXB object to represent response body entity */).expires(/* Expires response header value).header(“CustomHeaderName”, “CustomHeaderValue”).build();
      }
      @PUT
      @Consumes(“text/plain”)
      @Produces(“text/plain”)
      public String updateBookInformation(@PathParam(“bookID”) String theBookID, String theRequestEntity, @javax.ws.rs.HeaderParam(“Content-Length”) String contentLengthHeader) {
        /* … */
        String responseEntity = /* a plain text representation */;
        return responseEntity;
      }
    
      @DELETE
      public void removeBook(@PathParam(“bookID”) String theBookID) { /* … */ }
    }

다음에 수행할 작업

표시에 대해 지원되는 모든 표준 미디어 형식 목록은 JAX-RS 스펙을 참조하십시오.

고급 사용자는 클라이언트가 선호하는 자원 표시를 조정하기 위해 컨텐츠 조정을 사용하거나 표시에 대한 Java 유형의 사용자 정의 맵핑을 정의하는 방법을 고려할 수도 있습니다. 이 옵션에 대해 자세히 학습하려면 사용자 정의된 엔티티 형식 사용 정보 또는 컨텐츠 조정으로 다중 컨텐츠 유형 지원 정보를 참조하십시오.


주제 유형을 표시하는 아이콘 태스크 주제



시간소인 아이콘 마지막 업데이트 날짜: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_mediatype
파일 이름:twbs_jaxrs_defresource_mediatype.html