Red Hat Training

A Red Hat training course is available for Red Hat Fuse

18.3. 모델 스키마를 사용하여 REST 서비스 정의

18.3.1. 주석이 없는 RESTful 서비스

JAX-RS 모델 스키마를 사용하면 Java 클래스에 주석을 달지 않고 RESTful 서비스를 정의할 수 있습니다. 즉, @Path , @Path Param,@Consumes, @Consumes ,@ Consumes , @tentSourcePolicy 등과 같은 주석을 Java 클래스(또는 인터페이스)에 직접 추가하는 대신, 모델 스키마를 사용하여 모든 관련 REST 메타데이터를 별도의 XML 파일에 제공할 수 있습니다. 예를 들어 서비스를 구현하는 Java 소스를 수정할 수 없는 경우 유용합니다.

18.3.2. 모델 스키마 예

예 18.1. “샘플 JAX-RS 모델 스키마” BookStoreNoAnnotations 루트 리소스 클래스에 대한 서비스 메타데이터를 정의하는 모델 스키마의 예를 보여줍니다.

예 18.1. 샘플 JAX-RS 모델 스키마

<model xmlns="http://cxf.apache.org/jaxrs">
  <resource name="org.apache.cxf.systest.jaxrs.BookStoreNoAnnotations" path="bookstore"
    produces="application/json" consumes="application/json">
    <operation name="getBook" verb="GET" path="/books/{id}" produces="application/xml">
       <param name="id" type="PATH"/>
    </operation>
    <operation name="getBookChapter" path="/books/{id}/chapter">
       <param name="id" type="PATH"/>
    </operation>
    <operation name="updateBook" verb="PUT">
       <param name="book" type="REQUEST_BODY"/>
    </operation>
  </resource>
  <resource name="org.apache.cxf.systest.jaxrs.ChapterNoAnnotations">
    <operation name="getItself" verb="GET"/>
    <operation name="updateChapter" verb="PUT" consumes="application/xml">
        <param name="content" type="REQUEST_BODY"/>
    </operation>
  </resource>
</model>

18.3.3. 네임스페이스

모델 스키마를 정의하는 데 사용하는 XML 네임스페이스는 Blueprint XML에서 해당 JAX-RS 엔드포인트를 정의하는지 또는 Spring XML에서 정의하는지에 따라 달라집니다. 다음 표에서는 어떤 XML 언어에 사용할 네임스페이스를 보여줍니다.

XML 언어네임스페이스

Blueprint

http://cxf.apache.org/blueprint/jaxrs

Spring

http://cxf.apache.org/jaxrs

18.3.4. 끝점에 모델 스키마를 연결하는 방법

모델 스키마를 끝점에 정의하고 연결하려면 다음 단계를 수행합니다.

  1. 선택한 주입 플랫폼(Blueprint XML 또는 Spring XML)에 적합한 XML 네임스페이스를 사용하여 모델 스키마를 정의합니다.

  2. 모델 스키마 파일을 프로젝트의 리소스에 추가하여 스키마 파일을 최종 패키지(JAR, WAR 또는 OSGi 번들 파일)의 classpath에서 사용할 수 있도록 합니다.

    참고

    또는 엔드포인트의 jaxrs:model 하위 요소를 사용하여 모델 스키마를 JAX-RS 엔드포인트에 직접 포함할 수도 있습니다.

  3. 엔드포인트의 model 스키마를 classpath의 모델 스키마 위치로 설정하여 모델 스키마를 사용하도록 엔드포인트를 구성합니다(classpath URL 사용).
  4. 필요한 경우 jaxrs:serviceBeans 요소를 사용하여 루트 리소스를 명시적으로 인스턴스화합니다. 모델 스키마에서 루트 리소스 클래스를 직접 참조하는 경우(기본 인터페이스 참조 대신) 이 단계를 건너뛸 수 있습니다.

18.3.5. 클래스를 참조하는 모델 스키마 구성

모델 스키마가 루트 리소스 클래스에 직접 적용되는 경우 모델 스키마가 루트 리소스 빈을 자동으로 인스턴스화하므로 jaxrs:serviceBeans 요소를 사용하여 루트 리소스 빈을 정의할 필요가 없습니다.

예를 들어 customer-resources.xml 이 메타데이터를 고객 리소스 클래스와 연결하는 모델 스키마로 설정된 경우 다음과 같이 customerService 서비스 끝점을 인스턴스화할 수 있습니다. 

<jaxrs:server id="customerService"
              address="/customers"
              modelRef="classpath:/org/example/schemas/customer-resources.xml" />

18.3.6. 인터페이스를 참조하는 모델 스키마 구성

