24.3. 코드 주석 달기

24.3.1. JAX-WS 주석 개요

JAX-WS 주석은 SEI를 완전히 지정된 서비스 정의에 매핑하는 데 사용되는 메타데이터를 지정합니다. 주석에 제공된 정보 중 하나는 다음과 같습니다.

  • 서비스의 대상 네임스페이스입니다.
  • 요청 메시지를 보유하는 데 사용되는 클래스의 이름입니다.
  • 응답 메시지를 보유하는 데 사용되는 클래스의 이름입니다.
  • 작업을 한 가지 방법으로 수행 하는 경우If an operation is a one way
  • 서비스에서 사용하는 바인딩 스타일
  • 사용자 지정 예외에 사용되는 클래스의 이름입니다.
  • 서비스에서 사용하는 유형이 정의된 네임스페이스
참고

대부분의 주석에는 적절한 기본값이 있으며 해당 주석에 값을 제공할 필요가 없습니다. 그러나 주석에 제공하는 정보가 많을수록 서비스 정의가 더 잘 지정됩니다. 잘 지정되어 있는 서비스 정의는 분산 애플리케이션의 모든 부분이 함께 작동할 가능성이 높아집니다.

24.3.2. 필수 주석

24.3.2.1. 개요

Java 코드에서 서비스를 생성하려면 코드에 주석을 하나만 추가해야 합니다. SEI 및 구현 클래스 모두에 @WebService 주석을 추가해야 합니다.

24.3.2.2. @WebService 주석

@WebService 주석은 javax.jws.WebService 인터페이스에서 정의되며 인터페이스 또는 서비스로 사용할 클래스에 배치됩니다. @WebService 에 설명 된 속성이 있습니다. 표 24.1. “@WebService 속성”

표 24.1. @WebService 속성

속성설명

name

서비스 인터페이스의 이름을 지정합니다. 이 속성은 WSDL 계약에서 서비스 인터페이스를 정의하는 wsdl:portType 요소의 name 속성에 매핑됩니다. 기본값은 구현 클래스 이름에 PortType 을 추가하는 것입니다.[a]

targetNamespace

서비스가 정의된 대상 네임스페이스를 지정합니다. 이 속성을 지정하지 않으면 대상 네임스페이스는 패키지 이름에서 파생됩니다.If this property is not specified, the target namespace is derived from the package name.

serviceName

게시된 서비스의 이름을 지정합니다. 이 속성은 게시된 서비스를 정의하는 wsdl:service 요소의 name 속성에 매핑됩니다. 기본값은 서비스 구현 클래스의 이름을 사용하는 것입니다.

wsdlLocation

서비스의 WSDL 계약이 저장되는 URL을 지정합니다. 상대 URL을 사용하여 지정해야 합니다. 기본값은 서비스가 배포되는 URL입니다.

endpointInterface

구현 클래스에서 구현하는 SEI의 전체 이름을 지정합니다. 이 속성은 서비스 구현 클래스에서 특성이 사용되는 경우에만 지정됩니다.

portName

서비스가 게시되는 끝점의 이름을 지정합니다. 이 속성은 게시된 서비스의 끝점 세부 정보를 지정하는 wsdl:port 요소의 name 속성에 매핑됩니다. 기본값은 서비스 구현 클래스 이름에 추가 포트입니다.

[a] SEI에서 WSDL을 생성할 때 구현 클래스 이름 대신 인터페이스의 이름이 사용됩니다.
참고

@WebService 주석 속성의 값을 제공할 필요가 없습니다. 그러나 가능한 한 많은 정보를 제공하는 것이 좋습니다.

24.3.2.3. SEI에 주석 달기

SEI에서는 @WebService 주석을 추가해야 합니다. SEI는 서비스를 정의하는 계약이므로 @WebService 주석 속성에서 서비스에 대해 가능한 한 자세히 지정해야 합니다.

예 24.3. “@WebService 주석과 인터페이스”@WebService 주석을 사용하여 예 24.1. “간단한 SEI” 에 정의된 인터페이스를 표시합니다.

예 24.3. @WebService 주석과 인터페이스

package com.fusesource.demo;

import javax.jws.*;

@WebService(name="quoteUpdater",
            targetNamespace="http://demos.redhat.com",
	        serviceName="updateQuoteService",
            wsdlLocation="http://demos.redhat.com/quoteExampleService?wsdl",
            portName="updateQuotePort")
public interface quoteReporter
{
  public Quote getQuote(String ticker);
}

예 24.3. “@WebService 주석과 인터페이스”@WebService 주석은 다음과 같습니다.

서비스 인터페이스를 정의하는 wsdl:portType 요소의 name 속성 값이 quoteUpdater 임을 지정합니다.

서비스의 대상 네임스페이스가 http://demos.redhat.com 임을 지정합니다.

게시된 서비스를 정의하는 wsdl:service 요소의 값이 updateQuoteService 임을 지정합니다.

서비스가 http://demos.redhat.com/quoteExampleService?wsdl 에서 WSDL 계약을 게시하도록 지정합니다.

서비스를 노출하는 엔드포인트를 정의하는 wsdl:port 요소의 name 속성 값이 updateQuotePort 임을 지정합니다.

24.3.2.4. 서비스 구현에 주석 달기

@WebService 주석으로 SEI에 주석을 추가하는 것 외에도 @WebService 주석을 사용하여 서비스 구현 클래스에 주석을 달아야 합니다. 서비스 구현 클래스에 주석을 추가할 때 endpointInterface 속성만 지정해야 합니다. 예 24.4. “주석이 달린 서비스 구현 클래스” 에 표시된 대로 속성은 SEI의 전체 이름으로 설정해야 합니다.

예 24.4. 주석이 달린 서비스 구현 클래스

package org.eric.demo;

import javax.jws.*;

@WebService(endpointInterface="com.fusesource.demo.quoteReporter")
public class stockQuoteReporter implements quoteReporter
{
public Quote getQuote(String ticker)
  {
  ...
  }
}

