18장. JAX-RS 엔드포인트 구성

XML에서 JAX-RS 서버 끝점을 정의하려면 최소한 다음을 지정해야 합니다.

다음 Blueprint XML 예제에서는 상대 주소를 지정하는 JAX-RS 엔드포인트를 정의하는 방법을 보여줍니다. /customers (기본 HTTP 컨테이너로 배포 가능)는 service.CustomerService 리소스 클래스에 의해 구현됩니다.

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs"
    xmlns:cxf="http://cxf.apache.org/blueprint/core"
    xsi:schemaLocation="
http://www.osgi.org/xmlns/blueprint/v1.0.0 https://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
http://cxf.apache.org/blueprint/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd
http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd
">

    <cxf:bus>
        <cxf:features>
            <cxf:logging/>
        </cxf:features>
    </cxf:bus>

     <jaxrs:server id="customerService" address="/customers">
        <jaxrs:serviceBeans>
           <ref component-id="serviceBean" />
        </jaxrs:serviceBeans>
     </jaxrs:server>

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

Blueprint에서 JAX-RS 엔드포인트를 정의하려면 일반적으로 다음과 같은 XML 네임스페이스가 필요합니다.

다음 Spring XML 예제에서는 상대 주소 /customers (기본 HTTP 컨테이너에 배포)를 지정하고 service.CustomerService 리소스 클래스에 의해 구현되는 JAX-RS 엔드포인트를 정의하는 방법을 보여줍니다.

<beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:jaxrs="http://cxf.apache.org/jaxrs"
      xsi:schemaLocation="
         http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
         http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd">

     <jaxrs:server id="customerService" address="/customers">
        <jaxrs:serviceBeans>
           <ref bean="serviceBean"/>
        </jaxrs:serviceBeans>
     </jaxrs:server>

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

Spring에서 JAX-RS 엔드포인트를 정의하려면 일반적으로 다음과 같은 XML 네임스페이스가 필요합니다.

(spring only) JAX-RS 루트 리소스 클래스를 명시적으로 지정하는 대신 Spring XML을 사용하면 자동 검색을 구성할 수 있으므로 특정 Java 패키지가 리소스 클래스( @Path에서 주석이 달린 클래스) 및 모든 검색된 리소스 클래스가 자동으로 엔드포인트에 연결됩니다. 이 경우 jaxrs:server 요소에서 address 속성과 basePackages 속성만 지정해야 합니다.

예를 들어 a.b.c Java 패키지에서 모든 JAX-RS 리소스 클래스를 사용하는 JAX-RS 엔드포인트를 정의하려면 다음과 같이 Spring XML에서 엔드포인트를 정의할 수 있습니다.

<jaxrs:server address="/customers" basePackages="a.b.c"/>

자동 검색 메커니즘은 지정된 Java 패키지에서 찾은 모든 JAX-RS 공급자 클래스도 엔드포인트에 검색하고 설치합니다.

(spring only) Spring XML을 사용하면 빈 요소에서 scope 속성을 설정하여 빈의 라이프사이클을 제어할 수 있습니다. Spring에서 다음 범위 값을 지원합니다.

Spring 범위에 대한 자세한 내용은 빈 범위에 대한 Spring 프레임워크 설명서 를 참조하십시오.

jaxrs:serviceBeans 요소를 통해 JAX-RS 리소스 빈을 지정하는 경우 Spring 범위가 제 대로 작동하지 않습니다. 이 경우 리소스 빈에 scope 속성을 지정하면 scope 속성이 효과적으로 무시됩니다.

빈 범위가 JAX-RS 서버 끝점 내에서 제대로 작동하도록 하려면 서비스 팩토리에서 제공하는 간접 수준이 필요합니다. 빈 범위를 구성하는 가장 간단한 방법은 다음과 같이 jaxrs:server 요소의 bean 특성을 사용하여 리소스 빈을 지정하는 것입니다.

<beans ... >
  <jaxrs:server id="customerService" address="/service1"
    beanNames="customerBean1 customerBean2"/>

  <bean id="customerBean1" class="demo.jaxrs.server.CustomerRootResource1" scope="prototype"/>
  <bean id="customerBean2" class="demo.jaxrs.server.CustomerRootResource2"  scope="prototype"/>
</beans>

