24.3.3. 선택적 주석

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
  );
}