24.3.3. 선택적 주석

초록

@WebService 주석은 Java 인터페이스 또는 Java 클래스를 활성화하는 서비스에 충분하지만 서비스 공급자로 서비스가 노출되는 방법을 완전히 설명하지는 않습니다. JAX-WS 프로그래밍 모델은 사용하는 바인딩과 같이 서비스에 대한 세부 정보를 Java 코드에 추가하는 데 다양한 선택적 주석을 사용합니다. 이러한 주석을 서비스의 SEI에 추가합니다.

SEI에 제공하는 세부 정보가 많을수록 개발자가 정의하는 기능을 사용할 수 있는 애플리케이션을 더 쉽게 구현할 수 있습니다. 또한 도구에서 생성된 WSDL 문서를 보다 구체적으로 만듭니다.

24.3.3.1. 개요

주석을 사용하여 바인딩 속성 정의

서비스에 SOAP 바인딩을 사용하는 경우 JAX-WS 주석을 사용하여 여러 바인딩 속성을 지정할 수 있습니다. 이러한 속성은 서비스의 WSDL 계약에 지정할 수 있는 속성에 직접 해당합니다. 매개 변수 스타일과 같은 일부 설정은 메서드를 구현하는 방법을 제한할 수 있습니다. 이러한 설정은 메서드 매개 변수에 주석을 달 때 사용할 수 있는 주석에도 영향을 미칠 수 있습니다.

24.3.3.2. @SOAPBinding 주석

@SOAPBinding 주석은 javax.jws.soap.SOAPBinding 인터페이스에서 정의됩니다. 배포 시 서비스에서 사용하는 SOAP 바인딩에 대한 세부 정보를 제공합니다. @SOAPBinding 주석을 지정하지 않으면 래핑된 doc/literal SOAP 바인딩을 사용하여 서비스가 게시됩니다.

SEI 및 SEI의 메서드에 @SOAPBinding 주석을 넣을 수 있습니다. 메서드에서 사용하는 경우 메서드의 @SOAPBinding 주석이 설정됩니다.

표 24.2. “@SOAPBinding 속성” @SOAPBinding 주석의 속성을 표시합니다.

표 24.2. @SOAPBinding 속성

속성설명

style

style.DOCUMENT(기본값)

Style.RPC

SOAP 메시지의 스타일을 지정합니다. RPC 스타일을 지정하면 SOAP 본문 내의 각 메시지 부분이 매개변수 또는 반환 값이며 soap:body 요소 내의 래퍼 요소 내에 표시됩니다. 래퍼 요소 내의 메시지 부분은 작업 매개 변수에 해당하며 작업의 매개변수와 동일한 순서로 표시되어야 합니다. DOCUMENT 스타일을 지정 하는 경우 SOAP 본문의 내용은 유효한 XML 문서 여야 하지만 폼이 엄격한 제한 되지 않습니다.If DOCUMENT style is specified, the contents of the SOAP body must be a valid XML document, but its form is not as tightly constrained.

Use

use.LITERAL(기본값)

Use.ENCODED[a]

SOAP 메시지의 데이터를 스트리밍하는 방법을 지정합니다.Specifies how the data of the SOAP message is streamed.

parameterStyle [b]

ParameterStyle.BARE

ParameterStyle.WRAPPED (기본값)

WSDL 계약의 메시지 부분에 해당하는 메서드 매개 변수가 SOAP 메시지 본문에 배치되는 방법을 지정합니다.Specifies how the method parameters, which correspond to message parts in a WSDL contract, are placed into the SOAP message body. BARE를 지정하면 각 매개 변수가 메시지 본문에 메시지 루트의 하위 요소로 배치됩니다. WRAPPED를 지정하면 모든 입력 매개 변수가 요청 메시지의 단일 요소로 래핑되고 모든 출력 매개 변수는 응답 메시지의 단일 요소로 래핑됩니다.

[a] Use.ENCODED는 현재 지원되지 않습니다.
[b] 스타일 을 RPC로 설정하는 경우 WRAPPED 매개변수 스타일을 사용해야 합니다.

24.3.3.3. 문서 베어 스타일 매개변수

문서 베어 스타일은 Java 코드 간의 가장 직접적인 매핑이며 서비스의 결과 XML 표현입니다. 이 스타일을 사용하면 작업의 매개 변수 목록에 정의된 입력 및 출력 매개변수에서 스키마 유형이 직접 생성됩니다.

style 속성이 Style.DOCUMENT로 설정된 @SOAPBinding 주석을 사용하여 베어 문서\literal 스타일 을 사용하고 해당 parameterStyle 속성을 ParameterStyle.BARE로 설정하도록 지정합니다.

베어 매개 변수를 사용할 때 문서 스타일 사용 제한 사항을 위반하지 않도록 하려면 작업이 다음 조건을 준수해야 합니다.

  • 작업에는 입력 또는 입력/출력 매개변수가 두 개 이상 있어야 합니다.
  • 작업에 void 이외의 반환 유형이 있는 경우 출력 또는 입력/출력 매개변수가 없어야 합니다.
  • 작업에 void 의 반환 유형이 있는 경우 출력 또는 입력/출력 매개 변수가 없어야 합니다.
참고

@WebParam 주석 또는 @WebResult 주석을 사용하여 SOAP 헤더에 배치된 모든 매개변수는 허용된 매개 변수 수에 대해 계산되지 않습니다.

24.3.3.4. 래핑된 매개변수 문서

문서 래핑 스타일을 사용하면 Java 코드 간 매핑과 서비스의 결과 XML 표현과 같은 더 많은 RPC를 사용할 수 있습니다. 이 스타일을 사용하면 메서드의 매개 변수 목록의 매개 변수가 바인딩에 의해 단일 요소로 래핑됩니다. 이 문제의 단점은 Java 구현 간의 간접 계층과 메시지가 유선에 배치되는 방식을 도입한다는 것입니다.

