第3章 JAX-WS Web サービスの開発

サーバー側で Web サービスエンドポイントを開発する場合、ボトムアップ開発 として知られる Java コードや、トップダウン開発というサービスを定義する WSDL から開始するオプションを利用できます。これが新しいサービスで、既存のコントラクトがない場合、ボトムアップアプローチが最速のルートになります。サービスを稼働させるためには、クラスにアノテーションをいくつか追加する必要があります。ただし、すでに定義されているコントラクトでサービスを開発する場合は、ツールによるアノテーション付きコードの生成を可能にするため、トップダウンアプローチを使用した方がはるかに簡単です。

ボトムアップのユースケース:

トップダウンのユースケース:

wsprovide を使用したダウンアップグレードストラテジー

ボトムアップストラテジーでは、サービスの Java コードを開発し、JAX-WS アノテーションを使用してアノテーションを付ける必要があります。これらのアノテーションを使用して、サービスに生成されるコントラクトをカスタマイズできます。XML ベースの Web Services の Jakarta EE は Jakarta XML Web Services Specification 2.3 です。たとえば、操作名を任意のものにマッピングするように変更できます。ただし、すべてのアノテーションには適切なデフォルトがあるため、@WebService アノテーションのみが必要になります。

これは、単一クラスを作成するのと同じように簡単に実行できます。

package echo;

@javax.jws.WebService
public class Echo {

   public String echo(String input) {
      return input;
   }
}

デプロイメントはこのクラスを使用して構築でき、JBossWS にデプロイするために必要な唯一の Java コードです。ラッパークラスと呼ばれるその他の Java アーティファクトは、デプロイ時に生成されます。

wsprovide ツールの主な目的は、移植可能な AX-WS アーティファクトを生成することです。さらに、サービスの WSDL ファイルを提供するのに使用できます。これは、-w オプションを使用して wsprovide を呼び出すことで取得できます。

$ javac -d . Echo.java
$ EAP_HOME/bin/wsprovide.sh --classpath=. -w echo.Echo

アクセスメントを検査すると、EchoService という名前のサービスが表示されます。

<wsdl:service name="EchoService">
  <wsdl:port name="EchoPort" binding="tns:EchoServiceSoapBinding">
    <soap:address location="http://localhost:9090/EchoPort"/>
  </wsdl:port>
</wsdl:service>

予想通りに、このサービスは、echo という操作を定義します。

<wsdl:portType name="Echo">
  <wsdl:operation name="echo">
    <wsdl:input name="echo" message="tns:echo">
    </wsdl:input>
    <wsdl:output name="echoResponse" message="tns:echoResponse">
    </wsdl:output>
  </wsdl:operation>
</wsdl:portType>

デプロイ時に、このツールを実行する必要はありません。これは、移植可能なアーティファクトまたはサービスの抽象的なコントラクトを生成する場合にのみ必要です。

デプロイメントの POJO エンドポイントは、簡単な web.xml ファイルに作成できます。

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
  version="2.4">

  <servlet>
    <servlet-name>Echo</servlet-name>
    <servlet-class>echo.Echo</servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>Echo</servlet-name>
    <url-pattern>/Echo</url-pattern>
  </servlet-mapping>
</web-app>

web.xml と単一の Java クラスを使用して WAR を作成できます。

$ mkdir -p WEB-INF/classes
$ cp -rp echo WEB-INF/classes/
$ cp web.xml WEB-INF
$ jar cvf echo.war WEB-INF
added manifest
adding: WEB-INF/(in = 0) (out= 0)(stored 0%)
adding: WEB-INF/classes/(in = 0) (out= 0)(stored 0%)
adding: WEB-INF/classes/echo/(in = 0) (out= 0)(stored 0%)
adding: WEB-INF/classes/echo/Echo.class(in = 340) (out= 247)(deflated 27%)
adding: WEB-INF/web.xml(in = 576) (out= 271)(deflated 52%)

WAR は JBoss EAP にデプロイできます。これにより、内部的に wsprovide が呼び出され、その WSDL が生成されます。デプロイメントに成功し、デフォルト設定を使用している場合は、管理コンソールで利用できるようにする必要があります。

wsconsume を使用したトップダウンストラテジー

トップダウンの開発ストラテジーは、サービスの抽象的なコントラクトで始まります。これには WSDL ファイルおよびゼロ以上のスキーマファイルが含まれます。wsconsume ツールを使用してこのコントラクトを消費し、アノテーション付きの Java クラスと、それを定義するオプションのプションのソースを生成します。

ボトムアップの例から WSDL ファイルを使用して、このサービスに準拠する新しい Java 実装を生成することができます。-k オプションは wsconsume に渡され、Java クラスのみを提供する代わりに、生成された Java ソースファイルを保存します。

$ EAP_HOME/bin/wsconsume.sh -k EchoService.wsdl

以下の表には、生成される各ファイルの目的をまとめています。

サービスエンドポイントインターフェースを調べると、ボトムアップの例で手動で記述したクラスよりも明示的なアノテーションが表示されますが、これらは同じコントラクトに対して評価されます。

@WebService(targetNamespace = "http://echo/", name = "Echo")
@XmlSeeAlso({ObjectFactory.class})
public interface Echo {

    @WebMethod
    @RequestWrapper(localName = "echo", targetNamespace = "http://echo/", className = "echo.Echo_Type")
    @ResponseWrapper(localName = "echoResponse", targetNamespace = "http://echo/", className = "echo.EchoResponse")
    @WebResult(name = "return", targetNamespace = "")
    public java.lang.String echo(
        @WebParam(name = "arg0", targetNamespace = "")
        java.lang.String arg0
    );
}

パッケージ化以外の不明な部分は実装クラスで、上記のインターフェースを使用して記述できるようになりました。

package echo;

@javax.jws.WebService(endpointInterface="echo.Echo")
public class EchoImpl implements Echo {
   public String echo(String arg0) {
      return arg0;
   }
}

クライアント側の詳細を確認する前に、Web サービスの中心となる切り離す概念を理解することが重要です。Web サービスは、この方法で使用することもできますが、内部 RPC には適していません。CORBA や RMI などのより優れた技術があります。Web サービスは、特に相互運用可能な粒度の細かい対応のために設計されました。Web サービスの対話に参加しているいかなるパーティも、特定のオペレーティングシステム上で実行したり、特定のプログラミング言語で記述されているといった保証はありません。そのため、クライアントおよびサーバー実装は明確に分離することが重要です。一般的なのは、抽象的なコントラクト定義のみです。何らかの理由でソフトウェアがこの原理に準拠しない場合は、Web サービスを使用しないことをお勧めします。上記の理由により、クライアント開発に推奨される方法は、クライアントが同じサーバーで実行されている場合でもトップダウンアプローチに従うことです。

wsconsume を使用したトップダウンストラテジー

このセクションは、サーバー側のトップダウンセクションのプロセスを繰り返しますが、デプロイ済みの WSDL を使用します。これは、デプロイ時に計算される soap:addressの正しい値を取得します (下記参照)。この値は、必要に応じて手動で編集できますが、正しいパスを指定する必要があります。

<wsdl:service name="EchoService">
  <wsdl:port name="EchoPort" binding="tns:EchoServiceSoapBinding">
    <soap:address location="http://localhost.localdomain:8080/echo/Echo"/>
  </wsdl:port>
</wsdl:service>

wsconsume を使用して、デプロイされた WSDL の Java クラスを生成します。

$ EAP_HOME/bin/wsconsume.sh -k http://localhost:8080/echo/Echo?wsdl

EchoService.java クラスが、WSDL が取得元の場所を保存する方法に注目してください。

@WebServiceClient(name = "EchoService",
                  wsdlLocation = "http://localhost:8080/echo/Echo?wsdl",
                  targetNamespace = "http://echo/")
public class EchoService extends Service {

    public final static URL WSDL_LOCATION;