모델 스키마가 루트 리소스의 기본 인터페이스인 Java 인터페이스에 적용되는 경우 엔드포인트에서 jaxrs:serviceBeans 요소를 사용하여 루트 리소스 클래스를 인스턴스화해야 합니다.

예를 들어 customer-interfaces.xml 이 메타데이터를 고객 인터페이스와 연결하는 모델 스키마라고 가정하면 다음과 같이 customerService 서비스 엔드 포인트를 인스턴스화할 수 있습니다. 

<jaxrs:server id="customerService"
              address="/customers"
              modelRef="classpath:/org/example/schemas/customer-interfaces.xml">
    <jaxrs:serviceBeans>
       <ref component-id="serviceBean" />
    </jaxrs:serviceBeans>
</jaxrs:server>

<bean id="serviceBean" class="service.CustomerService"/>

18.3.7. 모델 스키마 참조

모델 스키마는 다음 XML 요소를 사용하여 정의됩니다.A model schema is defined using the following XML elements:

model
모델 스키마의 루트 요소입니다. model 스키마를 참조해야 하는 경우(예: modelRef 특성을 사용하는 JAX-RS 끝점에서 이 요소에 대한 id 특성을 설정해야 합니다.
model/resource

리소스 요소는 메타데이터를 특정 루트 리소스 클래스(또는 해당 인터페이스와 연결)하는 데 사용됩니다. 리소스 요소에서 다음 속성을 정의할 수 있습니다.

속성description +

name

이 리소스 모델이 적용되는 리소스 클래스(또는 해당 인터페이스)의 이름입니다.

+

path

이 리소스에 매핑되는 REST URL 경로의 구성 요소입니다.

+

consumes

이 리소스에서 사용하는 콘텐츠 유형(인터넷 미디어 유형)을 지정합니다(예: application/xml 또는 application/json ).

+

produces

이 리소스에서 생성한 콘텐츠 유형(인터넷 미디어 유형)을 지정합니다(예: application/xml 또는 application/json ).

+

model/resource/operation

작업 요소는 메타데이터를 Java 메서드와 연결하는 데 사용됩니다. 작업 요소에서 다음 특성을 정의할 수 있습니다.

속성description +

name

이 요소가 적용되는 Java 메서드의 이름입니다.

+

path

이 메서드에 매핑되는 REST URL 경로의 구성 요소입니다. 이 특성 값에는 매개변수 참조(예: path="/books/{id}/chapter" )가 포함될 수 있으며, 여기서 {id} 는 경로에서 id 매개 변수 값을 추출합니다.

+

verb

이 메서드에 매핑되는 HTTP 동사를 지정합니다. 일반적으로 GET,POST,PUT 또는 DELETE 중 하나입니다. HTTP 동사를 지정하지 않으면 Java 메서드가 하위 리소스 오브젝트에 대한 참조를 반환하는 하위 리소스 locater 이라고 가정합니다(sub- resource 클래스는 리소스 요소를 사용하는 메타데이터도 제공해야 함).

+

consumes

이 작업에서 사용하는 콘텐츠 유형(인터넷 미디어 유형)을 지정합니다(예: application/xml 또는 application/json ).

+

produces

이 작업에서 생성한 콘텐츠 유형(인터넷 미디어 유형)을 지정합니다(예: application/xml 또는 application/json ).

+

oneWay

true 인 경우 작업을 단방향 으로 구성합니다. 즉 응답 메시지가 필요하지 않습니다. 기본값은 false입니다.

+

model/resource/operation/param

param 요소는 REST URL에서 값을 추출하여 메서드 매개변수 중 하나에 삽입합니다. param 요소에서 다음 속성을 정의할 수 있습니다.

속성description +

name

이 요소가 적용되는 Java 메서드 매개 변수의 이름입니다.

+

type

REST URL 또는 메시지에서 매개변수 값을 추출하는 방법을 지정합니다. PATH,QUERY,MATRIX,HEADER,COOKIE,FORM,CONTEXT,REQUEST_BODY 값 중 하나로 설정할 수 있습니다.

+

defaultValue

REST URL 또는 메시지에서 값을 추출할 기본값입니다.

+

인코딩

true 인 경우 매개 변수 값이 URI 인코딩 형식으로 삽입됩니다(즉, %nn 인코딩 사용). 기본값은 false 입니다. 예를 들어, URL 경로에서 매개 변수를 추출하는 경우, 인코딩이 true 로 설정된 /name/Joe%20Bloggs 에서 매개 변수를 추출할 때 매개 변수가 Joe%20Bloggs 로 삽입되고, 그렇지 않으면 매개 변수가 Joe Bloggs 로 삽입됩니다.

+