래핑된 document\literal 스타일을 사용하도록 지정하려면 style 속성이 Style.DOCUMENT로 설정된 @SOAPBinding 주석을 사용하고 해당 parameterStyle 속성을 ParameterStyle.WRAPPED로 설정합니다.

“@RequestWrapper 주석” 주석 및 “@ResponseWrapper 주석” 주석을 사용하여 래퍼를 생성하는 방법을 제어할 수 있습니다.

24.3.3.5. 예제

예 24.5. “SOAP Binding Annotation을 사용하여 문서 Bare SOAP 바인딩 지정” 문서 베어 SOAP 메시지를 사용하는 SEI를 보여줍니다.

예 24.5. SOAP Binding Annotation을 사용하여 문서 Bare SOAP 바인딩 지정

package org.eric.demo;

import javax.jws.*;
import javax.jws.soap.*;
import javax.jws.soap.SOAPBinding.*;

@WebService(name="quoteReporter")
@SOAPBinding(parameterStyle=ParameterStyle.BARE)
public interface quoteReporter
{
  ...
}

24.3.3.6. 개요

주석을 사용하여 작업 속성 정의

런타임이 Java 메서드 정의를 XML 작업 정의에 매핑하면 다음과 같은 세부 정보를 제공합니다.

  • 교환된 메시지는 XML에서 어떻게 보이는지
  • 메시지를 한 가지 방법으로 최적화할 수 있는 경우
  • 메시지가 정의된 네임스페이스

24.3.3.7. @WebMethod 주석

@WebMethod 주석은 javax.jws.WebMethod 인터페이스에서 정의됩니다. SEI의 메서드에 배치됩니다. @WebMethod 주석은 메서드가 연결된 작업을 설명하는 wsdl:operation 요소에 일반적으로 표시되는 정보를 제공합니다.

표 24.3. “@WebMethod Properties” @WebMethod 주석의 속성을 설명합니다.

표 24.3. @WebMethod Properties

속성설명

operationName

관련 wsdl:operation 요소의 이름 의 값을 지정합니다. 기본값은 메서드의 이름입니다.

작업

메서드에 대해 생성된 soap:operation 요소의 soapAction 특성 값을 지정합니다. 기본값은 빈 문자열입니다.

exclude

메서드를 서비스 인터페이스에서 제외해야 하는지 여부를 지정합니다. 기본값은 false입니다.

24.3.3.8. @RequestWrapper 주석

@RequestWrapper 주석은 javax.xml.ws.RequestWrapper 인터페이스에서 정의됩니다. SEI의 메서드에 배치됩니다. @RequestWrapper 주석은 메시지 교환을 시작하는 요청 메시지의 메서드 매개변수에 래퍼 빈을 구현하는 Java 클래스를 지정합니다. 또한 요청 메시지를 마샬링 및 해제할 때 런타임에서 사용하는 요소 이름과 네임스페이스를 지정합니다.

표 24.4. “@RequestWrapper 속성” @RequestWrapper 주석의 속성을 설명합니다.

표 24.4. @RequestWrapper 속성

속성설명

localName

요청 메시지의 XML 표현에 래퍼 요소의 로컬 이름을 지정합니다.Specifies the local name of the wrapper element in the XML representation of the request message. 기본값은 메서드의 이름 또는 “@WebMethod 주석” 주석의 operationName 속성 값입니다.

targetNamespace

XML 래퍼 요소가 정의된 네임스페이스를 지정합니다. 기본값은 SEI의 대상 네임스페이스입니다.

className

래퍼 요소를 구현하는 Java 클래스의 전체 이름을 지정합니다.

참고

className 속성만 필요합니다.

중요

메서드에 @SOAPBinding 주석을 추가하고 해당 parameterStyle 속성이 ParameterStyle.BARE 로 설정된 경우 이 주석은 무시됩니다.

24.3.3.9. @ResponseWrapper 주석

@ResponseWrapper 주석은 javax.xml.ws.ResponseWrapper 인터페이스에서 정의됩니다. SEI의 메서드에 배치됩니다. @ResponseWrapper 는 메시지 교환의 응답 메시지에 메서드 매개 변수에 대한 래퍼 빈을 구현하는 Java 클래스를 지정합니다. 또한 응답 메시지를 마샬링 및 해제할 때 런타임에서 사용하는 요소 이름 및 네임스페이스를 지정합니다.

표 24.5. “@ResponseWrapper 속성” @ResponseWrapper 주석의 속성을 설명합니다.

표 24.5. @ResponseWrapper 속성

속성설명

localName

응답 메시지의 XML 표현에 래퍼 요소의 로컬 이름을 지정합니다.Specifies the local name of the wrapper element in the XML representation of the response message. 기본값은 Response가 추가된 메서드의 이름 또는 Response가 추가된 “@WebMethod 주석” 주석의 operationName 속성 값입니다.

targetNamespace

XML 래퍼 요소가 정의된 네임스페이스를 지정합니다. 기본값은 SEI의 대상 네임스페이스입니다.

className

래퍼 요소를 구현하는 Java 클래스의 전체 이름을 지정합니다.

참고

className 속성만 필요합니다.

중요

@SOAPBinding 주석에도 메서드에 주석이 추가되고 해당 parameterStyle 속성이 ParameterStyle.BARE 로 설정된 경우 이 주석은 무시됩니다.

24.3.3.10. @WebFault 주석

@WebFault 주석은 javax.xml.ws.WebFault 인터페이스에서 정의됩니다. SEI에서 throw되는 예외에 적용됩니다. @WebFault 주석은 Java 예외를 wsdl:fault 요소에 매핑하는 데 사용됩니다. 이 정보는 서비스 및 소비자 둘 다 처리할 수 있는 표현으로 예외를 마샬링하는 데 사용됩니다.

표 24.6. “@WebFault Properties” @WebFault 주석의 속성을 설명합니다.

표 24.6. @WebFault Properties

속성설명

name

fault 요소의 로컬 이름을 지정합니다.

targetNamespace