    public final static QName SERVICE = new QName("http://echo/", "EchoService");
    public final static QName EchoPort = new QName("http://echo/", "EchoPort");

    ...

    @WebEndpoint(name = "EchoPort")
    public Echo getEchoPort() {
        return super.getPort(EchoPort, Echo.class);
    }

    @WebEndpoint(name = "EchoPort")
    public Echo getEchoPort(WebServiceFeature... features) {
        return super.getPort(EchoPort, Echo.class, features);
    }
}

ご覧のとおり、この生成されたクラスは JAX-WS、javax.xml.ws.Service の主なクライアントエントリーポイントを拡張します。Service を直接使用することはできますが、設定情報を提供するため、これははるかに簡単です。サービスエンドポイントインターフェースのインスタンスを返す getEchoPort() メソッドに注意してください。返されたインターフェースでメソッドを呼び出すと、Web サービスの操作をすべて呼び出すことができます。

クライアントの書き込みとコンパイル:

import echo.*;

public class EchoClient {

   public static void main(String args[]) {

      if (args.length != 1) {
          System.err.println("usage: EchoClient <message>");
          System.exit(1);
      }

      EchoService service = new EchoService();
      Echo echo = service.getEchoPort();
      System.out.println("Server said: " + echo.echo(args0));
   }
}

以下のように ENDPOINT_ADDRESS_PROPERTY を設定すると、ランタイム時に操作のエンドポイントアドレスを変更できます。

EchoService service = new EchoService();
Echo echo = service.getEchoPort();

/* Set NEW Endpoint Location */
String endpointURL = "http://NEW_ENDPOINT_URL";
BindingProvider bp = (BindingProvider)echo;
bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpointURL);

System.out.println("Server said: " + echo.echo(args0));

JAX-WS Web サービスエンドポイントは、Web サービスのサーバーコンポーネントです。クライアントおよび他の Web サービスは、Simple Object Access Protocol (SOAP) と呼ばれる XML 言語を使用して HTTP プロトコルを介して通信します。エンドポイント自体は JBoss EAP コンテナーにデプロイされます。

WSDL 記述子は、以下のいずれかの方法で作成できます。

エンドポイント実装 Bean には JAX-WS アノテーションが付けられ、サーバーにデプロイされます。サーバーは、クライアント消費のために、抽象的なコントラクトを自動的に生成し、パブリッシュします。すべてのマーシャリングおよびアンマーシャリングは、Java Architecture for XML Binding (JAXB) サービスに委任されます。

エンドポイント自体は Plain Old Java Object (POJO) または Jakarta EE Web アプリケーションである場合があります。EJB3 ステートレスセッション Bean を使用してエンドポイントを公開することもできます。Web アーカイブ (WAR) ファイルにパッケージ化されます。Java Service Endpoint (JSE) と呼ばれるエンドポイントをパッケージ化するための仕様は JSR-181 で定義されています。JAX-WS API 仕様の Jakarta EE は Jakarta Web Services Metadata Specification 2.1 です。

@WebService
@SOAPBinding(style = SOAPBinding.Style.RPC)
public class JSEBean {
    @WebMethod
    public String echo(String input) {
        ...
    }
}

<web-app ...>
  <servlet>
    <servlet-name>TestService</servlet-name>
    <servlet-class>org.jboss.quickstarts.ws.jaxws.samples.jsr181pojo.JSEBean01</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>TestService</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

以下の EJB3 ステートレスセッション Bean は、リモートインターフェースとエンドポイント操作に同じメソッドを公開します。

@Stateless
@Remote(EJB3RemoteInterface.class)

@WebService

@SOAPBinding(style = SOAPBinding.Style.RPC)
public class EJB3Bean implements EJB3RemoteInterface {
    @WebMethod
    public String echo(String input) {
        ...
    }
}

サービスエンドポイントインターフェース

JAX-WS サービスは通常 Java サービスエンドポイントインターフェース (SEI) を実装します。これは、WSDL ポートタイプから、直接またはアノテーションを使用してマッピングされる可能性があります。この SEI は、Java オブジェクトとその XML 表現の詳細を隠す高度な抽象化を提供します。

エンドポイントプロバイダーインターフェース

JAX-WS サービスは、XML メッセージレベルで動作する必要があることがあります。エンドポイント Provider インターフェースは、この機能を実装する Web サービスにこの機能を提供します。

エンドポイントの使用およびアクセス

Web サービスをデプロイしたら、WSDL を消費してアプリケーションの基盤となるコンポーネントのスタブを作成できます。その後、アプリケーションはエンドポイントにアクセスしてその作業を実行できます。

JAX-WS サービスエンドポイントは、JAX-WS クライアントからのリクエストに応答し、それ自体の WSDL 定義を公開するサーバー側のコンポーネントです。

JAX-WS エンドポイントアプリケーションの開発方法の実例については、JBoss EAP に同梱される以下のクイックスタートを参照してください。

開発要件

Web サービスは、JAX-WS API および JSR 181: Web Services Metadata for the Java Platform 仕様の要件を満たす必要があります。有効な実装は以下の要件を満たします。Web Services Metadata の Jakarta EE に相当するものは、Jakarta Web Services Metadata Specification 2.1 仕様 に含まれています。

これらの要件を満たす Web サービス実装の例を以下に示します。

package org.jboss.quickstarts.ws.jaxws.samples.retail.profile;

import javax.ejb.Stateless;
import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.jws.soap.SOAPBinding;

@Stateless

@WebService(
    name = "ProfileMgmt",
    targetNamespace = "http://org.jboss.ws/samples/retail/profile",
    serviceName = "ProfileMgmtService")
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
public class ProfileMgmtBean {
    @WebMethod
    public DiscountResponse getCustomerDiscount(DiscountRequest request) {
        DiscountResponse dResponse = new DiscountResponse();
        dResponse.setCustomer(request.getCustomer());
        dResponse.setDiscount(10.00);
        return dResponse;
    }
}

以下は、ProfileMgmtBean bean によって DiscountRequest の例です。アノテーションは詳細度のために含まれています。通常、これは JAXB デフォルトは妥当な設定であり、指定する必要はありません。

package org.jboss.test.ws.jaxws.samples.retail.profile;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlType;

import org.jboss.test.ws.jaxws.samples.retail.Customer;

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(
  name = "discountRequest",
  namespace="http://org.jboss.ws/samples/retail/profile",
  propOrder = { "customer" }
)
public class DiscountRequest {

   protected Customer customer;

   public DiscountRequest() {
   }

   public DiscountRequest(Customer customer) {
      this.customer = customer;
   }

   public Customer getCustomer() {
      return customer;
   }

   public void setCustomer(Customer value) {
      this.customer = value;
   }

}

デプロイメントのパッケージ化

実装クラスは JAR デプロイメントでラップされます。デプロイメントに必要なメタデータは、実装クラスとサービスエンドポイントインターフェース上のアノテーションから取得されます。管理 CLI または管理コンソールを使用して JAR をデプロイでき、HTTP エンドポイントが自動的に作成されます。

以下のリストは、EJB Web サービスの JAR デプロイメントの構造の例を示しています。

$ jar -tf jaxws-samples-retail.jar
org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.class
org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.class
org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.class
org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.class
org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtBean.class
org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.class
org/jboss/test/ws/jaxws/samples/retail/profile/package-info.class

Web サービスエンドポイントの作成後、手動で、あるいは JAX-WS アノテーションを使用して、その WSDL にアクセスできます。XML ベースの Web Services の Jakarta EE は Jakarta Enterprise Web Services 1.4 仕様 です。これは、Web サービスと通信する基本的なクライアントアプリケーションを作成するのに使用できます。パブリッシュされた WSDL から Java コードを生成するプロセスは、Web サービスを使用すると呼ばれます。これは以下の場合に発生します。

クライアントアーティファクトの作成

