어노테이션을 사용하여 JAX-WS 웹 서비스 개발

JAX-WS (Java™ API for XML-Based Web Services) 는 두 가지 다른 서비스 엔드포인트 구현 유형인 표준 웹 서비스 엔드포인트 인터페이스와 새 제공자 인터페이스를 지원하여 서비스가 XML 메시지 레벨에서 작동할 수 있도록 합니다. 서비스 엔드포인트 구현 또는 클라이언트에서 어노테이션을 사용하여 서비스 엔드포인트를 웹 서비스로 정의할 수 있습니다.

시작하기 전에

웹 서비스에 대한 개발 환경을 설정하십시오.

이 태스크 정보

이 태스크는 JAX-WS 웹 서비스를 개발하기 위한 필수 단계입니다.

JAX-WS 기술은 표준 서비스 엔드포인트 인터페이스 및 새 제공자 인터페이스 둘 다를 기반으로 하는 웹 서비스 구현을 지원합니다. JAX-WS 엔드포인트는 JAX-RPC (Java API for XML-based RPC) 스펙의 엔드포인트 구현과 유사합니다. JAX-RPC와는 달리, SEI(Service Endpoint Interface)에 대한 요구사항은 JAX-WS 웹 서비스에 대해 선택사항입니다. 연관된 SEI가 없는 JAX-WS 서비스는 내부 SEI가 있는 것으로 간주되는 반면, 연관된 SEI가 있는 서비스는 명시적 SEI가 있는 것으로 간주됩니다. 또한 JAX-WS에 필요한 서비스 엔드포인트 인터페이스는 JAX-RPC에 필요한 서비스 엔드포인트보다 더 일반적입니다. JAX-WS로 인해 SEI는 JAX-RPC 스펙에서 요구되는 것처럼 java.rmi.Remote 인터페이스를 확장할 필요가 없습니다.

JAX-WS 프로그래밍 모델은 또한 메타데이터로 Java 클래스에 어노테이션을 작성하기 위한 지원을 사용하여 서비스 엔드포인트 구현을 웹 서비스로 정의하고 클라이언트가 웹 서비스에 액세스할 수 있는 방법을 정의합니다. JAX-WS는 Java 프로그래밍 언어(JSR 175) 스펙에 대한 메타데이터 기능, Java 플랫폼(JSR 181) 스펙에 대한 웹 서비스 메타데이터 및 JAX-WS 2.0(JSR 224) 스펙에서 정의한 어노테이션 기반의 어노테이션을 지원하는 데, 이는 JAXB(Java Architecture for XML Binding) 어노테이션을 포함하는 것입니다. 어노테이션을 사용하면, 서비스 엔드포인트 구현이 WSDL 파일을 요구하지 않고도 독립적으로 웹 서비스를 설명할 수 있습니다. 어노테이션은 서비스 엔드포인트 구현 또는 웹 서비스 클라이언트를 구성하는 데 필요한 모든 WSDL 정보를 제공할 수 있습니다. 사용자는 클라이언트 및 서버에서 사용되는 서비스 엔드포인트 인터페이스 또는 서버 측 서비스 구현 클래스에서 어노테이션을 지정할 수 있습니다.

지원되는 표준 및 스펙에 관한 자세한 내용은 웹 서비스 스펙 및 API 문서를 참조하십시오.

상향식 접근 방식으로 알려진 기존 Java 클래스에서 시작하여 JAX-WS웹 서비스를 개발하는 경우, 처음에 클래스를 웹 서비스로 정의하기 위해 @WebService (javax.jws.WebService) 어노테이션 또는 @WebServiceProvider (javax.xml.ws.Provider) 어노테이션으로 클래스에 어노테이션을 작성해야 합니다. @WebService 어노테이션은 서비스를 SEI 엔드포인트로 정의하고, @WebServiceProvider 어노테이션은 서비스를 제공자 기반 엔드포인트로 정의합니다.

SEI 기반 JAX-WS 웹 서비스 개발

SEI 기반 엔드포인트의 경우, 서비스 엔드포인트 인터페이스 (SEI) 는 Java 클래스인지 또는 Java 인터페이스인지에 관계없이 특정 웹 서비스에서 제공하는 비즈니스 메소드를 선언합니다. JAX-WS 엔드포인트에서 웹 서비스 클라이언트를 호출할 수 있는 유일한 메소드는 명시 또는 내부 SEI에서 정의되는 비즈니스 메소드입니다.

모든 SEI 기반 엔드포인트에는 구현 클래스에 포함된 @WebService 어노테이션이 있어야 합니다. 서비스 구현에서 명시적 SEI를 사용하는 경우, 해당 인터페이스를 @WebService 어노테이션에서 endpointInterface 속성으로 참조해야 합니다. 서비스 구현이 명시 SEI를 사용하지 않는 경우 서비스는 구현 클래스에 의해 내부에서 설명되고 내부 SEI가 됩니다.

제공자 인터페이스를 사용하여 JAX-WS 웹 서비스 개발