fault 요소가 정의된 네임스페이스를 지정합니다.Specifies the namespace under which the fault element is defined. 기본값은 SEI의 대상 네임스페이스입니다.

faultName

예외를 구현하는 Java 클래스의 전체 이름을 지정합니다.

중요

name 속성이 필요합니다.

24.3.3.11. @Oneway 주석

@Oneway 주석은 javax.jws.Oneway 인터페이스에서 정의됩니다. 서비스의 응답이 필요하지 않은 SEI의 메서드에 배치됩니다. @Oneway 주석은 응답을 기다리지 않고 응답을 처리하는 리소스를 예약하지 않고 메서드 실행을 최적화할 수 있음을 런타임에 지시합니다.

이 주석은 다음 기준을 충족하는 방법에서만 사용할 수 있습니다.

  • void를 반환합니다.
  • holder 인터페이스를 구현하는 매개 변수가 없습니다.
  • 소비자로 다시 전달할 수 있는 예외는 throw되지 않습니다.

24.3.3.12. 예제

예 24.6. “Annotated methods가 있는 SEI” 주석이 달린 메서드가 포함된 SEI를 표시합니다.

예 24.6. Annotated methods가 있는 SEI

package com.fusesource.demo;

import javax.jws.*;
import javax.xml.ws.*;

@WebService(name="quoteReporter")
public interface quoteReporter
{
  @WebMethod(operationName="getStockQuote")
  @RequestWrapper(targetNamespace="http://demo.redhat.com/types",
                  className="java.lang.String")
  @ResponseWrapper(targetNamespace="http://demo.redhat.com/types",
                   className="org.eric.demo.Quote")
  public Quote getQuote(String ticker);
}

24.3.3.13. 개요

주석을 사용하여 매개 변수 속성 정의

SEI의 메서드 매개 변수는 wsdl:message 요소와 wsdl:part 요소에 해당합니다. JAX-WS는 메서드 매개 변수에 대해 생성된 wsdl:part 요소를 설명할 수 있는 주석을 제공합니다.

24.3.3.14. @WebParam 주석

@WebParam 주석은 javax.jws.WebParam 인터페이스에서 정의됩니다. SEI에 정의된 메서드의 매개 변수에 배치됩니다. @WebParam 주석을 사용하면 매개 변수가 SOAP 헤더에 배치될 경우 매개 변수의 방향을 지정하고 생성된 wsdl:part 의 기타 속성을 지정할 수 있습니다.

표 24.7. “@WebParam 속성” @WebParam 주석의 속성을 설명합니다.

표 24.7. @WebParam 속성

속성설명

name

 

생성된 WSDL 문서에 표시되는 매개 변수의 이름을 지정합니다. RPC 바인딩의 경우 매개 변수를 나타내는 wsdl:part 의 이름입니다. 문서 바인딩의 경우 매개 변수를 나타내는 XML 요소의 로컬 이름입니다.For document bindings, this is the local name of the XML element representing the parameter. JAX-WS 사양에 따라 기본값은 argN 입니다. 여기서 N 은 0 기반 인수 인덱스(예: arg0, arg1, 등)로 대체됩니다.

targetNamespace

 

매개변수의 네임스페이스를 지정합니다. 매개 변수가 XML 요소에 매핑되는 문서 바인딩에서만 사용됩니다. 기본값은 서비스의 네임스페이스를 사용하는 것입니다.

mode

mode.IN (기본값)[a]

Mode.OUT

Mode.INOUT

매개 변수의 방향을 지정합니다.

header

false(기본값)

true

매개 변수가 SOAP 헤더의 일부로 전달되는지 여부를 지정합니다.

partName

 

매개 변수에 대한 wsdl:part 요소의 name 속성 값을 지정합니다. 이 속성은 문서 스타일 SOAP 바인딩에 사용됩니다.

[a] Holder 인터페이스를 구현하는 모든 매개변수는 기본적으로 Mode.INOUT에 매핑됩니다.

24.3.3.15. @WebResult 주석

@WebResult 주석은 javax.jws.WebResult 인터페이스에서 정의됩니다. SEI에 정의된 메서드에 배치됩니다. @WebResult 주석을 사용하면 메서드의 반환 값에 대해 생성된 wsdl:part 의 속성을 지정할 수 있습니다.

표 24.8. “@WebResult 속성” @WebResult 주석의 속성을 설명합니다.

표 24.8. @WebResult 속성

속성설명

name

생성된 WSDL 문서에 표시되는 반환 값의 이름을 지정합니다. RPC 바인딩의 경우 이는 반환 값을 나타내는 wsdl:part 의 이름입니다. 문서 바인딩의 경우 이는 반환 값을 나타내는 XML 요소의 로컬 이름입니다.For document bindings, this is the local name of the XML element representing the return value. 기본값은 return입니다.

targetNamespace

반환 값의 네임스페이스를 지정합니다. 반환 값이 XML 요소에 매핑되는 문서 바인딩에서만 사용됩니다. 기본값은 서비스의 네임스페이스를 사용하는 것입니다.

header

반환 값이 SOAP 헤더의 일부로 전달되는지 여부를 지정합니다.Specifies if the return value is passed as part of the SOAP header.

partName

반환 값에 대한 wsdl:part 요소의 name 속성 값을 지정합니다. 이 속성은 문서 스타일 SOAP 바인딩에 사용됩니다.

24.3.3.16. 예제

예 24.7. “완전히 주석 처리 SEI” 주석이 완전히 추가된 SEI를 표시합니다.

예 24.7. 완전히 주석 처리 SEI

package com.fusesource.demo;

import javax.jws.*;
import javax.xml.ws.*;
import javax.jws.soap.*;
import javax.jws.soap.SOAPBinding.*;
import javax.jws.WebParam.*;

@WebService(targetNamespace="http://demo.redhat.com",
            name="quoteReporter")