クライアントアーティファクトを作成する前に、WSDL コントラクトを作成する必要があります。以下の WSDL コントラクトは、本セクションの残りの部分に記載の例に使用します。

以下の例は、ProfileMgmtService.wsdl ファイルにこの WSDL コントラクトがあることを前提としています。

<definitions
    name='ProfileMgmtService'
    targetNamespace='http://org.jboss.ws/samples/retail/profile'
    xmlns='http://schemas.xmlsoap.org/wsdl/'
    xmlns:ns1='http://org.jboss.ws/samples/retail'
    xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
    xmlns:tns='http://org.jboss.ws/samples/retail/profile'
    xmlns:xsd='http://www.w3.org/2001/XMLSchema'>

   <types>

      <xs:schema targetNamespace='http://org.jboss.ws/samples/retail'
                 version='1.0' xmlns:xs='http://www.w3.org/2001/XMLSchema'>
         <xs:complexType name='customer'>
            <xs:sequence>
               <xs:element minOccurs='0' name='creditCardDetails' type='xs:string'/>
               <xs:element minOccurs='0' name='firstName' type='xs:string'/>
               <xs:element minOccurs='0' name='lastName' type='xs:string'/>
            </xs:sequence>
         </xs:complexType>
      </xs:schema>

      <xs:schema
          targetNamespace='http://org.jboss.ws/samples/retail/profile'
          version='1.0'
          xmlns:ns1='http://org.jboss.ws/samples/retail'
          xmlns:tns='http://org.jboss.ws/samples/retail/profile'
          xmlns:xs='http://www.w3.org/2001/XMLSchema'>

         <xs:import namespace='http://org.jboss.ws/samples/retail'/>
         <xs:element name='getCustomerDiscount'
                     nillable='true' type='tns:discountRequest'/>
         <xs:element name='getCustomerDiscountResponse'
                     nillable='true' type='tns:discountResponse'/>
         <xs:complexType name='discountRequest'>
            <xs:sequence>
               <xs:element minOccurs='0' name='customer' type='ns1:customer'/>

            </xs:sequence>
         </xs:complexType>
         <xs:complexType name='discountResponse'>
            <xs:sequence>
               <xs:element minOccurs='0' name='customer' type='ns1:customer'/>
               <xs:element name='discount' type='xs:double'/>
            </xs:sequence>
         </xs:complexType>
      </xs:schema>

   </types>

   <message name='ProfileMgmt_getCustomerDiscount'>
      <part element='tns:getCustomerDiscount' name='getCustomerDiscount'/>
   </message>
   <message name='ProfileMgmt_getCustomerDiscountResponse'>
      <part element='tns:getCustomerDiscountResponse'
            name='getCustomerDiscountResponse'/>
   </message>
   <portType name='ProfileMgmt'>
      <operation name='getCustomerDiscount'
                 parameterOrder='getCustomerDiscount'>

         <input message='tns:ProfileMgmt_getCustomerDiscount'/>
         <output message='tns:ProfileMgmt_getCustomerDiscountResponse'/>
      </operation>
   </portType>
   <binding name='ProfileMgmtBinding' type='tns:ProfileMgmt'>
      <soap:binding style='document'
                    transport='http://schemas.xmlsoap.org/soap/http'/>
      <operation name='getCustomerDiscount'>
         <soap:operation soapAction=''/>
         <input>

            <soap:body use='literal'/>
         </input>
         <output>
            <soap:body use='literal'/>
         </output>
      </operation>
   </binding>
   <service name='ProfileMgmtService'>
      <port binding='tns:ProfileMgmtBinding' name='ProfileMgmtPort'>

         <!-- service address will be rewritten to actual one when WSDL is requested from running server -->
         <soap:address location='http://SERVER:PORT/jaxws-retail/ProfileMgmtBean'/>
      </port>
   </service>
</definitions>

Wsconsume.sh ツールまたは wsconsume.bat ツールは、抽象的なコントラクト (WSDL) を消費し、アノテーション付きの Java クラスと、これを定義するオプションのソースを生成するために使用されます。このファイルは EAP_HOME/bin/ ディレクトリーにあります。

$ ./wsconsume.sh --help
WSConsumeTask is a cmd line tool that generates portable JAX-WS artifacts from a WSDL file.

usage: org.jboss.ws.tools.cmd.WSConsume [options] <wsdl-url>

options:
    -h, --help                  Show this help message
    -b, --binding=<file>        One or more JAX-WS or Java XML Binding files
    -k, --keep                  Keep/Generate Java source
    -c  --catalog=<file>        Oasis XML Catalog file for entity resolution
    -p  --package=<name>        The target package for generated source
    -w  --wsdlLocation=<loc>    Value to use for @WebService.wsdlLocation
    -o, --output=<directory>    The directory to put generated artifacts
    -s, --source=<directory>    The directory to put Java source
    -t, --target=<2.0|2.1|2.2>  The JAX-WS target
    -q, --quiet                 Be somewhat more quiet
    -v, --verbose               Show full exception stack traces
    -l, --load-consumer         Load the consumer and exit (debug utility)
    -e, --extension             Enable SOAP 1.2 binding extension
    -a, --additionalHeaders     Enable processing of implicit SOAP headers
    -n, --nocompile             Do not compile generated sources

以下のコマンドは、出力に一覧表示されている .java ファイルを ProfileMgmtService.wsdl ファイルから生成します。ソースは、-p スイッチで指定されたパッケージのディレクトリー構造を使用します。

[user@host bin]$ wsconsume.sh -k -p org.jboss.test.ws.jaxws.samples.retail.profile ProfileMgmtService.wsdl
output/org/jboss/test/ws/jaxws/samples/retail/profile/Customer.java
output/org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.java
output/org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.java
output/org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.java
output/org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.java
output/org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.java
output/org/jboss/test/ws/jaxws/samples/retail/profile/package-info.java
output/org/jboss/test/ws/jaxws/samples/retail/profile/Customer.class
output/org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.class
output/org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.class
output/org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.class
output/org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.class
output/org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.class
output/org/jboss/test/ws/jaxws/samples/retail/profile/package-info.class

.java ソースファイルとコンパイルされた .class ファイルはどちらも、コマンドを実行するディレクトリー内の output/ ディレクトリーに生成されます。

wsconsume コマンドは、すべてのカスタムデータタイプ (JAXB アノテーションが付けられたクラス)、サービスエンドポイントインターフェース、およびサービスファクトリークラスを生成します。これらのアーティファクトは、Web サービスクライアントの実装をビルドするために使用されます。

サービススタブの構成

Web サービスクライアントはサービススタブを使用して、リモート Web サービス呼び出しの詳細を抽象化します。クライアントアプリケーションの場合、Web サービスの呼び出しは他のビジネスコンポーネントの呼び出しと同様になります。この場合、サービスエンドポイントインターフェースはビジネスインターフェースとして機能し、サービスファクトリークラスはサービススタブとしての構築に使用されません。

以下の例では、まずは WSDL の場所とサービス名を使用してサービスファクトリーを作成します。次に、 wsconsume により作成されたサービスエンドポイントインターフェースを使用してサービススタブを構築します。最後に、スタブは他のビジネスインターフェースと同様に使用できます。

JBoss EAP 管理コンソールでは、エンドポイントの WSDL URL を確認できます。この URL を見つけるには、Runtime に移動して、該当するサーバーを選択し、Webservicesを 選択してエンドポイントを選択します。

import javax.xml.ws.Service;
[...]
Service service = Service.create(
new URL("http://example.org/service?wsdl"),
new QName("MyService")
);
ProfileMgmt profileMgmt = service.getPort(ProfileMgmt.class);

// Use the service stub in your application

クライアントは Java Enterprise Edition 7 コンテナーにデプロイされた JAX-WS エンドポイントと通信し、そこから要求を行います。以下のクラス、メソッド、およびその他の実装の詳細は、JBoss EAP に含まれる Javadocs バンドルの関連セクションを参照してください。