위 예제에서는 두 개의 리소스 빈, customerBean1 및 customerBean2 를 구성합니다. beanNames 특성은 리소스 빈 ID의 공백으로 구분된 목록으로 지정됩니다.

궁극적인 수준의 유연성을 위해 jaxrs:serviceFactories 요소를 사용하여 JAX-RS 서버 엔드포인트를 구성할 때 서비스 팩토리 개체를 명시적으로 정의할 수 있습니다. 이러한 보다 자세한 접근 방식은 기본 서비스 팩토리 구현을 사용자 지정 구현으로 교체할 수 있다는 이점이 있으므로 빈 라이프사이클을 궁극적으로 제어할 수 있습니다. 다음 예제에서는 다음 방법을 사용하여 두 리소스 빈인 customerBean1 및 customerBean2 를 구성하는 방법을 보여줍니다.

<beans ... >
  <jaxrs:server id="customerService" address="/service1">
    <jaxrs:serviceFactories>
      <ref bean="sfactory1" />
      <ref bean="sfactory2" />
    </jaxrs:serviceFactories>
  </jaxrs:server>

  <bean id="sfactory1" class="org.apache.cxf.jaxrs.spring.SpringResourceFactory">
     <property name="beanId" value="customerBean1"/>
  </bean>
  <bean id="sfactory2" class="org.apache.cxf.jaxrs.spring.SpringResourceFactory">
     <property name="beanId" value="customerBean2"/>
  </bean>

  <bean id="customerBean1" class="demo.jaxrs.server.CustomerRootResource1" scope="prototype"/>
  <bean id="customerBean2" class="demo.jaxrs.server.CustomerRootResource2"  scope="prototype"/>
</beans>

jaxrs:server 요소의 docLocation 속성을 사용하여 WADL 문서를 JAX-RS 서버 끝점과 선택적으로 연결할 수 있습니다. 예를 들면 다음과 같습니다.

<jaxrs:server address="/rest" docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
      <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
</jaxrs:server>

JAX-B 형식의 메시지 콘텐츠를 설명하는 외부 XML 스키마가 있는 경우 jaxrs:schemaLocations 요소를 통해 이러한 외부 스키마를 JAX-RS 서버 끝점과 연결할 수 있습니다.

예를 들어 서버 끝점과 WADL 문서를 연결하고 수신되는 메시지에 대해 스키마 유효성 검사를 활성화하려면 다음과 같이 연결된 XML 스키마 파일을 지정할 수 있습니다.

<jaxrs:server address="/rest"
              docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
     <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
   <jaxrs:schemaLocations>
     <jaxrs:schemaLocation>classpath:/schemas/a.xsd</jaxrs:schemaLocation>
     <jaxrs:schemaLocation>classpath:/schemas/b.xsd</jaxrs:schemaLocation>
   </jaxrs:schemaLocations>
</jaxrs:server>

또는 지정된 디렉토리에 모든 스키마 파일 *.xsd 를 포함하려는 경우 다음과 같이 디렉터리 이름만 지정할 수 있습니다.

<jaxrs:server address="/rest"
              docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
     <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
   <jaxrs:schemaLocations>
     <jaxrs:schemaLocation>classpath:/schemas/</jaxrs:schemaLocation>
   </jaxrs:schemaLocations>
</jaxrs:server>

이러한 방식으로 스키마를 지정하는 것은 일반적으로 JAX-B 스키마에 액세스해야 하는 모든 종류의 기능에 유용합니다.

jaxrs:dataBinding 요소를 사용하여 메시지 본문을 요청 및 응답 메시지에서 인코딩하는 데이터 바인딩을 지정할 수 있습니다. 예를 들어 JAX-B 데이터 바인딩을 지정하려면 다음과 같이 JAX-RS 끝점을 구성할 수 있습니다.

<jaxrs:server id="jaxbbook" address="/jaxb">
  <jaxrs:serviceBeans>
    <ref bean="serviceBean" />
  </jaxrs:serviceBeans>
  <jaxrs:dataBinding>
    <bean class="org.apache.cxf.jaxb.JAXBDataBinding"/>
  </jaxrs:dataBinding>
</jaxrs:server>>

Aegis 데이터 바인딩을 지정하려면 다음과 같이 JAX-RS 끝점을 구성할 수 있습니다.