@SOAPBinding(style=Style.RPC, use=Use.LITERAL)
public interface quoteReporter
{
  @WebMethod(operationName="getStockQuote")
  @RequestWrapper(targetNamespace="http://demo.redhat.com/types",
                  className="java.lang.String")
  @ResponseWrapper(targetNamespace="http://demo.redhat.com/types",
                   className="org.eric.demo.Quote")
  @WebResult(targetNamespace="http://demo.redhat.com/types",
             name="updatedQuote")
  public Quote getQuote(
                        @WebParam(targetNamespace="http://demo.redhat.com/types",
                                  name="stockTicker",
                                  mode=Mode.IN)
                        String ticker
  );
}

24.3.4. Apache CXF 주석

24.3.4.1. WSDL 문서

24.3.4.1.1. @WSDLDocumentation 주석

@WSDLDocumentation 주석은 org.apache.cxf.annotations.WSDLDocumentation 인터페이스에서 정의됩니다. SEI 또는 SEI 방법에 설치할 수 있습니다.

이 주석을 사용하면 SEI를 WSDL으로 변환한 후 wsdl:documentation 요소에 표시되는 문서를 추가할 수 있습니다. 기본적으로 설명서 요소는 포트 유형 내에 표시되지만 placement 속성을 지정하여 documentation in the WSDL 파일의 다른 위치에 표시되도록 할 수 있습니다. 24.3.4.2절. “@WSDLDocumentation 속성” @WSDLDocumentation 주석에서 지원하는 속성을 보여줍니다.

24.3.4.2. @WSDLDocumentation 속성

속성설명

value

(필수) 문서 텍스트를 포함하는 문자열입니다.

배치

(선택 사항) WSDL 파일에서 이 문서가 표시되는 위치를 지정합니다. 가능한 배치 값 목록은 “WSDL 계약 포함” 에서 참조하십시오.

faultClass

(선택 사항) 배치가 FAULT_MESSAGE,PORT_TYPE_OPERATION_FAULT 또는 BINDING_OPERATION_FAULT 로 설정된 경우 이 속성을 오류를 나타내는 Java 클래스로 설정해야 합니다.

24.3.4.2.1. @WSDLDocumentationCollection 주석

@WSDLDocumentationCollection 주석은 org.apache.cxf.annotations.WSDLDocumentationCollection 인터페이스에서 정의됩니다. SEI 또는 SEI 방법에 설치할 수 있습니다.

이 주석은 단일 배치 위치 또는 다양한 배치 위치에 여러 문서 요소를 삽입하는 데 사용됩니다.

24.3.4.2.2. WSDL 계약 포함

WSDL 계약에 문서가 표시될 위치를 지정하려면 WSDLDocumentation.Placement 유형의 placement 속성을 지정할 수 있습니다. 배치에는 다음 값 중 하나가 있을 수 있습니다.

  • WSDLDocumentation.Placement.BINDING
  • WSDLDocumentation.Placement.BINDING_OPERATION
  • WSDLDocumentation.Placement.BINDING_OPERATION_FAULT
  • WSDLDocumentation.Placement.BINDING_OPERATION_INPUT
  • WSDLDocumentation.Placement.BINDING_OPERATION_OUTPUT
  • WSDLDocumentation.Placement.DEFAULT
  • WSDLDocumentation.Placement.FAULT_MESSAGE
  • WSDLDocumentation.Placement.INPUT_MESSAGE
  • WSDLDocumentation.Placement.OUTPUT_MESSAGE
  • WSDLDocumentation.Placement.PORT_TYPE
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION_FAULT
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION_INPUT
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION_OUTPUT
  • WSDLDocumentation.Placement.SERVICE
  • WSDLDocumentation.Placement.SERVICE_PORT
  • WSDLDocumentation.Placement.TOP
24.3.4.2.3. @WSDLDocumentation의 예

24.3.4.3절. “@WSDLDocumentation 사용” SEI 및 해당 방법 중 하나에 @WSDLDocumentation 주석을 추가하는 방법을 보여줍니다.

24.3.4.3. @WSDLDocumentation 사용