概要

Service は、WSDL サービスを表す抽象化です。WSDL サービスは、一連の関連ポートです。それぞれには、特定のプロトコルとエンドポイントアドレスに結合したポートタイプが含まれます。

通常、サービスの生成は、残りのコンポーネントのスタブが、既存の WSDL コントラクトから生成されると行われます。WSDL コントラクトは、デプロイされたエンドポイントの WSDL URL 経由で利用できます。または、EAP_HOME/bin/ ディレクトリーの wsprovide ツールを使用してエンドポイントソースから作成できます。

このタイプの使用は、静的なユースケースと呼ばれます。この場合、コンポーネントのスタブのいずれかとして作成された Service クラスのインスタンスを作成します。

Service.create メソッドを使用してサービスを手動で作成することもできます。これは、動的なユースケースと呼ばれます。

使用方法

静的ユースケース

JAX-WS クライアントの静的ユースケースでは、すでに WSDL コントラクトが存在することを前提としています。これは外部ツールで生成されるか、JAX-WS エンドポイントの作成時に適切な JAX-WS アノテーションを使用して生成される可能性があります。

コンポーネントのスタブを生成するには、EAP_HOME/bin に含まれる wsconsume ツールを使用します。このツールは、コンテナー URL またはファイルをパラメーターとして取り、ディレクトリーツリーで構造化された複数のファイルを生成します。Service を表すソースおよびクラスファイルはそれぞれ _Service.java と _Service.class です。

生成された実装クラスには、引数のないパブリックコンストラクターと、2 つの引数を持つコンストラクターがあります。これら 2 つの引数はそれぞれ WSDL の場所 (java.net.URL) とサービス名 (javax.xml.namespace.QName) を表します。

引数なしのコンストラクターは最もよく使用されます。この場合、WSDL の場所とサービス名は WSDL にあるものです。これらは、生成されたクラスをデコレートする @WebServiceClient アノテーションから暗黙的に設定されます。

@WebServiceClient(name="StockQuoteService", targetNamespace="http://example.com/stocks", wsdlLocation="http://example.com/stocks.wsdl")
public class StockQuoteService extends javax.xml.ws.Service
{
   public StockQuoteService() {
      super(new URL("http://example.com/stocks.wsdl"), new QName("http://example.com/stocks", "StockQuoteService"));
   }

   public StockQuoteService(String wsdlLocation, QName serviceName) {
      super(wsdlLocation, serviceName);
   }
   ...
}

サービスからポートを取得する方法と、ポートでの操作の呼び出し方法に関する詳細は、Dynamic Proxy を参照してください。XML ペイロードを直接使用するか、SOAP メッセージ全体の XML 表現を使用する方法は、Dispatch を参照してください。

動的ユースケース

動的の場合、スタブは自動的に生成されません。代わりに、Web サービスクライアントは Service.create メソッドを使用して Service インスタンスを作成します。以下のコードはこのプロセスを示しています。

URL wsdlLocation = new URL("http://example.org/my.wsdl");
QName serviceName = new QName("http://example.org/sample", "MyService");
Service service = Service.create(wsdlLocation, serviceName);

ハンドラー解決

JAX-WS は、ハンドラーと呼ばれるメッセージ処理モジュールに柔軟なプラグインフレームワークを提供します。これらのハンドラーは JAX-WS ランタイムシステムの機能を拡張します。Service インスタンスは、getHandlerResolver と setHandlerResolver メソッドのペア経由で HandlerResolver へのアクセスを提供し、サービス別、ポート別、またはプロトコル別のバインディングベースでハンドラーのセットを設定することができます。

Service インスタンスでプロキシーまたは Dispatch インスタンスを作成すると、現在サービスに登録されているハンドラーリゾルバーが必要なハンドラーチェーンを作成します。Service インスタンスに設定されたハンドラーリゾルバーへの変更は、以前に作成されたプロキシーまたは Dispatch インスタンスでのハンドラーには影響を与えません。

Executor

Service インスタンスは、java.util.concurrent.Executor を使用して設定できます。Executor は、アプリケーションによってリクエストされた非同期コールバックを呼び出します。Service の setExecutor および getExecutor メソッドは、サービスに設定された Executor を変更および取得できます。

動的プロキシー

動的プロキシーは、Service で提供される getPort メソッドのいずれかを使用するクライアントプロキシーのインスタンスです。portName は、サービスが使用する WSDL ポートの名前を指定します。serviceEndpointInterface は、作成された動的プロキシーインスタンスでサポートされるサービスエンドポイントインターフェースを指定します。

public <T> T getPort(QName portName, Class<T> serviceEndpointInterface)
public <T> T getPort(Class<T> serviceEndpointInterface)

Service Endpoint Interface は通常 wsconsume ツールを使用して生成されます。これは、WSDL を解析し、そこから Java クラスを作成します。

ポートを返す、タイプ指定されたメソッドも提供されます。これらのメソッドは、SEI を実装する動的プロキシーも返します。以下の例を参照してください。

@WebServiceClient(name = "TestEndpointService", targetNamespace = "http://org.jboss.ws/wsref",
   wsdlLocation = "http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl")

public class TestEndpointService extends Service {
    ...

    public TestEndpointService(URL wsdlLocation, QName serviceName) {
        super(wsdlLocation, serviceName);
    }

    @WebEndpoint(name = "TestEndpointPort")
    public TestEndpoint getTestEndpointPort() {
        return (TestEndpoint)super.getPort(TESTENDPOINTPORT, TestEndpoint.class);
    }
}

@WebServiceRef

@WebServiceRef アノテーションは Web サービスへの参照を宣言します。これは、JSR 250 で定義された javax.annotation.Resource アノテーションによって示されるリソースパターンに従います。これらのアノテーションの Jakarta EE と同等の Jakarta EE は、Jakarta Annotations 1.3 仕様 に含まれています。

Dispatch

XML Web サービスは、Java EE コンテナーおよびすべてのクライアントにデプロイされる、エンドポイント間の通信に XML メッセージを使用します。XML メッセージは、Simple Object Access Protocol (SOAP) と呼ばれる XML 言語を使用します。JAX-WS API は、エンドポイントとクライアントのメカニズムを提供し、各エンドポイントが SOAP メッセージを送受信できるようにします。マーシャリングは、Java オブジェクトを SOAP XML メッセージに変換するプロセスです。マーシャリング解除とは、SOAP XML メッセージを Java オブジェクトに変換するプロセスのことです。

変換の結果ではなく、raw SOAP メッセージ自体にアクセスする必要がある場合があります。Dispatch クラスはこの機能を提供します。Dispatch は、以下の定数のいずれかによって識別される、2 つの使用モードのいずれかで動作します。

Dispatch は低レベルの API で、クライアントはメッセージまたはペイロードを XML として構成する必要があります。これは、個別のプロトコルの標準と、メッセージまたはペイロード構造の詳細な知識とメッセージに忠実に従った状態を意味します。Dispatch は、メッセージの入出力または、任意のタイプのメッセージペイロードに対応した汎用クラスです。

Service service = Service.create(wsdlURL, serviceName);
Dispatch dispatch = service.createDispatch(portName, StreamSource.class, Mode.PAYLOAD);

String payload = "<ns1:ping xmlns:ns1='http://oneway.samples.jaxws.ws.test.jboss.org/'/>";
dispatch.invokeOneWay(new StreamSource(new StringReader(payload)));

payload = "<ns1:feedback xmlns:ns1='http://oneway.samples.jaxws.ws.test.jboss.org/'/>";
Source retObj = (Source)dispatch.invoke(new StreamSource(new StringReader(payload)));

非同期呼び出し

BindingProvider インターフェースは、クライアントが使用できるプロトコルバインディングを提供するコンポーネントを表します。これはプロキシーによって実装され、Dispatch インターフェースによって拡張されます。