<jaxrs:server id="aegisbook" address="/aegis">
  <jaxrs:serviceBeans>
    <ref bean="serviceBean" />
  </jaxrs:serviceBeans>
  <jaxrs:dataBinding>
    <bean class="org.apache.cxf.aegis.databinding.AegisDatabinding">
      <property name="aegisContext">
        <bean class="org.apache.cxf.aegis.AegisContext">
          <property name="writeXsiTypes" value="true"/>
        </bean>
      </property>
    </bean>
  </jaxrs:dataBinding>
</jaxrs:server>

HTTP 대신 JMS 메시징 라이브러리를 전송 프로토콜로 사용하도록 JAX-RS를 구성할 수 있습니다. JMS 자체는 전송 프로토콜이 아니 므로 실제 메시징 프로토콜은 사용자가 구성하는 특정 JMS 구현에 따라 다릅니다.

예를 들어 다음 Spring XML 예제에서는 JMS 전송 프로토콜을 사용하도록 JAX-RS 서버 엔드포인트를 구성하는 방법을 보여줍니다.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:jms="http://cxf.apache.org/transports/jms"
       xmlns:jaxrs="http://cxf.apache.org/jaxrs"
       xsi:schemaLocation="
http://cxf.apache.org/transports/jms http://cxf.apache.org/schemas/configuration/jms.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd">

    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>
    <bean id="ConnectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="tcp://localhost:${testutil.ports.EmbeddedJMSBrokerLauncher}" />
    </bean>

    <jaxrs:server xmlns:s="http://books.com"
    	serviceName="s:BookService"
    	transportId= "http://cxf.apache.org/transports/jms"
    	address="jms:queue:test.jmstransport.text?replyToName=test.jmstransport.response">
        <jaxrs:serviceBeans>
            <bean class="org.apache.cxf.systest.jaxrs.JMSBookStore"/>
        </jaxrs:serviceBeans>
    </jaxrs:server>

</beans>

이전 예제에 대한 다음 사항에 유의하십시오.

JAX-RS 서버 끝점은 파일 접미사(URL에서 표시됨)를 MIME 콘텐츠 유형 헤더에 자동으로 매핑하도록 구성하고 언어 접미사를 언어 유형 헤더에 매핑할 수 있습니다. 예를 들어 다음 형식의 HTTP 요청을 고려하십시오.For example, consider a HTTP request of the following form:

GET /resource.xml

다음과 같이 .xml 접미사를 자동으로 매핑하도록 JAX-RS 서버 끝점을 구성할 수 있습니다.

<jaxrs:server id="customerService" address="/">
  <jaxrs:serviceBeans>
    <bean class="org.apache.cxf.jaxrs.systests.CustomerService" />
  </jaxrs:serviceBeans>
  <jaxrs:extensionMappings>
    <entry key="json" value="application/json"/>
    <entry key="xml" value="application/xml"/>
  </jaxrs:extensionMappings>
</jaxrs:server>

이전 서버 끝점에서 HTTP 요청을 수신하면 type, application/xml 의 새 콘텐츠 유형 헤더를 자동으로 생성하고 리소스 URL에서 .xml 접미사를 제거합니다.

언어 매핑의 경우 다음 형식의 HTTP 요청을 고려하십시오.For the language mapping, consider a HTTP request of the following form:

GET /resource.en

다음과 같이 JAX-RS 서버 끝점을 구성하여 .en 접미사가 자동으로 매핑할 수 있습니다.

<jaxrs:server id="customerService" address="/">
  <jaxrs:serviceBeans>
    <bean class="org.apache.cxf.jaxrs.systests.CustomerService" />
  </jaxrs:serviceBeans>
  <jaxrs:languageMappings>
     <entry key="en" value="en-gb"/>
  </jaxrs:languageMappings>
</jaxrs:server>

이전 서버 끝점에서 HTTP 요청을 수신하면 값이 en-gb 인 새 허용 언어 헤더를 자동으로 생성하고 리소스 URL에서 .en 접미사를 제거합니다.

표 18.1. “JAX-RS Server Endpoint Attributes” jaxrs:server 요소에서 사용 가능한 특성을 설명합니다.

표 18.2. “JAX-RS Server Endpoint Child Elements” jaxrs:server 요소의 하위 요소에 대해 설명합니다.