JAX-WS 프로그래밍 모델은 SEI 기반 엔드포인트 대신에 동적으로 제공자 엔드포인트(javax.xml.ws.Provider)에 대한 제공자 인터페이스를 소개합니다. 제공자 인터페이스는 웹 서비스에 대해 좀 더 메시지 지향적인 접근 방식을 지원합니다. 프로바이더 인터페이스를 사용하면, 단순한 인터페이스를 구현하는 Java 클래스를 작성하여 일반 서비스 구현 클래스를 만들 수 있습니다. 제공자 인터페이스는 하나의 메소드(invoke 메소드)를 정의하며, 일반 서비스를 사용하여 다양한 메시지 또는 메시지 페이로드에 대한 작업 시 입력 및 출력 유형을 모두 제어합니다. 모든 제공자 엔드포인트는 @WebServiceProvider(javax.xml.ws.WebServiceProvider) 어노테이션을 사용하여 어노테이션을 작성해야 합니다. 서비스 구현은 javax.xml.ws.Provider 인터페이스 구현 시 @WebService 어노테이션을 지정할 수 없습니다.

WebSphere® Application Server 버전 7.0 이상부터 Java EE 5애플리케이션 모듈 (웹 애플리케이션 모듈 버전 2.5 이상 또는 EJB 모듈 버전 3.0 이상) 에서 JAX-WS 서비스 및 클라이언트를 식별하기 위한 어노테이션을 스캔합니다. 하지만 기본적으로 성능을 고려하여 JAX-WS 어노테이션을 찾기 위해 Java EE 5 이전 애플리케이션 모듈(웹 애플리케이션 모듈 버전 2.4 이하 또는 EJB 모듈 버전 2.1 이하)을 스캔하지 않습니다. 웹 서비스의 버전 6.1 기능팩에서, 기본 동작은 이전 Java EE 5 웹 애플리케이션 모듈을 스캔하여 JAX-WS 서비스를 식별하고 애플리케이션 설치 중 서비스 클라이언트에 대해 이전 Java EE 5 웹 애플리케이션 모듈과 EJB 모듈을 스캔하는 것입니다. WebSphere Application Server 버전 7.0 이상의 기본 동작은 애플리케이션 설치 또는 서버 시작 중에 어노테이션에 대해Java EE 5이전 모듈을 스캔하지 않는 것이므로 이전 릴리스의 기능팩으로 역방향 호환성을 유지하려면 웹 애플리케이션 아카이브 (WAR) 파일 또는 EJB 모듈의 META-INF/MANIFEST.MF 에서 UseWSFEP61ScanPolicy 특성을 구성하거나 JVM (Java Virtual Machine) 사용자 정의 특성 com.ibm.websphere.webservices.UseWSFEP61ScanPolicy을 정의해야 합니다. 서버에서 애플리케이션 설치 및 서버 시작 중에 스캔을 요청합니다. 어노테이션 스캔에 대한 정보는 JAX-WS 어노테이션 정보를 참조하십시오.

프로시저

SEI 엔드포인트 또는 제공자 인터페이스를 사용하여 웹 서비스를 정의할지 여부를 결정하십시오.
Java 오브젝트와 해당 XML 표시 간의 변환 세부사항을 숨기는 상위 레벨 Java 중심 추상을 선호하는 경우 SEI 기반 엔드포인트를 사용하여 웹 서비스를 개발하는 것을 고려하십시오. 그러나 XML 메시지 레벨에서 웹 서비스를 운영할 경우 제공자 기반 엔드포인트를 사용할 것을 고려하십시오.
서비스 엔드포인트에 어노테이션을 다십시오.
1. javax.jws.WebService 어노테이션을 사용하여 SEI 기반 엔드포인트에 어노테이션을 작성하십시오.
  - SEI 기반 엔드포인트의 경우, javax.jws.WebService 어노테이션을 사용하여 구현 클래스에 어노테이션을 작성하십시오. 이 엔드포인트가 명시적 SEI임을 지정하는 @WebService.endpointInterface 속성을 정의하여 서비스 엔드포인트 인터페이스를 명시적으로 참조하도록 선택할 수 있습니다. 이 경우 참조되는 Java 인터페이스에는 javax.jws.WebService 어노테이션도 포함되어야 합니다. endpointInterface 속성이 정의되어 있지 않거나 비어 있는 경우, 구현 Bean은 내재적 SEI로 간주됩니다. 서비스 엔드포인트 인터페이스의 메소드에 @WebMethod 어노테이션을 추가하여 Java-to-WSDL 맵핑을 사용자 정의할 수 있습니다. 모든 공용 메소드는 @WebMethod 어노테이션의 지정 여부와 관계 없이 노출된 메소드로 간주됩니다. exclude 속성을 포함하는 서비스 엔드포인트 인터페이스에 @WebMethod 어노테이션이 없어야 합니다.
  - 내재적 SEI를 사용하는 경우, @WebMethod 어노테이션을 선택적으로 사용하여 메소드를 표시하는 방법에 대해 더 세분화된 제어를 적용할 수 있습니다. 자세한 설명은 "SEI 기반 JAX-WS 웹 서비스 정보의 표시(exposing) 메소드"를 참조하십시오.