BindingProvider インスタンスは非同期操作機能を提供する可能性があります。非同期操作の呼び出しは、呼び出し時に BindingProvider インスタンスから切り離されます。操作が完了しても、応答コンテキストは更新されません。代わりに、Response インターフェースを使用して個別の応答コンテキストを利用できます。

public void testInvokeAsync() throws Exception {
   URL wsdlURL = new URL("http://" + getServerHost() + ":8080/jaxws-samples-asynchronous?wsdl");
   QName serviceName = new QName(targetNS, "TestEndpointService");
   Service service = Service.create(wsdlURL, serviceName);
   TestEndpoint port = service.getPort(TestEndpoint.class);
   Response response = port.echoAsync("Async");
   // access future
   String retStr = (String) response.get();
   assertEquals("Async", retStr);
}

@oneway 呼び出し

@oneway アノテーションは、指定の web メソッドが入力メッセージを取得し、出力メッセージを返しないことを示します。通常、@Oneway メソッドは、ビジネスメソッドの実行前に、制御のスレッドを呼び出しアプリケーションに戻します。

@WebService (name="PingEndpoint")
@SOAPBinding(style = SOAPBinding.Style.RPC)
public class PingEndpointImpl {
   private static String feedback;

   @WebMethod
   @Oneway
   public void ping() {
      log.info("ping");
      feedback = "ok";
   }

   @WebMethod
   public String feedback() {
      log.info("feedback");
      return feedback;
   }
}

タイムアウトの設定

2 種類のプロパティーが HTTP 接続のタイムアウトの動作と、メッセージの受信を待機しているクライアントのタイムアウトを制御します。最初のプロパティーは、javax.xml.ws.client.connectionTimeout で、次のプロパティーは、javax.xml.ws.client.receiveTimeout です。それぞれはミリ秒単位で示され、正しい構文を以下に示します。

public void testConfigureTimeout() throws Exception {
   //Set timeout until a connection is established
   ((BindingProvider)port).getRequestContext().put("javax.xml.ws.client.connectionTimeout", "6000");

   //Set timeout until the response is received
   ((BindingProvider) port).getRequestContext().put("javax.xml.ws.client.receiveTimeout", "1000");

   port.echo("testTimeout");
}

JBossWS では、追加の設定データを事前定義し、エンドポイント実装に関連付けることができます。事前定義されたエンドポイント設定は JAX-WS クライアントおよび JAX-WS エンドポイントの設定に使用できます。エンドポイント設定には JAX-WS ハンドラーとキー/値のプロパティー宣言を含めることができます。この機能は、ハンドラーを Web サービスのエンドポイントに追加し、JBossWS および Apache CXF 内部を制御する key/value プロパティーを設定する便利な方法を提供します。

webservices サブシステムを使用すると、エンドポイント設定データの名前付きセットを定義できます。各エンドポイント設定にはサブシステム内で一意な名前を付ける必要があります。その後、org.jboss.ws.api.annotation.EndpointConfig アノテーションを使用して、デプロイされたプリケーションの JAX-WS 実装にエンドポイント設定を割り当てることができます。エンドポイント設定の割り当ての詳細は、Assigning a Configuration を参照してください。

デフォルトの JBoss EAP 設定には、事前定義されたエンドポイント設定があります。

エンドポイント設定の追加

管理 CLI を使用して新しいエンドポイント設定を追加できます。

/subsystem=webservices/endpoint-config=My-Endpoint-Config:add

エンドポイント設定の構成

管理 CLI を使用してエンドポイント設定の key/value プロパティー宣言を追加できます。

/subsystem=webservices/endpoint-config=Standard-Endpoint-Config/property=PROPERTY_NAME:add(value=PROPERTY_VALUE)

これらのエンドポイント設定のhandler chains および handlers を設定できます。

エンドポイント設定の削除

管理 CLI を使用してエンドポイント設定を削除できます。

/subsystem=webservices/endpoint-config=My-Endpoint-Config:remove

各エンドポイント設定は PRE または POST ハンドラーチェーンに関連付けることができます。各ハンドラーチェーンには JAX-WS 準拠のハンドラーが含まれ、メッセージに対して追加の処理を実行できます。アウトバウンドメッセージの場合、PRE ハンドラーチェーンハンドラーは、@HandlerChain アノテーションなどの標準の JAX-WS を使用してエンドポイントにアタッチされたハンドラーの前に実行されます。POST ハンドラーチェーンハンドラーは、通常のエンドポイントハンドラーの後に実行されます。受信メッセージには、逆が適用されます。

Endpoint --> PRE Handlers --> Endpoint Handlers --> POST Handlers --> ... --> Client

Client --> ... --> POST Handlers --> Endpoint Handlers --> PRE Handlers --> Endpoint

ハンドラーチェーンの追加

以下の管理 CLI コマンドを使用すると、POST ハンドラーチェーンをエンドポイント設定に追加できます。

/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain:add

以下の管理 CLI コマンドを使用すると、PRE ハンドラーチェーンをエンドポイント設定に追加できます。

/subsystem=webservices/endpoint-config=My-Endpoint-Config/pre-handler-chain=my-pre-handler-chain:add

ハンドラーチェーンの設定

protocol-bindings 属性を使用して、ハンドラーチェーンの開始をトリガーするプロトコルを設定します。

/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain:write-attribute(name=protocol-bindings,value=##SOAP11_HTTP)

ハンドラーチェーンのハンドラーの設定に関する詳細は、ハンドラーのセクションを参照してください。

ハンドラーチェーンの削除

管理 CLI を使用してハンドラーチェーンを削除できます。

/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain:remove

JAX-WS ハンドラーがハンドラーチェーンに追加され、ハンドラークラスの完全修飾名を指定します。エンドポイントがデプロイされると、参照デプロイメントごとにそのクラスのインスタンスが作成されます。org.jboss.as.webservices.server.integration モジュールのデプロイメントクラスローダーまたはクラスローダーのいずれかがハンドラークラスをロードできる必要があります。

利用可能なハンドラーの一覧は 、 ハンドラー Javadoc を参照してください。

ハンドラーの追加

以下の管理 CLI コマンドを使用するとハンドラーをハンドラーチェーンに追加できます。ハンドラーのクラス名を指定する必要があります。

/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain/handler=my-handler:add(class="com.arjuna.webservices11.wsarj.handler.InstanceIdentifierInHandler")

ハンドラーの設定

管理 CLI を使用してハンドラーのクラスを更新できます。

/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain/handler=my-handler:add(class="org.jboss.ws.common.invocation.RecordingServerHandler")

ハンドラーの削除

管理 CLI を使用してハンドラーを削除できます。

/subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-post-handler-chain/handler=my-handler:

WSDL コントラクトで公開されるエンドポイントの <soap:address> 要素の書き換えがサポートされます。この機能は、各エンドポイントのクライアントに公開されるサーバーアドレスを制御するのに役立ちます。

以下の表は、この機能に設定できる属性を表しています。

管理 CLI を使用してこれらの属性を更新できます。例を以下に示します。

/subsystem=webservices:write-attribute(name=wsdl-uri-scheme, value=https)

各 Web サービスエンドポイントは、エンドポイント実装を提供するデプロイメントで公開されます。各エンドポイントはデプロイメントリソースとしてクエリーできます。各 Web サービスのエンドポイントは、Web コンテキストと WSDL URL を指定します。管理 CLI または管理コンソールを使用してこのランタイム情報にアクセスできます。

以下の管理 CLI コマンドは、jaxws-samples-handlerchain.war デプロイメントからの TestService エンドポイントの詳細を表示します。

/deployment="jaxws-samples-handlerchain.war"/subsystem=webservices/endpoint="jaxws-samples-handlerchain:TestService":read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "average-processing-time" => 23L,
        "class" => "org.jboss.test.ws.jaxws.samples.handlerchain.EndpointImpl",
        "context" => "jaxws-samples-handlerchain",
        "fault-count" => 0L,
        "max-processing-time" => 23L,
        "min-processing-time" => 23L,
        "name" => "TestService",
        "request-count" => 1L,
        "response-count" => 1L,
        "total-processing-time" => 23L,
        "type" => "JAXWS_JSE",
        "wsdl-url" => "http://localhost:8080/jaxws-samples-handlerchain?wsdl"
    }
}