@WebService
@WSDLDocumentation("A very simple example of an SEI")
public interface HelloWorld {
    @WSDLDocumentation("A traditional form of greeting")
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.4절. “문서를 사용하여 생성된 WSDL” 에 표시된 WSDL은 24.3.4.3절. “@WSDLDocumentation 사용” SEI에서 생성되는 경우 문서 요소의 기본 배치는 각각 PORT_TYPEPORT_TYPE_OPERATION 입니다.

24.3.4.4. 문서를 사용하여 생성된 WSDL

<wsdl:definitions ... >
  ...
  <wsdl:portType name="HelloWorld">
    <wsdl:documentation>A very simple example of an SEI</wsdl:documentation>
    <wsdl:operation name="sayHi">
      <wsdl:documentation>A traditional form of greeting</wsdl:documentation>
      <wsdl:input name="sayHi" message="tns:sayHi">
    </wsdl:input>
      <wsdl:output name="sayHiResponse" message="tns:sayHiResponse">
    </wsdl:output>
    </wsdl:operation>
  </wsdl:portType>
  ...
</wsdl:definitions>
24.3.4.4.1. @WSDLDocumentationCollection의 예

24.3.4.5절. “@WSDLDocumentationCollection 사용” SEI에 @WSDLDocumentationCollection 주석을 추가하는 방법을 보여줍니다.

24.3.4.5. @WSDLDocumentationCollection 사용

@WebService
@WSDLDocumentationCollection(
    {
        @WSDLDocumentation("A very simple example of an SEI"),
        @WSDLDocumentation(value = "My top level documentation",
                           placement = WSDLDocumentation.Placement.TOP),
        @WSDLDocumentation(value = "Binding documentation",
                           placement = WSDLDocumentation.Placement.BINDING)
    }
)
public interface HelloWorld {
    @WSDLDocumentation("A traditional form of Geeky greeting")
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.6. 메시지 스키마 유효성 검사

24.3.4.6.1. @SchemaValidation 주석

@SchemaValidation 주석은 org.apache.cxf.annotations.SchemaValidation 인터페이스에서 정의됩니다. SEI 및 개별 SEI 방법에 설치할 수 있습니다.

이 주석은 이 끝점으로 전송된 XML 메시지의 스키마 유효성 검사를 설정합니다. 이 기능은 들어오는 XML 메시지 형식에 문제가 있다고 의심되는 경우 테스트 목적에 유용할 수 있습니다. 성능에 큰 영향을 미치기 때문에 유효성 검사가 기본적으로 비활성화되어 있습니다.

24.3.4.6.2. 스키마 검증 유형

스키마 유효성 검사 동작은 값이 org.apache.cxf.annotations.SchemaValidation.SchemaValidationType 유형의 열거형인 type 매개 변수에 의해 제어됩니다. 24.3.4.7절. “스키마 유효성 검사 유형 값” 사용 가능한 유효성 검사 유형 목록을 표시합니다.

24.3.4.7. 스키마 유효성 검사 유형 값

유형설명

IN

클라이언트 및 서버에서 들어오는 메시지에 스키마 유효성 검사를 적용합니다.

OUT

클라이언트 및 서버에서 나가는 메시지에 스키마 유효성 검사를 적용합니다.

BOTH

클라이언트와 서버에서 수신 및 발신 메시지에 스키마 유효성 검사를 적용합니다.

NONE

모든 스키마 유효성 검사가 비활성화됩니다.

REQUEST

스키마 검증을 적용하여 메시지 요청(즉, 발신 클라이언트 메시지 및 수신 서버 메시지에 유효성 검사가 적용됩니다.

RESPONSE

응답 메시지에 스키마 유효성 검사를 적용합니다. 즉, 들어오는 클라이언트 메시지 및 발신 서버 메시지에 유효성 검사가 적용됩니다.

24.3.4.7.1. 예제

다음 예제에서는 MyService SEI를 기반으로 끝점에 대한 메시지의 스키마 유효성 검사를 활성화하는 방법을 보여줍니다. 주석을 SEI 전체에 적용하는 방법과 SEI의 개별 메서드에 주석을 적용하는 방법을 확인합니다.

@WebService
@SchemaValidation(type = SchemaValidationType.BOTH)
public interface MyService {
    Foo validateBoth(Bar data);

    @SchemaValidation(type = SchemaValidationType.NONE)
    Foo validateNone(Bar data);

    @SchemaValidation(type = SchemaValidationType.IN)
    Foo validateIn(Bar data);

    @SchemaValidation(type = SchemaValidationType.OUT)
    Foo validateOut(Bar data);

    @SchemaValidation(type = SchemaValidationType.REQUEST)
    Foo validateRequest(Bar data);

    @SchemaValidation(type = SchemaValidationType.RESPONSE)
    Foo validateResponse(Bar data);
}

24.3.4.8. 데이터 바인딩 지정

24.3.4.8.1. @DataBinding 주석

@DataBinding 주석은 org.apache.cxf.annotations.DataBinding 인터페이스에서 정의됩니다. 그것은 SEI에 배치되어 있습니다.

이 주석은 데이터 바인딩을 SEI와 연결하고 기본 JAXB 데이터 바인딩을 대체하는 데 사용됩니다. @DataBinding 주석의 값은 데이터 바인딩인ClassName .class 여야 합니다.

24.3.4.8.2. 지원되는 데이터 바인딩

현재 Apache CXF에서 지원되는 데이터 바인딩은 다음과 같습니다.

  • org.apache.cxf.jaxb.JAXBDataBinding

    (기본값) 표준 JAXB 데이터 바인딩입니다.

  • org.apache.cxf.sdo.SDODataBinding

    Service Data Objects(SDO) 데이터 바인딩은 Apache Tuscany SDO 구현을 기반으로 합니다. Maven 빌드 컨텍스트에서 이 데이터 바인딩을 사용하려면 cxf-rt-databinding-sdo 아티팩트에 종속성을 추가해야 합니다.

  • org.apache.cxf.aegis.databinding.AegisDatabinding

    Maven 빌드 컨텍스트에서 이 데이터 바인딩을 사용하려면 cxf-rt-databinding-aegis 아티팩트에 종속성을 추가해야 합니다.

  • org.apache.cxf.xmlbeans.XmlBeansDataBinding

    Maven 빌드 컨텍스트에서 이 데이터 바인딩을 사용하려면 cxf-rt-databinding-xmlbeans 아티팩트에 종속성을 추가해야 합니다.

  • org.apache.cxf.databinding.source.SourceDataBinding

    이 데이터 바인딩은 Apache CXF 코어에 속합니다.

  • org.apache.cxf.databinding.stax.StaxDataBinding

    이 데이터 바인딩은 Apache CXF 코어에 속합니다.

24.3.4.8.3. 예제

24.3.4.9절. “데이터 바인딩 설정” HelloWorld SEI와 SDO 바인딩을 연결하는 방법을 보여줍니다.

24.3.4.9. 데이터 바인딩 설정

@WebService
@DataBinding(org.apache.cxf.sdo.SDODataBinding.class)
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.10. 메시지 압축

24.3.4.10.1. @GZIP 주석

@GZIP 주석은 org.apache.cxf.annotations.GZIP 인터페이스에서 정의됩니다. 그것은 SEI에 배치되어 있습니다.

메시지의 GZIP 압축을 활성화합니다. GZIP는 협상된 개선 사항입니다. 즉, 클라이언트의 초기 요청은 gzip으로 지정되지 않지만 Accept 헤더가 추가되고 서버가 GZIP 압축을 지원하는 경우 응답이 gzip으로 표시되고 후속 요청도 수행됩니다.

24.3.4.11절. “@GZIP 속성” @GZIP 주석에서 지원하는 선택적 속성을 보여줍니다.

24.3.4.11. @GZIP 속성

속성설명

threshold

이 속성에서 지정한 크기보다 작은 메시지는 gzip으로 표시되지 않습니다. 기본값은 -1(제한 없음)입니다.

24.3.4.11.1. @FastInfoset

@FastInfoset 주석은 org.apache.cxf.annotations.FastInfoset 인터페이스에서 정의됩니다. 그것은 SEI에 배치되어 있습니다.

메시지에 FastInfoset 형식을 사용할 수 있습니다. FastInfoset은 XML 메시지의 이진 인코딩 형식이며, 이는 메시지 크기와 XML 메시지의 처리 성능을 모두 최적화하는 것을 목표로 합니다. 자세한 내용은 Fast Infoset 에 대한 다음 Sun 문서를 참조하십시오.

FastInfoset은 협상된 개선 사항입니다. 즉, 클라이언트의 초기 요청은 FastInfoset 형식이 아니지만 Accept 헤더가 추가되고 서버가 FastInfoset을 지원하는 경우 응답은 FastInfoset에 있으며 이후 요청도 포함됩니다.

24.3.4.12절. “@FastInfoset Properties” @FastInfoset 주석에서 지원하는 선택적 속성을 보여줍니다.

24.3.4.12. @FastInfoset Properties

속성설명

force

협상 대신 FastInfoset 형식을 강제로 사용하는 부울 속성입니다. true 인 경우 fastInfoset 형식을 강제로 사용합니다. 그렇지 않으면 협상합니다. 기본값은 false 입니다.

24.3.4.12.1. @GZIP의 예

24.3.4.13절. “GZIP 활성화” HelloWorld SEI에 대해 GZIP 압축을 활성화하는 방법을 보여줍니다.

24.3.4.13. GZIP 활성화

@WebService
@GZIP
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}
24.3.4.13.1. @FastInfoset 시험

24.3.4.14절. “FastInfoset 활성화” HelloWorld SEI에 대해 FastInfoset 형식을 활성화하는 방법을 보여줍니다.

24.3.4.14. FastInfoset 활성화

@WebService
@FastInfoset
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.15. 끝점에서 로깅 활성화

24.3.4.15.1. @logging 주석

@Logging 주석은 org.apache.cxf.annotations.Logging 인터페이스에서 정의됩니다. 그것은 SEI에 배치되어 있습니다.

이 주석을 사용하면 SEI와 연결된 모든 끝점에 로깅할 수 있습니다. 24.3.4.16절. “@logging 속성” 이 주석에서 설정할 수 있는 선택적 속성을 표시합니다.

24.3.4.16. @logging 속성

속성설명

제한

로그에서 메시지가 잘리는 것 이상으로 크기 제한을 지정합니다. 기본값은 64K입니다.

inLocation

수신 메시지를 로깅할 위치를 지정합니다. < stderr >, < stdout > , < logger > 또는 파일 이름이 될 수 있습니다. 기본값은 &lt ;logger> 입니다.

outLocation

나가는 메시지를 로깅할 위치를 지정합니다. < stderr >, < stdout > , < logger > 또는 파일 이름이 될 수 있습니다. 기본값은 &lt ;logger> 입니다.

24.3.4.16.1. 예제

24.3.4.17절. “주석을 사용한 로깅 구성” 는 들어오는 메시지가 < stdout >로 전송되고 발신 메시지가 < logger >로 전송되는 HelloWorld SEI에 대한 로깅을 활성화하는 방법을 보여줍니다.

24.3.4.17. 주석을 사용한 로깅 구성

@WebService
@Logging(limit=16000, inLocation="<stdout>")
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.18. 끝점에 속성 및 정책 추가

초록

속성 및 정책을 모두 사용하여 구성 데이터를 끝점과 연결할 수 있습니다. 이러한 문제의 근본적인 차이점은 속성이 Apache CXF 특정 구성 메커니즘인 반면 정책 은 표준 WSDL 구성 메커니즘입니다. 일반적으로 정책은 WS 사양 및 표준에서 시작되며 일반적으로 WSDL 계약에 표시되는 wsdl:policy 요소를 정의하여 설정됩니다. 반대로 속성은 Apache CXF 관련이며 일반적으로 Apache CXF Spring 구성 파일에서 jaxws:properties 요소를 정의하여 설정됩니다.

그러나 여기에 설명된 대로 주석을 사용하여 Java에서 속성 설정 및 WSDL 정책 설정을 정의할 수도 있습니다.

24.3.4.19. 속성 추가

24.3.4.19.1. @EndpointProperty 주석

@EndpointProperty 주석은 org.apache.cxf.annotations.EndpointProperty 인터페이스에서 정의됩니다. 그것은 SEI에 배치되어 있습니다.

이 주석은 Apache CXF 관련 구성 설정을 엔드포인트에 추가합니다. 엔드포인트 속성은 Spring 구성 파일에 지정할 수도 있습니다. 예를 들어 끝점에서 WS-Security를 구성하려면 Spring 구성 파일에서 jaxws:properties 요소를 사용하여 끝점 속성을 추가할 수 있습니다.

<beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:jaxws="http://cxf.apache.org/jaxws"
   ... >

