18장. Cryostat-RS 끝점 구성

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

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

<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>

블루프린트에 Cryostat-RS 끝점을 정의하려면 일반적으로 다음 XML 네임스페이스가 필요합니다.

다음 Spring XML 예제에서는 상대 주소, /customers (기본 HTTP 컨테이너에 배포됨)를 지정하고 service.CustomerService 리소스 클래스에 의해 구현되는 Cryostat-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에서 Cryostat-RS 끝점을 정의하려면 일반적으로 다음 XML 네임스페이스가 필요합니다.

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

예를 들어 a.b.c Java 패키지 아래에 있는 모든 Cryostat-RS 리소스 클래스를 사용하는 Cryostat-RS 끝점을 정의하려면 다음과 같이 Spring XML에서 끝점을 정의할 수 있습니다.

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

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

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

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

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

Cryostat-RS 서버 엔드포인트 내에서 8080 범위가 제대로 작동하도록 하려면 서비스 팩토리에서 제공하는 간접 수준이 필요합니다. Quarkus 범위를 구성하는 가장 간단한 방법은 다음과 같이 jaxrs:server 요소에서 8080 Names 속성을 사용하여 리소스 빈 을 지정하는 것입니다.

<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 를 구성합니다. Cryo statNames 속성은 공백으로 구분된 리소스 8080 ID 목록으로 지정됩니다.

궁극적인 유연성 수준을 위해 jaxrs:serviceFactories 요소를 사용하여 Cryostat-RS 서버 엔드포인트를 구성할 때 서비스 팩토리 오브젝트를 명시적으로 정의할 수 있는 옵션이 있습니다. 이 보다 자세한 접근 방식은 기본 서비스 팩토리 구현을 사용자 지정 구현으로 대체할 수 있다는 장점이 있으므로, Cryostat 라이프사이클을 완벽하게 제어할 수 있습니다. 다음 예제에서는 다음 방법을 사용하여 두 개의 리소스 빈, 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 문서를 Cryostat-RS 서버 끝점과 연결할 수 있습니다. 예를 들면 다음과 같습니다.

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

Cryostat-B 형식의 메시지 콘텐츠를 설명하기 위해 일부 외부 XML 스키마가 있는 경우 jaxrs:schemaLocations 요소를 통해 이러한 외부 스키마를 Cryostat-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>

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

jaxrs:dataBinding 요소를 사용하여 요청 및 응답 메시지에서 메시지 본문을 인코딩하는 데이터 바인딩을 지정할 수 있습니다. 예를 들어 Cryostat-B 데이터 바인딩을 지정하려면 다음과 같이 Cryostat-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 데이터 바인딩을 지정하려면 다음과 같이 Cryostat-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 메시징 라이브러리를 전송 프로토콜로 사용하도록 Cryostat-RS를 구성할 수 있습니다. JMS 자체는 전송 프로토콜이 아니므로 실제 메시징 프로토콜은 구성하는 특정 JMS 구현에 따라 다릅니다.

예를 들어 다음 Spring XML 예제에서는 JMS 전송 프로토콜을 사용하도록 Cryostat-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>

이전 예에 대해서는 다음 사항에 유의하십시오.

Cryostat-RS 서버 끝점은 파일 접미사(URL에 표시되는)를 MIME 콘텐츠 유형 헤더에 자동으로 매핑하고 언어 접미사를 언어 유형 헤더에 매핑하도록 구성할 수 있습니다. 예를 들어 다음 양식의 HTTP 요청을 고려하십시오.

GET /resource.xml

다음과 같이 .xml 접미사를 자동으로 매핑하도록 Cryostat-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 요청을 고려하십시오.

GET /resource.en

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

<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.en 접미사를 사용하여 새 수락 언어 헤더를 자동으로 생성하고 리소스 URL에서 .en 접미사를 제거합니다.

표 18.1. “Cryostat-RS Server 끝점 속성” jaxrs:server 요소에서 사용할 수 있는 특성에 대해 설명합니다.

표 18.2. “Cryostat-RS Server Endpoint Cryostat” jaxrs:server 요소의 하위 요소를 설명합니다.