/subsystem=webservices:write-attribute(name=statistics-enabled,value=true)

管理コンソールの Runtime タブから、Web サービスエンドポイントのランタイム情報を表示することもできます。そのためには、該当するサーバーを選択し、Webservices を選択してエンドポイントを選択します。

明示的な設定割り当ては、指定の設定に従ってセットアップされる必要のあるエンドポイントまたはクライアントを開発者が事前に認識するためのものです。この設定は、アプリケーションデプロイメントに含まれる記述子か、または webservices サブシステムに含まれます。

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>org.jboss.test.ws.jaxws.jbws3282.Endpoint4Impl</config-name>
    <pre-handler-chains>
      <javaee:handler-chain>
        <javaee:handler>
          <javaee:handler-name>Log Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.LogHandler</javaee:handler-class>
        </javaee:handler>
      </javaee:handler-chain>
    </pre-handler-chains>
    <post-handler-chains>
      <javaee:handler-chain>
        <javaee:handler>
          <javaee:handler-name>Routing Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.RoutingHandler</javaee:handler-class>
        </javaee:handler>
      </javaee:handler-chain>
    </post-handler-chains>
  </endpoint-config>
  <endpoint-config>
    <config-name>EP6-config</config-name>
    <post-handler-chains>
      <javaee:handler-chain>
        <javaee:handler>
          <javaee:handler-name>Authorization Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.AuthorizationHandler</javaee:handler-class>
        </javaee:handler>
      </javaee:handler-chain>
    </post-handler-chains>
  </endpoint-config>
</jaxws-config>

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <client-config>
    <config-name>Custom Client Config</config-name>
    <pre-handler-chains>
      <javaee:handler-chain>
        <javaee:handler>
          <javaee:handler-name>Routing Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.RoutingHandler</javaee:handler-class>
        </javaee:handler>
        <javaee:handler>
          <javaee:handler-name>Custom Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.CustomHandler</javaee:handler-class>
        </javaee:handler>
      </javaee:handler-chain>
    </pre-handler-chains>
  </client-config>
  <client-config>
    <config-name>Another Client Config</config-name>
    <post-handler-chains>
      <javaee:handler-chain>
        <javaee:handler>
          <javaee:handler-name>Routing Handler</javaee:handler-name>
          <javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.RoutingHandler</javaee:handler-class>
        </javaee:handler>
      </javaee:handler-chain>
    </post-handler-chains>
  </client-config>
</jaxws-config>

<subsystem xmlns="urn:jboss:domain:webservices:2.0">
    <!-- ... -->
    <endpoint-config name="Standard-Endpoint-Config"/>
    <endpoint-config name="Recording-Endpoint-Config">
        <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM">
            <handler name="RecordingHandler" class="org.jboss.ws.common.invocation.RecordingServerHandler"/>
        </pre-handler-chain>
    </endpoint-config>
    <client-config name="Standard-Client-Config"/>
</subsystem>

<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>Custom WS-Security Endpoint</config-name>
    <property>
      <property-name>ws-security.signature.properties</property-name>
      <property-value>bob.properties</property-value>
    </property>
    <property>
      <property-name>ws-security.encryption.properties</property-name>
      <property-value>bob.properties</property-value>
    </property>
    <property>
      <property-name>ws-security.signature.username</property-name>
      <property-value>bob</property-value>
    </property>
    <property>
      <property-name>ws-security.encryption.username</property-name>
      <property-value>alice</property-value>
    </property>
    <property>
      <property-name>ws-security.callback-handler</property-name>
      <property-value>org.jboss.test.ws.jaxws.samples.wsse.policy.basic.KeystorePasswordCallback</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

<subsystem xmlns="urn:jboss:domain:webservices:2.0">
    <!-- ... -->
    <endpoint-config name="Standard-Endpoint-Config">
        <property name="schema-validation-enabled" value="true"/>
    </endpoint-config>
    <!-- ... -->
    <client-config name="Standard-Client-Config">
        <property name="schema-validation-enabled" value="true"/>
    </client-config>
</subsystem>

@EndpointConfig(configFile = "WEB-INF/my-endpoint-config.xml", configName = "Custom WS-Security Endpoint")
public class ServiceImpl implements ServiceIface {
   public String sayHello() {
      return "Secure Hello World!";
   }
}

import org.jboss.ws.api.configuration.ClientConfigFeature;

Service service = Service.create(wsdlURL, serviceName);

Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config"));
port.echo("Kermit");

Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config"), true);

Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature(null, "Container Custom Client Config"));

import org.jboss.ws.api.configuration.ClientConfigUtil;
import org.jboss.ws.api.configuration.ClientConfigurer;

Service service = Service.create(wsdlURL, serviceName);
Endpoint port = service.getPort(Endpoint.class);
BindingProvider bp = (BindingProvider)port;

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config");
port.echo("Kermit");

ClientConfigUtil.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config");

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigHandlers(bp, null, "Container Custom Client Config");

import org.jboss.ws.api.configuration.ClientConfigUtil;
import org.jboss.ws.api.configuration.ClientConfigurer;

Service service = Service.create(wsdlURL, serviceName);
Endpoint port = service.getPort(Endpoint.class);

ClientConfigUtil.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config");
port.echo("Kermit");

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config");

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigProperties(port, null, "Container Custom Client Config");

アプリケーション開発者は、クライアントおよびエンドポイントの実装に使用する必要がある設定を認識していない場合があります。その他の場合は、コンパイルタイム依存関係であるため、JBossWS API の明示的な使用が許可されない可能性があります。このようなシナリオに対応するため、JBossWS ではデフォルトのクライアント、jaxws-client-config.xml、およびエンドポイント、jaxws-endpoint-config.xml、記述子をルートディレクトリー内のアプリケーションに含めることができます。これらは、設定ファイル名が指定されていない場合に設定を取得するために解析されます。

<config-file>WEB-INF/jaxws-endpoint-config.xml</config-file>

設定名が指定されていない場合、JBossWS は以下のようにという名前の設定を自動的に検索します。

Dispatch クライアントの自動設定名は選択されません。

たとえば、事前設定されていないエンドポイント実装クラス org.foo.bar.EndpointImpl により、JBossWS はアプリケーションデプロイメントのルートで jaxws-endpoint-config.xml 記述子内で org.foo.bar.EndpointImpl という名前の設定を検索します。同様に、クライアント側では、org.foo.bar.Endpoint インターフェースを実装するクライアントプロキシーには、jaxws-client-config.xml 記述子の org.foo.bar.Endpoint という名前の設定からセットアップ読み取りが行われます。

JBossWS は、明示的な設定が指定されておらず、デフォルトの記述子が利用できないか、または関連する設定を含まない場合に、コンテナーから事前定義された設定を取得するようフォールバックします。この動作により、コンテナーはデプロイされたアプリケーションから独立して管理できるため、JAX-WS クライアントおよびエンドポイントの設定に対する追加の制御が管理者に付与されます。

JBossWS は明示的に名前が付けられた設定の webservices サブシステムにアクセスします。使用されるデフォルト設定名は以下のようになります。

Dispatch クライアントは自動的には設定されません。上記で計算した名前を使用して設定が見つからない場合、Standard-Client-Config および Standard-Endpoint-Config 設定がクライアントとエンドポイントにそれぞれ使用されます。

デプロイメントの依存関係を設定するには、MANIFEST.MF ファイルに追加します。例を以下に示します。

Manifest-Version: 1.0
Dependencies: org.jboss.ws.cxf.jbossws-cxf-client services export,foo.bar