   <jaxws:endpoint
      id="MyService"
      address="https://localhost:9001/MyService"
      serviceName="interop:MyService"
      endpointName="interop:MyServiceEndpoint"
      implementor="com.foo.MyService">

      <jaxws:properties>
         <entry key="ws-security.callback-handler" value="interop.client.UTPasswordCallback"/>
         <entry key="ws-security.signature.properties" value="etc/keystore.properties"/>
         <entry key="ws-security.encryption.properties" value="etc/truststore.properties"/>
         <entry key="ws-security.encryption.username" value="useReqSigCert"/>
      </jaxws:properties>

   </jaxws:endpoint>
</beans>

또는 24.3.4.20절. “@EndpointProperty Annotations를 사용하여 WS-Security 구성” 와 같이 SEI에 @EndpointProperty 주석을 추가하여 Java에서 이전 구성 설정을 지정할 수 있습니다.

24.3.4.20. @EndpointProperty Annotations를 사용하여 WS-Security 구성

@WebService
@EndpointProperty(name="ws-security.callback-handler" value="interop.client.UTPasswordCallback")
@EndpointProperty(name="ws-security.signature.properties" value="etc/keystore.properties")
@EndpointProperty(name="ws-security.encryption.properties" value="etc/truststore.properties")
@EndpointProperty(name="ws-security.encryption.username" value="useReqSigCert")
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}
24.3.4.20.1. @EndpointProperties 주석

@EndpointProperties 주석은 org.apache.cxf.annotations.EndpointProperties 인터페이스에서 정의됩니다. 그것은 SEI에 배치되어 있습니다.

이 주석은 여러 @EndpointProperty 주석을 목록으로 그룹화하는 방법을 제공합니다. @EndpointProperties 를 사용하면 24.3.4.21절. “@EndpointProperties 주석을 사용하여 WS-Security 구성” 와 같이 24.3.4.20절. “@EndpointProperty Annotations를 사용하여 WS-Security 구성” 을 다시 쓸 수 있습니다.

24.3.4.21. @EndpointProperties 주석을 사용하여 WS-Security 구성

@WebService
@EndpointProperties(
  {
  @EndpointProperty(name="ws-security.callback-handler" value="interop.client.UTPasswordCallback"),
  @EndpointProperty(name="ws-security.signature.properties" value="etc/keystore.properties"),
  @EndpointProperty(name="ws-security.encryption.properties" value="etc/truststore.properties"),
  @EndpointProperty(name="ws-security.encryption.username" value="useReqSigCert")
})
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.22. 정책 추가

24.3.4.22.1. @policy 주석

@Policy 주석은 org.apache.cxf.annotations.Policy 인터페이스에서 정의됩니다. SEI 또는 SEI 방법에 설치할 수 있습니다.

이 주석은 WSDL 정책을 SEI 또는 SEI 방법과 연결하는 데 사용됩니다. 이 정책은 표준 wsdl:policy 요소가 포함된 XML 파일을 참조하는 URI를 제공하여 지정합니다. WSDL 계약이 SEI에서 생성되는 경우(예: java2ws 명령줄 툴 사용) 이 정책을 WSDL에 포함할지 여부를 지정할 수 있습니다.

24.3.4.23절. “@policy 속성” @Policy 주석에서 지원하는 속성을 표시합니다.

24.3.4.23. @policy 속성

속성설명

uri

(필수) 정책 정의가 포함된 파일의 위치입니다.

includeInWSDL

(선택 사항) WSDL을 생성할 때 생성된 계약에 정책을 포함할지 여부입니다. 기본값은 true 입니다.

배치

(선택 사항) WSDL 파일에서 이 문서가 표시되는 위치를 지정합니다. 가능한 배치 값 목록은 “WSDL 계약 포함” 에서 참조하십시오.

faultClass

(선택 사항) 배치가 BINDING_OPERATION_FAULT 또는 PORT_TYPE_OPERATION_FAULT 로 설정된 경우 이 속성도 설정하여 이 정책이 적용되는 오류를 지정해야 합니다. 값은 오류를 나타내는 Java 클래스입니다.

24.3.4.23.1. @policies 주석

@Policies 주석은 org.apache.cxf.annotations.Policies 인터페이스에서 정의됩니다. SEI 또는 thse SEI 방법에 배치할 수 있습니다.

이 주석은 여러 @Policy 주석을 목록으로 그룹화하는 방법을 제공합니다.

24.3.4.23.2. WSDL 계약 포함

WSDL 계약에 정책이 표시될 위치를 지정하려면 Policy.Placement 유형인 placement 속성을 지정할 수 있습니다. 배치에는 다음 값 중 하나가 있을 수 있습니다.

Policy.Placement.BINDING
Policy.Placement.BINDING_OPERATION
Policy.Placement.BINDING_OPERATION_FAULT
Policy.Placement.BINDING_OPERATION_INPUT
Policy.Placement.BINDING_OPERATION_OUTPUT
Policy.Placement.DEFAULT
Policy.Placement.PORT_TYPE
Policy.Placement.PORT_TYPE_OPERATION
Policy.Placement.PORT_TYPE_OPERATION_FAULT
Policy.Placement.PORT_TYPE_OPERATION_INPUT
Policy.Placement.PORT_TYPE_OPERATION_OUTPUT
Policy.Placement.SERVICE
Policy.Placement.SERVICE_PORT
24.3.4.23.3. @Policy의 예

다음 예제에서는 WSDL 정책을 HelloWorld SEI와 연결하는 방법과 정책을 sayHi 메서드와 연결하는 방법을 보여줍니다. 정책은 주석 디렉터리에 있는 파일 시스템의 XML 파일에 저장됩니다.

@WebService
@Policy(uri = "annotationpolicies/TestImplPolicy.xml",
        placement = Policy.Placement.SERVICE_PORT),
@Policy(uri = "annotationpolicies/TestPortTypePolicy.xml",
        placement = Policy.Placement.PORT_TYPE)
public interface HelloWorld {
    @Policy(uri = "annotationpolicies/TestOperationPTPolicy.xml",
            placement = Policy.Placement.PORT_TYPE_OPERATION),
    String sayHi(@WebParam(name = "text") String text);
}
24.3.4.23.4. @Policies의 예

@Policies 주석을 사용하여 다음 예와 같이 여러 @Policy 주석을 목록에 그룹화할 수 있습니다.

@WebService
@Policies({
    @Policy(uri = "annotationpolicies/TestImplPolicy.xml",
            placement = Policy.Placement.SERVICE_PORT),
    @Policy(uri = "annotationpolicies/TestPortTypePolicy.xml",
            placement = Policy.Placement.PORT_TYPE)
})
public interface HelloWorld {
    @Policy(uri = "annotationpolicies/TestOperationPTPolicy.xml",
            placement = Policy.Placement.PORT_TYPE_OPERATION),
    String sayHi(@WebParam(name = "text") String text);
}