2. javax.xml.ws.WebServiceProvider 어노테이션을 사용하여 제공자 기반 엔드포인트에 어노테이션을 작성하십시오.
  - 제공자 기반 엔드포인트의 경우, javax.xml.ws.WebServiceProvider 어노테이션을 사용하여 구현 클래스에 어노테이션을 작성하십시오. 이 어노테이션은 언바인드된 클래스(예: Provider<T>)와 달리 견고하게 유형화된 javax.xml.ws.Provider.interface 클래스(예: Provider<Source> 또는 Provider<SOAPMessage>)를 구현하는 클래스에서만 지정해야 합니다. 강하게 유형 지정된 클래스는 특정 입력 및 출력 Java 유형 (예: Source 또는 SOAPMessage) 과 연관된 클래스입니다.
```
@WebServiceProvider(
        serviceName="StringProviderService", 
        wsdlLocation="META-INF/echostring.wsdl", 
        targetNamespace="http://stringprovider.sample.test.org")
```
  - (선택사항) JAX-WS 2.2 스펙에 따라, 제공자 구현이 널값을 리턴하도록 제공자 기반 엔드포인트를 정의하는 경우 응답이 필요하지 않습니다. javax.xml.ws.WebServiceProvider 어노테이션에서 WSDL을 지정하지 않고 invoke() 메소드가 널값을 리턴할 경우 JAX-WS 런타임 환경의 기본 동작은 빈 SOAPBody를 포함하는 SOAPEnvelope로 구성된 응답을 리턴하는 것입니다. JAX-WS 런타임 환경에서 이 시나리오를 요청 전용 조작으로 해석하고 응답을 리턴하지 않도록 하려면 JVM 특성 jaxws.provider.interpretNullAsOneway를 true로 설정할 수 있습니다.
SEI 기반 JAX-WS웹 서비스에서 메소드를 조작으로 노출합니다. 에 대한 우수 사례 이해 및 적용

SEI 기반 엔드포인트에 대한 웹 서비스 조작으로 공개될 메소드에 관해 다중 웹 서비스 스펙에 걸친 모호함으로 인해, 사용할 JAX-WS 구현에 상관 없이 다음 우수 사례에서는 일관된 작동을 보증할 수 있습니다.

결과

이 웹 서비스 애플리케이션을 나타내는 서비스 엔드포인트 구현이 정의되었습니다. 지원되는 JAX-WS 어노테이션에 대해 자세히 학습하려면 JAX-WS 어노테이션 문서를 참조하십시오.

샘플 JavaBeans 서비스 엔드포인트 구현 및 인터페이스

다음 예제는 단순한 명시적 JavaBeans 서비스 엔드포인트 구현 및 연관된 서비스 엔드포인트 인터페이스를 보여줍니다.

/** This is an excerpt from the service implementation file, EchoServicePortTypeImpl.java. 
package com.ibm.was.wssample.echo;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.Marshaller;
import javax.xml.bind.Unmarshaller;
import javax.xml.transform.stream.StreamSource;

@javax.jws.WebService(serviceName = "EchoService", endpointInterface = 
"com.ibm.was.wssample.echo.EchoServicePortType", targetNamespace="http://com/ibm/was/wssample/echo/", 
portName="EchoServicePort")
public class EchoServicePortTypeImpl implements EchoServicePortType {

                public EchoServicePortTypeImpl() {
                }

                public String echo(String obj) {
                        String str;
                        ....
                        str = obj;
                        ....
                        
                        return str;

                }

}

/**  This is a sample EchoServicePortType.java service interface. */

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


@WebService(name = "EchoServicePortType", targetNamespace = "http://com/ibm/was/wssample/echo/", 
wsdlLocation="WEB-INF/wsdl/Echo.wsdl")
public interface EchoServicePortType {


    /** ...the method process ...*/
        @WebMethod

}

샘플 제공자 엔드포인트 구현

다음 예제는 Java 클래스에 대한 단순 제공자 서비스 엔드포인트 인터페이스를 설명합니다.

package jaxws.provider.source;

import javax.xml.ws.Provider;
import javax.xml.ws.WebServiceProvider;
import javax.xml.transform.Source;

@WebServiceProvider()
public class SourceProvider implements Provider<Source> {

    public Source echo(Source data) {
        return data;
    }
}

제공자 구현 예제에서 javax.xml.transform.Source 유형은 일반 <Source> 메소드에 지정됩니다. 일반 <Source> 메소드는 입력 및 출력 유형을 모두 Source 오브젝트임을 지정합니다.

다음에 수행할 내용

JavaBeans에서 JAX-WS 애플리케이션에 대한 Java 아티팩트를 개발하십시오. 자세히 학습하려면 JAX-WS 애플리케이션에 대한 Java 아티팩트 생성 정보를 참조하십시오.