この MANIFEST.MF ファイルは、org.jboss.ws.cxf.jbossws-cxf-client および foo.bar モジュールの依存関係を宣言します。エクスポート および サービス のオプションなど、MANIFEST.MF ファイルに依存関係を宣言する方法は、JBoss EAP 『開発ガイド』 の「 MANIFEST.MF への依存関係の設定の追加 」を参照してください。

Apache CXF エンドポイントやハンドラーなどのエンドポイントおよびハンドラーでアノテーションを使用する場合は、マニフェストファイルに適切なモジュール依存関係を追加します。この手順を省略すると、アノテーションは選択されず、完全に無視されます。

Dependencies: com.sun.xml.bind services export

Dependencies: org.apache.cxf services

Dependencies: org.jboss.ws.cxf.jbossws-cxf-client services

Dependencies: my.org annotations

状況によっては、MANIFEST.MF ファイルでモジュールの依存関係を設定する便利なアプローチは機能しない場合があります。たとえば、MANIFEST.MF ファイルに依存関係を設定しても、指定のモジュール依存関係から特定のリソースをインポートおよびエクスポートしても機能しません。これらのシナリオでは、jboss-deployment-structure.xml 記述子ファイルをデプロイメントに追加し、そのデプロイメントにモジュール依存関係を設定します。

jboss-deployment-structure.xml の使用に関する詳細は、JBoss EAP 『開発ガイド』 の「 jboss-deployment-structure.xml への依存関係設定の追加 」を参照してください。

Web サービスは、WS-Security 機能が必要な多くの実際のシナリオをサポートします。これらのシナリオには、X509 証明書による署名および暗号化サポート、ユーザー名トークンによる認証および承認、および WS-SecurityPolicy 仕様でカバーされるすべての WS-Security 設定が含まれます。

その他の WS-* 機能については、WS-Security 機能のコアは Apache CXF エンジンを介して提供されます。さらに、JBossWS 統合では、WS-Security が有効なエンドポイントの設定を簡素化するいくつかの設定拡張が追加されました。

WS-Trust は、WS-Security の拡張機能を定義する Web サービス仕様です。これは、分散システムにセキュリティーを実装するための一般的なフレームワークです。標準は、クライアントを認証し、さまざまなタイプの認証および承認データを含むトークンを発行できる集中型セキュリティートークンサービス (STS) に基づいています。この仕様は、セキュリティートークンの発行、交換、および検証に使用されるプロトコルを記述します。WS-Trust アーキテクチャーでは、以下の仕様が重要な役割を果たします。

WS-Trust 拡張機能は、複数のドメインにまたがり、セキュリティー鍵の共有を必要とするアプリケーションのニーズに対応します。これは、Web サービスプロバイダーと Web サービスプロバイダー間の信頼関係をブローカーするために、標準ベースの信頼できるサードパーティーの Web サービス (STS) を提供することで行います。このアーキテクチャーは、この情報の一般的な場所を提供することで、認証情報の変更を必要とするサービス更新の一時停止も軽減します。STS は、要求側とプロバイダーの両方がセキュリティートークンを取得し、検証する一般的なアクセスポイントです。

WS-Trust 仕様には、主に以下のコンポーネントがあります。

次のセクションでは、基本的な WS-Trust シナリオについて説明します。高度なシナリオは、Advanced WS-Trust Scenarios を参照してください。

Security Token Service (STS) は WS-Trust 仕様の中核となります。認証および承認の標準ベースのメカニズムです。STS は、トークンの形式、名前空間、または信頼の境界に基づいて、セキュリティートークンの発行、変更、および検証を行うための WS-Trust 仕様のプロトコルの実装です。STS は、Web サービス要求側と Web サービスプロバイダーとの間の信頼関係をブローカー化するために信頼できるサードパーティーとして機能する Web サービスです。これは、要求側とプロバイダーの両方が信頼する共通のアクセスポイントで、相互運用可能なセキュリティートークンを提供します。これにより、要求元とプロバイダー間の直接的な関係が不要になります。STS は認証用の標準ベースのメカニズムであるため、レルム間および異なるプラットフォーム間での相互運用性を確保します。

STS コントラクトは、他のアプリケーションおよびプロセスが対話する方法を定義します。特に、WSDL は WS-Trust ポリシーと WS-Security ポリシーを定義します。このポリシーでは、リクエストャーが STS のエンドポイントと正常に通信するために満たさなければならなりません。Web サービスリクエスターは STS のパッケージを使用し、STSClient ユーティリティーを使用して、指定されたセキュリティーポリシーに準拠するメッセージリクエストを生成し、STS エンドポイントに送信します。STS は要求を検証し、適切な応答を返します。

/subsystem=security/security-domain=sts:add(cache-type=default)

/subsystem=security/security-domain=sts/authentication=classic:add

/subsystem=security/security-domain=sts/authentication=classic/login-module=UsersRoles:add(code=UsersRoles,flag=required,module-options=[usersProperties=${jboss.server.config.dir}/sts-users.properties,rolesProperties=${jboss.server.config.dir}/sts-roles.properties])

reload

<security-domain name="sts" cache-type="default">
  <authentication>
    <login-module code="UsersRoles" flag="required">
      <module-option name="usersProperties" value="${jboss.server.config.dir}/sts-users.properties"/>
      <module-option name="rolesProperties" value="${jboss.server.config.dir}/sts-roles.properties"/>
    </login-module>
  </authentication>
</security-domain>

Eric=samplePass
Alan=samplePass

Eric=All
Alan=

<web-app>
  <!-- Define STS servlet -->
  <servlet>
    <servlet-name>STS-servlet</servlet-name>
    <servlet-class>com.example.sts.PicketLinkSTService</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>STS-servlet</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
  <!-- Define a security constraint that requires the All role to access resources -->
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>STS</web-resource-name>
      <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>All</role-name>
    </auth-constraint>
  </security-constraint>
  <!-- Define the Login Configuration for this Application -->
  <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>STS Realm</realm-name>
  </login-config>
  <!-- Security roles referenced by this web application -->
  <security-role>
    <description>The role that is required to log in to the IDP Application</description>
    <role-name>All</role-name>
  </security-role>
</web-app>

<jboss-web>
  <security-domain>sts</security-domain>
  <context-root>SecureTokenService</context-root>
</jboss-web>

<jboss-deployment-structure>
  <deployment>
    <dependencies>
      <module name="org.picketlink"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

<?xml version="1.0"?>
<wsdl:definitions name="PicketLinkSTS" targetNamespace="urn:picketlink:identity-federation:sts"
	xmlns:tns="urn:picketlink:identity-federation:sts"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
	xmlns:wsap10="http://www.w3.org/2006/05/addressing/wsdl"
	xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/">
  <wsdl:types>
    <xs:schema targetNamespace="urn:picketlink:identity-federation:sts"
      xmlns:tns="urn:picketlink:identity-federation:sts"
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      version="1.0" elementFormDefault="qualified">
      <xs:element name="MessageBody">
        <xs:complexType>
          <xs:sequence>
            <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##any"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  </wsdl:types>
  <wsdl:message name="RequestSecurityToken">
    <wsdl:part name="rstMessage" element="tns:MessageBody"/>
  </wsdl:message>
  <wsdl:message name="RequestSecurityTokenResponse">
    <wsdl:part name="rstrMessage" element="tns:MessageBody"/>
  </wsdl:message>
  <wsdl:portType name="SecureTokenService">
    <wsdl:operation name="IssueToken">
      <wsdl:input wsap10:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue" message="tns:RequestSecurityToken"/>
      <wsdl:output wsap10:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Issue" message="tns:RequestSecurityTokenResponse"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="STSBinding" type="tns:SecureTokenService">
    <soap12:binding transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="IssueToken">
      <soap12:operation soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue" style="document"/>
      <wsdl:input>
        <soap12:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap12:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="PicketLinkSTS">
    <wsdl:port name="PicketLinkSTSPort" binding="tns:STSBinding">
      <soap12:address location="http://localhost:8080/SecureTokenService/PicketLinkSTS"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

@WebServiceProvider(serviceName = "PicketLinkSTS", portName = "PicketLinkSTSPort", targetNamespace = "urn:picketlink:identity-federation:sts", wsdlLocation = "WEB-INF/wsdl/PicketLinkSTS.wsdl")
@ServiceMode(value = Service.Mode.MESSAGE)
public class PicketLinkSTService extends PicketLinkSTS {
    private static Logger log = Logger.getLogger(PicketLinkSTService.class.getName());

    @Resource
    public void setWSC(WebServiceContext wctx) {
        log.debug("Setting WebServiceContext = " + wctx);
        this.context = wctx;
    }
}

<!DOCTYPE PicketLinkSTS>
<PicketLinkSTS xmlns="urn:picketlink:federation:config:2.1"
               STSName="PicketLinkSTS" TokenTimeout="7200" EncryptToken="false">
    <KeyProvider
            ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager">
        <Auth Key="KeyStoreURL" Value="sts_keystore.jks"/>
        <Auth Key="KeyStorePass" Value="testpass"/>
        <Auth Key="SigningKeyAlias" Value="sts"/>
        <Auth Key="SigningKeyPass" Value="keypass"/>
        <ValidatingAlias Key="http://services.testcorp.org/provider1"
                         Value="service1"/>
    </KeyProvider>
    <TokenProviders>
        <TokenProvider
                ProviderClass="org.picketlink.identity.federation.core.wstrust.plugins.saml.SAML11TokenProvider"
                TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1"
                TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:1.0:assertion"/>
        <TokenProvider
                ProviderClass="org.picketlink.identity.federation.core.wstrust.plugins.saml.SAML20TokenProvider"
                TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0"
                TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:2.0:assertion"/>
    </TokenProviders>
    <ServiceProviders>
        <ServiceProvider Endpoint="http://services.testcorp.org/provider1"
                         TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0"
                         TruststoreAlias="service1"/>
    </ServiceProviders>
</PicketLinkSTS>

 WSTrustClient client = new WSTrustClient("PicketLinkSTS", "PicketLinkSTSPort",
       "http://localhost:8080/SecureTokenService/PicketLinkSTS",
       new SecurityInfo(username, password));

org.w3c.dom.Element assertion = null;
try {
   assertion = client.issueToken(SAMLUtil.SAML2_TOKEN_TYPE);
} catch (WSTrustException wse) {
   System.out.println("Unable to issue assertion: " + wse.getMessage());
   wse.printStackTrace();
}

final STSClientPool pool = STSClientPoolFactory.getPoolInstance();
pool.createPool(20, stsClientConfig);
final STSClient client = pool.getClient(stsClientConfig);

pool.returnClient();

if (! pool.configExists(stsClientConfig) {
    pool.createPool(stsClientConfig);
}

pool.destroyPool(stsClientConfig);

webservices サブシステムには、アダプターが含まれます。これは、アノテーションまたはデプロイメント記述子のいずれかを使用して、Web サービスエンドポイントをセキュアにするために Elytron セキュリティードメインの設定することができます。

Elytron セキュリティーを有効にすると、JAAS サブジェクトまたはプリンシパルを Apache CXF エンドポイントの SecurityContext にプッシュし、認証されたアイデンティティーを EJB コンテナーに伝播できます。

以下は、Apache CXF インターセプターを使用して、認証された情報を EJB コンテナーに伝播する方法の例になります。

public class PropagateSecurityInterceptor extends WSS4JInInterceptor {
    public PropagateSecurityInterceptor() {
      super();
      getAfter().add(PolicyBasedWSS4JInInterceptor.class.getName());
   }
   @Override
   public void handleMessage(SoapMessage message) throws Fault {
      ...
      final Endpoint endpoint = message.getExchange().get(Endpoint.class);
      final SecurityDomainContext securityDomainContext = endpoint.getSecurityDomainContext();
      //push subject principal retrieved from CXF to ElytronSecurityDomainContext
      securityDomainContext.pushSubjectContext(subject, principal, null)
      }
    }

JAX-WS ハンドラーは、渡されるメッセージをログに記録するように設定できます。@HandlerChain JAX-WS アノテーションを使用して、ハンドラーが希望のクライアントやエンドポイントに追加できるため、このアプローチは移植性があると言えます。

事前定義されたクライアントおよびエンドポイント設定メカニズムにより、ロギングハンドラーを任意のクライアントおよびエンドポイントの組み合わせに追加したり、一部のクライアントおよびエンドポイントのみに追加したりできます。ロギングハンドラーを一部のクライアントまたはエンドポイントのみに追加するには、@EndpointConfig アノテーションと JBossWS API を使用します。

org.jboss.ws.api.annotation.EndpointConfig アノテーションは、エンドポイント設定を JAX-WS エンドポイント実装に割り当てるために使用されます。webservices サブシステムに定義された設定を割り当てる場合、設定名のみが指定されます。アプリケーションに定義されている設定を割り当てる場合は、デプロイメント記述子への相対パスと設定名を指定する必要があります。

Apache CXF には、コンソール、クライアントのログファイル、またはサーバーのログファイルにメッセージをログに記録するために使用できるロギングインターセプターが同梱されています。これらのインターセプターは、以下を含む複数の方法でクライアント、エンドポイント、およびバスに追加できます。

JBossWS サーバー側の Apache CXF との統合では、提供された Web サービスデプロイメントに適切な Apache CXF 構造を内部で作成します。デプロイメントに複数のエンドポイントが含まれる場合、それらはすべて同じ Apache CXF バス内に存在し、他のデプロイメントのバスインスタンスとは分離されます。

JBossWS はサーバー側で Apache CXF 設定オプションのほとんどに対して適切なデフォルト値を設定しますが、ユーザーはデプロイメント用に作成される Bus インスタンスを微調整する必要があるかもしれません。jboss-webservices.xml 記述子はデプロイメントレベルのカスタマイズに使用できます。

<webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2">
  ...
  <property>
    <name>...</name>
    <value>...</value>
  </property>
  ...
</webservices>

<webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2">
  <property>
    <name>cxf.management.enabled</name>
    <value>true</value>
  </property>
  <property>
    <name>cxf.management.installResponseTimeInterceptors</name>
    <value>false</value>
  </property>
</webservices>

<?xml version="1.1" encoding="UTF-8"?>
<webservices
  xmlns="http://www.jboss.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.2"
  xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee">

  <property>
    <name>cxf.interceptors.in</name>
    <value>org.jboss.test.ws.jaxws.cxf.interceptors.BusInterceptor</value>
  </property>
  <property>
    <name>cxf.interceptors.out</name>
    <value>org.jboss.test.ws.jaxws.cxf.interceptors.BusCounterInterceptor</value>
  </property>
</webservices>

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointImpl</config-name>
    <property>
      <property-name>cxf.interceptors.in</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointInterceptor,org.jboss.test.ws.jaxws.cxf.interceptors.FooInterceptor</property-value>
    </property>
    <property>
      <property-name>cxf.interceptors.out</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointCounterInterceptor</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

<?xml version="1.1" encoding="UTF-8"?>
<webservices
  xmlns="http://www.jboss.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.2"
  xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee">

  <property>
    <name>cxf.features</name>
    <value>org.apache.cxf.feature.FastInfosetFeature</value>
  </property>
</webservices>

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>Custom FI Config</config-name>
    <property>
      <property-name>cxf.features</property-name>
      <property-value>org.apache.cxf.feature.FastInfosetFeature</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

import org.Bar;
import org.Foo;
...
Foo foo = new Foo();
foo.setPar(34);
Bar bar = new Bar();
bar.setColor("blue");