Cosminexus V11 アプリケーションサーバ Webサービス開発ガイド

手引書

3021-3-J23-50

前書き

対象製品

マニュアル「アプリケーションサーバ & BPM/ESB基盤 概説」の前書きの対象製品の説明を参照してください。

輸出時の注意

本製品を輸出される場合には、外国為替及び外国貿易法の規制並びに米国輸出管理規則など外国の輸出関連法規をご確認の上、必要な手続きをお取りください。

なお、不明な場合は、弊社担当営業にお問い合わせください。

商標類

HITACHI，Cosminexus，JP1，TPBroker，uCosminexusは，株式会社 日立製作所の商標または登録商標です。

Microsoft，Excel，Windows，Windows Server は，マイクロソフト 企業グループの商標です。

Oracle(R)，Java ，MySQL及びNetSuite は，Oracle，その子会社及び関連会社の米国及びその他の国における登録商標です。

その他記載の会社名，製品名などは，それぞれの会社の商標もしくは登録商標です。

マイクロソフト製品のスクリーンショットの使用について

マイクロソフトの許可を得て使用しています。

発行

2024年 2月 3021-3-J23-50

著作権

All Rights Reserved. Copyright (C) 2020, 2024, Hitachi, Ltd.

変更内容

変更内容(3021-3-J23-50) uCosminexus Application Server 11-40，uCosminexus Client 11-40，uCosminexus Developer 11-40，uCosminexus Service Architect 11-40，uCosminexus Service Platform 11-40

追加・変更内容

変更個所

マニュアル訂正の内容を反映した。

-

単なる誤字・脱字などはお断りなく訂正しました。

はじめに

このマニュアルをお読みになる際の前提情報については，マニュアル「アプリケーションサーバ & BPM/ESB基盤 概説」のはじめにの説明を参照してください。

第1編　概要

1　Webサービスの開発および実行の概要

Application ServerのJAX-WS機能を使用して，JAX-WS 2.2仕様に従ったSOAP Webサービスを開発できます。また，Application ServerのJAX-RS機能を使用して，JAX-RS 1.1仕様に従ったRESTful Webサービス（Webリソース）を開発できます。

この章では，Webサービス開発の概要，および前提条件について説明します。

1.1　JAX-WS・JAX-RS仕様の対応バージョン，プレフィクスおよび名前空間URI

このマニュアルは，Application Serverで提供する機能を利用して，JAX-WS 2.2仕様またはJAX-RS 1.1仕様に対応したWebサービスを開発，実行する方法について説明したものです。

JAX-WS 2.2仕様，JAX-RS 1.1仕様，およびプレフィクスと名前空間URIの対応については，次に示します。

JAX-WS 2.2仕様の対応バージョン

このマニュアルで「JAX-WS 2.2仕様」と表記した場合，次のバージョンの仕様を意味します。

Specification: JSR-000224 - JavaTM API for XML-Based Web Services
Version: 2.2
Status: Maintenance Release 3
Release: 10 December 2009

また，このマニュアルで「バインディング宣言のスキーマ」と表記した場合，次のスキーマを意味します。

http://java.sun.com/xml/ns/jaxws/wsdl_customizationschema_2_0.xsd(Date Published: May 11, 2006)

JAX-RS 1.1仕様の対応バージョン

このマニュアルで「JAX-RS 1.1仕様」と表記した場合，次のバージョンの仕様を意味します。

Specification: JSR-000311 - JavaTM API for RESTful Web Services
Version: 1.1
Status: Final Release
Release: September 17, 2009

プレフィクスと名前空間URIの対応

このマニュアルで使用するプレフィクスと名前空間URIの対応を次に示します。特に断りがないかぎり，次のプレフィクスを使用します。

表1‒1　プレフィクスと名前空間URIの対応

項番

プレフィクス

名前空間URI

1

cwsrm

http://jaxws.cosminexus.com/cwsrm

2

er

urn:oasis:names:tc:entity:xmlns:xml:catalog

3

javaee

http://java.sun.com/xml/ns/javaee

4

jaxb

http://java.sun.com/xml/ns/jaxb

5

jaxws

http://java.sun.com/xml/ns/jaxws

6

jaxwsdd

http://java.sun.com/xml/ns/jax-ws/ri/runtime

7

net35rmp

http://schemas.microsoft.com/ws-rx/wsrmp/200702

8

S

S11またはS12を示す。

9

S11

http://schemas.xmlsoap.org/soap/envelope/

10

S12

http://www.w3.org/2003/05/soap-envelope

11

soap

http://schemas.xmlsoap.org/wsdl/soap/

12

soap12

http://schemas.xmlsoap.org/wsdl/soap12/

13

soapenv

http://schemas.xmlsoap.org/soap/envelope/

14

soapenv12

http://www.w3.org/2003/05/soap-envelope

15

wsa

http://www.w3.org/2005/08/addressing

16

wsam

http://www.w3.org/2007/05/addressing/metadata

17

wsaw

http://www.w3.org/2006/05/addressing/wsdl

18

wsdl

http://schemas.xmlsoap.org/wsdl/

19

wsi

http://ws-i.org/profiles/basic/1.1/xsd

20

wsp

http://www.w3.org/ns/ws-policy

21

wsrm

http://docs.oasis-open.org/ws-rx/wsrm/200702

22

wsrmp

http://docs.oasis-open.org/ws-rx/wsrmp/200702

23

wsu

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd

24

xmime

http://www.w3.org/2005/05/xmlmime

25

xop

http://www.w3.org/2004/08/xop/include

26

xsd

http://www.w3.org/2001/XMLSchema

27

xsi

http://www.w3.org/2001/XMLSchema-instance

1.2　Webサービスの開発の概要

Application Serverでは，Webサービスの通信基盤としてJAX-WSエンジンおよびJAX-RSエンジンを提供しています。JAX-WSエンジンは，JAX-WS 2.2仕様に従って，SOAPメッセージのバインディングを実現します。JAX-RSエンジンは，JAX-RS 1.1仕様に従って，RESTful HTTPメッセージのバインディングを実現します。

このマニュアルでは，JAX-WSエンジンまたはJAX-RSエンジンを介して利用できるWebサービスの開発方法について説明します。

1.2.1　SOAP Webサービスの開発の概要

SOAP Webサービス（JAX-WSエンジンを利用したWebサービス）は，次のどれかの方法で開発します。

WSDLを起点とした開発

Webサービスの定義を記述したWSDLを起点とした開発方法です。コマンドでWSDLからJavaソースを生成し，必要な処理を実装します。

SEI（サービスエンドポイントインタフェース）を起点とした開発

SEIを起点とした開発方法です。作成したWebサービス実装クラスから，コマンドでWebサービスの実装に必要な追加のJavaソース（Java Beansクラスなど）を生成します。Webサービス実装クラスは，POJOとしても，EJBを基にしても作成できます。

プロバイダを起点とした開発

プロバイダを起点とした開発方法です。プロバイダ実装クラスを実装します。

それぞれの開発の流れについては，「2.1　SOAP Webサービス開発の流れ」を参照してください。

参考

SOAPアプリケーションの開発について

既存機能であるSOAPアプリケーション開発支援機能およびSOAP通信基盤を使用して，Webサービスを開発することもできます（このときに開発するアプリケーションを「SOAPアプリケーション」と呼びます）。ただし，SOAPアプリケーションはSOAP通信基盤で動作することを前提としているため，JAX-WSエンジン上で利用する場合には条件があります。

SOAPアプリケーションの開発については，マニュアル「アプリケーションサーバ SOAPアプリケーション開発の手引」を参照してください。

JAX-WSエンジン上で利用する場合の条件および移行手順については，「付録A　旧バージョンからの移行」を参照してください。

1.2.2　RESTful Webサービスの開発の概要

RESTful Webサービス（JAX-RSエンジンを利用したWebサービス）は，Webリソースを実装して開発します。Webリソースは，HTTPリクエストに対しての処理を実装します。なお，RESTful WebサービスそのものをWebリソースと呼ぶこともあります。

開発の流れについては，「2.3　RESTful Webサービスの開発の流れ」を参照してください。

1.3　Webサービスの開発時および実行時に使用する機能

SOAP WebサービスとRESTful Webサービス（Webリソース）の開発時および実行時に使用する機能について説明します。

1.3.1　SOAP Webサービスの機能

次の図に示すSOAP Webサービスの構成を基に，JAX-WSエンジンの機能について説明します。

図1‒1　SOAP Webサービスの構成（POJOのWebサービス）

図1‒2　SOAP Webサービスの構成（EJBのWebサービス）

図1‒3　SOAP Webサービスの構成（J2EEコンテナ上で動作するWebサービスクライアント）

JAX-WSエンジン

SOAP Webサービスの通信基盤となるエンジンです。Webサービス側およびWebサービスクライアント側に配置され，送受信されたSOAPメッセージのマーシャル／アンマーシャルをする役割を果たします。

Webサービスクライアント側のJAX-WSエンジン

WebサービスクライアントからJAX-WS APIを介してJavaオブジェクトを受け取り，SOAP要求メッセージを生成（マーシャル）します。生成したSOAP要求メッセージは呼び出し先のWebサービスに送信します。

また，WebサービスからSOAP応答メッセージを受け取り，Javaオブジェクトを生成（アンマーシャル）します。生成したJavaオブジェクトはWebサービスクライアントに返します。

Webサービス側のJAX-WSエンジン

Webサービスクライアント側からSOAP要求メッセージを受け取り，Javaオブジェクトを生成（アンマーシャル）します。このとき，対象となるWebサービス実装クラスまたはプロバイダ実装クラスを見つけ出し（ディスカバリ），オペレーションに対応するメソッドを呼び出します（ディスパッチ）。また，対象となるWebサービス実装クラスまたはプロバイダ実装クラスからJavaオブジェクトを受け取り，SOAP応答メッセージを生成（マーシャル）します。生成したSOAP応答メッセージは，呼び出し元であるWebサービスクライアントに返します。

コマンド

SOAP Webサービスの開発で使用するコマンドです。WebサービスおよびWebサービスクライアントの実装に必要なJavaソースやWSDLを生成できます。JAX-WSエンジンを利用するWebサービスの開発では次のコマンドを使用します。

cjwsimportコマンド

hwsgenコマンド

コマンドの使用方法については，「14.　コマンド」を参照してください。

自動生成クラス

コマンドを実行して生成されるJavaソースです。生成されたJavaソースを利用して，WebサービスおよびWebサービスクライアントを実装します。

JAX-WS API

JAX-WS 2.2仕様のAPIです。プロバイダを起点としたWebサービスの開発や，ディスパッチベースのWebサービスクライアントを開発する場合に使用します。また，ハンドラフレームワークやアドレッシングなどの機能を追加する場合にも使用できます。

1.3.2　RESTful Webサービスの機能

次の図に示すRESTful Webサービス（Webリソース）の構成を基に，JAX-RSエンジンの機能について説明します。

図1‒4　RESTful Webサービスの構成

JAX-RSエンジン

RESTful Webサービス（Webリソース）の通信基盤となるエンジンです。

Webリソースクライアント側のJAX-RSエンジン

WebリソースクライアントからRESTful Webサービス用クライアントAPIを介してJavaオブジェクトを受け取り，HTTPリクエストを生成します。生成したHTTPリクエストは呼び出し先のWebリソースに送信します。

また，WebリソースからHTTPレスポンスを受け取り，Javaオブジェクトを生成します。生成したJavaオブジェクトはWebリソースクライアントに返します。

Webリソース側のJAX-RSエンジン

クライアントからHTTPリクエストを受け取り，対象となるリソースクラスを見つけ出し（ディスカバリ），要求に対応するメソッドを呼び出します（ディスパッチ）。また，対象となるリソースクラスからHTTPレスポンスを生成し，呼び出し元に返します。JAX-RSエンジンはディスパッチの際，リソースクラスに含まれるアノテーションに基づき，必要なインジェクションを行います。

RESTful Webサービス用クライアント API

RESTful Webサービス(Webリソース) を呼び出すクライアントで使用できるAPIです。

1.4　Webサービスの開発および実行の前提条件

Application Server上でWebサービスを開発する場合の前提条件，およびサポート範囲について説明します。

1.4.1　前提となる構成ソフトウェア

WebサービスはDeveloperを利用して開発し，Application Serverを利用して実行します。

Developerの前提ソフトウェアについては，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「1.3　開発環境のマシン構成」を参照してください。

Application Serverの前提ソフトウェアについては，マニュアル「アプリケーションサーバ & BPM/ESB基盤 概説」の「2.2　構成ソフトウェア」を参照してください。

1.4.2　機能および仕様に関する前提条件

(1)　SOAP Webサービスの機能および仕様に関する前提条件

Application Server上でSOAP Webサービスを開発するときに利用できる機能および仕様について説明します。標準仕様のサポート範囲については，次に示す個所を参照してください。

「19.　JAX-WS仕様のサポート範囲」

「20.　WSDL仕様のサポート範囲」

「22.　SAAJ仕様のサポート範囲」

「23.　WS-RM仕様のサポート範囲」

(a)　デフォルトマッピング

Application ServerのJAX-WS機能で提供しているコマンドは，JAX-WS 2.2仕様の2章で規定されたWSDLからJavaへのデフォルトのマッピング，JAX-WS 2.2仕様の3章で規定されたJavaからWSDLへのデフォルトのマッピングに従って動作します。

また，Webサービス側のJAX-WSエンジンは，WebサービスのメタデータであるWSDLを要求された場合，WARファイルまたはEJB JARファイルにWSDLがなければ，JAX-WS 2.2仕様の3章で規定されたJavaからWSDLへのデフォルトのマッピングに従って，WSDLを生成します。

WSDLからJavaへのデフォルトのマッピングについては，「15.1　WSDLからJavaへのデフォルトマッピング」を参照してください。JavaからWSDLへのデフォルトのマッピングについては，「16.1　JavaからWSDLへのデフォルトマッピング」を参照してください。

(b)　マッピングのカスタマイズ

Application ServerのJAX-WS機能で提供しているコマンドは，JAX-WS 2.2仕様の7章で規定されたWSDLからJavaへのマッピングのカスタマイズ（バインディング宣言），およびJAX-WS 2.2仕様の8章で規定されたJavaからWSDLへのマッピングのカスタマイズ（アノテーション）に従って動作します。

また，Webサービス側のJAX-WSエンジンは，WebサービスのメタデータであるWSDLを要求された場合，WARファイルまたはEJB JARファイルにWSDLがなければ，JAX-WS 2.2仕様の7章で規定されたJavaからWSDLへのマッピングのカスタマイズに従って，WSDLを生成します。

WARファイルについては「3.5.1　WARファイルの構成」を参照してください。EJB JARファイルについては「3.5.2　EJB JARファイルの構成」を参照してください。WSDLからJavaへのマッピングのカスタマイズについては，「15.2　WSDLからJavaへのマッピングのカスタマイズ」を参照してください。JavaからWSDLへのデフォルトのマッピングについては，「16.2　JavaからWSDLへのマッピングのカスタマイズ」を参照してください。

(c)　JavaとWSDL間のバインディング

Application ServerのJAX-WSエンジンは，WebサービスおよびWebサービスクライアントともに，JAX-WS 2.2仕様の2章および3章に従って，JavaとWSDL間をバインディングします。

Application ServerのJAX-WSエンジンのサポート範囲については，「10.2　JAX-WSエンジンの動作」を参照してください。

(d)　WSDL仕様

Application ServerのJAX-WS機能では，WSDL 1.1仕様のWSDLをサポートしています。WSDL定義のスタイルとしては，document/literalスタイルだけサポートしています。document/literalスタイルであれば，wrapperスタイルおよびnon-wrapperスタイルのどちらも利用できます。

WSDL 1.1仕様のサポート範囲については，「20.1　WSDL 1.1仕様のサポート範囲」を参照してください。

(e)　SOAP仕様

Application ServerのJAX-WS機能では，SOAP 1.1仕様およびSOAP 1.2仕様のSOAPメッセージをサポートしています。

(f)　Message Exchange Pattern（MEP）

Application ServerのJAX-WS機能では，MEPとしてrequest-responseオペレーション，およびone-wayオペレーションをサポートしています。request-responseオペレーション，およびone-wayオペレーションの定義方法については，次に示す個所を参照してください。

「15.1.4　メッセージのパートからパラメタおよび戻り値へのマッピング（wrapperスタイルの場合）」

「15.1.5　メッセージのパートからパラメタおよび戻り値へのマッピング（non-wrapperスタイルの場合）」

「16.2.4　javax.jws.Onewayアノテーション」

また，one-wayオペレーションおよび注意事項については，「10.22　one-wayオペレーション」を参照してください。

(g)　非同期関連の機能

Application ServerのJAX-WS機能では，JAX-WS 2.2仕様の2.3.4項や，4章などに記載されているWebサービスクライアントでの非同期呼び出しを実現する機能はサポートしていません。

(h)　Dispatch／Providerインタフェース関連の機能

Application ServerのJAX-WS機能では，JAX-WS 2.2仕様の4章に記載されているDispatchインタフェース，JAX-WS 2.2仕様の5章に記載されているProviderインタフェース，およびDispatchインタフェースとProviderインタフェースに関連する機能をサポートしています。ただし，JAX-WS 2.2仕様の4章に記載されているオブジェクトのうち，次のオブジェクトはサポートしていません。

javax.activation.DataSource

javax.xml.transform.stax.StAXSource

(i)　Endpointクラスおよび発行関連の機能

Application ServerのJAX-WS機能では，JAX-WS 2.2仕様の5章に記載されているWebサービスのエンドポイントを動的に生成し，発行するための機能はサポートしていません。

(j)　ハンドラ関連の機能

Application ServerのJAX-WS機能では，Webサービスクライアントの実装で，APIによる動的なハンドラ設定をサポートしています。また，Webサービスの実装で，アノテーションによる動的なハンドラ設定をサポートしています。JSR-109仕様を前提とする静的な設定はサポートしていません。

(k)　添付ファイルの使用

Application ServerのJAX-WS機能では，SAAJ 1.3仕様，およびWSDLにwsi:swaRef型を記述する形式の添付ファイルおよびMTOM/XOP仕様形式の添付ファイルをサポートしています。WSDL 1.1仕様のMIME拡張要素を使用する記述（MIMEバインディング）はサポートしていません。wsi:swaRef形式の添付ファイルの使用方法については，「28.　添付ファイル機能（wsi:swaRef形式）」を参照してください。MTOM/XOP仕様形式の添付ファイルの使用方法については，「30.　添付ファイル機能（MTOM/XOP）」を参照してください。

(l)　メッセージコンテキスト

Application ServerのJAX-WS機能では，JAX-WS 2.2仕様の9章に記載されている標準のメッセージコンテキストプロパティは，読み取りだけサポートしています。Webサービスクライアントの実装でタイムアウトを設定するためのプロパティをサポートしています。メッセージコンテキストの使用方法および注意事項については，「19.2.5　メッセージコンテキストの使用」を参照してください。

(m)　API

Application ServerのJAX-WS機能では，JAX-WS 2.2仕様のAPIをサポートしています。JAX-WS APIのサポート範囲については，「19.2　APIのサポート範囲」を参照してください。

(n)　XML／HTTPバインディング

Application ServerのJAX-WS機能では，JAX-WS 2.2仕様の11章に記載されているXML／HTTPバインディングはサポートしていません。

(o)　ラッパbeanの動的生成

Application ServerのJAX-WS機能では，SEIを起点として開発したWebサービスで，JAX-WS2.2仕様の3.6.2.1項および3.7節に記載されているラッパbean（リクエストbeanとレスポンスbean），およびフォルトbeanのJavaBeansクラスをJAX-WSエンジンが動的に生成する機能（以降，ラッパbeanの動的生成機能と呼ぶ場合があります）をサポートしています。Webサービスクライアントや，WSDLを起点とするWebサービスでは，ラッパbeanの動的生成機能はサポートしていません。

ラッパbeanの動的生成機能については，「10.23　ラッパbeanの動的生成機能」を参照してください。

(p)　関連する標準仕様

関連する標準仕様について説明します。

MTOM仕様に関連する機能

Application ServerのJAX-WS機能では，JAX-WS 2.2仕様の2.4節や6.5節などに記載されたMTOM仕様に関連する機能をサポートしています。

WS-Addressing仕様

Application ServerのJAX-WS機能では，JAX-WS 2.2仕様の5.2.8項などに記載されたWS-Addressing仕様に関連する機能をサポートしています。詳細については，「37.　アドレッシング機能」を参照してください。

XML Catalogs 1.1仕様

Application ServerのJAX-WS機能では，JAX-WS 2.2仕様の4.4節などに記載されたXML Catalogs 1.1仕様に関連する機能をサポートしています。

XML Catalogs 1.1仕様のサポート範囲については，「21.　XML Catalogs 1.1のサポート範囲」を参照してください。

WSEE（JSR-109）仕様

Application ServerのJAX-WS機能では，WSEE（JSR-109）仕様をサポートしています。WSEE（JSR-109）仕様の項目とサポートの対応を次の表に示します。

表1‒2　WSEE（JSR-109）仕様の項目とサポートの対応

項番

項目

サポート

1

ステートレスセッションビーンおよびシングルトンセッションビーンの次の方法。

WSDLへのマッピングまたはバインディング方法。

SOAPへのマッピングまたはバインディング方法。

ステートレス

○

シングルトン

−

2

クライアントモデル。特に，JNDIを使用してサービスインタフェースを発見する方法と，JAX-WS仕様のWebServiceRefアノテーションを使用する方法。

4.2.2項の内容（サービスクラスおよびポートのインジェクション）

○

4.2.2項以外の内容

−

3

デプロイメントモデル。EARファイルへのパッケージング方法とライフサイクル。

5.4節記載の内容

○

5.4節以外の内容

−

4

デプロイメントディスクリプタ。webservices.xmlの構文と記述する必要がある内容，およびJAX-WS仕様（Web Services Metadata （JSR-181）仕様）で定義されるアノテーションとのマッピング。

−

5

ロールなど既存のJava EEコンテナの機能とのマッピング。

−

（凡例）

○：サポートしていることを示します。

−：サポートしていないことを示します。

なお，web.xmlを省略した場合の動作はサポートしています。web.xmlを省略した場合の動作については，「3.4.3　web.xmlをWARファイルに含めない場合の動作」を参照してください。

SAAJ 1.3仕様

Application ServerのJAX-WS機能では，SAAJ 1.3仕様をサポートしています。SAAJ 1.3仕様のAPIについては，「22.1　SAAJ 1.3仕様のサポート範囲」を参照してください。

(2)　RESTful Webサービスの機能および仕様に関する前提条件

Application Server上でRESTful Webサービス（Webリソース）を開発するときに利用できる機能および仕様について説明します。標準仕様のサポート範囲については，「24.　JAX-RS仕様のサポート範囲」を参照してください。

(a)　リソースクラス

Webリソースを実装するクラスで，JAX-RS 1.1仕様の3章で定義されています。ルートリソースクラスとサブリソースクラスの2種類があります。Application ServerのJAX-RS機能はどちらのリソースクラスもサポートしています。

ルートリソースクラスについては，「17.1.1　ルートリソースクラス」を参照してください。サブリソースクラスについては，「17.1.7　サブリソースクラス」を参照してください。

(b)　プロバイダ

JAX-RSエンジンを拡張する機能で，JAX-RS 1.1仕様の4章で定義されています。エンティティプロバイダ，コンテキストプロバイダ，例外マッピングプロバイダの3種類があります。

エンティティプロバイダは，HTTPエンティティボディとJava型をマッピングするプロバイダです。JAX-RS機能は，ビルトインのエンティティプロバイダをサポートしています。ビルトインのエンティティプロバイダがサポートするMIMEタイプとJava型については，「17.1.1(4)(c)　エンティティパラメタ」を参照してください。

コンテキストプロバイダは，リソースやほかのプロバイダにコンテキストを提供するプロバイダです。JAX-RS機能は，ビルトインのコンテキストプロバイダをサポートしています。ビルトインのコンテキストプロバイダがサポートするコンテキストについては，「24.4　コンテキスト」を参照してください。

例外マッピングプロバイダは，Webリソースの例外のHTTPレスポンスへのマッピングをカスタマイズするプロバイダです。例外マッピングプロバイダについては，「17.2.2　例外マッピングプロバイダ」を参照してください。

(c)　Application

Applicationはリソースクラスとプロバイダのファクトリで，JAX-RS 1.1仕様の2章で定義されています。JAX-RS 1.1仕様はビルトインのApplicationをサポートしています。ビルトインのApplicationについては，「11.3.1　WARファイルの構成」を参照してください。

1.5　Webサービスとクライアントの形態

ここでは，Application ServerがサポートするWebサービスとクライアントの形態について説明します。

1.5.1　Webサービスの形態

Application Serverでは，次に示す形態のWebサービスをサポートしています。

Webサービス実装クラスを使用したSOAP Webサービス

プロバイダ実装クラスを使用したSOAP Webサービス

RESTful Webサービス（Webリソース）

それぞれの形態について説明します。

(1)　Webサービス実装クラスを使用したSOAP Webサービス

Webサービス実装クラスを使用する場合の形態を次に示します。

図1‒5　Webサービス実装クラスを使用したSOAP Webサービスの形態

Webサービス実装クラスを使用すると，WSDLのオペレーションに対応するJavaメソッドを実装するだけでWebサービスを実現できます。複雑な変換はスタブが実施するため，Webサービス開発時に，APIを利用してSOAPメッセージを構成するXMLを組み立てるような，複雑なプログラミングをする必要はありません。

スタブは，ツールが自動生成するか，またはJAX-WSエンジンが動的に生成します。WSDLは自動生成でき，必須となります。また，WSDLに含まれないSOAPメッセージを送受信することはできないので注意してください。なお，Webサービス実装クラスは，POJOとしても，EJBを基にしても作成できます。

(2)　プロバイダ実装クラスを使用したSOAP Webサービス

プロバイダ実装クラスを使用する場合の形態を次に示します。

図1‒6　プロバイダ実装クラスを使用したSOAP Webサービスの形態

プロバイダ実装クラスを使用する場合はスタブもWSDLも必要ないため，任意のSOAPメッセージを動的に送受信したいときに適しています。プロバイダ実装クラスはJAX-WSエンジンがマーシャルしたオブジェクトをそのまま受け取るため，Webサービス開発時に，APIを利用してSOAPメッセージを構成するXMLから値を直接取得したり，APIを利用してSOAPメッセージを構成するXMLを組み立てたりする必要があります。

(3)　RESTful Webサービス（Webリソース）

RESTful Webサービス（Webリソース）はリソースクラスを実装することで実現します。

図1‒7　RESTful Webサービス（Webリソース）

リソースクラスには，ルートリソースクラスとサブリソースクラスがあります。

ルートリソースクラスは，クラスレベルでPathアノテーションでアノテートされたJavaクラスです。サブリソースクラスは，クラスレベルでPathアノテーションでアノテートされていないJavaクラスです。

リソースクラスには次に示すメソッドのどれかを実装します。

リソースメソッド

サブリソースメソッド

サブリソースロケ−タ

1.5.2　クライアントの形態

Application Serverでは，SOAP Webサービスを呼び出すクライアントとして，次に示す形態をサポートしています。

スタブベースのWebサービスクライアント

ディスパッチベースのWebサービスクライアント

それぞれの形態について説明します。

なお，Webリソースクライアントは，RESTful Webサービス用クライアントAPIか，またはjava.net.URLやjava.net.HttpURLConnectionなどの標準的なJava APIを利用して実装してください。

(1)　スタブベースのWebサービスクライアント

スタブベースのWebサービスクライアントを使用する場合の形態を次に示します。

図1‒8　Webサービスクライアント（スタブベース）

スタブベースのWebサービスクライアントを使用すると，WSDLのオペレーションに対応するJavaメソッドを呼び出すだけで，Webサービスを呼び出せます。複雑な変換は自動生成されるスタブが実施するため，Webサービスクライアント開発時に，APIを利用してSOAPメッセージを構成するXMLを組み立てるような，複雑なプログラミングをする必要はありません。ただし，WSDLに定義されていないSOAPメッセージを送受信することはできないので注意してください。また，スタブおよびWSDLは必須です。WSDLは，対象のWebサービスから入手する必要があります。

(2)　ディスパッチベースのWebサービスクライアント

ディスパッチベースのWebサービスクライアントを使用する場合の形態を次に示します。

図1‒9　Webサービスクライアント（ディスパッチベース）

ディスパッチベースのWebサービスクライアントを使用する場合は，スタブもWSDLも必要ないため，任意のSOAPメッセージを動的に送受信したいときに適しています。ディスパッチベースのWebサービスクライアントは，生成したオブジェクトをjavax.xml.ws.Dispatchインタフェース経由でJAX-WSエンジンに受け渡すため，Webサービスクライアント開発時に，APIを利用してSOAPメッセージを構成するXMLから値を直接取得したり，APIを利用してSOAPメッセージを構成するXMLを組み立てたりする必要があります。

注意事項

ディスパッチベースのWebサービスクライアントでは，javax.xml.ws.Dispatchインタフェースの代わりにjavax.xml.soap.SOAPConnectionクラスを使用してSOAPメッセージを送受信することもできます。ただし，javax.xml.soap.SOAPConnectionクラスを使用した場合，動作定義ファイルおよびメッセージコンテキストの設定は無効になり，ログも出力されないため，注意してください。

また，このマニュアルでは，javax.xml.soap.SOAPConnectionクラスを使用する場合の動作については説明しません。ほかのSAAJ 1.3仕様のAPIと同様に，JDKのドキュメントを参照してください。なお，特に問題のないかぎり，javax.xml.soap.SOAPConnectionクラスではなくjavax.xml.ws.Dispatchインタフェースを使用してください。

1.6　JAX-WSエンジンとJAX-RSエンジンの設定

JAX-WSエンジンとJAX-RSエンジンを利用するには，J2EEサーバ用オプション定義ファイルにJAX-WSエンジンとJAX-RSエンジンを有効にするための定義をする必要があります。

JAX-WSエンジンとJAX-RSエンジンを有効にするための定義については，「付録A.1(3)　動作環境の切り替え」のJAX-WSエンジンとJAX-RSエンジンを利用する場合の説明を参照してください。

2　開発の流れ

JAX-WS 2.2仕様に従ったSOAP Webサービスは，WSDLを起点とした開発，SEIを起点とした開発，またはプロバイダを起点とした開発のどれかで開発します。SOAP Webサービスを呼び出すクライアントは，スタブベース，またはディスパッチベースのどちらかで開発します。

RESTful Webサービス（Webリソース）は，リソースクラスを実装して開発します。RESTful Webサービスを呼び出すクライアントは，RESTful Webリソース用クライアントAPI，または標準的なJava APIを使用して開発します。

この章では，Webサービスおよびクライアントの開発の流れについて説明します。

2.1　SOAP Webサービス開発の流れ

SOAP Webサービスには，次に示す開発方法があります。

WSDLを起点とした開発（2.1.1）

SEIを起点とした開発（2.1.2）

SEIを起点とした開発（hwsgenコマンドを使用する場合）（2.1.3）

プロバイダを起点とした開発（2.1.4）

開発方法を選択する流れを次に示します。

図2‒1　SOAP Webサービス開発方法の選択の流れ

2.1.1　WSDLを起点とした開発の流れ

WSDLを起点としたWebサービスの開発の流れを次の図に示します。

図2‒2　WSDLを起点としたWebサービスの開発の流れ

WSDLファイルを作成する

WSDLファイルは，手動またはコマンドで作成できます。

手動で作成する場合

Webサービスのメタ情報として，WSDL 1.1仕様，XML Schema仕様，およびWS-I Basic Profile 1.1に従ってWSDLファイルを作成します。なお，SOAP 1.1のメッセージを受信する場合はSOAP 1.1仕様の拡張要素を記述し，SOAP 1.2のメッセージを受信する場合はSOAP 1.2仕様の拡張要素を記述してください。

WSDL 1.1仕様のサポート範囲については，「20.1　WSDL 1.1仕様のサポート範囲」を参照してください。

コマンドで生成する場合

コマンドでのWSDLの生成は，ユーザがWSDLやXML Schemaの構文ではなく，Java言語での開発に慣れている場合にお勧めします。

一時的にWebサービス実装クラスを作成・コンパイルしたあと，-wsdlオプションを指定してhwsgenコマンドのWSDL生成機能を実行し，WSDLファイルを生成します。生成したWSDLは，必要に応じて変更してください。ここで作成するWebサービス実装クラスは，hwsgenコマンドの入力だけに利用します。そのため，メソッドを実装する必要はありません。

SOAP 1.2仕様のメッセージを受信する場合は，Webサービス実装クラスの作成時，javax.xml.ws.BindingTypeアノテーションに"http://www.w3.org/2003/05/soap/bindings/HTTP/"を指定してください。

WSDL生成後，不要になったWebサービス実装クラスは削除してください。

cjwsimportコマンドを実行する（Javaソースの生成）

cjwsimportコマンドを実行して，作成したWSDLファイルから，SEI，Webサービス実装クラスのスケルトン，JavaBeansクラス（スタブ）など，Webサービスの開発・実行に必要なJavaソースを生成します。cjwsimportコマンドは，-generateServiceオプションを指定して実行します。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

Webサービスを実装する

手順2で生成されたスタブを利用して，Webサービス実装クラスのスケルトンに必要な処理を記述し，Webサービスを実装します。また，実装したWebサービス実装クラスをコンパイルします。なお，javax.xml.ws.BindingTypeアノテーションはWSDLの内容に応じて自動的に付加されます。

DDを作成する

web.xmlおよびapplication.xmlを作成します。web.xmlには，Webサービス固有の情報を記述します。web.xmlの作成については，「3.4　web.xmlの作成」を参照してください。

EARファイルを作成する

作成したファイルを含むEARファイルを作成します。EARファイルの作成については，「3.5.3　EARファイルの作成」を参照してください。

EARファイルをデプロイし，開始する

作成したEARファイルをデプロイし，J2EEアプリケーション（Webサービス）として開始します。J2EEアプリケーションのインポートおよび開始コマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」および「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

WSDLを起点としたWebサービスの開発例については，次に示す個所を参照してください。

「4.3　Webサービスの開発例（WSDL起点）」

「35.3　Webサービスの開発例（WSDL起点・WS-RM 1.2）」

2.1.2　SEIを起点とした開発の流れ

SEIを起点としたWebサービスの開発の流れを次の図に示します。

図2‒3　SEIを起点としたWebサービスの開発の流れ

WSDLはJAX-WSエンジンによって自動生成されますが，手順4に従いコマンドを実行することでWSDLを生成することもできます。WSDLをコマンドで生成しない場合，手順4は不要です。

Webサービス実装クラスを作成する

Webサービス実装クラスは，POJOとして作成する場合とEJBを基に作成する場合があります。どちらの場合も，JAX-WS 2.2仕様およびJAXB 2.2仕様に従って，Webサービス実装クラスを作成します。SOAP 1.2仕様のメッセージを受信する場合は，javax.xml.ws.BindingTypeアノテーションに"http://www.w3.org/2003/05/soap/bindings/HTTP/"を指定してください。

JAX-WS 2.2仕様のサポート範囲については，「19.1　JAX-WS 2.2仕様のサポート範囲」を参照してください。JAXB 2.2仕様のサポート範囲については，マニュアル「XML Processor ユーザーズガイド」の「付録B　JAXB仕様のサポート範囲」を参照してください。

Webサービス実装クラスをコンパイルする

javacコマンドを実行して，作成したWebサービス実装クラスをコンパイルします。javacコマンドについては，JDKのドキュメントを参照してください。

DDを作成する

web.xmlおよびapplication.xmlを作成します。web.xmlには，Webサービス固有の情報を記述します。web.xmlの作成については，「3.4　web.xmlの作成」を参照してください。

hwsgenコマンドのWSDL生成機能を実行する（任意）

-wsdlオプションを指定してhwsgenコマンドを実行し，Webサービス実装クラスからWSDLを生成，およびアノテーションなどのエラーチェックをします。手順6.のJavaBeansクラス（スタブ）の動的生成時にエラーが発生しないようにするには，コンパイルしたWebサービス実装クラスに対してhwsgenコマンドを実行してください。この手順は任意です。なお，ここで生成したWSDLは，変更しないでください。

hwsgenコマンドのWSDL生成機能で生成したWSDLは，メールで送付するなど，メタデータの発行機能以外の任意の方法で展開できます。

hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を参照してください。

EARファイルを作成する

作成したファイルを含むEARファイルを作成します。EARファイルの作成については，「3.5.3　EARファイルの作成」を参照してください。

EARファイルをデプロイし，開始する

作成したEARファイルをデプロイし，J2EEアプリケーション（Webサービス）として開始します。J2EEアプリケーションのインポートおよび開始コマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」および「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

JavaBeansクラス（スタブ）は，J2EEアプリケーション（Webサービス）を開始するときにJAX-WSエンジンが動的に生成します。また，JavaBeansクラス（スタブ）の動的生成でエラーが発生しないように，コンパイルしたWebサービス実装クラスに対して手順4.に従いコマンドを実行すると，事前にアノテーションなどのエラーチェックができます。エラーチェックについては，「10.23.1　hwsgenコマンドによるエラーチェックについて」を参照してください。

SEIを起点としたWebサービスの開発例については，次に示す個所を参照してください。

「5.3　Webサービスの開発例（SEI起点）」

「6.3　Webサービスの開発例（SEI起点・hwsgenコマンド）」

「7.3　Webサービスの開発例（SEI起点・カスタマイズ）」

「8.3　Webサービスの開発例（SEI起点・EJBのWebサービス）」

「29.3　Webサービスの開発例（SEI起点・wsi:swaRef形式の添付ファイル）」

「33.3　Webサービスの開発例（SEI起点・ストリーミング）」

「38.3　Webサービスの開発例（SEI起点・アドレッシング）」

2.1.3　SEIを起点とした開発の流れ（hwsgenコマンドを使用する場合）

コンパイル済みのWebサービス実装クラスから，hwsgenコマンドでJavaソースを生成する場合の，SEIを起点としたWebサービスの開発の流れを次の図に示します。

図2‒4　SEIを起点としたWebサービスの開発の流れ（hwsgenコマンドを使用する場合）

hwsgenコマンドを実行する

Webサービス実装クラスは，POJOとして作成する場合とEJBを基に作成する場合があります。どちらの場合も，hwsgenコマンドを実行するとき，-wsdlオプションを指定すると，WSDLの生成，およびアノテーションなどのエラーチェックができます。この場合，生成したWSDLは変更しないでください。

hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を参照してください。

DDを作成する

web.xmlおよびapplication.xmlを作成します。web.xmlには，Webサービス固有の情報を記述します。web.xmlの作成については，「3.4　web.xmlの作成」を参照してください。

EARファイルを作成する

作成したファイルを含むEARファイルを作成します。EARファイルの作成については，「3.5.3　EARファイルの作成」を参照してください。

EARファイルをデプロイし，開始する

作成したEARファイルをデプロイし，J2EEアプリケーション（Webサービス）として開始します。J2EEアプリケーションのインポートおよび開始コマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」および「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

JavaBeansクラス（スタブ）は，J2EEアプリケーション（Webサービス）を開始するときにJAX-WSエンジンが動的に生成します。

SEIを起点としたWebサービスの開発例については，次に示す個所を参照してください。

「5.3　Webサービスの開発例（SEI起点）」

「6.3　Webサービスの開発例（SEI起点・hwsgenコマンド）」

「7.3　Webサービスの開発例（SEI起点・カスタマイズ）」

「8.3　Webサービスの開発例（SEI起点・EJBのWebサービス）」

「29.3　Webサービスの開発例（SEI起点・wsi:swaRef形式の添付ファイル）」

「33.3　Webサービスの開発例（SEI起点・ストリーミング）」

「38.3　Webサービスの開発例（SEI起点・アドレッシング）」

2.1.4　プロバイダを起点とした開発の流れ

プロバイダを起点としたWebサービスの開発の流れを次の図に示します。

図2‒5　プロバイダを起点としたWebサービスの開発の流れ

プロバイダ実装クラスを作成する

Webサービス実装クラスは，POJOとして作成します。JAX-WS 2.2仕様およびJAXB 2.2仕様に従って，プロバイダ実装クラスを作成します。SOAP 1.2仕様のメッセージを受信する場合は，javax.xml.ws.BindingTypeアノテーションに"http://www.w3.org/2003/05/soap/bindings/HTTP/"を指定してください。

JAX-WS 2.2仕様のサポート範囲については，「19.1　JAX-WS 2.2仕様のサポート範囲」を参照してください。JAXB 2.2仕様のサポート範囲については，マニュアル「XML Processor ユーザーズガイド」の「付録B　JAXB仕様のサポート範囲」を参照してください。

javacコマンドを実行する（コンパイルとエラーチェック）

javacコマンドを実行し，作成したプロバイダ実装クラスのコンパイル，およびエラーチェックをします。

DDを作成する

web.xmlおよびapplication.xmlを作成します。web.xmlには，Webサービス固有の情報を記述します。web.xmlの作成については，「3.4　web.xmlの作成」を参照してください。

EARファイルを作成する

作成したファイルを含むEARファイルを作成します。EARファイルの作成については，「3.5.3　EARファイルの作成」を参照してください。

EARファイルをデプロイし，開始する

作成したEARファイルをデプロイし，J2EEアプリケーション（Webサービス）として開始します。J2EEアプリケーションのインポートおよび開始コマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」および「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

プロバイダを起点としたWebサービスの開発例については，「9.3　Webサービスの開発例（プロバイダ起点・SAAJ）」を参照してください。

2.2　Webサービスクライアント開発の流れ

SOAP Webサービスを呼び出すクライアントには，次に示す開発方法があります。

スタブベースのWebサービスクライアントの開発（2.2.1）

ディスパッチベースのWebサービスクライアントの開発（2.2.2）

2.2.1　スタブベースのWebサービスクライアントの開発の流れ

スタブベースのWebサービスクライアントの開発の流れを次の図に示します。

図2‒6　Webサービスクライアントの開発の流れ（スタブベース）

WSDLファイルを入手する（または，公開されているWSDLのURLを取得する）

呼び出そうとしているWebサービスのメタ情報が記述されたWSDLファイルを入手します。または，呼び出そうとしているWebサービスがWSDLファイルのURLを公開している場合，URLを取得します。

cjwsimportコマンドを実行する（Javaソースの生成）

cjwsimportコマンドを実行して，入手したWSDLファイル，または取得したWSDLファイルのURLから，サービスクラスやSEIなど，Webサービスクライアントの開発・実行に必要なJavaソースを生成します。cjwsimportコマンドは，-generateServiceオプションを指定しないで実行します。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

Webサービスクライアントを実装する

生成されたJavaソースを利用して，Webサービスクライアントを実装します。実装したWebサービスクライアントは，javacコマンドでコンパイルします。Webサービスクライアントの実装については，「3.6　Webサービスクライアントの実装」を参照してください。

Webサービスを呼び出す

作成したWebサービスクライアントを実行して，Webサービスを呼び出します。

WSDLを起点に開発する場合のスタブベースのWebサービスクライアントの開発例については，「4.5　Webサービスクライアントの開発例（WSDL起点）」を参照してください。

SEIを起点に開発する場合のスタブベースのWebサービスクライアントの開発例については，次に示す個所を参照してください。

「5.5　Webサービスクライアントの開発例（SEI起点）」

「6.5　Webサービスクライアントの開発例（SEI起点・hwsgenコマンド）」

「7.5　Webサービスクライアントの開発例（SEI起点・カスタマイズ）」

「8.5　Webサービスクライアントの開発例（SEI起点・EJBのWebサービス）」

「29.5　Webサービスクライアントの開発例（SEI起点・wsi:swaRef形式の添付ファイル）」

「33.3　Webサービスの開発例（SEI起点・ストリーミング）」

「38.5　Webサービスクライアントの開発例（SEI起点・アドレッシング）」

2.2.2　ディスパッチベースのWebサービスクライアントの開発の流れ

ディスパッチベースのWebサービスクライアントを開発する場合は，JAX-WS 2.2仕様およびJAXB 2.2仕様に従って，Webサービスクライアントを実装してください。

ディスパッチベースのWebサービスクライアントの開発例については，「9.5　Webサービスクライアントの開発例（プロバイダ起点・SAAJ）」を参照してください。

2.3　RESTful Webサービスの開発の流れ

RESTful Webサービス（Webサービス）の開発の流れを次の図に示します。

図2‒7　RESTful Webサービスの開発の流れ

ルートリソースクラスを作成する

ルートリソースクラスを作成し，リソースメソッド，サブリソースメソッド，またはサブリソースロケータのどれか一つ以上を実装します。必要があればサブリソースクラスや例外マッピングプロバイダも作成してください。

javacコマンドを実行する

javacコマンドを実行して，作成したJavaソースをコンパイルします。

DDを作成する

web.xmlおよびapplication.xmlを作成します。web.xmlには，Webサービス固有の情報を記述します。web.xmlの作成については，「11.2　web.xmlの作成」を参照してください。

EARファイルを作成する

作成したファイルを含むEARファイルを作成します。EARファイルの作成については，「11.3.2　EARファイルの作成」を参照してください。

EARファイルをデプロイし，開始する

作成したEARファイルをデプロイし，J2EEアプリケーション（Webサービス）として開始します。J2EEアプリケーションのインポートおよび開始コマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」および「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

RESTful Webサービス（Webサービス）の開発例については，「12.3　Webリソースの開発例」を参照してください。

第2編　開発と実行

3　SOAP Webサービス開発のポイント

この章では，Webサービス開発の作業ごとに，あらかじめ理解しておく必要がある点と注意事項について説明します。

3.1　WSDLの作成

WSDLを起点とした開発では，WSDL 1.1仕様およびWS-I Basic Profile 1.1に従ってWSDLを作成します。WSDL 1.1仕様のサポート範囲については，「20.1　WSDL 1.1仕様のサポート範囲」を参照してください。

POJOのWebサービスの場合，作成したWSDLは，WARファイルを構成するwsdlディレクトリに格納します。WSDLの格納先については，「3.5.1　WARファイルの構成」を参照してください。

EJBのWebサービスの場合，作成したWSDLは，EJB JARファイルを構成するwsdlディレクトリに格納します。WSDLの格納先については，「3.5.2　EJB JARファイルの構成」を参照してください。

wsdlディレクトリにWSDLが含まれていない場合，Webサービスをデプロイするときに，Webサービス側のJAX-WSエンジンによってJAX-WS 2.2仕様に従ったWSDLが自動生成されます。

3.2　WSDLとJavaソースのマッピング

cjwsimportコマンド実行時に，WSDLとJavaソース間でマッピングされます。ここでは，WSDLとJavaソース間のマッピング例（デフォルトマッピング）を示します。

3.2.1　WSDLからJavaソースへのマッピング例

cjwsimportコマンドを実行すると，WSDLからJavaソースへマッピングされます。WSDLからJavaソースへのマッピング例を次の図に示します。

図3‒1　WSDLからJavaソースへのマッピング例

マッピングについては，「15.　WSDLからJavaへのマッピング」を参照してください。

3.2.2　JavaソースからWSDLへのマッピング例

JavaソースからWSDLへのマッピング例を次の図に示します。

図3‒2　JavaソースからWSDLへのマッピング例

マッピングについては，「16.　JavaからWSDLへのマッピング」を参照してください。

3.3　Webサービス実装クラスおよびプロバイダ実装クラスの作成

Webサービス実装クラスまたはプロバイダ実装クラスは，コンパイルしたJavaクラスファイル（*.class）として作成します。

POJOのWebサービスの場合

Webサービス実装クラスまたはプロバイダ実装クラスは，WARファイルを構成するディレクトリに含めます。次に示すどちらか，または両方に一つ以上含めてください。

classesディレクトリ以下

libディレクトリ以下に含まれるJARファイル内

Webサービス実装クラスまたはプロバイダ実装クラスの格納先については，「3.5.1　WARファイルの構成」を参照してください。

EJBのWebサービスの場合

Webサービス実装クラスは，EJB JARファイルを構成するディレクトリに含めます。次に示すディレクトリに一つ以上含めてください。

EJB-JARファイルのルートディレクトリ以下

Webサービス実装クラスの格納先については，「3.5.2　EJB JARファイルの構成」を参照してください。

作成時の注意事項

通常，Webサービスはステートレスです。Webサービス実装クラスまたはプロバイダ実装クラスのフィールドを，複数回のWebサービスの呼び出しで共有しないでください。

3.4　web.xmlの作成

ここでは，POJOのWebサービスで使用するWARファイルに含まれるweb.xmlについて説明します。

web.xmlを作成する場合，ファイル名称は"web.xml"とし，WARファイルを構成するWEB-INFディレクトリの直下に格納します。web.xmlの格納が必須かどうかは，J2EEサーバ用ユーザプロパティファイル（usrconf.properties）のwebserver.container.jaxws.webservice.no_webxml.enabledプロパティの設定値によって異なります。

"strict"または"true"（推奨は"strict"）を設定した場合

WEB-INFディレクトリの直下に"web.xml"という名称でweb.xmlを格納するかどうかは任意です。格納する場合，Webサービスの実行に必要な定義が記述されていなければなりません。

"lax"を設定した場合

WEB-INFディレクトリの直下に"web.xml"という名称でweb.xmlを格納するかどうかは任意です。格納する場合，Webサービスの実行に必要な定義が記述されていなくてもかまいません。

"none"または"false"（推奨は"none"）を設定した場合

必ずWEB-INFディレクトリの直下に"web.xml"という名称でweb.xmlを格納してください。

次に，Webサービスの実行に必要な定義，web.xmlの例，およびweb.xmlをWARファイルに含めない場合の動作について説明します。

3.4.1　Webサービスの実行に必要な定義

webserver.container.jaxws.webservice.no_webxml.enabledプロパティに"strict"を設定してweb.xmlをWARファイルに含める場合，または"none"を設定した場合，web.xmlは，次に示す条件を満たすように作成してください。

バージョン

web.xmlのバージョンは，2.5以上にしてください。

リスナ

web-app要素に，次に示すlistener要素を含めてください。

<listener>
  <listener-class>
    com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
  </listener-class>
</listener>

サーブレット

web-app要素に，次に示すservlet要素を含めてください。

<servlet>
  <description>Endpoint servlet for Cosminexus JAX-WS</description>
  <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
  <servlet-name>CosminexusJaxwsServlet</servlet-name>
  <servlet-class>
    com.cosminexus.xml.ws.transport.http.servlet.WSServlet
  </servlet-class>
</servlet>

サーブレットマッピング

web-app要素以下にservlet-mapping要素を記述し，Webサービス実装クラスまたはプロバイダ実装クラスと同じ数のurl-pattern要素を含めてください。

servlet-mapping要素の記述例を次に示します。

<servlet-mapping>
  <servlet-name>CosminexusJaxwsServlet</servlet-name>
  <url-pattern>" / "＋Webサービス1のサービス名</url-pattern>
  <url-pattern>" / "＋Webサービス2のサービス名</url-pattern>
    :
  <url-pattern>" / "＋Webサービスnのサービス名</url-pattern>
</servlet-mapping>

url-pattern要素の「" / "＋Webサービス1のサービス名」は，次の値にプレフィクスとして「/」（スラッシュ）を付けた文字列を記述します。

Webサービス実装クラスのjavax.jws.WebServiceアノテーションのserviceName属性の値

プロバイダ実装クラスのjavax.xml.ws.WebServiceProviderアノテーションのserviceName属性の値

参考

WARファイルにcosminexus-jaxws.xmlを含める場合

cosminexus-jaxws.xmlのWebサービス実装クラス，またはプロバイダ実装クラスに対応するendpoint要素のurl-pattern属性の値を記述してください。cosminexus-jaxws.xmlについては，「10.3　cosminexus-jaxws.xmlによるカスタマイズ」を参照してください。

そのほかの要素

任意に記述できます。WARファイルに作成したサーブレット，リスナ，JSPなどを含める場合，適宜，web.xmlに定義してください。

3.4.2　web.xmlの例

web.xmlの例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;fromwsdl&quot;</description>
  <display-name>Sample_web_service_fromwsdl</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/TestJaxWsService</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

この例では，次の属性の値が「TestJaxWsService」であることを想定しています。

Webサービス実装クラスのjavax.jws.WebServiceアノテーションのserviceName属性

プロバイダ実装クラスのjavax.xml.ws.WebServiceProviderアノテーションのserviceName属性

このとき，url-pattern要素の値は「/」（スラッシュ）を付けて「/TestJaxWsService」と記述します。

参考

WARファイルにcosminexus-jaxws.xmlを含める場合

Webサービス実装クラスまたはプロバイダ実装クラスに対応するendpoint要素のurl-pattern属性の値が「/TestJaxWsService」であれば，例と同じように記述します。

3.4.3　web.xmlをWARファイルに含めない場合の動作

Application ServerのJAX-WS機能では，webserver.container.jaxws.webservice.no_webxml.enabledプロパティに"strict"，または"lax"を設定してweb.xmlをWARファイルに含めない場合，Webサービス呼び出し時に次に示す内容のweb.xmlがあるものとして処理されます。

<?xml version="1.0" encoding="UTF-8"?>
<！-- web-app要素を記述する -->
  <description>Cosminexus JAX-WS Default web.xml</description>
  <display-name>Cosminexus_JAX_WS_Default_web_xml</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>"/"＋Webサービス1のサービス名</url-pattern>
    <url-pattern>"/"＋Webサービス2のサービス名</url-pattern>
      :
    <url-pattern>"/"＋Webサービスnのサービス名</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

url-pattern要素の「" / "＋Webサービス1のサービス名」は，次の属性の値に，プレフィクスとして「/」（スラッシュ）を付けた文字列が定義されます。

Webサービス実装クラスのjavax.jws.WebServiceアノテーションのserviceName属性の値

プロバイダ実装クラスのjavax.xml.ws.WebServiceProviderアノテーションのserviceName属性の値

WARファイル内に格納したすべてのWebサービス実装クラスまたはプロバイダ実装クラスについて，url-pattern要素があるかのように動作します。

webserver.container.jaxws.webservice.no_webxml.enabledプロパティに"lax"を設定してweb.xmlをWARファイルに含める場合でも，「3.4.1　Webサービスの実行に必要な定義」の内容が正しくweb.xmlに記述されていないときは，web.xmlが含まれない場合と同様に，上記に示す内容のweb.xmlがあるものと仮定してWebサービスを呼び出します。なお，このとき仮定されるweb.xmlは，上記の内容からsession-config要素以下を除いた内容です。

注意事項

JAX-WSエンジンが仮定したweb.xmlは，実際にWARファイル内に生成されるわけではありません。Webサービスが呼び出される場合を除いて，すべてこの仮定はないものとして扱われます。

（例）

cjgetapppropコマンドで取得できる属性ファイルには，web.xmlに関する情報は含まれません。また，webserver.container.jaxws.webservice.no_webxml.enabledプロパティに"lax"を設定して不正な内容のweb.xmlをWARファイルに含めた場合は，実際に含まれているweb.xmlに関する情報だけが取得できます。

webserver.container.jaxws.webservice.no_webxml.enabledプロパティに"lax"を設定して不正な内容のweb.xmlをWARファイルに含めた場合，JAX-WSエンジンがWebサービス呼び出し時に仮定するweb.xmlの内容が，実際のweb.xmlに記載されるわけではありません。

webserver.container.jaxws.webservice.no_webxml.enabledプロパティに"lax"を設定する場合，「3.4.1　Webサービスの実行に必要な定義」の内容をすべて定義したweb.xmlをWARファイルに含めてください。一部だけを定義したweb.xmlをWARファイルに含めた場合の動作は保証されません。

3.5　アーカイブの作成

WARファイルの構成，EJB JARファイルの構成およびEARファイルの作成について説明します。

3.5.1　WARファイルの構成

POJOのWebサービスで使用するWARファイルは，次の表に示す構成にする必要があります。

表3‒1　WARファイルの構成

ディレクトリ

備考

/

−

┣

┃

META-INF/

−

┗

MANIFEST.MF

−

┗

WEB-INF/

−

┣

web.xml

作成したweb.xmlです。

┣

classes/

コンパイルしたJavaクラスを格納します。

┣

lib/

コンパイルしたJavaクラスを含むJARファイルを格納します。

┗

wsdl/

作成したWSDLを格納します。WSDLをWebサービスのメタデータとして公開するには，このディレクトリに含める必要があります。なお，別のWARファイルおよびEJB JARファイルに含まれるWSDLファイルをこのディレクトリに含めないでください。

（凡例）

−：説明や補足事項が特にないことを示します。

注

cosminexus-jaxws.xmlをWARファイルに含める場合は，WEB-INFディレクトリ直下に含めます。cosminexus-jaxws.xmlについては，「10.3　cosminexus-jaxws.xmlによるカスタマイズ」を参照してください。

Application ServerのJAX-WSエンジンでは，同一のWARファイルに，複数のWebサービスを含められます。複数のWebサービスを含める場合，異なる機能を持つクラスのクラス名は重複できません。異なる機能を持つクラスのクラス名が重複していると，Webサービスが正常に動作しないおそれがあります。ただし，複数のWebサービスで同じクラスを利用する場合は，クラス名が重複していてもかまいません。

cjwsimportコマンドがpackage-info.javaを生成した場合は，パッケージ名から名前空間へのマッピングに必要なアノテーションなどのWebサービスに必要な情報が出力されているため，必ずpackage-info.javaをWARファイルに含めてください。

3.5.2　EJB JARファイルの構成

EJBのWebサービスで使用するEJB JARファイルは，次の表に示す構成にする必要があります。

表3‒2　EJB JARファイルの構成

ディレクトリ

備考

/

コンパイルしたJavaクラスを格納します。EJBのWebサービス実装クラスは，このディレクトリに含める必要があります。

┗

META-INF/

−

┣

┃

┃

┃

┃

wsdl/

作成したWSDLを格納します。WSDLをWebサービスのメタデータとして公開するには，このディレクトリに含める必要があります。なお，別のWARファイルおよびEJB JARファイルに含まれるWSDLファイルをこのディレクトリに含めないでください。

┗

MANIFEST.MF

−

（凡例）

−：説明や補足事項が特にないことを示します。

注

Application ServerのJAX-WSエンジンでは，同一のEJB JARファイルに，複数のWebサービスを含められます。複数のWebサービスを含める場合，異なる機能を持つクラスのクラス名は重複できません。異なる機能を持つクラスのクラス名が重複していると，Webサービスが正常に動作しないおそれがあります。ただし，複数のWebサービスで同じクラスを利用する場合は，クラス名が重複していてもかまいません。

cjwsimportコマンドがpackage-info.javaを生成した場合は，パッケージ名から名前空間へのマッピングに必要なアノテーションなどのWebサービスに必要な情報が出力されているため，必ずpackage-info.javaをEJB JARファイルに含めてください。

3.5.3　EARファイルの作成

WebサービスをJ2EEサーバにデプロイするには，作成したWARファイルまたはEJB JARファイルを含めたEARファイルを作成します。EARファイルを作成するには，application.xmlが必要になります。

EARファイルの構成については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「1.4.2　アーカイブ形式のJ2EEアプリケーション」を参照してください。

3.5.4　EJBのWebサービスの設定用WARファイルの作成

EJBのWebサービス呼び出し機能は，EARファイルに設定用WARファイルを含めない構成で利用できます。ただし，WARファイルの指定が必要なアプリケーションサーバの機能を利用するために，EARファイルに設定用WARファイルを含めることができます。ここでは設定用WARファイルについて説明します。

(1)　EARファイルに設定用WARファイルを含めない場合

EARファイルにEJB JARファイルが含まれていて，さらにEJB JARファイルにEJBのWebサービス実装クラスが含まれるとき，JAX-WSエンジンは設定用WARファイルを含むと仮定して動作します。仮定される設定用WARファイルの構成を次の表に示します。

表3‒3　仮定される設定用WARファイルの構成

ディレクトリ

備考

/

−

┣

┃

┃

WEB-INF/

−

┗

web.xml

3.5.4(4)を参照してください。

┗

META-INF/

−

（凡例）

−：説明や補足事項が特にないことを示します。

(2)　EARファイルに設定用WARファイルを含める場合

EJBのWebサービス実装クラスを呼び出す際に同時にサーブレットフィルタ機能を適用するなど，web.xmlに設定を加えたい場合，作成したweb.xmlを設定用WARファイルに格納し，EARファイルに含めます。設定用WARファイルの構成を次の表に示します。なお，設定用WARファイルには命名規則があります。設定用WARファイルのファイル名については，「3.5.4(3)　設定用WARファイル名」を参照してください。

表3‒4　設定用WARファイルの構成

ディレクトリ

備考

/

−

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

WEB-INF/

−

┣

┃

┃

classes/

コンパイルしたJavaクラスを格納します。フィルタを使用する場合は，フィルタのJavaクラスをこのディレクトリに格納します。※

┣

┃

┃

lib/

コンパイルしたJavaクラスを含むJARファイルを格納します。フィルタを使用する場合は，フィルタのJavaクラスを含むJARファイルをこのディレクトリに格納します。※

┗

web.xml

3.5.4(4)を参照してください。

┗

META-INF/

−

（凡例）

−：説明や補足事項が特にないことを示します。

注※

設定用WARファイルのclassesにPOJOのWebサービスを含めないでください。POJOのWebサービスを含めた場合の動作は保証されません。

(3)　設定用WARファイル名

EARファイルに設定用WARファイルを含める場合，EJBのWebサービスの設定用WARファイル名は，J2EEサーバ用ユーザプロパティファイル（usrconf.properties）のwebserver.container.jaxws.webservice.wsee.warnameプロパティで指定したファイル名にする必要があります。

EARファイルに設定用WARファイルを含めない場合，webserver.container.jaxws.webservice.wsee.warnameプロパティで指定したファイル名の設定用WARファイルを含むと仮定して動作します。EARファイルに設定用WARファイルを含めない場合，メッセージがJ2EEサーバのログに出力されるので，JAX-WSエンジンが設定用WARファイルを含むと仮定したことを確認できます（KDJE42391-I）。このメッセージが出力されなかった場合は，プロパティで指定した設定用WARファイルがEARファイルに含まれることを確認できます。

なお，プロパティのデフォルト値は「CosminexusWSEE.war」です。

EJBのWebサービス呼び出しに対して，次に示す設定を使用できます。これらの設定を使用する場合は，設定用WARファイルをEARファイルに含めて，設定用WARファイル名を指定してください。

コンテキストルートの設定

「application.xmlの<web-uri>要素」に設定用WARファイル名を指定します。

EJBのWebサービスの設定用WARファイルに対してコンテキストルートを設定しなかった場合，コンテキストルートは「/」と仮定されます。

cosminexus.xmlの<war>要素で指定する設定

「cosminexus.xmlの<module-name>要素」に設定用WARファイル名を指定します。

注意事項

webserver.container.jaxws.webservice.wsee.warnameプロパティの値を変更するには，EJBのWebサービスを含むWebアプリケーションを停止してください。Webアプリケーションを開始した状態で，プロパティの値を変更した場合は動作を保証されません。ほかのアプリケーションが不正となって，予期しない例外が発生する場合があります。

(4)　設定用WARファイルのweb.xml

ここではEJBのWebサービスの設定用WARファイルに含まれるweb.xmlについて説明します。

web.xmlを作成する場合，ファイル名称は"web.xml"とし，WARファイルを構成するWEB-INFディレクトリの直下に格納します。web.xmlの格納が必須かどうかは，J2EEサーバ用ユーザプロパティファイル（usrconf.properties）のwebserver.container.jaxws.webservice.wsee.no_webxml.enabledプロパティの設定値によって異なります。

"strict"を設定した場合

WEB-INFディレクトリの直下に"web.xml"という名称でweb.xmlを格納するかどうかは任意です。格納する場合，Webサービスの実行に必要な定義が記述されていなければなりません。

"lax"を設定した場合

WEB-INFディレクトリの直下に"web.xml"という名称でweb.xmlを格納するかどうかは任意です。格納する場合，Webサービスの実行に必要な定義が記述されていなくてもかまいません。

"none"を設定した場合

必ずWEB-INFディレクトリの直下に"web.xml"という名称でweb.xmlを格納してください。

次に，設定用WARファイルにweb.xmlを含めない場合の動作および設定用WARファイルにweb.xmlを含める場合の動作について説明します。

(a)　設定用WARファイルにweb.xmlを含めない場合

webserver.container.jaxws.webservice.wsee.no_webxml.enabledプロパティの設定値に"strict"，または"lax"を設定して，EJBのWebサービスの設定用WARファイルにweb.xmlを含めない場合，Webサービス呼び出し時に次に示す内容のweb.xmlがあるものとして処理されます。

<?xml version="1.0" encoding="UTF-8"?>
<！-- web-app要素を記述する -->
  <description>Cosminexus JAX-WS Default web.xml</description>
  <display-name>Cosminexus_JAX_WS_Default_web_xml</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.EJBWSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>EJB Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>EJB_Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsEjbServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.EJBWSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsEjbServlet</servlet-name>
    <url-pattern>"/" + Webサービス1のサービス名+ "/" + Webサービス1のクラス名</url-pattern>
    <url-pattern>"/" + Webサービス2のサービス名+ "/" + Webサービス2のクラス名</url-pattern>
      :
    <url-pattern>"/" + Webサービスnのサービス名+ "/" + Webサービスnのクラス名</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

url-pattern要素の「"/" + Webサービス1のサービス名+ "/" + Webサービス1のクラス名」は，Webサービス実装クラスのjavax.jws.WebServiceアノテーションのserviceName属性とname属性の値に，プレフィクスとして「/」（スラッシュ）を付けた文字列が定義されます。

設定用WARファイル内に格納したすべてのWebサービス実装クラスについて，url-pattern要素があるかのように動作します。

注意事項

JAX-WSエンジンが仮定したweb.xmlは，実際に設定用WARファイル内に生成されるわけではありません。Webサービスが呼び出される場合を除いて，すべてこの仮定はないものとして扱われます。

（例）

cjgetapppropコマンドで取得できる属性ファイルには，web.xmlに関する情報は含まれません。また，webserver.container.jaxws.webservice.wsee.no_webxml.enabledプロパティに"lax"を設定して不正な内容のweb.xmlを設定用WARファイルに含めた場合は，実際に含まれているweb.xmlに関する情報だけが取得できます。

webserver.container.jaxws.webservice.wsee.no_webxml.enabledプロパティに"lax"を設定して不正な内容のweb.xmlを設定用WARファイルに含めた場合，JAX-WSエンジンがWebサービス呼び出し時に仮定するweb.xmlの内容が，実際のweb.xmlに記載されるわけではありません。

(b)　設定用WARファイルにweb.xmlを含める場合

webserver.container.jaxws.webservice.wsee.no_webxml.enabledプロパティに"strict"を設定してweb.xmlをWARファイルに含める場合，または"none"を設定した場合，web.xmlは，次に示す条件を満たすように作成してください。

バージョン

web.xmlのバージョンは，2.5以上にしてください。

リスナ

web-app要素に，次に示すlistener要素を含めてください。

<listener>
  <listener-class>
    com.cosminexus.xml.ws.transport.http.servlet.EJBWSServletContextListener
  </listener-class>
</listener>

サーブレット

web-app要素に，次に示すservlet要素を含めてください。

<servlet>
  <description>EJB Endpoint servlet for Cosminexus JAX-WS</description>
  <display-name>EJB_Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
  <servlet-name>CosminexusJaxwsEjbServlet</servlet-name>
  <servlet-class>
    com.cosminexus.xml.ws.transport.http.servlet.EJBWSServlet
  </servlet-class>
</servlet>

サーブレットマッピング

web-app要素以下にservlet-mapping要素を記述し，Webサービス実装クラスと同じ数のurl-pattern要素を含めてください。

servlet-mapping要素の記述例を次に示します。

<servlet-mapping>
  <servlet-name>CosminexusJaxwsEjbServlet</servlet-name>
  <url-pattern>"/" + Webサービス1のサービス名+ "/" + Webサービス1のクラス名</url-pattern>
  <url-pattern>"/" + Webサービス2のサービス名+ "/" + Webサービス2のクラス名</url-pattern>
    :
  <url-pattern>"/" + Webサービスnのサービス名+ "/" + Webサービスnのクラス名</url-pattern>
</servlet-mapping>

url-pattern要素の「Webサービスnのサービス名」および「Webサービスnのクラス名」には，次の文字列を記述します。

「Webサービスnのサービス名」

Webサービス実装クラスのjavax.jws.WebServiceアノテーションのserviceName属性の値を記述します。serviceName属性が省略されている場合，Webサービス実装クラスのクラス名（単純名）にサフィックスとして"Service"を付けた文字列を記述します。

「Webサービスnのクラス名」

Webサービス実装クラスのjavax.jws.WebServiceアノテーションのname属性の値を記述します。name属性が省略されている場合，Webサービス実装クラスのクラス名（単純名）を記述します。

そのほかの要素

任意に記述できます。WARファイルに作成したサーブレットなどを含める場合，適宜，web.xmlに定義してください。

EJBのWebサービスの設定用WARファイルに含めるweb.xmlの例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Cosminexus JAX-WS Default web.xml</description>
  <display-name>Cosminexus_JAX_WS_Default_web_xml</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.EJBWSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>EJB Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>EJB_Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.EJBWSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/AddNumbersImplService/AddNumbersImpl</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

この例では，Webサービス実装クラスのjavax.jws.WebServiceアノテーションのserviceName属性の値が「AddNumbersImplService」で，さらにname属性が「AddNumbersImpl」であることを想定しています。

webserver.container.jaxws.webservice.wsee.no_webxml.enabledプロパティの設定値に"lax"を設定し，設定用WARファイルにweb.xmlを含める場合，リスナ，サーブレット，サーブレットマッピング，およびそのほかの要素が不完全に含まれるとき，動作は保証されません。

3.6　Webサービスクライアントの実装

Webサービスクライアントの形態に制限はありません。例えば，次に示すようなWebサービスクライアントを開発できます。なお，J2EEコンテナ上で動作するWebサービスクライアントを開発する場合の条件は，EJBのときはEJB 3.0以降，JSPやサーブレットなどのWebアプリケーションのときはServlet 2.5以降となります。例えば，Webアプリケーションでweb.xmlをWARファイルに含める場合は，web.xmlのバージョンを2.5以上にしてください。

Javaアプリケーション（JavaアプリケーションからWebサービスを呼び出す）

JSP（JSPからWebサービスを呼び出す）

サーブレット（サーブレットからWebサービスを呼び出す）

EJB（EJBからWebサービスを呼び出す）

Webサービス（Webサービス実装クラスから別のWebサービスをさらに呼び出す）

Application ServerのJAX-WS機能では，次のどれかの方法でWebサービスクライアントを実装できます。

サービスクラスとスタブを使用する（スタブベースのWebサービスクライアントの開発）

javax.xml.ws.Dispatchインタフェースを利用する（ディスパッチベースのWebサービスクライアントの開発）

その他のJAX-WS APIを利用する（APIベースのWebサービスクライアントの開発）

ここでは，Webサービスクライアントの実装例について説明します。また，サービスクラスやポートを使用する上での注意事項についても説明します。

3.6.1　スタブベースの実装例

cjwsimportコマンドで自動生成したサービスクラスやスタブを使用して，Webサービスクライアントを開発できます。スタブベースのWebサービスクライアントの実装で，サービスクラスの生成やポートを取得するには，次の方法があります。

サービスクラスのコンストラクタの利用

サービスクラスのコンストラクタを利用して，サービスクラスのインスタンスを生成します。生成したサービスクラスのインスタンスから，ポートを取得します。

javax.xml.ws.WebServiceRefアノテーションの利用

javax.xml.ws.WebServiceRefアノテーションを利用して，サービスクラスやポートをインジェクトします。

サービスクラスやポートのインジェクションについては，「10.21.1　サービスクラスおよびポートのインジェクション」を，javax.xml.ws.WebServiceRefアノテーションについては，「19.3　アノテーションのサポート範囲」を参照してください。

(1)　参照されるWSDL

スタブベースのWebサービスクライアントを実行する場合，WSDLのパスまたはURLが必要になります。このとき，次の条件の組み合わせによって，参照されるWSDLが異なります。

javax.xml.ws.WebServiceRefアノテーションを利用してインジェクションする場合

インジェクションする場合に参照されるWSDLについては，「19.3.1(2)　wsdlLocation要素（javax.xml.ws.WebServiceRef）」を参照してください。

サービスクラスのコンストラクタを利用してインスタンスを生成する場合

参照されるWSDLは次に示す条件の組み合わせによって異なります。

利用するコンストラクタの種類

cjwsimportコマンドに-wsdllocationオプションを指定して実行したかどうか

条件ごとの参照されるWSDLの対応を次の表に示します。なお，それぞれの条件での例については，「3.6.1(5)(a)　サービスクラスをインスタンス化する」を参照してください。

表3‒5　条件の組み合わせと参照されるWSDLの対応

項番

利用するコンストラクタ

-wsdllocation

オプション

参照されるWSDL

1

デフォルトコンストラクタ

×

cjwsimportコマンドの引数に指定したWSDL※1

2

デフォルトコンストラクタ

○

-wsdllocationオプションに指定したWSDL※2

3

java.net.URL オブジェクトおよびjavax.xml.namespace.QNameオブジェクトをパラメタに持つコンストラクタ

−

パラメタのURLに指定したWSDL※2

（凡例）

○：指定した場合。

×：指定しなかった場合。

−：指定の有無は参照されるWSDLに影響しません。

注※1

Webサービスクライアントを実行する場合，WSDLはcjwsimportコマンド実行時と同じ場所に存在している必要があります。cjwsimportコマンド実行時に相対パスを指定した場合も，WSDLはcjwsimportコマンド実行時と同じ場所に存在している必要があります。

注※2

絶対URLを指定した場合，Webサービスクライアントの実行時に，WSDLがそのURLが示す場所に存在している必要があります。

相対URLを指定した場合，Webサービスクライアントの実行時に，WSDLがカレントディレクトリを基準として相対URLを解決した場所に存在している必要があります。

(2)　参照されるエンドポイントアドレス

接続するWebサービスのURL（エンドポイントアドレス）は，デフォルトではWSDLのポート（wsdl:port要素）が持つアドレス情報（soap:address子要素のlocation属性）が利用されます。ただし，メッセージコンテキストのjavax.xml.ws.service.endpoint.addressプロパティを利用すると，エンドポイントアドレスを動的に変更できます。エンドポイントアドレスを動的に変更する例については，「3.6.1(5)(c)　ポートのメソッドを呼び出す」を参照してください。

(3)　サービスクラスの生成およびポートの取得

サービスクラスの生成やポートの取得には処理コストが掛かるので，次のように，ポートをインジェクションまたは再利用することをお推めします。

WebサービスクライアントをサーブレットやEJBとして実装する場合

ポートをインジェクションします。詳細については，「10.21　インジェクション」を参照してください。

ほかのアプリケーション（コマンドラインアプリケーションなど）でWebサービスクライアントを実装する場合

初期化処理でサービスクラスの生成やポートの取得を実施し再利用します。ポートを取得するたびにサービスクラスを生成したり，ポートのメソッドを呼び出すたびにポートを取得したりする必要はありません。

(4)　サービスの選択

呼び出すWebサービスのWSDLに複数のサービス（wsdl:service要素）が含まれる場合，サービスクラスを生成するときに，java.net.URLオブジェクトとjavax.xml.namespace.QNameオブジェクトをパラメタに持つコンストラクタを使用し，javax.xml.namespace.QNameオブジェクトでそのサービス（wsdl:service要素）を呼び出すのか明示的に指定してください。

(5)　基本的な実装例

Webサービスクライアントの実装には，コンストラクタを利用してサービスクラスを生成する方法と，インジェクションを利用する方法があります。ここでは，コンストラクタを利用してサービスクラスを生成する実装の手順を説明します。インジェクションについては，「10.21.1　サービスクラスおよびポートのインジェクション」を参照してください。

スタブベースのWebサービスクライアントを開発する場合，cjwsimportコマンドを使用してWebサービスを呼び出すために必要なJavaソースを生成します。cjwsimportコマンドは，-generateServiceオプションを指定しないで実行してください。

スタブベースのWebサービスクライアントは，次のJavaソースを使用してWebサービスを呼び出します。

サービスクラス

サービスクラスは，JAX-WS 2.2仕様で規定されたWebサービスを呼び出すためのWSDLのサービス（wsdl:service要素）に対応するクラスです。wsdl:service要素がwsdl:port要素をまとめるように，複数のポートをまとめています。

Webサービスクライアントを実装する場合は，はじめにサービスクラスのインスタンスを生成します。

ポート

WSDLのポート（wsdl:port要素）に対応するインスタンスで，インタフェースはサービスエンドポイントインタフェース（SEI）です。リモートにある接続先Webサービスのプロキシのように動作するため，Webサービスクライアントがこのポートのメソッドを呼び出すことで，Webサービスのオペレーションを透過的に呼び出せます。

Webサービスクライアントの実装でWebサービスのオペレーションを呼び出す手順は，次のとおりです。

サービスクラスをインスタンス化する

ポートを取得する

ポートのメソッドを呼び出す

ここでは，「5.1　開発例の構成（SEI起点）」に構成を示すWebサービス（足し算をするWebサービス）を呼び出すWebサービスクライアントの実装例を示します。

Webサービスクライアントの実装に使用するクラスおよびメソッドを次の表に示します。必要に応じて，「5.5.1　サービスクラスを生成する」に記載されたサービスクラスの生成物の内容を参照してください。

表3‒6　Webサービスクライアントの実装例で使用するクラスおよびメソッド

項番

種別

クラスおよびメソッド

1

サービスクラス

AddNumbersImplService

2

SEI

AddNumbersImpl

3

SEIのメソッド

int add(int, int)

4

クライアントのメインクラス

TestClient

(a)　サービスクラスをインスタンス化する

デフォルトのコンストラクタを使用してサービスクラスのオブジェクトを生成する例を次に示します。

// サービスクラスをインスタンス化する
AddNumbersImplService service = new AddNumbersImplService();

この場合，cjwsimportコマンドの引数または-wsdllocationオプションに指定したWSDLが参照されます。

cjwsimportコマンドの実行時に-wsdllocationオプションを指定しなかった場合の三つの例を次に示します。

実行例1

> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" D:¥dev¥development.wsdl

D:¥dev¥development.wsdlは，Webサービスクライアント実行時にも存在し，参照できる状態である必要があります。

実行例2

> D:
> cd D:¥dev¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" relative¥development.wsdl

D:¥dev¥relative¥development.wsdlは，Webサービスクライアント実行時にも存在し，参照できる状態である必要があります。

実行例3

> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" http://sample.com/fromjava/AddNumbersImplService?wsdl

http://sample.com/fromjava/AddNumbersImplService?wsdlは，Webサービスクライアント実行時にも存在し，参照できる状態である必要があります。

cjwsimportコマンドの実行時に-wsdllocationオプションを指定した場合の二つの例を次に示します。

実行例1

> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -wsdllocation file:/home/wsdl4runtime/master.wsdl D:¥dev¥development.wsdl

file:/home/wsdl4runtime/master.wsdlは，Webサービスクライアント実行時にも存在し，参照できる状態である必要があります。D:¥dev¥development.wsdlは，Webサービスクライアント開発時に実装に必要なJavaコードの生成に使用されるだけです。そのため，D:¥dev¥development.wsdlは実行時には存在しない，または参照できない状態でも問題ありません。

実行例2

> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -wsdllocation ./wsdl4runtime/master.wsdl D:¥dev¥development.wsdl

Webサービスクライアント実行時のカレントディレクトリを<実行時カレントディレクトリ>とした場合，<実行時カレントディレクトリ>/wsdl4runtime/master.wsdlが存在し，参照できる状態である必要があります。

なお，デフォルトのコンストラクタではなく，java.net.URLオブジェクトおよびjavax.xml.namespace.QNameオブジェクトをパラメタに持つコンストラクタを使用する場合は，次の例のようになります。

// サービスクラスをインスタンス化する
java.net.URL wsdlLocation = new java.io.File( "./wsdl4runtime/master.wsdl" ).toURL();
javax.xml.namespace.QName serviceName =
  new javax.xml.namespace.QName( "http:/sample.com/", "AddNumbersImplService");
AddNumbersImplService service =
  new AddNumbersImplService( wsdlLocation, serviceName );

java.net.URLオブジェクトで指定したURLのWSDLが参照されるため，cjwsimportコマンドの引数や-wsdllocationオプションで指定したWSDLは，Webサービスクライアント実行時には存在しない，または参照できない状態でも問題ありません。ただし，Webサービスクライアント実行時のカレントディレクトリを<実行時カレントディレクトリ>とした場合は，<実行時カレントディレクトリ>/wsdl4runtime/master.wsdlが存在し，参照できる状態である必要があります。

(b)　ポートを取得する

インスタンス化したサービスクラスからポートを取得する例を次に示します。

// ポートを取得する
AddNumbersImpl port = service.getAddNumbersImplPort();

(c)　ポートのメソッドを呼び出す

インスタンス化したサービスクラスから取得したポートのメソッドを呼び出す例を次に示します。

// ポートのメソッドを呼び出す
int returnValue = port.add(205, 103)

この例では，ポートのメソッドの引数に二つの値を渡すと，Webサービスで足し算の処理が行われます。戻り値として足し算の演算結果が返されます。

接続するWebサービスのURL（エンドポイントアドレス）は，デフォルトでは，WSDLのポート（wsdl:port要素）が持つアドレス情報（soap:address子要素のlocation属性）が利用されます。ただし，メッセージコンテキストのjavax.xml.ws.service.endpoint.addressプロパティを利用すると，エンドポイントアドレスを動的に変更できます。

エンドポイントアドレスを動的に変更しない場合，参照されるWSDLのsoap:address子要素のlocation属性に，WebサービスクライアントからアクセスできるURLが記述されているかどうか確認してください。

エンドポイントアドレスを動的に変更する場合，ポートのメソッドを呼び出す前に要求コンテキストを取得し，javax.xml.ws.service.endpoint.addressプロパティの値を変更します。例を次に示します。

// 要求コンテキストを取得する
java.util.Map<String, Object> context =
  ( ( javax.xml.ws.BindingProvider )port ).getRequestContext();

// エンドポイントアドレスを変更する
// (javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTYは
//  "javax.xml.ws.service.endpoint.address"を定義した定数)
context.put( javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
   "http://other.remote.org/fromjava/AddNumbersImplService" );

// ポートのメソッドを呼び出す
int returnValue = port.add(205, 103)

注意事項

サービスクラスの生成やポートの取得には処理コストが掛かるので，一度生成，取得したサービスクラスとポートは再利用することをお勧めします。ポートのWebメソッドを複数回呼び出す場合に，サービスクラスを複数回生成したり，ポートを複数回取得したりする必要はありません。ただし，複数スレッドでポートを共有する場合，共有するポートの要求コンテキストのプロパティに対する設定は，複数スレッドが動作する前に実行してください。複数スレッドの動作中にプロパティに対する設定を行うと，通信が失敗したり，不正なSOAPメッセージが送信されたりすることがあります。なお，ポートは要求コンテキスト以外，スレッドセーフです。

ポートのメソッドを複数回呼び出す例を次に示します。

// サービスクラスをインスタンス化する
AddNumbersImplService service = new AddNumbersImplService();
// ポートを取得する
AddNumbersImpl port = service.getAddNumbersImplPort();

// ポートのメソッドを複数回呼び出す
for (int i = 0; i < 10; i++) {
      int returnValue = port.add(i, i);
}

(6)　JavaアプリケーションのWebサービスクライアントの実装例

JavaアプリケーションのWebサービスクライアントから，サービスクラスを使用してWebサービスを呼び出す処理を実装します。

ここでは，「5.1　開発例の構成（SEI起点）」に構成を示すWebサービス（足し算をするWebサービス）を呼び出すWebサービスクライアントの実装例を示します。Webサービスクライアントの実装に使用するクラスおよびメソッドを次の表に示します。必要に応じて，「5.5.1　サービスクラスを生成する」に記載されたサービスクラスの生成物の内容を参照してください。

表3‒7　Webサービスクライアントの実装例で使用するクラスおよびメソッド（JavaアプリケーションのWebサービスクライアントの場合）

項番

種別

クラスおよびメソッド

1

サービスクラス

AddNumbersImplService

2

ポート

AddNumbersImpl

3

ポートのメソッド

int add(int, int)

4

Webサービスクライアントのクライアントのメインクラス

TestClient

Javaアプリケーションの実装例を次に示します。

package com.example.sample.client;

import com.example.sample.AddNumbersImplTestJaxWs;
import com.example.sample.AddNumbersImplTestJaxWsService;
import com.sample.AddNumbersFault_Exception;

// Sample implementation of web service's client
public class TestClient {
    public static void main( String[] args ) {
        try {
            // サービスクラスをインスタンス化する
            AddNumbersImplTestJaxWsService service = new AddNumbersImplTestJaxWsService();
            // ポートを取得する
            AddNumbersImplTestJaxWs port = service.getAddNumbersImplPortTestJaxWs();

            // ポートのメソッドを呼び出す
            port.jaxWsTest1( ... );
            int number1 = 205;
            int number2 = 103;
            int returnValue = port.add(number1, number2);

            // 結果を表示する
            System.out.println( "[RESULT] " + number1 + " + " + number2 + " = " + returnValue );
        }
        catch( Exception e ){
            // 例外処理(ここでは単にスタックトレースを出力)
            e.printStackTrace();
        }
    }
}

プログラムの実行結果を次に示します。

[RESULT] 205 + 103 = 308

(7)　サーブレットのWebサービスクライアントの実装例

サーブレット形態のWebサービスクライアントから，サービスクラスを使用してWebサービスを呼び出す処理を実装します。

ここでは，「5.1　開発例の構成（SEI起点）」に構成を示すWebサービス（足し算をするWebサービス）を呼び出すWebサービスクライアントの実装例を示します。Webサービスクライアントの実装に使用するクラスおよびメソッドを次の表に示します。必要に応じて，「5.5.1　サービスクラスを生成する」に記載されたサービスクラスの生成物の内容を参照してください。

表3‒8　Webサービスクライアントの実装例で使用するクラスおよびメソッド（サーブレットから呼び出す場合）

項番

種別

クラスおよびメソッド

1

サービスクラス

AddNumbersImplService

2

ポート

AddNumbersImpl

3

ポートのメソッド

int add(int, int)

4

Webサービスクライアントとなるサーブレット実装クラス

TestClient

(a)　ポートのインジェクション

サーブレットからWebサービスを呼び出す実装では，ポート型のフィールドにjavax.xml.ws.WebServiceRefアノテーションを指定して，サーブレットインスタンスの生成時にポートのインジェクションを実行します。

インジェクションの例を次に示します。

...
public class TestClient extends HttpServlet {

    // ポート(AddNumbersImpl)型のフィールドに，ポートをインジェクトする
    @WebServiceRef(AddNumbersImplService.class)
    AddNumbersImpl port;

    @Override
    public void init() {
    }
    ...
}

(b)　ポートのメソッド呼び出しによるWebサービスのオペレーション実行

サーブレットのフィールドとして生成したポートを使って，メソッドを呼び出します。

メソッド呼び出しの例を次に示します。

...
public class TestClient extends HttpServlet {

    // ポート(AddNumbersImpl)型のフィールドに，ポートをインジェクトする
    @WebServiceRef(AddNumbersImplService.class)
    AddNumbersImpl port;
    ...
    @Override
    public void doGet(HttpServletRequest request, HttpServletResponse response)
    throws ServletException, IOException {
        ...
            int number1 = ...; // requestオブジェクトから取得した値を代入
            int number2 = ...; // requestオブジェクトから取得した値を代入
            // ポートのメソッドを呼び出す
            int returnValue = port.add(number1, number2);
            ...
    }
}

サーブレットからWebサービスを呼び出す場合の実装例の全体を次に示します。

package com.sample.client;

import java.io.IOException;
import java.io.PrintWriter;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.sample.AddNumbersFault_Exception;
import com.sample.AddNumbersImpl;
import com.sample.AddNumbersImplService;

public class TestClient extends HttpServlet {

    // ポート(AddNumbersImpl)型のフィールドに，ポートをインジェクトする
    @WebServiceRef(AddNumbersImplService.class)
    AddNumbersImpl port;

    @Override
    public void init() {
    }

    @Override
    public void doGet(HttpServletRequest request, HttpServletResponse response)
    throws ServletException, IOException {
        PrintWriter out = response.getWriter();

        try {
            // Invoke a method of the target web service.
            int number1 = ...; // requestオブジェクトから取得した値を代入
            int number2 = ...; // requestオブジェクトから取得した値を代入
            // ポートのメソッドを呼び出す
            int returnValue = port.add(number1, number2);
            // 結果を表示する
            out.println("<html><body>");
            out.println("<h1>RESULT</h1>");
            out.println(number1 + " + " + number2 + " = " + returnValue);
            out.println("</body></html>");
        } catch(AddNumbersFault_Exception e) {
            // 例外処理(ここでは単に例外の詳細メッセージを出力)
            out.println("<html><body>");
            out.println("<h1>" + e.getMessage() + "</h1>");
            out.println("</body></html>");
        }
    }
}

プログラムの実行結果を次に示します。ブラウザなどからサーブレットに接続すると実行結果が表示されます。

RESULT
205 + 103 = 308

(c)　注意事項

Webサービスクライアント（サーブレット）と接続先のWebサービスが，同じJ2EEサーバ上にデプロイされている環境では，次の場合，J2EEサーバの起動時に例外が発生します。

initメソッドまたはjavax.annotation.PostConstructアノテーションを指定したメソッドの中で，WebサービスからWSDLを取得してサービスクラスを生成するときに，Webサービスクライアントが含まれるWARファイルのweb.xmlにload-on-startup要素を指定した場合

javax.xml.ws.WebServiceRefアノテーションを利用して，WebサービスからWSDLを取得してサービスクラスやポートをインジェクトする場合

例外が発生する場合の対策方法を次に示します。

J2EEサーバを停止する前に，Webサービスクライアントが含まれるWebアプリケーションを停止してください。J2EEサーバを再起動したあとに，Webサービスクライアントが含まれるWebアプリケーションを開始してください。

WebサービスとWebサービスクライアントを別のJ2EEサーバにデプロイして，WebサービスをデプロイしたJ2EEサーバを起動したあとにWebサービスクライアントをデプロイしたJ2EEサーバを起動してください。

カタログ機能を使用して，サービスクラスの生成時にローカルに格納したWSDL文書を参照するように設定してください。

initメソッドまたはjavax.annotation.PostConstructアノテーションを指定したメソッドで，サービスクラスを生成する場合は，URLをパラメタに取るコンストラクタにローカルのWSDL文書を指定してサービスクラスを生成してください。または，web.xmlにload-on-startup要素を指定しないでください。

javax.xml.ws.WebServiceRefアノテーションを利用する場合は，wsdlLocation要素に相対パスまたは絶対パスで，ローカルに格納したWSDL文書を指定してください。

3.6.2　ディスパッチベースの実装例

Application Serverでサポートしているjavax.xml.ws.Dispatchインタフェース，JAX-WS 2.2仕様，JAXB 2.2仕様，およびSAAJ 1.3仕様などのAPIを使用して開発してください。

(1)　ディスパッチベースのWebサービスクライアントの実装例

ディスパッチベースのWebサービスクライアントの実装例を次に示します。

package com.example.sample.client;

import javax.xml.namespace.QName;
import javax.xml.soap.MessageFactory;
import javax.xml.soap.SOAPBody;
import javax.xml.soap.SOAPBodyElement;
import javax.xml.soap.SOAPElement;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPMessage;
import javax.xml.ws.Dispatch;
import javax.xml.ws.Service;
import javax.xml.ws.soap.SOAPBinding;

public class TestClient {
    public static void main( String[] args ) {
        QName port = new QName( "http://sample.com", "AddNumbersImplPort" );
        SOAPBody soapBody = null;

        // サービスを生成する
        Service service = Service.create(
            new QName("http://sample.com", "UserInfoPort") );

        // サービスにポートを追加する
        service.addPort( port, SOAPBinding.SOAP11HTTP_BINDING,
            "http://localhost:80/dispatch_provider/UserInfoService" );

        // ディスパッチを生成する
        Dispatch<SOAPMessage> dispatch = service.createDispatch(
            port, SOAPMessage.class, Service.Mode.MESSAGE );

        SOAPMessage request = null;
        try{
            // 要求メッセージを SAAJ 1.3仕様のAPIを使用して生成していく
            request = MessageFactory.newInstance().createMessage();
            SOAPBody reqSoapBody = request.getSOAPBody();
            SOAPElement soapElement = null;
            // SOAPボディに要素を追加
            SOAPBodyElement requestRoot= reqSoapBody.addBodyElement(
                new QName( ... ) );
            soapElement = requestRoot.addChildElement(
                new QName( ... ) );
            soapElement.addTextNode( ... );
            // 添付ファイルを追加する
            File attachment = new File( ... );
            FileDataSource fds = new FileDataSource( attachment );
            AttachmentPart apPart = request.createAttachmentPart( new DataHandler( fds ) );
            request.addAttachmentPart(apPart);
        }
        catch( SOAPException e ){
            // 例外処理
        }
        // 作成した要求メッセージを指定し，ディスパッチを利用してWebサービスを呼び出す
        SOAPMessage response = dispatch.invoke( request );

        try{
            // 応答メッセージについて必要な処理を行う
            SOAPBody resSoapBody = response.getSOAPBody();
            ...
        }
        catch( SOAPException e ){
            // 例外処理
        }
    }
}

プロバイダ実装クラスから送信されたSOAPフォルトをWebサービスクライアントの実装で利用する場合は，try-catchブロック内でinvoke()メソッドを呼び出し，javax.xml.ws.soap.SOAPFaultException例外を取得します。SOAPフォルトも，javax.xml.ws.soap.SOAPFaultException例外から取得できます。実装例を次に示します。

package com.example.sample.client;

import javax.xml.namespace.QName;
...
import javax.xml.ws.soap.SOAPBinding;
import javax.xml.ws.soap.SOAPFaultException;

public class TestClient {
    public static void main( String[] args ) {
...
        try{
            // 要求メッセージを SAAJ 1.3仕様のAPIを使用して生成していく
            ...
        }
        catch( SOAPException e ){
            // 例外処理
        }

        SOAPMessage response = null;
        try{
            // 作成した要求メッセージを指定し，ディスパッチを利用してWebサービスを呼び出す
            response = dispatch.invoke( request );
        }
        catch( SOAPFaultException e ){
            // SOAPフォルトを取得する処理
            SOAPFault fault = e.getFault();
            // 取得した SOAPフォルトに対して必要な処理を行う
            String faultCode = fault.getFaultCode();
            ...
        }

        try{
            // 応答メッセージについて必要な処理を行う
            ...
        }
        catch( SOAPException e ){
            e.printStackTrace();
        }
    }
}

(2)　参照されるエンドポイントアドレス

接続するWebサービスのURL（エンドポイントアドレス）は，メッセージコンテキストのjavax.xml.ws.service.endpoint.addressプロパティで指定および変更できます。エンドポイントアドレスを指定・変更する例については，「3.6.1(5)(c)　ポートのメソッドを呼び出す」を参照してください。

(3)　サービスクラスおよびディスパッチの再利用

サービスクラスおよびディスパッチの生成には処理コストが掛かるので，一度生成したサービスクラスおよびディスパッチは再利用することをお勧めします。ポートを追加したりディスパッチを生成したりするためにサービスクラスを複数回生成する必要はありません。同様に，ディスパッチのinvokeメソッドを複数回呼び出すためにディスパッチを複数回取得する必要はありません。ただし，複数スレッドでディスパッチを共有する場合，共有するディスパッチの要求コンテキストのプロパティに対する設定は，複数スレッドが動作する前に実行してください。複数スレッドの動作中にプロパティに対する設定を行うと，通信が失敗したり，不正なSOAPメッセージが送信されたりすることがあります。なお，ディスパッチは要求コンテキスト以外，スレッドセーフです。

WebサービスクライアントをサーブレットやEJBなどで実装する場合は，それぞれの初期化メソッドでサービスクラスおよびディスパッチを取得し，再利用することをお勧めします。ディスパッチの要求コンテキストのプロパティに対する変更も，それぞれの初期化メソッドで実行してください。

3.6.3　JAX-WS APIを使用する場合の実装例

Application ServerのJAX-WS機能がサポートしているJAX-WS APIを利用して，Webサービスクライアントを実装できます。JAX-WS APIのサポート範囲については，「19.2　APIのサポート範囲」を参照してください。

(1)　JAX-WS APIを使用する場合のWebサービスクライアントの実装例

JAX-WS APIを使用したWebサービスクライアントの実装例を示します。

package com.example.sample.client;

import com.example.sample.TestJaxWs;
import com.example.sample.TestJaxWsService;

import java.net.URL;
import java.net.MalformedURLException;
import java.util.Iterator;
import java.util.Map;
import javax.xml.namespace.QName;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.Service;
import javax.xml.ws.WebServiceException;

public class TestClient {
    public static void main( String[] args ) {

        // WSDLのURLとサービス名を設定
        URL url = null;
        try {
            url = new URL("http://localhost:8085/fromwsdl/test?wsdl");
        } catch (MalformedURLException e) {
            // 例外処理
        }
        QName serviceName =
            new QName("http://example.com/sample", "TestJaxWsService");

        // Serviceインスタンスの生成
        Service service = Service.create(url, serviceName);
        System.out.println(service.getWSDLDocumentLocation());

        QName portName = null;

        // ポート名のリストを表示
        Iterator it = service.getPorts();
        while(it.hasNext()) {
            portName = (QName)it.next();
            System.out.println(portName);
        }

        // ポートの取得
        TestJaxWs port = (TestJaxWs)service.getPort(TestJaxWs.class);

        // 送信コンテキストの取得
        Map<java.lang.String, java.lang.Object>context =
((BindingProvider)port).getRequestContext();
        System.out.println(context.entrySet());

        // サービスのメソッド呼び出し
        try {
            port.jaxWsTest1( "TEST", 123);
        } catch (WebServiceException e) {
            // 例外処理
        }
    }
}

(2)　javax.xml.ws.Serviceオブジェクトおよびポートの再利用

javax.xml.ws.Serviceオブジェクトの生成には処理コストが掛かるので，一度生成したjavax.xml.ws.Serviceオブジェクトは再利用することをお勧めします。ポートを取得するためにjavax.xml.ws.Serviceオブジェクトを複数回生成する必要はありません。

同様に，ポートの取得にも処理コストが掛かるので，一度取得したポートは再利用することをお勧めします。ポートのWebメソッドを複数回呼び出すためにポートを複数回取得する必要はありません。ただし，複数スレッドでポートを共有する場合，共有するポートの要求コンテキストのプロパティに対する設定は，複数スレッドが動作する前に実行してください。複数スレッドの動作中にプロパティに対する設定を行うと，通信が失敗したり，不正なSOAPメッセージが送信されたりすることがあります。なお，ポートは要求コンテキスト以外，スレッドセーフです。

WebサービスクライアントをサーブレットやEJBなどで実装する場合は，それぞれの初期化メソッドでjavax.xml.ws.Serviceオブジェクトの生成，またはポートの取得を実施し，再利用してください。ポートの要求コンテキストのプロパティに対する変更も，それぞれの初期化メソッドで実行してください。

3.6.4　注意事項

Webサービスクライアント実装時の注意事項について説明します。

(1)　オブジェクトの再利用

サービスクラス，ポート，およびディスパッチの生成には処理コストが掛かるので，インジェクションを利用するか（スタブベースの場合だけ），再利用することをお勧めします。オブジェクトの再利用については，それぞれ次の個所を参照してください。

スタブベースのWebサービスクライアントの場合

「3.6.1(3)　サービスクラスの生成およびポートの取得」

ディスパッチベースのWebサービスクライアントの場合

「3.6.2(3)　サービスクラスおよびディスパッチの再利用」

APIベースのWebサービスクライアントの場合

「3.6.3(2)　javax.xml.ws.Serviceオブジェクトおよびポートの再利用」

(2)　プロキシ・SSL接続・ベーシック認証の設定

必要に応じて，Webサービスクライアントの実行環境に，プロキシ，SSL接続，およびベーシック認証の設定を行ってください。詳細については，それぞれ次の個所を参照してください。

プロキシの設定

「10.10　プロキシサーバ経由の接続」

SSL接続の設定

「10.11　SSLプロトコルによる接続」

ベーシック認証の設定

「10.12　ベーシック認証による接続」

(3)　Windows環境での注意事項

Webサービスクライアントから大量のリクエストを送信するような環境では，次の例外が記録されることがあります。

java.net.BindException: Address already in use: connect [errno=10048, syscall=select]

例えば，サーブレットとして実装したWebサービスクライアントに対して大量のリクエストが到着すると，例外が発生します。

このような場合は，次に示すどちらか，または両方の値を見直してください。

OSで使用できるポート番号の範囲を広げる

TIME_WAITの継続時間を短くする

例えば，レジストリのMaxUserPortやTcpTimedWaitDelayの設定を見直します。ただし，OSのバージョンやエディション，セキュリティ更新プログラムの適用状況によって，仕様が異なるため，詳細については各OSのドキュメントを参照してください。また，これらの設定はOS全体に影響が及ぶため，注意が必要です。

(4)　通信失敗時のJava例外

Webサービスとの通信が失敗した場合，次の例外が記録されることがあります。

java.net.ConnectException: ["Connection refused: connect"または"接続を拒否されました"]

このメッセージは，OSや環境によって出力内容が異なる場合があります。

3.6.5　アドレッシング機能を使用したWebサービスにアクセスする場合の注意事項

アドレッシング機能が有効なWebサービスにアクセスする場合は，スタブベースのWebサービスクライアントを使用します。ディスパッチベースのWebサービスクライアントは使用できないので，注意してください。

4　WSDLを起点とした開発の例

この章では，WSDLを起点としたWebサービスを開発する場合の例を説明します。

4.1　開発例の構成（WSDL起点）

この章で説明する開発例では，WSDLを起点としたWebサービスを開発します。

開発するWebサービスの構成を次の表に示します。

表4‒1　Webサービスの構成（WSDL起点）

項番

項目

値

1

デプロイするJ2EEサーバの名称

jaxwsserver

2

Webサーバのホスト名とポート番号

webhost:8085

3

ネーミングサーバのURL

corbaname::testserver:900

4

コンテキストルート

fromwsdl

5

スタイル

document/literal/wrapped

6

名前空間URI

http://example.com/sample

7

ポートタイプ

個数

1

8

ローカル名

TestJaxWs

9

オペレーション

個数

1

10

ローカル名

jaxWsTest1

11

サービス

個数

1

12

ローカル名

TestJaxWsService

13

ポート

個数

1

14

ローカル名

testJaxWs

15

WSDLのファイル名

input.wsdl

Webサービス開発時のカレントディレクトリの構成を次の表に示します。

表4‒2　カレントディレクトリの構成（WSDL起点）

ディレクトリ

説明

c:¥temp¥jaxws¥works¥fromwsdl

カレントディレクトリです。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

server¥

Webサービスの開発で使用します。

┣

┃

┃

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

┗

application.xml

「4.3.6　application.xmlを作成する」で作成します。

┣

┃

┃

┃

src¥

Webサービスのソースファイル（*.java）を格納します。「4.3.2　SEIを生成する」および「4.3.4　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

┃

┃

┃

┃

┃

WEB-INF¥

WARファイルのWEB-INFディレクトリに対応します。

┣

web.xml

「4.3.5　web.xmlを作成する」で作成します。

┣

classes¥

コンパイルしたクラスファイル（*.class）を格納します。

┗

wsdl¥

作成したwsdlを格納します。

┣

┃

┃

┃

temporary¥

Javaで記述，変換したものを基にWSDLを作成する場合に一時ファイルを格納します。このディレクトリの作成は任意です。

┣

src¥

┗

classes¥

┣

fromwsdl.ear

「4.3.7　EARファイルを作成する」で作成します。

┗

fromwsdl.war

┗

client¥

Webサービスクライアントの開発で使用します。

┣

┃

┃

┃

src¥

Webサービスクライアントのソースファイル（*.java）を格納します。「4.5.1　サービスクラスを生成する」および「4.5.2　Webサービスクライアントの実装クラスを作成する」で使用します。

┣

┃

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「4.5.3　Webサービスクライアントの実装クラスをコンパイルする」で使用します。

┣

┃

usrconf.cfg

「4.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

┗

usrconf.properties

「4.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

カレントディレクトリのパスは，開発する環境に合わせて変更してください。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebサービスとWebサービスクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

4.2　開発例の流れ（WSDL起点）

この章で説明する開発例では，次の流れで開発および実行します。

Webサービスの開発

WSDLファイルを作成する（4.3.1）

cjwsimportコマンドを実行し，SEIを生成する（4.3.2）

Webサービス実装クラスを作成する（4.3.3）

Webサービス実装クラスをコンパイルする（4.3.4）

web.xmlを作成する（4.3.5）

application.xmlを作成する（4.3.6）

EARファイルを作成する（4.3.7）

デプロイと開始

EARファイルをデプロイする（4.4.1）

Webサービスを開始する（4.4.2）

Webサービスクライアントの開発

cjwsimportコマンドを実行し，サービスクラスを生成する（4.5.1）

Webサービスクライアントの実装クラスを作成する（4.5.2）

Webサービスクライアントの実装クラスをコンパイルする（4.5.3）

Webサービスの実行

Javaアプリケーション用オプション定義ファイルを作成する（4.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（4.6.2）

Webサービスクライアントを実行する（4.6.3）

4.3　Webサービスの開発例（WSDL起点）

ここでは，WSDLを起点とした場合のWebサービスの開発例を説明します。

4.3.1　WSDLファイルを作成する

WSDLファイルを作成し，Webサービスのメタ情報を定義します。WSDL定義は，次の仕様のサポート範囲内で定義してください。

WSDL 1.1仕様

サポート範囲については，「20.1　WSDL 1.1仕様のサポート範囲」を参照してください。

XML Schema仕様

サポート範囲については，マニュアル「XML Processor ユーザーズガイド」を参照してください。

WS-I Basic Profile 1.1

WSDLファイルの作成方法には，新規に作成する方法と，Javaソースを変換したものを利用して作成する方法の2種類があります。

(1)　新規にWSDLファイルを作成する

ここでは，WSDLファイル（input.wsdl）を作成します。作成したWSDLファイルは，UTF-8形式でc:¥temp¥jaxws¥works¥fromwsdl¥server¥WEB-INF¥wsdl¥ディレクトリに保存してください。

SOAP 1.1の場合の作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="TestJaxWsService"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://example.com/sample"
  targetNamespace="http://example.com/sample">

  <wsdl:types>
    <xsd:schema targetNamespace="http://example.com/sample">
      <!-- 要求メッセージの wrapper要素 -->
      <xsd:element name="jaxWsTest1" type="tns:jaxWsTest1"/>

      <!-- 応答メッセージの wrapper要素 -->
      <xsd:element name="jaxWsTest1Response" type="tns:jaxWsTest1Response"/>

      <!-- フォルトメッセージの wrapper要素 -->
      <xsd:element name="UserDefinedFault" type="tns:UserDefinedFault"/>

      <!-- 要求メッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="jaxWsTest1">
        <xsd:sequence>
          <xsd:element name="information" type="xsd:string"/>
          <xsd:element name="count" type="xsd:int"/>
        </xsd:sequence>
      </xsd:complexType>

      <!-- 応答メッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="jaxWsTest1Response">
        <xsd:sequence>
          <xsd:element name="return" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>

      <!-- フォルトメッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="UserDefinedFault">
        <xsd:sequence>
          <xsd:element name="additionalInfo" type="xsd:int"/>
          <xsd:element name="detail" type="xsd:string"/>
          <xsd:element name="message" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:schema>
  </wsdl:types>

  <!-- 要求メッセージ -->
  <wsdl:message name="jaxWsTest1Request">
    <wsdl:part name="inputParameters" element="tns:jaxWsTest1"/>
  </wsdl:message>

  <!-- 応答メッセージ -->
  <wsdl:message name="jaxWsTest1Response">
    <wsdl:part name="outputParameters" element="tns:jaxWsTest1Response"/>
  </wsdl:message>

  <!-- フォルトメッセージ -->
  <wsdl:message name="UserDefinedException">
    <wsdl:part name="fault" element="tns:UserDefinedFault"/>
  </wsdl:message>

  <!-- ポートタイプ -->
  <wsdl:portType name="TestJaxWs">
    <!-- オペレーション -->
    <wsdl:operation name="jaxWsTest1">
      <wsdl:input message="tns:jaxWsTest1Request"/>
      <wsdl:output message="tns:jaxWsTest1Response"/>
      <wsdl:fault name="UserDefinedFault"
        message="tns:UserDefinedException"/>
    </wsdl:operation>
  </wsdl:portType>

  <!-- バインディング(SOAP 1.1/HTTPバインディング) -->
  <wsdl:binding name="testJaxWsBinding" type="tns:TestJaxWs">
    <!-- document/literal/wrapped -->
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <!-- オペレーション -->
    <wsdl:operation name="jaxWsTest1">
      <soap:operation/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
      <wsdl:fault name="UserDefinedFault">
        <soap:fault name="UserDefinedFault" use="literal"/>
      </wsdl:fault>
    </wsdl:operation>
  </wsdl:binding>

  <!-- サービス -->
  <wsdl:service name="TestJaxWsService">
    <!-- ポート -->
    <wsdl:port name="testJaxWs" binding="tns:testJaxWsBinding">
      <soap:address location="http://webhost:8085/fromwsdl/TestJaxWsService"/>
    </wsdl:port>
  </wsdl:service>

</wsdl:definitions>

SOAP 1.2の場合の作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="TestJaxWsService"
  xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://example.com/sample"
  targetNamespace="http://example.com/sample">

  <wsdl:types>
    <xsd:schema targetNamespace="http://example.com/sample">
      <!-- 要求メッセージの wrapper要素 -->
      <xsd:element name="jaxWsTest1" type="tns:jaxWsTest1"/>

      <!-- 応答メッセージの wrapper要素 -->
      <xsd:element name="jaxWsTest1Response" type="tns:jaxWsTest1Response"/>

      <!-- フォルトメッセージの wrapper要素 -->
      <xsd:element name="UserDefinedFault" type="tns:UserDefinedFault"/>

      <!-- 要求メッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="jaxWsTest1">
        <xsd:sequence>
          <xsd:element name="information" type="xsd:string"/>
          <xsd:element name="count" type="xsd:int"/>
        </xsd:sequence>
      </xsd:complexType>

      <!-- 応答メッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="jaxWsTest1Response">
        <xsd:sequence>
          <xsd:element name="return" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>

      <!-- フォルトメッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="UserDefinedFault">
        <xsd:sequence>
          <xsd:element name="additionalInfo" type="xsd:int"/>
          <xsd:element name="detail" type="xsd:string"/>
          <xsd:element name="message" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:schema>
  </wsdl:types>

  <!-- 要求メッセージ -->
  <wsdl:message name="jaxWsTest1Request">
    <wsdl:part name="inputParameters" element="tns:jaxWsTest1"/>
  </wsdl:message>

  <!-- 応答メッセージ -->
  <wsdl:message name="jaxWsTest1Response">
    <wsdl:part name="outputParameters" element="tns:jaxWsTest1Response"/>
  </wsdl:message>

  <!-- フォルトメッセージ -->
  <wsdl:message name="UserDefinedException">
    <wsdl:part name="fault" element="tns:UserDefinedFault"/>
  </wsdl:message>

  <!-- ポートタイプ -->
  <wsdl:portType name="TestJaxWs">
    <!-- オペレーション -->
    <wsdl:operation name="jaxWsTest1">
      <wsdl:input message="tns:jaxWsTest1Request"/>
      <wsdl:output message="tns:jaxWsTest1Response"/>
      <wsdl:fault name="UserDefinedFault"
        message="tns:UserDefinedException"/>
    </wsdl:operation>
  </wsdl:portType>

  <!-- バインディング(SOAP 1.2/HTTPバインディング) -->
  <wsdl:binding name="testJaxWsBinding" type="tns:TestJaxWs">
    <!-- document/literal/wrapped -->
    <soap12:binding style="document" transport="http://www.w3.org/2003/05/soap/bindings/HTTP/"/>
    <!-- オペレーション -->
    <wsdl:operation name="jaxWsTest1">
      <soap12:operation/>
      <wsdl:input>
        <soap12:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap12:body use="literal"/>
      </wsdl:output>
      <wsdl:fault name="UserDefinedFault">
        <soap12:fault name="UserDefinedFault" use="literal"/>
      </wsdl:fault>
    </wsdl:operation>
  </wsdl:binding>

  <!-- サービス -->
  <wsdl:service name="TestJaxWsService">
    <!-- ポート -->
    <wsdl:port name="testJaxWs" binding="tns:testJaxWsBinding">
      <soap12:address location="http://webhost:8085/fromwsdl/TestJaxWsService"/>
    </wsdl:port>
  </wsdl:service>

</wsdl:definitions>

(2)　Javaソースを変換したものを基にWSDLファイルを作成する

ここでは，WSDL変換用に仮実装のWebサービス実装クラスと例外クラスを作成し，hwsgenコマンドのWSDL生成機能を実行して，コンパイル済みのJavaソースからWSDLファイルを作成します。作成したクラスは，javax.jws.WebServiceアノテーションでアノテートしてください。メソッドを実装する必要はありません。

仮実装のWebサービス実装クラスの例を次に示します。

package com.example.sample;

@javax.jws.WebService
public class TestJaxWsImpl {

    public String jaxWsTest1(String information, int count)
        throws UserDefinedException
    {
        // 実装不要
        return null;
    }

}

仮実装の例外クラスの例を次に示します。

package com.example.sample;

public class UserDefinedFault extends Exception{
    // 実装不要
    public int additionalInfo;
    public String detail;
    public String message;
}

作成したTestJaxWsImpl.javaとUserDefinedFault.javaをUTF-8形式でc:¥temp¥jaxws¥works¥fromwsdl¥server¥temporary¥src¥com¥example¥sample¥ディレクトリに保存し，コンパイルします。コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥server¥
> mkdir .¥temporary
> mkdir .¥temporary¥classes
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar" -d .¥temporary¥classes .¥temporary¥src¥com¥example¥sample¥TestJaxWsImpl.java .¥temporary¥src¥com¥example¥sample¥UserDefinedFault.java

コンパイルが正常に終了すると，c:¥temp¥jaxws¥works¥fromwsdl¥server¥temporary¥classes¥com¥example¥sample¥ディレクトリにTestJaxWsImpl.classとUserDefinedFault.classが生成されます。これらのクラスファイルを利用して，hwsgenコマンドのWSDL生成機能でWSDLファイルを作成します。

hwsgenコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥server¥
> mkdir .¥WEB-INF¥wsdl¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥hwsgen.bat" -r .¥WEB-INF¥wsdl -d .¥temporary¥classes -cp .¥temporary¥classes com.example.sample.TestJaxWsImpl

hwsgenコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥fromwsdl¥WEB-INF¥wsdl¥ディレクトリにTestJaxWsService.wsdlとTestJaxWsService_schema1.xsdが生成されます。c:¥temp¥jaxws¥works¥fromwsdl¥temporary¥classes¥ディレクトリにあるクラスは削除してください。

生成されたTestJaxWsService.wsdlとTestJaxWsService_schema1.xsdは，一部修正する必要があります。

TestJaxWsService.wsdlの修正例を次に示します。イタリック体になっている個所が，修正した個所です。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<definitions targetNamespace="http://example.com/sample" name="TestJaxWsImplService" xmlns:tns="http://example.com/sample" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/">
  <types>
    <xsd:schema targetNamespace="http://example.com/sample">
      <xsd:include schemaLocation="TestJaxWsImplService_schema1.xsd"/>
    </xsd:schema>
  </types>
  <message name="jaxWsTest1">
    <part name="parameters" element="tns:jaxWsTest1"/>
  </message>
  <message name="jaxWsTest1Response">
    <part name="parameters" element="tns:jaxWsTest1Response"/>
  </message>
  <message name="UserDefinedFault">
    <part name="fault" element="tns:UserDefinedFault"/>
  </message>
  <portType name="TestJaxWs">
    <operation name="jaxWsTest1">
      <input message="tns:jaxWsTest1"/>
      <output message="tns:jaxWsTest1Response"/>
      <fault message="tns:UserDefinedFault" name="UserDefinedFault"/>
    </operation>
  </portType>
  <binding name="testJaxWsBinding" type="tns:TestJaxWs">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
    <operation name="jaxWsTest1">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
      <fault name="UserDefinedFault">
        <soap:fault name="UserDefinedFault" use="literal"/>
      </fault>
    </operation>
  </binding>
  <service name="TestJaxWsService">
    <port name="testJaxWs" binding="tns:testJaxWsBinding">
      <soap:address location="http://webhost:8085/fromwsdl/TestJaxWsService"/>
    </port>
  </service>
</definitions>

TestJaxWsService_schema1.xsdの修正例を次に示します。イタリック体になっている個所が，修正した個所です。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" targetNamespace="http://example.com/sample" xmlns:tns="http://example.com/sample" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="UserDefinedFault" type="tns:UserDefinedFault"/>

  <xs:element name="jaxWsTest1" type="tns:jaxWsTest1"/>

  <xs:element name="jaxWsTest1Response" type="tns:jaxWsTest1Response"/>

  <xs:complexType name="jaxWsTest1">
    <xs:sequence>
      <xs:element name="arg0" type="xs:string" minOccurs="0"/>
      <xs:element name="arg1" type="xs:int"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="jaxWsTest1Response">
    <xs:sequence>
      <xs:element name="return" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="UserDefinedFault">
    <xs:sequence>
      <xs:element name="message" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

修正したTestJaxWsService.wsdlは，名前をinput.wsdlに変更して，c:¥temp¥jaxws¥works¥fromwsdl¥server¥WEB-INF¥wsdl¥ディレクトリに保存してください。

4.3.2　SEIを生成する

cjwsimportコマンドを実行すると，SEIなど，Webサービスの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

cjwsimportコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥server¥
> mkdir src¥
> mkdir WEB-INF¥classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -generateService -s src -d WEB-INF¥classes WEB-INF¥wsdl¥input.wsdl

cjwsimportコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥fromwsdl¥server¥src¥com¥example¥sample¥ディレクトリに，Javaソースが生成されます。com¥example¥sample¥（パッケージに対応するディレクトリパス）は，名前空間URIの記述によって変わります。名前空間URIとパッケージとのマッピングについては，「15.1.1　名前空間からパッケージ名へのマッピング」を参照してください。

生成物の一覧を次の表に示します。

表4‒3　SEI生成時の生成物（WSDL起点）

ファイル名

説明

JaxWsTest1.java

WSDL定義の「要求メッセージのwrapper要素が参照する型」に対応するJavaBeanクラスです。

JaxWsTest1Response.java

WSDL定義の「応答メッセージのwrapper要素が参照する型」に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

TestJaxWs.java

TestJaxWsポートタイプに対応するSEIです。

TestJaxWsImpl.java

TestJaxWsポートタイプに対応するスケルトンクラスです。

UserDefinedFault.java

WSDL定義の「フォルトメッセージのwrapper要素が参照する型」に対応するJavaBeanクラス（フォルトbean）です。

UserDefinedException.java

フォルトbeanのラッパ例外クラスです。

ファイル名のJaxWsTest1，TestJaxWs，およびTestJaxWsImplは，オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名の記述によって変わります。オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名とJavaソースとのマッピングについては，「15.　WSDLからJavaへのマッピング」を参照してください。

4.3.3　Webサービス実装クラスを作成する

スケルトンクラスにWebサービスの処理を追加し，Webサービス実装クラスを作成します。ここでは，受け取った要求メッセージの内容を，日付情報とともに応答メッセージとして返す処理を追加します。

Webサービス実装クラスの作成例を次に示します。

package com.example.sample;

import java.util.Calendar;
import javax.jws.WebService;

@WebService(endpointInterface = "com.example.sample.TestJaxWs", targetNamespace = "http://example.com/sample", serviceName = "TestJaxWsService", portName = "testJaxWs")
public class TestJaxWsImpl {

    public String jaxWsTest1(String information, int count)
        throws UserDefinedException
    {
        Calendar today = Calendar.getInstance();
        StringBuffer result = new StringBuffer( 256 );
        result.append( "We've got your #" );
        result.append( new Integer( count ) );
        result.append( " message ¥"" );
        result.append( information );
        result.append( "¥"! It's " );
        result.append( String.format( "%04d.%02d.%02d %02d:%02d:%02d", new Object[]{
            new Integer( today.get( Calendar.YEAR ) ),
            new Integer( today.get( Calendar.MONTH ) + 1 ),
            new Integer( today.get( Calendar.DAY_OF_MONTH ) ),
            new Integer( today.get( Calendar.HOUR_OF_DAY ) ),
            new Integer( today.get( Calendar.MINUTE ) ),
            new Integer( today.get( Calendar.SECOND ) ) } ) );
        result.append( " now. See ya!" );

        return result.toString();
    }

}

イタリック体になっている個所が，スケルトンに対して追加した実装です。

4.3.4　Webサービス実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービス実装クラスをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥server¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;.¥WEB-INF¥classes" -d .¥WEB-INF¥classes src¥com¥example¥sample¥TestJaxWsImpl.java

javacコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥fromwsdl¥server¥WEB-INF¥classes¥com¥example¥sample¥ディレクトリのTestJaxWsImpl.classが上書きされます。

javacコマンドについては，JDKのドキュメントを参照してください。

4.3.5　web.xmlを作成する

WARファイルの構成要素として必要なweb.xmlを作成します。

web.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;fromwsdl&quot;</description>
  <display-name>Sample_web_service_fromwsdl</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/TestJaxWsService</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

作成したweb.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥fromwsdl¥server¥WEB-INF¥ディレクトリに保存します。web.xmlの設定項目については，「3.4　web.xmlの作成」を参照してください。

4.3.6　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。

application.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;fromwsdl&quot;</description>
  <display-name>Sample_application_fromwsdl</display-name>
  <module>
    <web>
      <web-uri>fromwsdl.war</web-uri>
      <context-root>fromwsdl</context-root>
    </web>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥fromwsdl¥server¥META-INF¥ディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

4.3.7　EARファイルを作成する

jarコマンドを使用して，EARファイルを作成します。

EARファイルの作成例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥server¥
> jar cvf fromwsdl.war .¥WEB-INF
> jar cvf fromwsdl.ear .¥fromwsdl.war .¥META-INF¥application.xml

jarコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥fromwsdl¥server¥ディレクトリにfromwsdl.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

4.4　デプロイと開始の例（WSDL起点）

ここでは，WSDLを起点とした場合のデプロイと開始の例を説明します。

4.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxwsserver -nameserver corbaname::testserver:900 -f fromwsdl.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

4.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxwsserver -nameserver corbaname::testserver:900 -name Sample_application_fromwsdl

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

4.5　Webサービスクライアントの開発例（WSDL起点）

ここでは，WSDLを起点とした場合のWebサービスクライアントの開発例を説明します。

4.5.1　サービスクラスを生成する

cjwsimportコマンドを実行すると，サービスクラスなどWebサービスクライアントの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

Webサービスの開発と同じ環境で，Webサービスクライアントを開発する場合の実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥client¥
> mkdir src/
> mkdir classes/
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes ..¥server¥WEB-INF¥wsdl¥input.wsdl

Webサービスの開発と異なる環境で，Webサービスクライアントを開発する場合の実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥client¥
> mkdir src/
> mkdir classes/
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes http://webhost:8085/fromwsdl/TestJaxWsService?wsdl

正常に終了すると，c:¥temp¥jaxws¥works¥fromwsdl¥client¥src¥com¥example¥sample¥ディレクトリにJavaソースが生成されます。com¥example¥sample¥（パッケージに対応するディレクトリパス）は，名前空間URIの記述によって変わります。名前空間URIとパッケージとのマッピングについては，「15.1.1　名前空間からパッケージ名へのマッピング」を参照してください。

生成物の一覧を次の表に示します。

表4‒4　サービスクラス生成時の生成物（WSDL起点）

ファイル名

説明

JaxWsTest1.java

WSDL定義の「要求メッセージのwrapper要素が参照する型」に対応するJavaBeanクラスです。

JaxWsTest1Response.java

WSDL定義の「応答メッセージのwrapper要素が参照する型」に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

TestJaxWs.java

TestJaxWsポートタイプに対応するSEIです。

TestJaxWsService.java

サービスクラスです。

UserDefinedFault.java

WSDL定義の「フォルトメッセージのwrapper要素が参照する型」に対応するJavaBeanクラスです。

UserDefinedException.java

フォルトbeanのラッパ例外クラスです。

ファイル名のJaxWsTest1，TestJaxWs，およびTestJaxWsServiceは，オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名の記述によって変わります。オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名とJavaソースとのマッピングについては，次の個所を参照してください。

「15.1.2　ポートタイプからSEI名へのマッピング」

「15.1.3　オペレーションからメソッド名へのマッピング」

「15.1.4　メッセージのパートからパラメタおよび戻り値へのマッピング（wrapperスタイルの場合）」

「15.1.5　メッセージのパートからパラメタおよび戻り値へのマッピング（non-wrapperスタイルの場合）」

4.5.2　Webサービスクライアントの実装クラスを作成する

Webサービスを利用するWebサービスクライアントの実装クラスを作成します。

Webサービスに対して1回の呼び出しをするWebサービスクライアントの実装クラスの作成例を次に示します。

package com.example.sample.client;

import com.example.sample.TestJaxWs;
import com.example.sample.TestJaxWsService;
import com.example.sample.UserDefinedException;

public class TestClient {
    public static void main( String[] args ) {
        try {
            TestJaxWsService service = new TestJaxWsService();
            TestJaxWs port = service.getTestJaxWs();

            String returnValue = port.jaxWsTest1( "Invocation test.", 1003 );

            System.out.println( "[RESULT] " + returnValue );
        }
        catch( UserDefinedException e ){
            e.printStackTrace();
        }
    }

}

作成したTestClient.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥fromwsdl¥client¥src¥com¥example¥sample¥client¥ディレクトリに保存します。com.example.sample，TestJaxWs，TestJaxWsService，TestJaxWs，およびjaxWsTest1は，生成されたJavaソースのパッケージ名，クラス名，およびクラス内のメソッド名によって変わります。異なる構成のWebサービスを開発する場合には，パッケージ名，クラス名，およびクラス内のメソッド名の記述を見直す必要があります。

4.5.3　Webサービスクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービスクライアントをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥com¥example¥sample¥client¥TestClient.java

javacコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥fromwsdl¥client¥classes¥com¥example¥sample¥client¥ディレクトリに，TestClient.classが生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

4.6　Webサービスの実行例（WSDL起点）

ここでは，WSDLを起点とした場合のWebサービスクライアントの実行例を説明します。

4.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxws¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>
add.jvm.arg=-Dejbserver.server.prf.PRFID=<PRF ID>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。

作成したJavaアプリケーション用オプション定義ファイルは，UTF-8形式でc:¥temp¥jaxws¥works¥fromwsdl¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

4.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxws¥works¥fromwsdl¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

4.6.3　Webサービスクライアントを実行する

cjclstartapコマンドを使用して，Webサービスクライアントを実行します。

Webサービスクライアントの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  com.example.sample.client.TestClient

cjclstartapコマンドが正常に終了すると，Webサービスクライアントの実行結果が表示されます。実行結果の表示例を次に示します。

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxws¥works¥fromwsdl¥client, PID = 2636)
--------------------
[RESULT] We've got your #1003 message "Invocation test."! It's 2007.11.28 14:50:50 now. See ya!
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

5　SEIを起点とした開発の例

この章では，SEIを起点としたWebサービスを開発する場合の例を説明します。

5.1　開発例の構成（SEI起点）

この章で説明する開発例では，SEIを起点としたWebサービスを開発します。

開発するWebサービスの構成を次の表に示します。

表5‒1　Webサービスの構成（SEI起点）

項番

項目

値

1

デプロイするJ2EEサーバの名称

jaxwsserver

2

Webサーバのホスト名とポート番号

webhost:8085

3

ネーミングサーバのURL

corbaname::testserver:900

4

コンテキストルート

fromjava_dynamic_generate

5

スタイル

document/literal/wrapped

6

名前空間URI

http://sample.com

7

ポートタイプ

個数

1

8

ローカル名

AddNumbersImpl

9

オペレーション

個数

1

10

ローカル名

add

11

サービス

個数

1

12

ローカル名

AddNumbersImplService

13

ポート

個数

1

14

ローカル名

AddNumbersImplPort

15

Webサービス実装クラス

com.sample.AddNumbersImpl

16

Webサービス実装クラスで公開するメソッド

個数

1

17

メソッド名

add

18

Webサービス実装内のメソッドでスローする例外

個数

1

19

クラス名

com.sample.AddNumbersFault

Webサービス開発時のカレントディレクトリの構成を次の表に示します。

表5‒2　カレントディレクトリの構成（SEI起点）

ディレクトリ

説明

c:¥temp¥jaxws¥works¥fromjava

カレントディレクトリです。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

server¥

Webサービスの開発で使用します。

┣

┃

┃

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

┗

application.xml

「5.3.4　application.xmlを作成する」で作成します。

┣

┃

┃

┃

src¥

Webサービスのソースファイル（*.java）を格納します。「5.3.1　Webサービス実装クラスを作成する」および「5.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

┃

┃

┃

┃

┃

┃

WEB-INF¥

WARファイルのWEB-INFディレクトリに対応します。

┣

web.xml

「5.3.3　web.xmlを作成する」で作成します。

┣

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「5.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┗

wsdl¥

「5.3.5　WSDLファイルを作成する（任意）」で作成します。

┣

┃

fromjava_dynamic_generate.ear

「5.3.6　EARファイルを作成する」で作成します。

┗

fromjava_dynamic_generate.war

┗

client¥

Webサービスクライアントの開発で使用します。

┣

┃

┃

┃

┃

src¥

Webサービスクライアントのソースファイル（*.java）を格納します。「5.5.1　サービスクラスを生成する」および「5.5.2　Webサービスクライアントの実装クラスを作成する」で使用します。

┣

┃

┃

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「5.5.3　Webサービスクライアントの実装クラスをコンパイルする」で使用します。

┣

┃

┃

usrconf.cfg

「5.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

┗

usrconf.properties

「5.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebサービスとWebサービスクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

5.2　開発例の流れ（SEI起点）

この章で説明する開発例では，次の流れで開発および実行します。

Webサービスの開発

Webサービス実装クラスを作成する（5.3.1）

Webサービス実装クラスをコンパイルする（5.3.2）

web.xmlを作成する（5.3.3）

application.xmlを作成する（5.3.4）

WSDLファイルを作成する（任意）（5.3.5）

EARファイルを作成する（5.3.6）

デプロイと開始

EARファイルをデプロイする（5.4.1）

Webサービスを開始する（5.4.2）

Webサービスクライアントの開発

cjwsimportコマンドを実行し，サービスクラスを生成する（5.5.1）

Webサービスクライアントの実装クラスを作成する（5.5.2）

Webサービスクライアントの実装クラスをコンパイルする（5.5.3）

Webサービスの実行

Javaアプリケーション用オプション定義ファイルを作成する（5.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（5.6.2）

Webサービスクライアントを実行する（5.6.3）

5.3　Webサービスの開発例（SEI起点）

ここでは，SEIを起点とした場合のWebサービスの開発例を説明します。

5.3.1　Webサービス実装クラスを作成する

Webサービスの処理を記述したWebサービス実装クラスを新規に作成します。

ここでは，受け取った要求メッセージの内容を計算して，応答メッセージを返すWebサービス実装クラスを作成します。

SOAP 1.1の場合のWebサービス実装クラスの作成例を次に示します。作成したAddNumbersImpl.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥fromjava¥server¥src¥com¥sample¥ディレクトリに保存してください。

package com.sample;

@javax.jws.WebService
public class AddNumbersImpl{

    public int add( int number1, int number2 ) throws AddNumbersFault{

        if( ( number1 < 0 ) || ( number2 < 0 ) ){
            throw new AddNumbersFault( "Negative number cannot be added!",
                "Numbers: " + number1 + ", " + number2 );
        }
        return number1 + number2;
    }

}

また，com.sample.AddNumbersImplでスローしている例外クラスcom.sample.AddNumbersFaultを作成します。通常，例外クラスの作成は任意ですが，ここでは例外クラスを作成します。

例外クラスの作成例を次に示します。作成したAddNumbersFault.javaは，UTF-8形式で，c:¥temp¥jaxws¥works¥fromjava¥server¥src¥com¥sample¥ディレクトリに保存してください。

package com.sample;

public class AddNumbersFault extends Exception {

    String detail;

    public AddNumbersFault( String message, String detail ){
        super( message );
        this.detail = detail;
    }

    public String getDetail(){
        return detail;
    }
}

SOAP 1.2の場合のWebサービス実装クラスの作成例を次に示します。

package com.sample;

@javax.jws.WebService
@javax.xml.ws.BindingType(javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING)
public class AddNumbersImpl{

    public int add( int number1, int number2 ) throws AddNumbersFault{

        if( ( number1 < 0 ) || ( number2 < 0 ) ){
            throw new AddNumbersFault( "Negative number cannot be added!",
                "Numbers: " + number1 + ", " + number2 );
        }
        return number1 + number2;
    }

}

5.3.2　Webサービス実装クラスをコンパイルする

javacコマンドを実行して，Webサービス実装クラスをコンパイルします。javacコマンドについては，JDKのドキュメントを参照してください。

javacコマンドの実行例を次に示します。添付ファイル機能を使用したJavaプログラムをjavacコマンドでコンパイルする場合，javacコマンドの引数に"--add-modules=java.activation"を指定してください。

> cd c:¥temp¥jaxws¥works¥fromjava¥server¥
> mkdir .¥WEB-INF¥classes¥
> javac -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxp.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmstax.jar" -d WEB-INF¥classes¥ -s src src¥com¥sample¥AddNumbersImpl.java src¥com¥sample¥AddNumbersFault.java

javacコマンドが正常に終了すると，コンパイルしたクラスが，c:¥temp¥jaxws¥works¥fromjava¥server¥WEB-INF¥classes¥com¥sample¥ディレクトリに出力されます。なお，コンパイルしたWebサービス実装クラスに対してhwsgenコマンドを実行すると，事前にエラーチェックができます。hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を，エラーチェックについては，「10.23.1　hwsgenコマンドによるエラーチェックについて」を参照してください。

5.3.3　web.xmlを作成する

WARファイルの構成要素として必要なweb.xmlを作成します。

web.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;fromjava_dynamic_generate&quot;</description>
  <display-name>Sample_web_service_fromjava_dynamic_generate</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/AddNumbersImplService</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

作成したweb.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥fromjava¥server¥WEB-INF¥ディレクトリに保存します。web.xmlの設定項目については，「3.4　web.xmlの作成」を参照してください。

5.3.4　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。

application.xmlの作成例を次に示します。なお，Webサービスとしてapplication.xmlに設定する項目はありません。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;fromjava_dynamic_generate&quot;</description>
  <display-name>Sample_application_fromjava_dynamic_generate</display-name>
  <module>
    <web>
      <web-uri>fromjava_dynamic_generate.war</web-uri>
      <context-root>fromjava_dynamic_generate</context-root>
    </web>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥fromjava¥server¥META-INF¥ディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

5.3.5　WSDLファイルを作成する（任意）

SEI起点の開発ではWSDLファイルの作成は任意ですが，作成した場合はEARファイルに含めます。ここでは，hwsgenコマンドのWSDL生成機能を実行することで，コンパイル済みのJavaソースからWSDLファイルを作成する例を説明します。hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を参照してください。

hwsgenコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromwsdl¥server¥
> mkdir .¥WEB-INF¥wsdl¥
> mkdir .¥temporary
> "%COSMINEXUS_HOME%¥jaxws¥bin¥hwsgen.bat" -r .¥WEB-INF¥wsdl -d .¥temporary -cp .¥WEB-INF¥classes com.sample.AddNumbersImpl
> rmdir /S /Q .¥temporary

hwsgenコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥fromjava¥WEB-INF¥wsdlディレクトリに，リソースファイルが生成されます。生成物の一覧を次の表に示します。

表5‒3　hwsgenコマンド実行時の生成物

ファイル名

説明

AddNumbersImplService.wsdl

指定したJavaソースに対応するWSDLファイルです。

AddNumbersImplService_schema1.xsd

WSDLファイルから参照されるXML Schema定義です。

なお，c:¥temp¥jaxws¥works¥fromjava¥temporaryディレクトリに生成されるファイルは必要ないため削除してください。

5.3.6　EARファイルを作成する

jarコマンドを使用して，これまでに作成したファイルを含めたEARファイルを作成します。

EARファイルの作成例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromjava¥server¥
> jar cvf fromjava_dynamic_generate.war .¥WEB-INF
> jar cvf fromjava_dynamic_generate.ear .¥fromjava_dynamic_generate.war .¥META-INF¥application.xml

jarコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥fromjava¥server¥ディレクトリにfromjava_dynamic_generate.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

5.4　デプロイと開始の例（SEI起点）

ここでは，SEIを起点とした場合のデプロイと開始の例を説明します。

5.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromjava¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxwsserver -nameserver corbaname::testserver:900 -f fromjava_dynamic_generate.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

5.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromjava¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxwsserver -nameserver corbaname::testserver:900 -name Sample_application_fromjava_dynamic_generate

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

5.5　Webサービスクライアントの開発例（SEI起点）

ここでは，SEIを起点とした場合のWebサービスクライアントの開発例を説明します。

5.5.1　サービスクラスを生成する

cjwsimportコマンドを実行すると，サービスクラスなど，Webサービスクライアントの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

cjwsimportコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromjava¥client¥
> mkdir src¥
> mkdir classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes http://webhost:8085/fromjava_dynamic_generate/AddNumbersImplService?wsdl

cjwsimportコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥fromjava¥client¥src¥com¥sample¥ディレクトリに，Javaソースが生成されます。なお，com¥sample¥（パッケージに対応するディレクトリパス）は，名前空間URIの記述によって変わります。名前空間URIとパッケージとのマッピングについては，「15.1.1　名前空間からパッケージ名へのマッピング」を参照してください。

生成物の一覧を次の表に示します。

表5‒4　サービスクラス生成時の生成物（SEI起点）

ファイル名

説明

Add.java

WSDL定義の「オペレーション」の要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

AddResponse.java

WSDL定義の「オペレーション」の応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

AddNumbersImpl.java

WSDL定義の「サービス」に対応するSEIです。

AddNumbersImplService.java

サービスクラスです。

AddNumbersFault.java

AddNumbersFaultに対応するJavaBeanクラスです。

AddNumbersFault_Exception.java

フォルトbeanのラッパ例外クラスです。

ファイル名のAdd，AddNumbersImpl，およびAddNumbersImplServiceは，オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名の記述によって変わります。オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名のマッピングについては，次の個所を参照してください。

「15.1.2　ポートタイプからSEI名へのマッピング」

「15.1.3　オペレーションからメソッド名へのマッピング」

「15.1.4　メッセージのパートからパラメタおよび戻り値へのマッピング（wrapperスタイルの場合）」

「15.1.5　メッセージのパートからパラメタおよび戻り値へのマッピング（non-wrapperスタイルの場合）」

5.5.2　Webサービスクライアントの実装クラスを作成する

Webサービスを利用するWebサービスクライアントの実装クラスを作成します。

Webサービスに対して1回の呼び出しをするWebサービスクライアントの作成例を次に示します。

package com.sample.client;

import com.sample.AddNumbersImpl;
import com.sample.AddNumbersImplService;
import com.sample.AddNumbersFault_Exception;

public class TestClient {
    public static void main( String[] args ) {
        try {
            AddNumbersImplService service = new AddNumbersImplService();
            AddNumbersImpl port = service.getAddNumbersImplPort();

            int returnValue = port.add( 205, 103 );

            System.out.println( "[RESULT] " + returnValue );
        }
        catch( AddNumbersFault_Exception e ){
            e.printStackTrace();
        }
    }

}

作成したTestClient.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥fromjava¥client¥src¥com¥sample¥client¥ディレクトリに保存します。

なお，com.sample，AddNumbersImpl，AddNumbersImplService，AddNumbersImplPort，およびaddは，生成されたJavaソースのパッケージ名，クラス名，およびクラス内のメソッド名によって変わります。異なる構成のWebサービスを開発する場合には，パッケージ名，クラス名，およびクラス内のメソッド名の記述を見直す必要があります。

5.5.3　Webサービスクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービスクライアントをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromjava¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥com¥sample¥client¥TestClient.java

javacコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥fromjava¥client¥classes¥com¥sample¥client¥ディレクトリに，TestClient.classが生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

5.6　Webサービスの実行例（SEI起点）

ここでは，SEIを起点とした場合のWebサービスクライアントの実行例を説明します。

5.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxws¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>
add.jvm.arg=-Dejbserver.server.prf.PRFID=<PRF ID>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。

作成したJavaアプリケーション用オプション定義ファイルは，c:¥temp¥jaxws¥works¥fromjava¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

5.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxws¥works¥fromjava¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

5.6.3　Webサービスクライアントを実行する

cjclstartapコマンドを使用して，Webサービスクライアントを実行します。

Webサービスクライアントの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromjava¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  com.sample.client.TestClient

cjclstartapコマンドが正常に終了すると，Webサービスクライアントの実行結果が表示されます。実行結果の表示例を次に示します。

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxws¥works¥fromjava¥client, PID = 2636)
[RESULT] 308
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

6　SEIを起点とした開発の例（hwsgenコマンドを使用する場合）

この章では，SEIを起点としてhwsgenコマンドを使用してWebサービスを開発する場合の例を説明します。

6.1　開発例の構成（SEI起点・hwsgenコマンド）

この章で説明する開発例では，Application Serverが提供するhwsgenコマンドを使用して，SEIを起点としたWebサービスを開発します。hwsgenコマンドの使用方法については，「14.1.2　hwsgenコマンド」を参照してください。

開発するWebサービスの構成を次の表に示します。

表6‒1　Webサービスの構成（SEI起点・hwsgenコマンド）

項番

項目

値

1

デプロイするJ2EEサーバの名称

jaxwsserver

2

Webサーバのホスト名とポート番号

webhost:8085

3

ネーミングサーバのURL

corbaname::testserver:900

4

コンテキストルート

wsgen

5

スタイル

document/literal/wrapped

6

名前空間URI

http://sample.com

7

ポートタイプ

個数

1

8

ローカル名

AddNumbersImpl

9

オペレーション

個数

1

10

ローカル名

add

11

サービス

個数

1

12

ローカル名

AddNumbersImplService

13

ポート

個数

1

14

ローカル名

AddNumbersImplPort

15

Webサービス実装クラス

com.sample.AddNumbersImpl

16

Webサービス実装クラスで公開するメソッド

個数

1

17

メソッド名

add

18

Webサービス実装内のメソッドでスローする例外

個数

1

19

クラス名

com.sample.AddNumbersFault

Webサービス開発時のカレントディレクトリの構成を次の表に示します。

表6‒2　カレントディレクトリの構成（SEI起点・hwsgenコマンド）

ディレクトリ

説明

c:¥temp¥jaxws¥works¥wsgen

カレントディレクトリです。

├

│

│

│

│

│

│

│

│

│

│

│

│

│

│

│

│

server¥

Webサービスの開発で使用します。

├

│

│

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

└

application.xml

「6.3.4　application.xmlを作成する」で作成します。

├

│

│

│

│

│

│

WEB-INF¥

WARファイルのWEB-INFディレクトリに対応します。

├

web.xml

「6.3.3　web.xmlを作成する」で作成します。

├

│

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「6.3.2　Javaソースを生成する」で使用します。

└

wsdl¥

「6.3.2　Javaソースを生成する」で作成します。

├

wsgen.ear

「6.3.5　EARファイルを作成する」で作成します。

└

wsgen.war

└

client¥

Webサービスクライアントの開発で使用します。

├

│

│

│

│

src¥

Webサービスクライアントのソースファイル（*.java）を格納します。「6.5.1　サービスクラスを生成する」および「6.5.2　Webサービスクライアントの実装クラスを作成する」で使用します。

├

│

│

│

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「6.5.3　Webサービスクライアントの実装クラスをコンパイルする」で使用します。

├

│

│

usrconf.cfg

「6.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

└

usrconf.properties

「6.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

カレントディレクトリのパスは，開発する環境に合わせて変更してください。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebサービスとWebサービスクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

6.2　開発例の流れ（SEI起点・hwsgenコマンド）

この章で説明する開発例では，次の流れで開発および実行します。

Webサービスの開発

コンパイル済みのクラスファイルを保存する（6.3.1）

hwsgenコマンドを実行して追加のJavaコードを生成し，任意でWSDLも生成する（6.3.2）

web.xmlを作成する（6.3.3）

application.xmlを作成する（6.3.4）

EARファイルを作成する（6.3.5）

デプロイと開始

EARファイルをデプロイする（6.4.1）

Webサービスを開始する（6.4.2）

Webサービスクライアントの開発

cjwsimportコマンドを実行し，サービスクラスを生成する（6.5.1）

Webサービスクライアントの実装クラスを作成する（6.5.2）

Webサービスクライアントの実装クラスをコンパイルする（6.5.3）

Webサービスの実行

Javaアプリケーション用オプション定義ファイルを作成する（6.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（6.6.2）

Webサービスクライアントを実行する（6.6.3）

6.3　Webサービスの開発例（SEI起点・hwsgenコマンド）

ここでは，SEIを起点とし，hwsgenコマンドを使用する場合のWebサービスの開発例を説明します。

6.3.1　コンパイル済みのクラスファイルを保存する

コンパイル済みのWebサービス実装クラスAddNumbersImpl.classをc:¥temp¥jaxws¥works¥wsgen¥server¥WEB-INF¥classes¥com¥sample¥ディレクトリに保存します。また，コンパイル済みの例外クラスAddNumbersFault.classは，c:¥temp¥jaxws¥works¥wsgen¥server¥WEB-INF¥classes¥com¥sample¥ディレクトリに保存してください。

6.3.2　Javaソースを生成する

hwsgenコマンドを実行して，Webサービスの開発に必要なJavaコードを追加し，任意でWebサービスのメタ情報を示すリソースファイル（WSDLおよびXML Schema定義）を生成します。

リソースファイルも生成する場合のhwsgenコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsgen¥server¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥hwsgen.bat" -r WEB-INF¥wsdl -d WEB-INF¥classes -cp WEB-INF¥classes com.sample.AddNumbersImpl

hwsgenコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥wsgen¥server¥WEB-INF¥classes¥com¥sample¥ディレクトリに，Javaソースが生成されます。なお，com¥sample¥（パッケージに対応するディレクトリパス）は，名前空間URIの記述によって変わります。名前空間URIとパッケージとのマッピングについては，「15.1.1　名前空間からパッケージ名へのマッピング」を参照してください。

生成物の一覧を次の表に示します。

表6‒3　Javaソース生成時の生成物（SEI起点・hwsgenコマンド）

ファイル名

説明

Add.java

WSDL定義の「オペレーション」の要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

AddResponse.java

WSDL定義の「オペレーション」の応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

AddNumbersFaultBean.java

例外クラスのAddNumbersFaultに対応するJavaBeanクラスです。

ファイル名のAddおよびAddNumbersFaultは，Webサービス実装クラスで公開するメソッド名，ポートタイプのローカル名，およびWebサービス実装クラスでスローする例外のクラス名の記述によって変わります。オペレーションのローカル名のマッピングについては，「15.1.3　オペレーションからメソッド名へのマッピング」を参照してください。

なお，リソースファイルはc:¥temp¥jaxws¥works¥wsgen¥WEB-INF¥wsdl¥ディレクトリに生成されます。

6.3.3　web.xmlを作成する

WARファイルの構成要素として必要なweb.xmlを作成します。

web.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;wsgen &quot;</description>
  <display-name>Sample_web_service_wsgen</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/AddNumbersImplService</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

作成したweb.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥wsgen¥server¥WEB-INF¥ディレクトリに保存します。web.xmlの設定項目については，「3.4　web.xmlの作成」を参照してください。

6.3.4　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。

application.xmlの作成例を次に示します。なお，Webサービスとしてapplication.xmlに設定する項目はありません。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;wsgen&quot;</description>
  <display-name>Sample_application_wsgen</display-name>
  <module>
    <web>
      <web-uri>wsgen.war</web-uri>
      <context-root>wsgen</context-root>
    </web>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥ wsgen¥server¥META-INF¥ディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

6.3.5　EARファイルを作成する

jarコマンドを使用して，これまでに作成したファイルを含めたEARファイルを作成します。

EARファイルの作成例を次に示します。

> cd c:¥temp¥jaxws¥works¥fromjava¥server¥
> jar cvf wsgen.war .¥WEB-INF
> jar cvf wsgen.ear .¥wsgen.war .¥META-INF¥application.xml

jarコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥wsgen¥server¥ディレクトリにwsgen.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

6.4　デプロイと開始の例（SEI起点・hwsgenコマンド）

ここでは，SEIを起点としてhwsgenコマンドを使用した場合のデプロイと開始の例を説明します。

6.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsgen¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxwsserver -nameserver corbaname::testserver:900 -f fromjava.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

6.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsgen¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxwsserver -nameserver corbaname::testserver:900 -name Sample_application_fromjava

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

6.5　Webサービスクライアントの開発例（SEI起点・hwsgenコマンド）

ここでは，SEIを起点とし，hwsgenコマンドを使用した場合のWebサービスクライアントの開発例を説明します。

6.5.1　サービスクラスを生成する

cjwsimportコマンドを実行すると，サービスクラスなど，Webサービスクライアントの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

cjwsimportコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsgen¥client¥
> mkdir src¥
> mkdir classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes http://webhost:8085/wsgen/AddNumbersImplService?wsdl

cjwsimportコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥wsgen¥client¥src¥com¥sample¥ディレクトリに，Javaソースが生成されます。なお，com¥sample¥（パッケージに対応するディレクトリパス）は，名前空間URIの記述によって変わります。名前空間URIとパッケージとのマッピングについては，「15.1.1　名前空間からパッケージ名へのマッピング」を参照してください。

生成物の一覧を次の表に示します。

表6‒4　サービスクラス生成時の生成物（SEI起点・hwsgenコマンド）

ファイル名

説明

Add.java

WSDL定義の「オペレーション」の要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

AddResponse.java

WSDL定義の「オペレーション」の応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

AddNumbersImpl.java

WSDL定義の「サービス」に対応するSEIです。

AddNumbersImplService.java

サービスクラスです。

AddNumbersFault.java

AddNumbersFaultに対応するJavaBeanクラスです。

AddNumbersFault_Exception.java

フォルトbeanのラッパ例外クラスです。

ファイル名のAdd，AddNumbersImpl，およびAddNumbersImplServiceは，オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名の記述によって変わります。オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名のマッピングについては，次の個所を参照してください。

「15.1.2　ポートタイプからSEI名へのマッピング」

「15.1.3　オペレーションからメソッド名へのマッピング」

「15.1.4　メッセージのパートからパラメタおよび戻り値へのマッピング（wrapperスタイルの場合）」

「15.1.5　メッセージのパートからパラメタおよび戻り値へのマッピング（non-wrapperスタイルの場合）」

6.5.2　Webサービスクライアントの実装クラスを作成する

Webサービスを利用するWebサービスクライアントの実装クラスを作成します。

Webサービスに対して1回の呼び出しをするWebサービスクライアントの作成例を次に示します。

package com.sample.client;

import com.sample.AddNumbersImpl;
import com.sample.AddNumbersImplService;
import com.sample.AddNumbersFault_Exception;

public class TestClient {
    public static void main( String[] args ) {
        try {
            AddNumbersImplService service = new AddNumbersImplService();
            AddNumbersImpl port = service.getAddNumbersImplPort();

            int returnValue = port.add( 205, 103 );

            System.out.println( "[RESULT] " + returnValue );
        }
        catch( AddNumbersFault_Exception e ){
            e.printStackTrace();
        }
    }

}

作成したTestClient.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥wsgen¥client¥src¥com¥sample¥client¥ディレクトリに保存します。

なお，com.sample，AddNumbersImpl，AddNumbersImplService，AddNumbersImplPort，およびaddは，生成されたJavaソースのパッケージ名，クラス名，およびクラス内のメソッド名によって変わります。異なる構成のWebサービスを開発する場合には，パッケージ名，クラス名，およびクラス内のメソッド名の記述を見直す必要があります。

6.5.3　Webサービスクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービスクライアントをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsgen¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥client¥lib¥j2ee-javax.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥com¥sample¥client¥TestClient.java

javacコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥wsgen¥client¥classes¥com¥sample¥client¥ディレクトリに，TestClient.classが生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

6.6　Webサービスの実行例（SEI起点・hwsgenコマンド）

ここでは，SEIを起点とし，hwsgenコマンドを使用した場合のWebサービスクライアントの実行例を説明します。

6.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxws¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>
add.jvm.arg=-Dejbserver.server.prf.PRFID=<PRF ID>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。

作成したJavaアプリケーション用オプション定義ファイルは，c:¥temp¥jaxws¥works¥fromjava¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

6.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxws¥works¥wsgen¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

6.6.3　Webサービスクライアントを実行する

cjclstartapコマンドを使用して，Webサービスクライアントを実行します。

Webサービスクライアントの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsgen¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  com.sample.client.TestClient

cjclstartapコマンドが正常に終了すると，Webサービスクライアントの実行結果が表示されます。実行結果の表示例を次に示します。

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxws¥works¥wsgen¥client, PID = 2636)
[RESULT] 308
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

7　SEIを起点とした開発の例（カスタマイズする場合）

この章では，SEIを起点としたWebサービスをカスタマイズする場合の例を説明します。

7.1　開発例の構成（SEI起点・カスタマイズ）

この章で説明する開発例では，SEIを起点としたWebサービスを開発します。開発するWebサービスは，アノテーションを使用してカスタマイズします。

開発するWebサービスの構成を次の表に示します。

表7‒1　Webサービスの構成（SEI起点・カスタマイズ）

項番

項目

値

1

デプロイするJ2EEサーバの名称

jaxwsserver

2

Webサーバのホスト名とポート番号

webhost:8085

3

ネーミングサーバのURL

corbaname::testserver:900

4

コンテキストルート

annotations_dynamic_generate

5

スタイル

document/literal/wrapped

6

名前空間URI

http://example.org/sample

7

ポートタイプ

個数

1

8

ローカル名

TestJaxWs

9

オペレーション

個数

1

10

ローカル名

jaxWsTest1

11

サービス

個数

1

12

ローカル名

TestJaxWsService

13

ポート

個数

1

14

ローカル名

testJaxWs

15

Webサービス実装クラス

com.sample.AddNumbersImpl

16

Webサービス実装クラスで公開するメソッド

個数

1

17

ローカル名

add

18

Webサービス実装内のメソッドでスローする例外

個数

1

19

ローカル名

com.sample.AddNumbersFault

Webサービス開発時のカレントディレクトリの構成を次の表に示します。

表7‒2　カレントディレクトリの構成（SEI起点・カスタマイズ）

ディレクトリ

説明

c:¥temp¥jaxws¥works¥annotations

カレントディレクトリです。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

server¥

Webサービスの開発で使用します。

┣

┃

┃

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

┗

application.xml

「7.3.4　application.xmlを作成する」で作成します。

┣

┃

┃

┃

src¥

Webサービスのソースファイル（*.java）を格納します。「7.3.1　Webサービス実装クラスを作成する」および「7.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

┃

┃

┃

┃

┃

WEB-INF¥

WARファイルのWEB-INFディレクトリに対応します。

┣

web.xml

「7.3.3　web.xmlを作成する」で作成します。

┗

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「7.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

annotations_dynamic_generate.ear

「7.3.5　EARファイルを作成する」で作成します。

┗

annotations_dynamic_generate.war

┗

client¥

Webサービスクライアントの開発で使用します。

┣

┃

┃

┃

┃

src¥

Webサービスクライアントのソースファイル（*.java）を格納します。「7.5.1　サービスクラスを生成する」および「7.5.2　Webサービスクライアントの実装クラスを作成する」で使用します。

┣

┃

┃

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「7.5.3　Webサービスクライアントの実装クラスをコンパイルする」で使用します。

┣

┃

┃

usrconf.cfg

「7.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

┗

usrconf.properties

「7.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

カレントディレクトリのパスは，開発する環境に合わせて変更してください。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebサービスとWebサービスクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

7.2　開発例の流れ（SEI起点・カスタマイズ）

この章で説明する開発例では，次の流れでカスタマイズおよび実行します。

Webサービスの開発

Webサービス実装クラスを作成する（7.3.1）

Webサービス実装クラスをコンパイルする（7.3.2）

web.xmlを作成する（7.3.3）

application.xmlを作成する（7.3.4）

EARファイルを作成する（7.3.5）

デプロイと開始

EARファイルをデプロイする（7.4.1）

Webサービスを開始する（7.4.2）

Webサービスクライアントの開発

cjwsimportコマンドを実行し，サービスクラスを生成する（7.5.1）

Webサービスクライアントの実装クラスを作成する（7.5.2）

Webサービスクライアントの実装クラスをコンパイルする（7.5.3）

Webサービスの実行

Javaアプリケーション用オプション定義ファイルを作成する（7.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（7.6.2）

Webサービスクライアントを実行する（7.6.3）

7.3　Webサービスの開発例（SEI起点・カスタマイズ）

ここでは，SEIを起点とした場合のWebサービス（カスタマイズあり）の開発例を説明します。

7.3.1　Webサービス実装クラスを作成する

Webサービスの処理を記述したWebサービス実装クラスを作成します。ここでは，受け取った要求メッセージの内容を計算して，応答メッセージを返すWebサービス実装クラスを作成します。

SOAP 1.1の場合のWebサービス実装クラスの作成例を次に示します。作成したAddNumbersImpl.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥annotations¥server¥src¥com¥sample¥ディレクトリに保存します。

package com.sample;

@javax.jws.WebService(name = "TestJaxWs",
    targetNamespace = "http://example.org/sample",
    serviceName = "TestJaxWsService", portName = "testJaxWs")
@javax.xml.ws.BindingType(javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_BINDING)
@javax.jws.soap.SOAPBinding(style = javax.jws.soap.SOAPBinding.Style.DOCUMENT, use = javax.jws.soap.SOAPBinding.Use.LITERAL)
public class AddNumbersImpl{

    @javax.jws.WebMethod(operationName = "jaxWsTest1")
    @javax.jws.WebResult(name = "return")
    public int add( @javax.jws.WebParam(name="num1")int number1, @javax.jws.WebParam(name="num2")int number2 ) throws AddNumbersFault{

        if( ( number1 < 0 ) || ( number2 < 0 ) ){
            throw new AddNumbersFault( "Negative number cannot be added!",
                "Numbers: " + number1 + ", " + number2 );
        }
        return number1 + number2;
    }

}

また，com.sample.AddNumbersImplでスローしている例外クラスcom.sample.AddNumbersFaultを作成します。通常，例外クラスの作成は任意ですが，ここでは例外クラスを作成します。

例外クラスの作成例を次に示します。作成したAddNumbersFault.javaは，UTF-8形式で，c:¥temp¥jaxws¥works¥annotations¥server¥src¥com¥sample¥ディレクトリに保存します。

package com.sample;

public class AddNumbersFault extends Exception {

    String detail;

    public AddNumbersFault( String message, String detail ){
        super( message );
        this.detail = detail;
    }

    public String getDetail(){
        return detail;
    }
}

SOAP 1.2の場合のWebサービス実装クラスの作成例を次に示します。

package com.sample;

@javax.jws.WebService(name = "TestJaxWs",
    targetNamespace = "http://example.org/sample",
    serviceName = "TestJaxWsService", portName = "testJaxWs")
@javax.xml.ws.BindingType(javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING)
@javax.jws.soap.SOAPBinding(style = javax.jws.soap.SOAPBinding.Style.DOCUMENT, use = javax.jws.soap.SOAPBinding.Use.LITERAL)
public class AddNumbersImpl{

    @javax.jws.WebMethod(operationName = "jaxWsTest1")
    @javax.jws.WebResult(name = "return")
    public int add( @javax.jws.WebParam(name="num1")int number1, @javax.jws.WebParam(name="num2")int number2 ) throws AddNumbersFault{

        if( ( number1 < 0 ) || ( number2 < 0 ) ){
            throw new AddNumbersFault( "Negative number cannot be added!",
                "Numbers: " + number1 + ", " + number2 );
        }
        return number1 + number2;
    }

}

7.3.2　Webサービス実装クラスをコンパイルする

javacコマンドを実行して，Webサービス実装クラスをコンパイルします。javacコマンドについては，JDKのドキュメントを参照してください。

javacコマンドの実行例を次に示します。添付ファイル機能を使用したJavaプログラムをjavacコマンドでコンパイルする場合，javacコマンドの引数に"--add-modules=java.activation"を指定してください。

> cd c:¥temp¥jaxws¥works¥annotations¥server¥
> mkdir .¥WEB-INF¥classes¥
> javac -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxp.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmstax.jar" -d WEB-INF¥classes¥ -s src src¥com¥sample¥AddNumbersImpl.java src¥com¥sample¥AddNumbersFault.java

javacコマンドが正常に終了すると，コンパイルしたクラスが，c:¥temp¥jaxws¥works¥annotations¥server¥WEB-INF¥classes¥com¥sample¥ディレクトリに出力されます。なお，コンパイルしたWebサービス実装クラスに対してhwsgenコマンドを実行すると，事前にエラーチェックができます。hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を，エラーチェックについては，「10.23.1　hwsgenコマンドによるエラーチェックについて」を参照してください。

7.3.3　web.xmlを作成する

WARファイルの構成要素として必要なweb.xmlを作成します。

web.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;annotations_dynamic_generate&quot;</description>
  <display-name>Sample_web_service_annotations_dynamic_generate</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/TestJaxWsService</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

作成したweb.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥annotations¥server¥WEB-INF¥ディレクトリに保存します。web.xmlの設定項目については，「3.4　web.xmlの作成」を参照してください。

7.3.4　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。

application.xmlの作成例を次に示します。なお，Webサービスとしてapplication.xmlに設定する項目はありません。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;annotations_dynamic_generate&quot;</description>
  <display-name>Sample_application_annotations_dynamic_generate</display-name>
  <module>
    <web>
      <web-uri>annotations_dynamic_generate.war</web-uri>
      <context-root>annotations_dynamic_generate</context-root>
    </web>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥annotations¥server¥META-INF¥ディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

7.3.5　EARファイルを作成する

jarコマンドを使用して，これまでに作成したファイルを含めたEARファイルを作成します。

> cd c:¥temp¥jaxws¥works¥annotations¥server¥
> jar cvf annotations_dynamic_generate.war .¥WEB-INF
> jar cvf annotations_dynamic_generate.ear .¥annotations_dynamic_generate.war .¥META-INF¥application.xml

jarコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥annotations¥server¥ディレクトリにannotations_dynamic_generate.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

7.4　デプロイと開始の例（SEI起点・カスタマイズ）

ここでは，SEIを起点とした場合のデプロイと開始の例を説明します。

7.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxws¥works¥annotations¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxwsserver -nameserver corbaname::testserver:900 -f annotations_dynamic_generate.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

7.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxws¥works¥annotations¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxwsserver -nameserver corbaname::testserver:900 -name Sample_application_annotations_dynamic_generate

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

7.5　Webサービスクライアントの開発例（SEI起点・カスタマイズ）

ここでは，SEIを起点とした場合のWebサービスクライアントをカスタマイズする例について説明します。

7.5.1　サービスクラスを生成する

cjwsimportコマンドを実行すると，サービスクラスなど，Webサービスクライアントの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

cjwsimportコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥annotations¥client¥
> mkdir src¥
> mkdir classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes http://webhost:8085/annotations_dynamic_generate/TestJaxWsService?wsdl

cjwsimportコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥annotations¥client¥src¥com¥example¥sample¥ディレクトリに，Javaソースが生成されます。なお，com¥example¥sample¥（パッケージに対応するディレクトリパス）は，名前空間URIの記述によって変わります。名前空間URIとパッケージとのマッピングについては，「15.1.1　名前空間からパッケージ名へのマッピング」を参照してください。

生成物の一覧を次の表に示します。

表7‒3　サービスクラス生成時の生成物（SEI起点・カスタマイズ）

ファイル名

説明

JaxWsTest1.java

WSDL定義の「オペレーション」の要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

JaxWsTest1Response.java

WSDL定義の「オペレーション」の応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

TestJaxWs.java

WSDL定義の「サービス」に対応するSEIです。

TestJaxWsService.java

サービスクラスです。

AddNumbersFault.java

AddNumbersFaultに対応するJavaBeanクラスです。

AddNumbersFault_Exception.java

フォルトbeanのラッパ例外クラスです。

ファイル名のJaxWsTest1，TestJaxWs，およびTestJaxWsServiceは，オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名の記述によって変わります。オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名のマッピングについては，次の個所を参照してください。

「15.1.2　ポートタイプからSEI名へのマッピング」

「15.1.3　オペレーションからメソッド名へのマッピング」

「15.1.4　メッセージのパートからパラメタおよび戻り値へのマッピング（wrapperスタイルの場合）」

「15.1.5　メッセージのパートからパラメタおよび戻り値へのマッピング（non-wrapperスタイルの場合）」

7.5.2　Webサービスクライアントの実装クラスを作成する

Webサービスを利用するWebサービスクライアントの実装クラスを作成します。

Webサービスに対して1回の呼び出しをするWebサービスクライアントの作成例を次に示します。

package org.example.sample.client;

import org.example.sample.TestJaxWs;
import org.example.sample.TestJaxWsService;
import org.example.sample.AddNumbersFault_Exception;

public class TestClient {
    public static void main( String[] args ) {
        try {
            TestJaxWsService service = new TestJaxWsService();
            TestJaxWs port = service.getTestJaxWs();

            int returnValue = port.jaxWsTest1( 205, 103 );

            System.out.println( "[RESULT] " + returnValue );
        }
        catch( AddNumbersFault_Exception e ){
            e.printStackTrace();
        }
    }

}

作成したTestClient.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥annotations¥client¥src¥com¥example¥sample¥client¥ディレクトリに保存します。

なお，org.example.sample，TestJaxWs，TestJaxWsService，およびjaxWsTest1は，生成されたJavaソースのパッケージ名，クラス名，およびクラス内のメソッド名によって変わります。異なる構成のWebサービスを開発する場合には，パッケージ名，クラス名，およびクラス内のメソッド名の記述を見直す必要があります。

7.5.3　Webサービスクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービスクライアントをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥annotations¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥org¥example¥sample¥client¥TestClient.java

javacコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥annotations¥client¥classes¥org¥example¥sample¥client¥ディレクトリに，TestClient.classが生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

7.6　Webサービスの実行例（SEI起点・カスタマイズ）

ここでは，SEIを起点とした場合のWebサービスクライアントをカスタマイズする実行例について説明します。

7.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxws¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>
add.jvm.arg=-Dejbserver.server.prf.PRFID=<PRF ID>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。

作成したJavaアプリケーション用オプション定義ファイルは，c:¥temp¥jaxws¥works¥annotations¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

7.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxws¥works¥annotations¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

7.6.3　Webサービスクライアントを実行する

cjclstartapコマンドを使用して，Webサービスクライアントを実行します。

Webサービスクライアントの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥annotations¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  org.example.sample.client.TestClient

cjclstartapコマンドが正常に終了すると，Webサービスクライアントの実行結果が表示されます。実行結果の表示例を次に示します。

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxws¥works¥annotations¥client, PID = 2636)
[RESULT] 308
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

8　SEIを起点とした開発の例（EJBのWebサービスの場合）

この章では，SEIを起点としたEJBのWebサービスを開発する場合の例を説明します。

8.1　開発例の構成（SEI起点・EJBのWebサービス）

この章で説明する開発例では，SEIを起点としたWebサービスを開発します。なお，ここではスタブベースでの開発例を説明しますが，ディスパッチベースやAPIベースでも開発できます。

開発するWebサービスの構成を次の表に示します。

表8‒1　Webサービスの構成（SEI起点）

項番

項目

値

1

デプロイするJ2EEサーバの名称

jaxwsserver

2

Webサーバのホスト名とポート番号

webhost:8085

3

ネーミングサーバのURL

corbaname::testserver:900

4

コンテキストルート

statelessjava_dynamic_generate

5

スタイル

document/literal/wrapped

6

名前空間URI

http://sample.com

7

ポートタイプ

個数

1

8

ローカル名

AddNumbersImpl

9

オペレーション

個数

1

10

ローカル名

add

11

サービス

個数

1

12

ローカル名

AddNumbersImplService

13

ポート

個数

1

14

ローカル名

AddNumbersImplPort

15

Webサービス実装クラス

com.sample.AddNumbersImpl

16

Webサービス実装クラスで公開するメソッド

個数

1

17

メソッド名

add

18

Webサービス実装内のメソッドでスローする例外

個数

1

19

クラス名

com.sample.AddNumbersFault

Webサービス開発時のカレントディレクトリの構成を次の表に示します。

表8‒2　カレントディレクトリの構成（SEI起点）

ディレクトリ

説明

c:¥temp¥jaxws¥works¥statelessjava

カレントディレクトリです。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

server¥

Webサービスの開発で使用します。

┣

┃

┃

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

┗

application.xml

「8.3.3　application.xmlを作成する」で作成します。

┣

┃

┃

┃

src¥

Webサービスのソースファイル（*.java）を格納します。「8.3.1　Webサービス実装クラスを作成する」および「8.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

┃

┃

┃

┃

┃

jar¥

コンパイルしたクラスファイル（*.class）を格納します。「8.3.1　Webサービス実装クラスを作成する」および「8.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┗

WEB-INF¥

EJB JARファイルのWEB-INFディレクトリに対応します。

┗

wsdl¥

「8.3.4　WSDLファイルを作成する（任意）」で作成します。

┣

┃

statelessjava_dynamic_generate.ear

「8.3.5　EARファイルを作成する」で作成します。

┗

statelessjava_dynamic_generate.war

┗

client¥

Webサービスクライアントの開発で使用します。

┣

┃

┃

┃

┃

src¥

Webサービスクライアントのソースファイル（*.java）を格納します。「8.5.1　サービスクラスを生成する」および「8.5.2　Webサービスクライアントの実装クラスを作成する」で使用します。

┣

┃

┃

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「8.5.3　Webサービスクライアントの実装クラスをコンパイルする」で使用します。

┣

┃

┃

usrconf.cfg

「8.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

┗

usrconf.properties

「8.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

カレントディレクトリのパスは，開発する環境に合わせて変更してください。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebサービスとWebサービスクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

8.2　開発例の流れ（SEI起点・EJBのWebサービス）

この章で説明する開発例では，次の流れで開発および実行します。

Webサービスの開発

Webサービス実装クラスを作成する（8.3.1）

Webサービス実装クラスをコンパイルする（8.3.2）

application.xmlを作成する（8.3.3）

WSDLファイルを作成する（任意）（8.3.4）

EARファイルを作成する（8.3.5）

デプロイと開始

EARファイルをデプロイする（8.4.1）

Webサービスを開始する（8.4.2）

Webサービスクライアントの開発

cjwsimportコマンドを実行し，サービスクラスを生成する（8.5.1）

Webサービスクライアントの実装クラスを作成する（8.5.2）

Webサービスクライアントの実装クラスをコンパイルする（8.5.3）

Webサービスの実行

Javaアプリケーション用オプション定義ファイルを作成する（8.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（8.6.2）

Webサービスクライアントを実行する（8.6.3）

8.3　Webサービスの開発例（SEI起点・EJBのWebサービス）

ここでは，SEIを起点とした場合のEJBのWebサービスの開発例を説明します。

8.3.1　Webサービス実装クラスを作成する

Webサービスの処理を記述したWebサービス実装クラスを新規に作成します。

ここでは，受け取った要求メッセージの内容を計算して，応答メッセージを返すWebサービス実装クラスを作成します。作成したAddNumbersImpl.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥statelessjava¥server¥src¥com¥sample¥ディレクトリに保存してください。

package com.sample;

@javax.ejb.Stateless
@javax.jws.WebService
public class AddNumbersImpl{

    public int add( int number1, int number2 ) throws AddNumbersFault{

        if( ( number1 < 0 ) || ( number2 < 0 ) ){
            throw new AddNumbersFault( "Negative number cannot be added!",
                "Numbers: " + number1 + ", " + number2 );
        }
        return number1 + number2;
    }

}

また，com.sample.AddNumbersImplでスローしている例外クラスcom.sample.AddNumbersFaultを作成します。通常，例外クラスの作成は任意ですが，ここでは例外クラスを作成します。

例外クラスの作成例を次に示します。作成したAddNumbersFault.javaは，UTF-8形式で，c:¥temp¥jaxws¥works¥statelessjava¥server¥src¥com¥sample¥ディレクトリに保存してください。

package com.sample;

public class AddNumbersFault extends Exception {

    String detail;

    public AddNumbersFault( String message, String detail ){
        super( message );
        this.detail = detail;
    }

    public String getDetail(){
        return detail;
    }
}

8.3.2　Webサービス実装クラスをコンパイルする

javacコマンドを実行して，Webサービス実装クラスをコンパイルします。javacコマンドについては，JDKのドキュメントを参照してください。

javacコマンドの実行例を次に示します。添付ファイル機能を使用したJavaプログラムをjavacコマンドでコンパイルする場合，javacコマンドの引数に"--add-modules=java.activation"を指定してください。

> cd c:¥temp¥jaxws¥works¥statelessjava¥server¥
> mkdir .¥WEB-INF¥classes¥
> javac -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxp.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmstax.jar" -d jar¥ -s src src¥com¥sample¥AddNumbersImpl.java src¥com¥sample¥AddNumbersFault.java

javacコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥statelessjava¥server¥WEB-INF¥classes¥com¥sample¥ディレクトリに出力されます。なお，コンパイルしたWebサービス実装クラスに対してhwsgenコマンドを実行すると，事前にエラーチェックができます。hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を，エラーチェックについては，「10.23.1　hwsgenコマンドによるエラーチェックについて」を参照してください。

8.3.3　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。

application.xmlの作成例を次に示します。なお，Webサービスとしてapplication.xmlに設定する項目はありません。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;statelessjava_dynamic_generate&quot;</description>
  <display-name>Sample_application_statelessjava_dynamic_generate</display-name>
  <module>
    <ejb>statelessjava_dynamic_generate.jar</ejb>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥statelessjava¥server¥META-INF¥ディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

8.3.4　WSDLファイルを作成する（任意）

SEI起点の開発ではWSDLファイルの作成は任意ですが，作成した場合はEARファイルに含めます。ここでは，hwsgenコマンドのWSDL生成機能を実行することで，コンパイル済みのJavaソースからWSDLファイルを作成する例を説明します。hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を参照してください。

hwsgenコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥statelessjava¥server¥
> mkdir .¥jar¥META-INF¥wsdl¥
> mkdir .¥temporary
> "%COSMINEXUS_HOME%¥jaxws¥bin¥hwsgen.bat" -r .¥jar¥META-INF¥wsdl -d .¥temporary -cp .¥jar com.sample.AddNumbersImpl
> rmdir /S /Q .¥temporary

hwsgenコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥statelessjava¥META-INF¥wsdl¥ディレクトリに，リソースファイルが生成されます。生成物の一覧を次の表に示します。

表8‒3　hwsgenコマンド実行時の生成物

ファイル名

説明

AddNumbersImplService.wsdl

指定したJavaソースに対応するWSDLファイルです。

AddNumbersImplService_schema1.xsd

WSDLファイルから参照されるXML Schema定義です。

なお，c:¥temp¥jaxws¥works¥statelessjava¥temporary¥ディレクトリに生成されるファイルは必要ないため削除してください。

8.3.5　EARファイルを作成する

jarコマンドを使用して，これまでに作成したファイルを含めたEARファイルを作成します。

EARファイルの作成例を次に示します。

> cd c:¥temp¥jaxws¥works¥statelessjava¥server¥
> jar cvf statelessjava_dynamic_generate.jar -C jar com
> jar cvf statelessjava_dynamic_generate.ear .¥statelessjava_dynamic_generate.jar .¥META-INF¥application.xml

jarコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥statelessjava¥server¥ディレクトリにstatelessjava_dynamic_generate.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

8.4　デプロイと開始の例（SEI起点・EJBのWebサービス）

ここでは，SEIを起点とした場合のデプロイと開始の例を説明します。

8.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxws¥works¥statelessjava¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxwsserver -nameserver corbaname::testserver:900 -f statelessjava_dynamic_generate.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

8.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxws¥works¥statelessjava¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxwsserver -nameserver corbaname::testserver:900 -name Sample_application_statelessjava_dynamic_generate

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

8.5　Webサービスクライアントの開発例（SEI起点・EJBのWebサービス）

ここでは，SEIを起点とした場合のWebサービスクライアントの開発例を説明します。

8.5.1　サービスクラスを生成する

cjwsimportコマンドを実行すると，サービスクラスなど，Webサービスクライアントの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

cjwsimportコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥statelessjava¥client¥
> mkdir src¥
> mkdir classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes http://webhost:8085/statelessjava_dynamic_generate/AddNumbersImplService?wsdl

cjwsimportコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥statelessjava¥client¥src¥com¥sample¥ディレクトリに，Javaソースが生成されます。なお，com¥sample¥（パッケージに対応するディレクトリパス）は，名前空間URIの記述によって変わります。名前空間URIとパッケージとのマッピングについては，「15.1.1　名前空間からパッケージ名へのマッピング」を参照してください。

生成物の一覧を次の表に示します。

表8‒4　サービスクラス生成時の生成物（SEI起点）

ファイル名

説明

Add.java

WSDL定義の「オペレーション」の要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

AddResponse.java

WSDL定義の「オペレーション」の応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

AddNumbersImpl.java

WSDL定義の「サービス」に対応するSEIです。

AddNumbersImplService.java

サービスクラスです。

AddNumbersFault.java

AddNumbersFaultに対応するJavaBeanクラスです。

AddNumbersFault_Exception.java

フォルトbeanのラッパ例外クラスです。

ファイル名のAdd，AddNumbersImpl，およびAddNumbersImplServiceは，オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名の記述によって変わります。オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名のマッピングについては，次の個所を参照してください。

「15.1.2　ポートタイプからSEI名へのマッピング」

「15.1.3　オペレーションからメソッド名へのマッピング」

「15.1.4　メッセージのパートからパラメタおよび戻り値へのマッピング（wrapperスタイルの場合）」

「15.1.5　メッセージのパートからパラメタおよび戻り値へのマッピング（non-wrapperスタイルの場合）」

8.5.2　Webサービスクライアントの実装クラスを作成する

Webサービスを利用するWebサービスクライアントの実装クラスを作成します。

Webサービスに対して1回の呼び出しをするWebサービスクライアントの作成例を次に示します。

package com.sample.client;

import com.sample.AddNumbersImpl;
import com.sample.AddNumbersImplService;
import com.sample.AddNumbersFault_Exception;

public class TestClient {
    public static void main( String[] args ) {
        try {
            AddNumbersImplService service = new AddNumbersImplService();
            AddNumbersImpl port = service.getAddNumbersImplPort();

            int returnValue = port.add( 205, 103 );

            System.out.println( "[RESULT] " + returnValue );
        }
        catch( AddNumbersFault_Exception e ){
            e.printStackTrace();
        }
    }

}

作成したTestClient.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥statelessjava¥client¥src¥com¥sample¥client¥ディレクトリに保存します。

なお，com.sample，AddNumbersImpl，AddNumbersImplService，AddNumbersImplPort，およびaddは，生成されたJavaソースのパッケージ名，クラス名，およびクラス内のメソッド名によって変わります。異なる構成のWebサービスを開発する場合には，パッケージ名，クラス名，およびクラス内のメソッド名の記述を見直す必要があります。

8.5.3　Webサービスクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービスクライアントをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥statelessjava¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥com¥sample¥client¥TestClient.java

javacコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥statelessjava¥client¥classes¥com¥sample¥client¥ディレクトリに，TestClient.classが生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

8.6　Webサービスの実行例（SEI起点・EJBのWebサービス）

ここでは，SEIを起点とした場合のWebサービスクライアントの実行例を説明します。

8.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxws¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>
add.jvm.arg=-Dejbserver.server.prf.PRFID=<PRF ID>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。

作成したJavaアプリケーション用オプション定義ファイルは，c:¥temp¥jaxws¥works¥statelessjava¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

8.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxws¥works¥statelessjava¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

8.6.3　Webサービスクライアントを実行する

cjclstartapコマンドを使用して，Webサービスクライアントを実行します。

Webサービスクライアントの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥statelessjava¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  com.sample.client.TestClient

cjclstartapコマンドが正常に終了すると，Webサービスクライアントの実行結果が表示されます。実行結果の表示例を次に示します。

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxws¥works¥statelessjava¥client, PID = 2636)
[RESULT] 308
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

9　プロバイダを起点とした開発の例（SAAJを利用した場合）

この章では，プロバイダを起点としたWebサービスを，SAAJを利用して開発する場合の例を説明します。

9.1　開発例の構成（プロバイダ起点・SAAJ）

この章で説明する開発例では，Dispatch／ProviderでSOAPメッセージを送受信するWebサービスを，SAAJを利用して開発します。

なお，ここでの例ではWebサービスクライアントから社員番号と社員の顔写真の情報が送信され，Webサービスが受信した情報を登録し，登録確認メッセージを返却するものとします。社員番号と登録確認メッセージのJavaデータ型はjava.lang.String，顔写真のJavaデータ型はjavax.activation.DataHandlerです。

開発するWebサービスの構成を次の表に示します。

表9‒1　Webサービスの構成（プロバイダ起点・SAAJ）

項番

項目

値

1

デプロイするJ2EEサーバの名称

jaxwsserver

2

Webサーバのホスト名とポート番号

webhost:8085

3

ネーミングサーバのURL

corbaname::testserver:900

4

コンテキストルート

dispatch_provider

5

名前空間URI

http://sample.com

6

サービス

個数

1

7

ローカル名

UserInfoService

8

ポート

個数

1

9

ローカル名

UserInfoPort

Webサービス開発時のカレントディレクトリの構成を次の表に示します。

表9‒2　カレントディレクトリの構成（プロバイダ起点・SAAJ）

ディレクトリ

説明

c:¥temp¥jaxws¥works¥dispatch_provider

カレントディレクトリです。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

server¥

Webサービスの開発で使用します。

┣

┃

┃

┃

┃

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

┗

application.xml

「9.3.4　application.xmlを作成する」で作成します。

┣

┃

src¥

Webサービスのソースファイル（*.java）を格納します。「9.3.1　プロバイダ実装クラスを作成する」で使用します。

┣

┃

┃

┃

┃

┃

WEB-INF¥

WARファイルのWEB-INFディレクトリに対応します。

┣

web.xml

「9.3.3　web.xmlを作成する」で作成します。

┗

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「9.3.2　Javaソースを生成する」で使用します。

┣

dispatch_provider.ear

「9.3.5　EARファイルを作成する」で作成します。

┗

dispatch_provider.war

┗

client¥

Webサービスクライアントの開発で使用します。

┣

┃

┃

src¥

Webサービスクライアントのソースファイル（*.java）を格納します。「9.5.1　Webサービスクライアントの実装クラスを作成する」で作成します。

┣

┃

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「9.5.2　Webサービスクライアントの実装クラスをコンパイルする」で作成します。

┣

┃

usrconf.cfg

「9.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

┗

usrconf.properties

「9.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

カレントディレクトリのパスは，開発する環境に合わせて変更してください。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebサービスとWebサービスクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

9.2　開発例の流れ（プロバイダ起点・SAAJ）

この章で説明する開発例では，次の流れで開発および実行します。

Webサービスの開発

プロバイダ実装クラスを作成する（9.3.1）

Javaソースを生成する（9.3.2）

web.xmlを作成する（9.3.3）

application.xmlを作成する（9.3.4）

EARファイルを作成する（9.3.5）

デプロイと開始

EARファイルをデプロイする（9.4.1）

Webサービスを開始する（9.4.2）

Webサービスクライアントの開発

Webサービスクライアントの実装クラスを作成する（9.5.1）

Webサービスクライアントの実装クラスをコンパイルする（9.5.2）

Webサービスの実行

Javaアプリケーション用オプション定義ファイルを作成する（9.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（9.6.2）

Webサービスクライアントを実行する（9.6.3）

9.3　Webサービスの開発例（プロバイダ起点・SAAJ）

ここでは，プロバイダを起点とし，SAAJを利用した場合のWebサービスの開発例を説明します。

9.3.1　プロバイダ実装クラスを作成する

プロバイダ実装クラスcom.sample.UserInfoImplを作成する例を次に示します。作成したcom.sample.UserInfoImplは，UTF-8形式でc:¥temp¥jaxws¥works¥dispatch_provider¥server¥src¥com¥sample¥ディレクトリに保存してください。

package com.sample;

import java.util.Iterator;
import javax.xml.namespace.QName;
import javax.xml.soap.AttachmentPart;
import javax.xml.soap.MessageFactory;
import javax.xml.soap.SOAPBody;
import javax.xml.soap.SOAPBodyElement;
import javax.xml.soap.SOAPElement;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPMessage;
import javax.xml.ws.Provider;
@javax.xml.ws.WebServiceProvider(serviceName="UserInfoService")
@javax.xml.ws.ServiceMode(value=javax.xml.ws.Service.Mode.MESSAGE)
public class UserInfoImpl implements Provider<SOAPMessage>{

    public SOAPMessage invoke( SOAPMessage request ){

        // 応答メッセージ
        SOAPMessage response = null;
        // 添付ファイル(顔写真)
        AttachmentPart attachment = null;

        try {
            // 要求メッセージからデータ取得
            // 社員番号を取得
            SOAPBody soapBody = request.getSOAPBody();
            SOAPBodyElement reqRoot =
                (SOAPBodyElement)soapBody.getChildElements().next();
            Iterator number_iterator = reqRoot.getChildElements();
            String number =

((SOAPElement)number_iterator.next()).getFirstChild().getNodeValue();

            // 顔写真を取得
            Iterator attachment_iterator = request.getAttachments();
            while(attachment_iterator.hasNext()){
                attachment = (AttachmentPart)attachment_iterator.next();
            }

            // 顔写真の登録処理など取得した添付ファイルに対して
            // ほかに必要な処理があれば実装する

            // 応答メッセージの生成
            response = MessageFactory.newInstance().createMessage();
            SOAPBody resSoapBody = response.getSOAPBody();
            SOAPBodyElement resRoot = resSoapBody.addBodyElement(
                new QName("http://sample.com", "result"));
            SOAPElement soapElement = resRoot.addChildElement(
                new QName("http://sample.com", "value"));
            // 登録確認メッセージを設定
            if(null ==  attachment){
                soapElement.addTextNode("Failure(no image).");
            } else {
                soapElement.addTextNode("Success.");
            }

        } catch (SOAPException e) {
            e.printStackTrace();
        }

        return response;
    }
}

SOAP 1.2の場合は，作成したプロバイダ実装クラスに対してjavax.xml.ws.BindingTypeアノテーションを付与してください。設定する値は，SOAP 1.2/HTTPバインディングを意味する"http://www.w3.org/2003/05/soap/bindings/HTTP/"にします。javax.xml.ws.BindingTypeアノテーションを付与する例を次に示します。

package com.sample;

import java.util.Iterator;
import javax.xml.namespace.QName;
import javax.xml.soap.AttachmentPart;
import javax.xml.soap.MessageFactory;
import javax.xml.soap.SOAPBody;
import javax.xml.soap.SOAPBodyElement;
import javax.xml.soap.SOAPElement;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPMessage;
import javax.xml.ws.Provider;

@javax.xml.ws.BindingType("http://www.w3.org/2003/05/soap/bindings/HTTP/")
@javax.xml.ws.WebServiceProvider
@javax.xml.ws.ServiceMode(value=javax.xml.ws.Service.Mode.MESSAGE)
public class UserInfoImpl mplements Provider<SOAPMessage>{

    public SOAPMessage invoke( SOAPMessage request ){

（以降はSOAP1.1の場合と同じ）

なお，javax.xml.ws.BindingTypeアノテーションの値には，"http://www.w3.org/2003/05/soap/bindings/HTTP/"の代わりに定数値フィールドjavax.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDINGを設定することもできます。定数値フィールドを設定した場合の例については，「5.3.1　Webサービス実装クラスを作成する」を参照してください。

9.3.2　Javaソースを生成する

作成したプロバイダ実装クラスcom.sample.UserInfoImplをコンパイルする例を次に示します。

> cd c:¥temp¥jaxws¥works¥dispatch_provider¥server¥
> mkdir WEB-INF¥classes¥
> javac -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxp.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmstax.jar" -d WEB-INF¥classes¥ -s src src¥com¥sample¥UserInfoImpl.java

コンパイルが正常に終了すると，c:¥temp¥jaxws¥works¥dispatch_provider¥server¥WEB-INF¥classes¥com¥sample¥ディレクトリに，UserInfoImpl.classが生成されます。

9.3.3　web.xmlを作成する

WARファイルの構成要素として必要なweb.xmlを作成します。

web.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;dispatch_provider&quot;</description>
  <display-name>Sample_web_service_dispatch_provider</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/UserInfoService</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

作成したweb.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥dispatch_provider¥server¥WEB-INFディレクトリに保存します。web.xmlの設定項目については，「3.4　web.xmlの作成」を参照してください。

9.3.4　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。application.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;dispatch_provider&quot;</description>
  <display-name>Sample_application_dispatch_provider</display-name>
  <module>
    <web>
      <web-uri>dispatch_provider.war</web-uri>
      <context-root>dispatch_provider</context-root>
    </web>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥dispatch_provider¥server¥META-INFディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

9.3.5　EARファイルを作成する

jarコマンドを使用して，これまでに作成したファイルを含めたEARファイルを作成します。

EARファイルの作成例を次に示します。

> cd c:¥temp¥jaxws¥works¥dispatch_provider¥server¥
> jar cvf dispatch_provider.war .¥WEB-INF
> jar cvf dispatch_provider.ear .¥dispatch_provider.war .¥META-INF¥application.xml

jarコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥dispatch_provider¥server¥ディレクトリにdispatch_provider.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

9.4　デプロイと開始の例（プロバイダ起点・SAAJ）

ここでは，プロバイダを起点とした場合のデプロイと開始の例を説明します。

9.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxws¥works¥dispatch_provider¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxwsserver -nameserver corbaname::testserver:900 -f dispatch_provider.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

9.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxws¥works¥dispatch_provider¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxwsserver -nameserver corbaname::testserver:900 -name Sample_application_dispatch_provider

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

9.5　Webサービスクライアントの開発例（プロバイダ起点・SAAJ）

ここでは，プロバイダを起点とし，SAAJを利用した場合のWebサービスクライアントの開発例を説明します。

9.5.1　Webサービスクライアントの実装クラスを作成する

Webサービスを利用するWebサービスクライアントの実装クラスを作成します。

Webサービスに対して1回の呼び出しをする，ディスパッチベースのWebサービスクライアントcom.sample.client.TestClientの作成例を次に示します。

なお，ディスパッチベースのWebサービスクライアントでは，SOAPバインディングのバージョンを明示する必要があるため，例ではSOAP 1.1/HTTPバインディングを指定しています。SOAP 1.2の場合は，SOAPBinding.SOAP11HTTP_BINDINGの部分をSOAPBinding.SOAP12HTTP_BINDINGに読み替えてください。

package com.sample.client;

import java.io.File;
import java.util.Iterator;
import javax.activation.DataHandler;
import javax.activation.FileDataSource;
import javax.xml.namespace.QName;
import javax.xml.soap.MessageFactory;
import javax.xml.ws.soap.SOAPBinding;
import javax.xml.soap.AttachmentPart;
import javax.xml.soap.SOAPBody;
import javax.xml.soap.SOAPBodyElement;
import javax.xml.soap.SOAPElement;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPMessage;
import javax.xml.ws.Dispatch;
import javax.xml.ws.Service;

public class TestClient {
    public static void main( String[] args ) {
        // サービス生成
        QName port = new QName( "http://sample.com", "UserInfoPort" );
        Service service = Service.create(
            new QName("http://sample.com", "UserInfoService"));
        String serviceURL = "http://webhost:8085/dispatch_provider/UserInfoService";

        // サービスにポートを追加
        service.addPort( port, SOAPBinding.SOAP11HTTP_BINDING, serviceURL );

        // Dispatchオブジェクト生成
        Dispatch<SOAPMessage> dispatch = service.createDispatch(
            port, SOAPMessage.class, Service.Mode.MESSAGE );

        // 要求メッセージ
        SOAPMessage request = null;

        try{
            // 要求メッセージの生成
            request = MessageFactory.newInstance().createMessage();
            SOAPBody reqSoapBody = request.getSOAPBody();

            // 社員番号を設定
            SOAPBodyElement requestRoot= soapBody.addBodyElement(
                new QName("http://sample.com", "number"));
            SOAPElement soapElement = requestRoot.addChildElement(
                new QName("http://sample.com", "value"));
            soapElement.addTextNode( "1234" );

            // 添付ファイル(顔写真)を設定
            String filePath = "C:¥¥attachment.jpg";
            FileDataSource fds = new FileDataSource(filePath);
            AttachmentPart apPart =
                request.createAttachmentPart(new DataHandler(fds));
            request.addAttachmentPart(apPart);

            // SOAPメッセージの送受信
            SOAPMessage response = dispatch.invoke( request );

            // 応答メッセージからデータを取得
            SOAPBody resSoapBody = response.getSOAPBody();
            SOAPBodyElement resRoot =
                (SOAPBodyElement)resSoapBody.getChildElements().next();
            Iterator iterator = resRoot.getChildElements();
            String result =

((SOAPElement)iterator.next()).getFirstChild().getNodeValue();

            // 登録確認メッセージの表示
            System.out.println( "[RESULT] " + result );
        } catch( SOAPException e ) {
            e.printStackTrace();
      }
   }
}

作成したTestClient.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥dispatch_provider¥client¥src¥com¥sample¥client¥ディレクトリに保存します。

9.5.2　Webサービスクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービスクライアントをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥dispatch_provider¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥com¥sample¥client¥TestClient.java

javacコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥dispatch_provider¥client¥classes¥com¥sample¥client¥ディレクトリに，TestClient.classが生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

9.6　Webサービスの実行例（プロバイダ起点・SAAJ）

ここでは，プロバイダを起点とし，SAAJを利用した場合のWebサービスの実行例を説明します。

9.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxws¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>
add.jvm.arg=-Dejbserver.server.prf.PRFID=<PRF ID>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。<PRF ID>の部分は，PRFデーモンの識別子を指定します。

作成したJavaアプリケーション用オプション定義ファイルは，c:¥temp¥jaxws¥works¥dispatch_provider¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

9.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxws¥works¥dispatch_provider¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

9.6.3　Webサービスクライアントを実行する

cjclstartapコマンドを使用して，Webサービスクライアントを実行します。

Webサービスクライアントの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥dispatch_provider¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  com.sample.client.TestClient

cjclstartapコマンドが正常に終了すると，Webサービスクライアントの実行結果が表示されます。実行結果の表示例を次に示します。

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxws¥works¥dispatch_provider¥client, PID = 2636)
[RESULT] Success.
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

10　JAX-WS機能の設定と動作

この章では，SOAP Webサービスを開発，運用するときのJAX-WS機能の各種設定と，運用に当たって理解が必要なJAX-WSエンジンの動作について説明します。

10.1　動作定義ファイル

ログやタイムアウトの設定などは動作定義ファイルに記述します。動作定義ファイルは，次の2種類があります。

共通定義ファイル

システム共通の動作を設定するための定義ファイルです。一つだけあります。

プロセス別の定義ファイル

プロセス固有の動作を設定する場合に作成する定義ファイルです。固有の設定が必要なプロセスごとに作成します。例えば，J2EEサーバごとに設定を変更したい場合や，Webサービスクライアントに設定を変更したい場合に作成します。

また，一部の定義については，Webサービスクライアントにメッセージコンテキストを取得して定義できます。メッセージコンテキストとして指定できる定義については，「19.2.5(1)　メッセージコンテキストのプロパティのサポート範囲」を参照してください。

ここでは，動作定義ファイルの記述規則，および各定義ファイルの設定について説明します。

10.1.1　動作定義ファイルの記述規則

動作定義ファイルの記述形式および記述規則について説明します。また，動作定義の優先度を示します。

(1)　記述形式

動作定義ファイルは，次のようにキーを指定します。

<キー名称>=<値>

(2)　記述規則

動作定義ファイルは，次に示す規則に従って記述してください。

改行までが<値>になります。

#で始まる行はコメントと見なされます。

<値>の後ろにコメントは追加できません。追加した場合，コメントまでが値と解釈されます。

記載する文字はJavaの仕様に従って，ISO 8859-1文字エンコーディングを使用してください。2バイト文字などは不正な文字列に解釈されるので，native2asciiコマンドで変換してください。native2asciiコマンドについては，JDKのドキュメントを参照してください。

<値>にはスペースも指定できます。

<キー名称>と=の間，および=と<値>の間にスペースを入れた場合，スペースが取り除かれて解釈されます。

設定できる<キー名称>以外の<キー名称>を設定した場合，その<キー名称>は使用されません（警告やエラーは出力されません）。

値がない行を指定した場合，デフォルト値が仮定されます。

キー名称は大文字／小文字を区別します。

(3)　動作定義の優先度

動作定義の優先順位は次のとおりです。

Webサービスクライアント（メッセージコンテキスト）に定義

プロセス別の定義ファイル

共通定義ファイル

Webサービスクライアントに定義する場合の例として，Webサービスクライアントに接続タイムアウト値を設定するコードを示します。

// setConnectTimeout()
int timeout = 60000;
Map<String, Object> ctxt = ((BindingProvider)port).getRequestContext();
ctxt.put("com.cosminexus.jaxws.connect.timeout", timeout);

10.1.2　共通定義ファイルの設定項目

共通定義ファイルを使用して，システム共通の動作定義を設定します。共通定義ファイルのファイル名，保存ディレクトリ名，および設定項目について説明します。

(1)　ファイル名

共通定義ファイルのファイル名を示します。

cjwconf.properties

(2)　保存先ディレクトリ

共通定義ファイルの保存先ディレクトリを示します。保存先ディレクトリは固定です。

<Application Serverのインストールディレクトリ>¥jaxws¥conf

(3)　設定項目

設定するキー名称と指定内容の一覧を次の表に示します。

表10‒1　共通定義ファイルの設定項目

項番

設定項目

キー名称

指定内容

デフォルト値

コンテキスト

1

稼働ログの出力レベル

com.cosminexus.jaxws.logger.runtime.message.level

稼働ログの出力レベルを指定します。

ERROR，WARN，INFO，DEBUG，NONEのどれかを指定します。各指定値に対応した出力内容については，「39.3.4　ログの重要度と出力条件」を参照してください。

INFO

−

2

稼働ログの面数

com.cosminexus.jaxws.logger.runtime.message.file_num

稼働ログの面数を指定します。

数字（1〜16）を指定します。

2

−

3

稼働ログの容量

com.cosminexus.jaxws.logger.runtime.message.file_size

稼働ログの容量を指定します。

4096〜16777216の数字（単位：バイト）を指定します。

2097152

−

4

保守ログの出力

com.cosminexus.jaxws.logger.runtime.maintenance.level

保守ログを出力するかどうかを指定します。

ALLを指定した場合

保守ログが出力されます。

NONEを指定した場合

保守ログが出力されません。

ALL

−

5

保守ログの面数

com.cosminexus.jaxws.logger.runtime.maintenance.file_num

保守ログの面数を指定します。

1〜16の数字を指定します。

2

−

6

保守ログの容量

com.cosminexus.jaxws.logger.runtime.maintenance.file_size

保守ログの容量を指定します。

4096〜16777216の数字（単位：バイト）を指定します。

16777216

−

7

例外ログの出力レベル

com.cosminexus.jaxws.logger.runtime.exception.level

例外ログの出力レベルを指定します。ERROR，WARN，INFO，DEBUG，NONEのどれかを指定します。各指定値に対応した出力内容については，「39.3.4　ログの重要度と出力条件」を参照してください。

INFO

−

8

例外ログの面数

com.cosminexus.jaxws.logger.runtime.exception.file_num

例外ログの面数を指定します。1〜16の数字を指定します。

2

−

9

例外ログの容量

com.cosminexus.jaxws.logger.runtime.exception.file_size

例外ログの容量を指定します。4096〜16777216の数字（単位：バイト）を指定します。

16777216

−

10

通信ログの出力レベル

（Webサービスクライアント側）

com.cosminexus.jaxws.logger.runtime.transport.client_dump

Webサービスクライアント側での通信ログの出力レベルを指定します。

NONEを指定した場合

Webサービスクライアントでは通信ログが出力されません。

ALLを指定した場合

Webサービスクライアントで送受信したメッセージが常に通信ログに出力されます。

HEADERを指定した場合

Webサービスクライアントで受信したメッセージのHTTPヘッダが常に通信ログに出力されます。

ERROR_HEADERを指定した場合

SOAPFaultを受信した場合に，受信したメッセージのHTTPヘッダが通信ログに出力されます。

注意事項

ALLを指定した場合，送受信するメッセージの長さによってはjava.lang.OutOfMemoryError例外が発生することがあります。その場合はJVMのヒープサイズを調整してください。

ERROR_HEADER

−

11

通信ログの出力レベル

（Webサービス側）

com.cosminexus.jaxws.logger.runtime.transport.server_dump

Webサービス側での通信ログの出力レベルを指定します。

NONEを指定した場合

Webサービス側では通信ログが出力されません。

ALLを指定した場合

Webサービス側で送受信したメッセージが常に通信ログに出力されます。

HEADERを指定した場合

Webサービス側で受信したメッセージのHTTPヘッダが常に通信ログに出力されます。

ERROR_HEADER

SOAPFaultを送信する場合に，受信したメッセージのHTTPヘッダが通信ログに出力されます。

なお，受信時のメッセージを出力する場合は，HTTPのリクエスト情報も出力されます。

注意事項

ALLを指定した場合，送受信するメッセージの長さによってはjava.lang.OutOfMemoryError例外が発生することがあります。その場合はJavaVMのヒープサイズを調整してください。

ERROR_HEADER

−

12

通信ログの面数

com.cosminexus.jaxws.logger.runtime.transport.file_num

通信ログの面数を指定します。1〜16の数字を指定します。

2

−

13

通信ログの容量

com.cosminexus.jaxws.logger.runtime.transport.file_size

通信ログの容量を指定します。4096〜16777216の数字（単位：バイト）を指定します。

16777216

−

14

通信ログの文字エンコーディング

com.cosminexus.jaxws.logger.runtime.transport.encoding

通信ログの文字エンコーディングを指定します。J2SE 6.0でサポートされている文字エンコーディングについては，J2SE 6.0のドキュメントを参照してください。

"DEFAULT"を指定した場合，通信ログの文字エンコーディングはデフォルトのプラットフォームエンコーディングとなります。

DEFAULT

−

15

稼働ログの出力レベル（cjwsimport）

com.cosminexus.jaxws.logger.cjwsimport.message.level

cjwsimportコマンドの稼働ログの出力レベルを指定します。ERROR，WARN，INFO，DEBUG，NONEのどれかを指定します。各指定値に対応した出力内容については，「39.3.4　ログの重要度と出力条件」を参照してください。

INFO

−

16

稼働ログの面数（cjwsimport）

com.cosminexus.jaxws.logger.cjwsimport.message.file_num

cjwsimportコマンドの稼働ログの面数を指定します。1〜16の数字を指定します。

2

−

17

稼働ログの容量（cjwsimport）

com.cosminexus.jaxws.logger.cjwsimport.message.file_size

cjwsimportコマンドの稼働ログの容量を指定します。4096〜16777216の数字（単位：バイト）を指定します。

2097152

−

18

例外ログの出力レベル（cjwsimport）

com.cosminexus.jaxws.logger.cjwsimport.exception.level

cjwsimportコマンドの例外ログの出力レベルを指定します。ERROR，WARN，INFO，DEBUG，NONEのどれかを指定します。各指定値に対応した出力内容については，「39.3.4　ログの重要度と出力条件」を参照してください。

INFO

−

19

例外ログの面数（cjwsimport）

com.cosminexus.jaxws.logger.cjwsimport.exception.file_num

cjwsimportコマンドの例外ログの面数を指定します。1〜16の数字を指定します。

2

−

20

例外ログの容量（cjwsimport）

com.cosminexus.jaxws.logger.cjwsimport.exception.file_size

cjwsimportコマンドの例外ログの容量を指定します。4096〜16777216の数字（単位：バイト）を指定します。

16777216

−

21

保守ログの出力（cjwsimport）

com.cosminexus.jaxws.logger.cjwsimport.maintenance.level

cjwsimportコマンドの保守ログを出力するかどうかを指定します。

ALLを指定した場合

保守ログが出力されます。

NONEを指定した場合

保守ログが出力されません。

ALL

−

22

保守ログの面数（cjwsimport）

com.cosminexus.jaxws.logger.cjwsimport.maintenance.file_num

cjwsimportコマンドの保守ログの面数を指定します。1〜16の数字を指定します。

2

−

23

保守ログの容量（cjwsimport）

com.cosminexus.jaxws.logger.cjwsimport.maintenance.file_size

cjwsimportコマンドの保守ログの容量を指定します。4096〜16777216の数字（単位：バイト）を指定します。

16777216

−

24

SOAPActionがない場合の動作オプション

com.cosminexus.jaxws.fault_omit_soapaction

SOAPActionがない場合の動作オプションを指定します。

trueを指定した場合

SOAPActionヘッダがない場合，SOAPフォルトメッセージを返します。

falseを指定した場合

SOAPActionヘッダがない場合，SOAPActionヘッダの値が空文字として動作します。

true

−

25

クライアントソケットの接続タイムアウト値

com.cosminexus.jaxws.connect.timeout

クライアントソケットの接続タイムアウト値を指定します。

このプロパティで指定したタイムアウト値は，Webサービス呼び出し時と，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時に適用されます。

0〜2147483647の数字（単位：ミリ秒）を指定します。0を指定した場合，タイムアウトされません。

OSのTCP接続に関連する設定を変更している場合，OSの設定値が優先されることがあります。

60000

○※

26

クライアントソケットの読み込みタイムアウト値

com.cosminexus.jaxws.request.timeout

クライアントソケットの読み込みタイムアウト値を指定します。

このプロパティで指定したタイムアウト値は，Webサービス呼び出し時と，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時に適用されます。

0〜2147483647の数字（単位：ミリ秒）を指定します。0を指定した場合，タイムアウトされません。

OSのTCP接続に関連する設定を変更している場合，OSの設定値が優先されることがあります。

300000

○※

27

ベーシック認証のユーザID

javax.xml.ws.security.auth.username

HTTP接続で使用するベーシック認証のユーザIDを指定します。

このプロパティで指定したユーザIDは，Webサービス呼び出し時と，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時に適用されます。

なし

○※

28

ベーシック認証のパスワード

javax.xml.ws.security.auth.password

HTTP接続で使用するベーシック認証のパスワードを指定します。

このプロパティで指定したパスワードは，Webサービス呼び出し時と，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時に適用されます。

javax.xml.ws.security.auth.usernameを指定していない場合，有効になりません。

なし

○※

29

HTTPセッションの維持の有無

javax.xml.ws.session.maintain

HTTPセッションの維持の有無を指定します。HTTPセッションは同じポートオブジェクトを使用している範囲で維持されます。

trueの場合

セッションが維持されます。

falseの場合

セッションが維持されません。

false

○※

30

ハンドラチェイン設定ファイルの厳密な検証

com.cosminexus.jaxws.validation.handlerchain.strict

ハンドラチェイン設定ファイルの検証を厳密に行うかどうかを指定します。ハンドラチェイン設定ファイルのjavaee:handler要素の子要素としてjavaee:handler-name要素が記述されていないとエラーになります。

false

−

31

HTTPリクエストに対するWSDLの発行

com.cosminexus.jaxws.security.publish_wsdl

WebサービスのURLに対して，クエリストリングが?wsdl，または?WSDLであるHTTP GETリクエストが送信された場合，そのWebサービスのWSDLを発行するかどうかを指定します。

trueを指定した場合

WSDLが発行されます。

falseを指定した場合

WSDLが発行されないで，405 Method Not Allowedが返されます。

true

−

32

HTTPリクエストに対するWebサービスの情報表示

com.cosminexus.jaxws.security.display_webservice_info

Webサービスに対して，GETによるHTTPリクエストが到着したとき，レスポンスとして，Webサービスの情報を表示するかどうかを指定します。

trueを指定した場合

そのリクエストURLに対応するWebサービスの情報が表示されます。

falseを指定した場合

405 Method Not Allowedが返されます。

false

−

33

Webサービスで発生したJava例外の伝搬

com.cosminexus.jaxws.fault.SOAPFaultBuilder.captureStackTrace

Webサービスで発生したJava例外をWebサービスクライアントに伝搬するかどうかを指定します。

trueを指定した場合

例外が伝搬されます。

falseを指定した場合

例外が伝搬されません。

false

−

34

ログの出力先ディレクトリ

com.cosminexus.jaxws.tool.log.directory

cjwsimportコマンドが出力するログの出力先ディレクトリを指定します。

<Application Serverのインストールディレクトリ>/jaxws/logs

−

35

プロキシサーバの認証ユーザID

com.cosminexus.jaxws.http.proxyUser

プロキシサーバの認証ユーザIDを指定します。Webサービスクライアントが，プロキシサーバを使用して外部のネットワークにあるWebサービスを呼び出す場合に，必要に応じて指定してください。

このプロパティで指定したユーザIDは，Webサービス呼び出し時と，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時に適用されます。

なし

−

36

プロキシサーバの認証ユーザIDに対応するパスワード

com.cosminexus.jaxws.http.proxyPassword

プロキシサーバの認証ユーザIDに対応するパスワードを指定します。Webサービスクライアントが，プロキシサーバを使用して外部のネットワークにあるWebサービスを呼び出す場合に，必要に応じて指定してください。

このプロパティで指定したパスワードは，Webサービス呼び出し時と，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時に適用されます。

なし

−

37

SSLプロトコルによる接続で使用するプロキシサーバの認証ユーザID

com.cosminexus.jaxws.https.proxyUser

SSLプロトコルによる接続で使用する，プロキシサーバの認証ユーザIDを指定します。Webサービスクライアントが，プロキシサーバを使用して外部のネットワークにあるWebサービスを呼び出す場合で，SSLプロトコルによる接続のときに，必要に応じて指定してください。

このプロパティで指定したユーザIDは，Webサービス呼び出し時と，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時に適用されます。

なし

−

38

SSLプロトコルによる接続で使用するプロキシサーバの認証ユーザIDに対応するパスワード

com.cosminexus.jaxws.https.proxyPassword

SSLプロトコルによる接続で使用する，プロキシサーバの認証ユーザIDに対応するパスワードを指定します。Webサービスクライアントが，プロキシサーバを使用して外部のネットワークにあるWebサービスを呼び出す場合で，SSLプロトコルによる接続のときに，必要に応じて指定してください。このプロパティで指定したユーザIDは，Webサービス呼び出し時と，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時に適用されます。

なし

−

39

soap12:binding要素のtransport属性の指定

com.cosminexus.jaxws.publish_wsdl.soap12binding

SOAP1.2の場合に，クエリストリングが?wsdlまたは?WSDLであるHTTP GETリクエストで発行されたWSDLで，wsdl:binding要素の子要素であるsoap12:binding要素のtransport属性に，http://schemas.xmlsoap.org/soap/httpを設定するかどうかを指定します。

DEFAULT

soap12:binding/@transport属性値を

"http://www.w3.org/2003/05/soap/bindings/HTTP/"にします。

WSI_BP20_TRANSPORT

soap12:binding/@transport属性値を

"http://schemas.xmlsoap.org/soap/http"にします。

DEFAULT

−

40

SSL接続におけるホスト名検証の有無

com.cosminexus.xml.ws.client.http.HostnameVerificationProperty

WebサービスクライアントがSSLプロトコルによる接続を行う場合，次に示す検証を省略するかどうかを指定します。

検証内容：エンドポイントアドレスに含まれるホスト名と，証明書のホスト名が一致しているかどうか。

true

検証を省略します。

false

検証を省略しません。

このプロパティで指定したSSL接続におけるホスト名検証の有無は，Webサービス呼び出し時と，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時に適用されます。

false

○※

（凡例）

○：メッセージコンテキストとして設定できることを示します。

−：メッセージコンテキストとして設定できないことを示します。

注※

メッセージコンテキストへの指定が有効になるのはWebサービス呼び出し時だけで，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時には適用されません。

メタデータ取得時にベーシック認証の情報，またはSSL接続におけるホスト名検証の有無を設定する場合は，共通定義ファイルまたはプロセス別の定義ファイルに記述するか，別途WSDLをローカルマシンにダウンロードして使用してください（ローカルマシンにあるWSDLを使用する場合は，メタデータ取得時にリモートマシンへの接続が発生しません）。WSDLから別途インポートされるWSDLがある場合は，インポートされるWSDLもローカルマシン上にダウンロードしてください。

また，このプロパティにメッセージコンテキストでtrueまたはfalseを設定する場合は，java.lang.String型の文字列で設定してください。java.lang.String型の文字列以外で設定した場合の動作は保証されません。設定方法については，「19.2.5(2)(k)　com.cosminexus.xml.ws.client.http.HostnameVerificationPropertyプロパティの設定方法」を参照してください。数字を設定する場合は，int型またはjava.lang.Integer型で設定してください。int型またはjava.lang.Integer型の数字以外で設定した場合の動作は保証されません。

(4)　設定を変更する場合

Webサービス側の設定を変更する場合

プロセス別の定義ファイルを使用していないすべてのJ2EEサーバを停止してから，共通定義ファイルの設定を変更してください。プロセス別の定義ファイルについては，「10.1.3　プロセス別の定義ファイルの設定」を参照してください。

ログ関連の設定を変更する場合，必要に応じてログを退避してから設定を変更してください。

Webサービスクライアント側の設定を変更する場合

すべてのJ2EEサーバ（WebサービスクライアントをJ2EEアプリケーションとした場合），またはすべてのJavaアプリケーションを停止してから，共通定義ファイルの設定を変更してください。

ログ関連の設定を変更する場合，必要に応じてログを退避してから設定を変更してください。

10.1.3　プロセス別の定義ファイルの設定

プロセス別に固有の定義をする場合に，プロセス別の定義ファイルを作成します。

プロセス別の定義ファイルのファイル名，および保存先のディレクトリ名は任意です。システムプロパティで保存先のパスを指定することで，プロセス別の定義が有効になります。プロセス別の定義ファイルの指定例を次に示します。

com.cosminexus.jaxws.confpath=d:/tmp/example.properties

プロセス別の定義を変更する場合，対象としているプロセス（J2EEアプリケーションまたはJavaアプリケーション）を停止してから，プロセス別の定義ファイルの定義を変更してください。

ログ関連の定義を変更する場合，必要に応じてログを退避してから，定義を変更してください。

10.2　JAX-WSエンジンの動作

Application ServerのJAX-WSエンジンの動作，およびApplication ServerのJAX-WSエンジンのサポート範囲について説明します。

10.2.1　JAX-WSエンジンの動作とサポート範囲

Webサービス側とWebサービスクライアント側でやり取りされるSOAPメッセージは，JAX-WSエンジンの動作によってマーシャル／アンマーシャルされます。

ここでは，Webサービス側およびWebサービスクライアント側のJAX-WSエンジンとサポート範囲について説明します。

(1)　Webサービス側のJAX-WSエンジンの動作とサポート範囲

Webサービス側のJAX-WSエンジンの動作について説明し，Webサービスを利用するWebサービスクライアントのサポート範囲について示します。

(a)　Webサービス側のJAX-WSエンジンの動作

Webサービス側のJAX-WSエンジンは，次に示すような流れで動作します。

Webサービスクライアント側からPOST HTTPメソッドによってSOAP要求メッセージを受け付け，アンマーシャルしてJavaオブジェクトに変換する。

対象となるWebサービス実装クラスまたはプロバイダ実装クラスを見つけ出し（ディスカバリ），オペレーションに対応するメソッドを呼び出す（ディスパッチ）。

対象となるWebサービス実装クラスまたはプロバイダ実装クラスからSOAP応答メッセージやフォルトメッセージを表現するJavaオブジェクトを受け取り，マーシャルしてSOAP応答メッセージまたはフォルトメッセージとして呼び出し元に返す。

ディスカバリとディスパッチについては，「10.2.2　ディスカバリとディスパッチ」を参照してください。

また，Webサービス側のJAX-WSエンジンは，HTTP GETメソッドによってWebサービスのメタデータであるWSDLを要求された場合，WARファイルにWSDLがなければ自動的に生成して返します。メタデータの発行については，「10.6　メタデータの発行」を参照してください。

なお，POSTでもGETでもないHTTPメソッドでWebサービス側のJAX-WSエンジンが呼び出された場合，HTTPステータスコード 405 Method Not Allowedを返します。

(b)　Webサービス側のJAX-WSエンジンのサポート範囲

Webサービス側のJAX-WSエンジンとWebサービスクライアントの関係について説明します。

Webサービス実装クラスの場合

Webサービス実装クラスの場合の，Webサービス側のJAX-WSエンジンとWebサービスクライアントの関係を次に示します。

図10‒1　Webサービス側のJAX-WSエンジンとWebサービスクライアントの関係（Webサービス実装クラスの場合）

Webサービス側のJAX-WSエンジンが受信できるメッセージ，および接続元のWebサービスクライアントの条件を次に示します。

Application ServerのJAX-WS機能で動作するWebサービスクライアント

Application ServerのJAX-WS機能が提供しているコマンドで開発し，Application ServerのJAX-WS機能で動作するWebサービスクライアントを利用できます。接続先のApplication ServerのJAX-WS機能が以前のバージョンの場合，そのバージョンでサポートしている機能だけを使用できます。

SOAP通信基盤で動作する，RPC形態のSOAPアプリケーションのクライアントSOAPアプリケーション開発支援機能で開発し，SOAP通信基盤で動作するRPC形態のSOAPアプリケーションのクライアントを利用できます。

開発時のSOAPアプリケーション開発支援機能およびSOAP通信基盤のバージョンは，07-10以降である必要があります。また，この場合のWebサービスは，SOAP通信基盤のJava2WSDLコマンドで生成した，document/literal形式のWSDLを起点として開発している必要があります。

そのほかのWebサービスクライアント

Application ServerのJAX-WS機能で動作するWebサービスが発行するメタデータ（WSDL）をサポートし，WS-I Basic Profile 1.1，およびAttachments Profile 1.0を適用した次のどれかの仕様に従ったSOAPメッセージ※を送受信できるWebサービスクライアントを利用できます。

SOAP 1.1仕様

SOAP 1.2仕様

SwA仕様（wsi:swaRef形式の添付ファイルを利用する場合）

MTOM/XOP仕様（MTOM/XOP仕様形式の添付ファイルを利用する場合）

WSDLのサポート範囲については，「20.1　WSDL 1.1仕様のサポート範囲」を参照してください。

注※

標準仕様の性質から，WS-I Basic Profile 1.1およびAttachments Profile 1.0を適用したSOAP 1.1仕様，SOAP 1.2仕様，SwA仕様，またはMTOM/XOP仕様でもまだあいまいな部分が残ります。したがって，相互接続性について十分に検証してから運用してください。

プロバイダ実装クラスの場合

プロバイダ実装クラスの場合の，Webサービス側のJAX-WSエンジンとWebサービスクライアントの関係を次に示します。

図10‒2　Webサービス側のJAX-WSエンジンとWebサービスクライアントの関係（プロバイダ実装クラスの場合）

Webサービス側のJAX-WSエンジンが受信できるメッセージ，および接続元のWebサービスクライアントの条件を次に示します。

Application ServerのJAX-WS機能で動作するWebサービスクライアント

Application ServerのJAX-WS機能が提供しているAPIで開発し，Application ServerのJAX-WS機能で動作するWebサービスクライアントを利用できます。接続先のApplication ServerのJAX-WS機能が以前のバージョンの場合，そのバージョンでサポートしている機能だけを使用できます。

Application ServerのJAX-WS機能で動作するディスパッチベースのWebサービスクライアント

SAAJ 1.2仕様を利用したSOAPアプリケーションのクライアント

SOAPアプリケーション開発支援機能で開発し，SOAP通信基盤で動作するSAAJ 1.2仕様を利用したSOAPアプリケーションのクライアントを利用できます。

開発時のSOAPアプリケーション開発支援機能およびSOAP通信基盤のバージョンは，07-10以降である必要があります。また，SOAPアプリケーション開発支援機能とApplication ServerのJAX-WS機能の両方でサポートする範囲のSOAPメッセージを送受信するSOAPアプリケーションである必要があります。

そのほかのWebサービスクライアント

WS-I Basic Profile 1.1およびAttachments Profile 1.0を適用した，次のどれかの仕様に従ったSOAPメッセージ※を送受信できるWebサービスクライアントを利用できます。

SOAP 1.1仕様

SOAP 1.2仕様

SwA仕様（wsi:swaRef形式の添付ファイルを利用する場合）

注※

標準仕様の性質から，WS-I Basic Profile 1.1およびAttachments Profile 1.0を適用したSOAP 1.1仕様，SOAP 1.2仕様，またはSwA仕様でもまだあいまいな部分が残ります。したがって，相互接続性について十分に検証してから運用してください。プロバイダ実装クラスの場合，送受信できるSOAPメッセージの自由度が大きくなるため，特に注意してください。

(2)　Webサービスクライアント側のJAX-WSエンジンの動作とサポート範囲

Webサービスクライアント側のJAX-WSエンジンの動作について説明し，Webサービスクライアントから利用できるWebサービスのサポート範囲について示します。

(a)　Webサービスクライアント側のJAX-WSエンジンの動作

Webサービスクライアント側のJAX-WSエンジンは，次に示すような流れで動作します。

Webサービスクライアントから，JAX-WS APIを介してSOAP要求メッセージを表現するJavaオブジェクトを受け取る。

受け取ったJavaオブジェクトをマーシャルして，SOAP要求メッセージとして送信する。

呼び出し先からSOAP応答メッセージやフォルトメッセージを受信し，アンマーシャルしてWebサービスクライアントに返す。

Webサービスクライアントは，生成されたクラスまたはJAX-WS APIを介してJAX-WSエンジンにアクセスするため，JAX-WSエンジンを意識する必要はありません。

また，生成されたクラスおよびJAX-WS APIは，JAX-WS 2.2仕様に基づくため，Webサービスクライアントの実装者は，標準仕様以外のインタフェースを考慮する必要はありません。Webサービスの呼び出し（SOAP要求メッセージの送信），およびSOAP応答メッセージおよびフォルトメッセージの受信は，標準仕様のインタフェースのサポート範囲内で行われます。

(b)　Webサービスクライアント側のJAX-WSエンジンのサポート範囲

Webサービスクライアント側のJAX-WSエンジンとWebサービスの関係について説明します。

スタブベースのWebサービスクライアントの場合

スタブベースのWebサービスクライアントの場合の，Webサービスクライアント側のJAX-WSエンジンとWebサービスの関係を次に示します。

図10‒3　Webサービスクライアント側のJAX-WSエンジンとWebサービスの関係（スタブベースの場合）

Webサービスクライアント側のJAX-WSエンジンが呼び出せるWebサービスの条件を次に示します。

Application ServerのJAX-WS機能が提供しているコマンドで開発したWebサービス実装クラス

Application ServerのJAX-WS機能が提供しているコマンドで開発し，JAX-WSエンジン上にデプロイされたWebサービス実装クラスを呼び出せます。接続先のApplication ServerのJAX-WS機能が以前のバージョンの場合，そのバージョンでサポートしている機能だけを使用できます。

SOAP通信基盤で動作するRPC形態のSOAPアプリケーション

SOAPアプリケーション開発支援機能で開発し，SOAP通信基盤にデプロイされたRPC形態のSOAPアプリケーションを呼び出せます。

開発時のSOAPアプリケーション開発支援機能およびSOAP通信基盤のバージョンは，07-10以降である必要があります。また，SOAP通信基盤のJava2WSDLコマンドで生成したdocument/literal形式のSOAPアプリケーションである必要があります。

そのほかのWebサービス

Application ServerのJAX-WS機能がサポートする範囲で記述されたWSDLをメタデータとして公開し，WS-I Basic Profile 1.1およびAttachments Profile 1.0を適用した次のどれかの仕様に従ったSOAPメッセージ※を送受信できるWebサービスクライアントを利用できます。

SOAP 1.1仕様

SOAP 1.2仕様

SwA仕様（wsi:swaRef形式の添付ファイルを利用する場合）

MTOM/XOP仕様（MTOM/XOP仕様形式の添付ファイルを利用する場合）

WSDLのサポート範囲については，「20.1　WSDL 1.1仕様のサポート範囲」を参照してください。

注※

標準仕様の性質から，WS-I Basic Profile 1.1およびAttachments Profile 1.0を適用したSOAP 1.1仕様，SOAP 1.2仕様，SwA仕様，またはMTOM/XOP仕様でもまだあいまいな部分が残ります。したがって，相互接続性について十分に検証してから運用してください。

ディスパッチベースのWebサービスクライアントの場合

ディスパッチベースのWebサービスクライアントの場合の，Webサービスクライアント側のJAX-WSエンジンとWebサービスの関係を次に示します。

図10‒4　Webサービスクライアント側のJAX-WSエンジンとWebサービスの関係（ディスパッチベースの場合）

Webサービスクライアント側のJAX-WSエンジンが呼び出せるWebサービスの条件を次に示します。

Application ServerのJAX-WS機能が提供しているコマンドで開発したWebサービス実装クラス

Application ServerのJAX-WS機能が提供しているコマンドで開発し，JAX-WSエンジン上にデプロイされたWebサービス実装クラスを呼び出せます。Application ServerのJAX-WS機能が以前のバージョンの場合，そのバージョンでサポートしている機能だけを使用できます。

Application ServerのJAX-WS機能が提供しているコマンドで開発したプロバイダ実装クラス

Application ServerのJAX-WS機能が提供しているコマンドで開発し，JAX-WSエンジン上にデプロイされたプロバイダ実装クラスを呼び出せます。

SOAP通信基盤で動作するRPC形態のSOAPアプリケーション

SOAPアプリケーション開発支援機能で開発し，SOAP通信基盤にデプロイされたRPC形態のSOAPアプリケーションを呼び出せます。

開発時のSOAPアプリケーション開発支援機能およびSOAP通信基盤のバージョンは，07-10以降である必要があります。また，SOAP通信基盤のJava2WSDLコマンドで生成したdocument/literal形式のSOAPアプリケーションである必要があります。

SOAP通信基盤で動作するメッセージング形態のSOAPアプリケーション

SOAPアプリケーション開発支援機能で開発し，バージョン07-10以降のSOAP通信基盤でデプロイしたメッセージング形態のSOAPアプリケーションのクライアントを利用できます。

SOAPアプリケーション開発支援機能とApplication ServerのJAX-WS機能の両方でサポートする範囲のSOAPメッセージを送受信するSOAPアプリケーションである必要があります。

そのほかのWebサービス

Application ServerのJAX-WS機能がサポートする範囲で記述されたWSDLをメタデータとして公開し，WS-I Basic Profile 1.1およびAttachments Profile 1.0を適用した次のどれかの仕様に従ったSOAPメッセージ※を送受信できるWebサービスクライアントを利用できます。

SOAP 1.1仕様

SOAP 1.2仕様

SwA仕様（wsi:swaRef形式の添付ファイルを利用する場合）

WSDLのサポート範囲については，「20.1　WSDL 1.1仕様のサポート範囲」を参照してください。

注※

標準仕様の性質から，WS-I Basic Profile 1.1およびAttachments Profile 1.0を適用したSOAP 1.1仕様，SOAP 1.2仕様，またはSwA仕様でもまだあいまいな部分が残ります。したがって，相互接続性について十分に検証してから運用してください。WSDLをメタデータとして公開していない場合，送受信できるSOAPメッセージの自由度が大きくなるので，特に注意してください。

(3)　配列またはjava.util.Listを利用する場合の注意事項

SOAPメッセージを送信する場合，配列やjava.util.Listオブジェクトの要素数が0で空の状態と，nullである状態は区別されないので，注意してください。

「10.2.1(3)(a)　SOAPメッセージを送信する場合」および「10.2.1(3)(b)　SOAPメッセージを受信する場合」では，JAX-WSエンジンの動作について説明します。また，特にWeb サービス側もWeb サービスクライアント側もApplication ServerのJAX-WS 機能を使用する場合の動作について「10.2.1(3)(c)　Webサービス側もWebサービスクライアント側もApplication ServerのJAX-WS機能を使用する場合」で説明します。

説明は次のメソッドを例にします。

@WebMethod
public List<String> test( List<Integer> param )

(a)　SOAPメッセージを送信する場合

Webサービスクライアントの実装クラスが上記のメソッドを次のように呼び出した場合のリクエストメッセージについて説明します。

第1引数にnullを与えてメソッドを呼び出した

第1引数に要素数が0であるjava.util.Listの具象クラスのオブジェクトを与えてメソッドを呼び出した

この場合に，Webサービスクライアント側のJAX-WSエンジンが送信するリクエストメッセージの抜粋を次に示します。

<test/>

どちらの条件でメソッドを呼び出した場合も，paramパラメタに対応する要素はリクエストメッセージには出現しません。Webサービスの実装クラスが戻り値を返す場合のレスポンスメッセージについても同様です。

(b)　SOAPメッセージを受信する場合

次の表に示す条件のどれかが満たされている場合，「10.2.1(3)(a)　SOAPメッセージを送信する場合」で説明したメッセージを受信したWebサービスクライアントやWebサービスの実装クラスは，要素数が0で空の状態である，配列やjava.util.Listの具象クラスのオブジェクトを受け取ります。

表10‒2　空の配列またはjava.util.Listの具象クラスのオブジェクトを受け取る条件

項番

条件

1

Webサービスクライアントの実装クラスでjava.util.Listオブジェクトを操作する場合

2

WSDLを起点として開発したWebサービスの実装クラスでjava.util.Listオブジェクトを操作する場合

3

SEIを起点として開発したWebサービスの実装クラスで，WSDLのオペレーションに対応するメソッド（WebMethodアノテーションでアノテートされたメソッド）の引数に直接出現する配列やjava.util.Listを操作する場合

なお，SEIを起点として開発したWebサービス実装クラスで，WSDLのオペレーションに対応するメソッドの引数に出現するJavaBeansクラスが持つ配列やjava.util.Listのプロパティは，そのJavaBeansクラスの実装に依存します。プロパティに対応する要素がリクエストメッセージにない場合，JavaBeansクラスは，nullである配列やjava.util.Listの具象クラスのオブジェクトを受け取ります。

(c)　Webサービス側もWebサービスクライアント側もApplication ServerのJAX-WS機能を使用する場合

Application ServerのJAX-WSエンジンの動作は，「10.2.1(3)(a)　SOAPメッセージを送信する場合」および「10.2.1(3)(b)　SOAPメッセージを受信する場合」で説明したとおりです。特にWebサービスクライアントおよびWebサービスの両方がApplication Server上にある場合，表10-2に示す条件を満たすWebサービスクライアントの実装クラスやWebサービスの実装クラスで，WebサービスクライアントおよびWebサービスのどちらか一方が配列やjava.util.Listオブジェクトとしてnullを送信しても，もう一方は要素数が0である配列やjava.util.Listの具象クラスを受信するので，注意してください。

10.2.2　ディスカバリとディスパッチ

JAX-WSエンジン上では，SOAPメッセージの送受信を実現するために，Webサービス実装クラスのディスカバリ，およびSOAPメッセージのディスパッチが行われます。

ここでは，Webサービス実装クラスのディスカバリ，SOAPメッセージのディスパッチ，およびフォルトと例外クラスのマッピングについて説明します。

また，インタフェースの透過性についても説明します。

(1)　ディスカバリ

Webサービス側のJAX-WSエンジンによって，Webサービスクライアントから要求されたWebサービス実装クラスまたはプロバイダ実装クラスが見つけ出されます。このことをディスカバリといいます。

ディスカバリでは，SOAP要求メッセージで要求されたURLから，適切なWebサービス実装クラスをマッピングする処理が行われます。ここでは，次のURLが要求された場合のマッピングについて説明します。

http://example.org/fromwsdl/TestJaxWsService

コンテキストルートを"fromwsdl"とした場合，コンテキストルートの後ろの"/TestJaxWsService"（下線部）はパス情報を表します。このパス情報を基に，Webサービス実装クラスまたはプロバイダ実装クラスがマッピングされます。

パス情報とのマッピングについて，Webサービス実装クラスの場合の例を次に示します。

図10‒5　Webサービス実装クラスのディスカバリ（POJOのWebサービス）

図10‒6　Webサービス実装クラスのディスカバリ（EJBのWebサービス）

Webサービス側のJAX-WSエンジンは，デプロイされているWebサービス実装クラスまたはプロバイダ実装クラスのうち，パス情報に対応するクラスを呼び出します。

POJOのWebサービスの場合，javax.jws.WebServiceアノテーションまたはjavax.xml.ws.WebServiceProviderアノテーションのserviceName属性が，パス情報から先頭のスラッシュ（/）を取り除いた文字列に等しいものを呼び出します。

EJBのWebサービスの場合，javax.jws.WebServiceアノテーションのserviceName属性が，パス情報の先頭のスラッシュ（/）と2番目のスラッシュ（/）の間の文字列に等しく，javax.jws.WebServiceアノテーションのname属性の値が，パス情報の2番目のスラッシュ（/）より後ろの文字列に等しいものを呼び出します。

javax.jws.WebServiceアノテーションおよびjavax.xml.ws.WebServiceProviderアノテーションのserviceName属性は省略できます。省略されている場合は，JSR-181仕様に基づいて，Webサービス実装クラスまたはプロバイダ実装クラスのクラス名（単純名）にサフィックスとして"Service"を付加された文字列が，serviceName属性の値と見なされます。また，javax.jws.WebServiceアノテーションのname属性は省略できます。省略されている場合は，JSR-181仕様に基づいて，Webサービス実装クラスのクラス名（単純名）がname属性の値と見なされます。

POJOのWebサービスの例でのパス情報と，呼び出されるWebサービス実装クラスの対応を示します。

パス情報がSample1Serviceの場合

Webサービス実装クラスA（org.foo.Test1.java）が呼び出されます。

パス情報がSample2Serviceの場合

Webサービス実装クラスB（org.foo.Test2.java）が呼び出されます。

パス情報がTest3Serviceの場合

Webサービス実装クラスC（org.foo.Test3.java）が呼び出されます。

EJBのWebサービスの例でのパス情報と，呼び出されるWebサービス実装クラスの対応を示します。

パス情報が/Sample1Service/Sample1の場合

EJB 1（org.foo.Test1.java）が呼び出されます。

パス情報が/Sample2Service/Test2の場合

EJB 2（org.foo.Test2.java）が呼び出されます。

パス情報が/Test3Service/Test3の場合

EJB 3（org.foo.Test3.java）が呼び出されます。

このマッピングは，cosminexus-jaxws.xmlを記述することでカスタマイズできます。次に示すcosminexus-jaxws.xmlの記述例を基に，マッピングのカスタマイズについて説明します。

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime'>
    <endpoint
        name="test1"
        implementation="org.foo.Test1"
        url-pattern="/test1"
    />
    <endpoint
        name="test2"
        implementation="org.foo.Test2"
        url-pattern="/test2"
    />
    <endpoint
        name="test3"
        implementation="org.foo.Test3"
        url-pattern="/test3"
    />
</endpoints>

この例でのパス情報と，呼び出されるWebサービス実装クラスの対応を示します。

パス情報がtest1の場合

Webサービス実装クラスA（org.foo.Test1.java）が呼び出されます。

パス情報がtest2の場合

Webサービス実装クラスB（org.foo.Test2.java）が呼び出されます。

パス情報がtest3の場合

Webサービス実装クラスC（org.foo.Test3.java）が呼び出されます。

ただし，cosminexus-jaxws.xmlのurl-pattern属性と，web.xmlのurl-pattern要素は，1対1で対応している必要があります。したがって，この例のマッピングをカスタマイズした場合は，web.xmlでも記述を変更する必要があります。web.xmlの記述例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app ...>
  ...
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/test1</url-pattern>
    <url-pattern>/test2</url-pattern>
    <url-pattern>/test3</url-pattern>
  </servlet-mapping>
  ...
</web-app>

cosminexus-jaxws.xmlのカスタマイズ方法については，「10.3　cosminexus-jaxws.xmlによるカスタマイズ」を参照してください。

(2)　SOAPメッセージのディスパッチ

Webサービス側のJAX-WSエンジンでは，発見した対象がWebサービス実装クラスの場合，受信したSOAPメッセージの内容に応じてオペレーションに対応するメソッドが呼び出され，実行されます。発見した対象がプロバイダ実装クラスの場合，アンマーシャルしたSOAPメッセージはプロバイダ実装クラスが指定するオブジェクトに変換され，invoke()メソッドが呼び出さます。

このことをSOAPメッセージのディスパッチといいます。

SOAPメッセージは，WS-I Basic Profile 1.1およびAttachments Profile 1.0を適用した，次のどれかの仕様に準拠していなければなりません。

SOAP 1.1仕様

SOAP 1.2仕様

SwA仕様（wsi:swaRef形式の添付ファイルを利用する場合）

MTOM/XOP仕様（MTOM/XOP仕様形式の添付ファイルを利用する場合）

SOAP 1.1仕様の場合のSOAPメッセージの例を次に示します。なお，添付ファイルを付けないSOAPメッセージの例を示します。添付ファイル付きSOAPメッセージについては，「28.4　添付ファイル付きSOAPメッセージ（wsi:swaRef形式）」を参照してください。

POST http://sample.org/fromjava/AddNumbersImplService HTTP/1.1
SOAPAction: ""
Content-Type: text/xml;charset="utf-8"
Accept: text/xml, multipart/related, text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:add xmlns:ns2="http://sample.com/">
      <arg0>256</arg0>
      <arg1>103</arg1>
    </ns2:add>
  </S:Body>
</S:Envelope>

メッセージ先頭にHTTPリクエストライン（POSTの行）およびHTTPリクエストのヘッダフィールド（SOAPAction，Content-Type，およびAcceptの行）が続きます。そのあとに空白行が入り，SOAPメッセージが続きます。このSOAPメッセージの内容を基に，適切なSEIが呼び出されて処理されます。

HTTPリクエストのヘッダフィールドには，空文字（""）が設定されたSOAPActionヘッダが必要です。SOAPActionヘッダに値が設定されていたとしても，JAX-WSエンジンによって無視されます。SOAPActionヘッダの値が引用符「"」で囲まれていない場合，エラーメッセージが出力されます（KDJW3022-W）。また，SOAPActionヘッダがHTTPリクエストに含まれていない場合の動作については，動作定義ファイルの設定によって異なります。動作定義ファイル設定については，「10.1　動作定義ファイル」を参照してください。

SOAP 1.2仕様の場合のSOAPメッセージの例を次に示します。なお，添付ファイルを付けないSOAPメッセージの例を示します。添付ファイル付きSOAPメッセージについては，「28.4　添付ファイル付きSOAPメッセージ（wsi:swaRef形式）」を参照してください。

POST http://sample.org/fromjava/AddNumbersImplService HTTP/1.1
Content-Type: application/soap+xml;charset="utf-8";action=""
Accept: application/soap+xml, multipart/related, text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <ns2:add xmlns:ns2="http://sample.com/">
      <arg0>256</arg0>
      <arg1>103</arg1>
    </ns2:add>
  </S:Body>
</S:Envelope>

SOAP 1.2仕様の場合，SOAPActionヘッダは，HTTPリクエストのヘッダフィールドに出現しても無視されます。また，actionパラメタは省略できます。

10.3　cosminexus-jaxws.xmlによるカスタマイズ

cosminexus-jaxws.xmlは，POJOのWebサービスのURLとWebサービス実装クラスまたはプロバイダ実装クラスのマッピングをカスタマイズするためのDDです。Webサービス実装クラスまたはプロバイダ実装クラスを見つけ出す処理（ディスカバリ）をカスタマイズしたい場合，または複数のURLに対して単一のWebサービス実装クラスおよびプロバイダ実装クラスを割り当てたい場合に作成します。

マッピングをカスタマイズしない場合，cosminexus-jaxws.xmlは不要です。また，cosminexus-jaxws.xmlをEJB JARファイルに含めても，EJBのWebサービスには適用されません。

マッピングのカスタマイズについては，「10.2.2(1)　ディスカバリ」を参照してください。

マッピングをカスタマイズする場合，cosminexus-jaxws.xmlが正しく記述されているか注意してください。cosminexus-jaxws.xmlはWebサービスの初期化時に読み込まれます。したがって，cosminexus-jaxws.xmlの読み込みでエラーが発生した場合，Webサービスの初期化に失敗します。Webサービスの初期化については，「10.9.1　Webサービスの初期化」を参照してください。

ここでは，cosminexus-jaxws.xmlのファイル名と格納先，および書式について説明します。

10.3.1　cosminexus-jaxws.xmlのファイル名と格納先

cosminexus-jaxws.xmlは，WARファイルに含めます。cosminexus-jaxws.xmlを含める場合は，WEB-INFディレクトリ直下に，cosminexus-jaxws.xmlという名称で含めてください。ファイル名と格納先を次に示します。

<WARのルート>/WEB-INF/cosminexus-jaxws.xml

10.3.2　cosminexus-jaxws.xmlの書式

cosminexus-jaxws.xmlのフォーマットとエンコーディングを次に示します。このフォーマットとエンコーディング以外で記述した場合の動作は保証されません。

フォーマット：XML バージョン 1.0

エンコーディング：UTF-8

cosminexus-jaxws.xmlで指定できる要素を次の表に示します。

表10‒3　cosminexus-jaxws.xmlの要素一覧

要素名

指定個数

説明

jaxwsdd:endpoints要素

1個

ルート要素です。

┗

jaxwsdd:endpoint要素

1個以上

URLと，Webサービス実装クラスまたはプロバイダ実装クラスのマッピングを指定します。

各要素および属性について説明します。

(1)　jaxwsdd:endpoints要素（cosminexus-jaxws.xml）

jaxwsdd:endpoints要素は，cosminexus-jaxws.xmlのルート要素です。属性は持ちません。

(2)　jaxwsdd:endpoint要素（cosminexus-jaxws.xml）

jaxwsdd:endpoint要素には，URLと，Webサービス実装クラスまたはプロバイダ実装クラスのマッピングを記述します。1個のjaxwsdd:endpoint要素に1個のマッピングを記述します。Webサービスが複数のポートを持つような場合（一つのWebサービスが複数のURLで提供される場合）や，同じWARファイル内に複数のWebサービスがある場合は，ポートやWebサービスに対応した数のjaxwsdd:endpoint要素を記述する必要があります。

jaxwsdd:endpoint要素の属性の一覧を次の表に示します。

表10‒4　jaxwsdd:endpoint要素の属性一覧

項番

属性名

必須

説明

1

name

○

jaxwsdd:endpoint要素を区別するための名前を指定します。

2

implementation

○

Webサービス実装クラスまたはプロバイダ実装クラスを指定します。

3

port

×

Webサービス実装クラスまたはプロバイダ実装クラスと対応づけるポートを指定します。javax.jws.WebServiceアノテーション，またはjavax.xml.ws.WebServiceProviderアノテーションの設定よりも優先されます。一つのWebサービス実装クラスまたはプロバイダ実装クラスを複数のURLにマッピングする場合に指定します。

4

url-pattern

○

Webサービス実装クラスまたはプロバイダ実装クラスと対応づけるURLを指定します。web.xmlのurl-pattern要素と対応しています。

（凡例）

○：指定が必須であることを示します。

×：指定が必須でないことを示します。

(a)　name属性（cosminexus-jaxws.xml）

jaxwsdd:endpoint要素を区別するための名前を空文字列以外の文字列（Javaで扱える文字列）で指定します。

空文字列を指定した場合，デプロイ時にKDJW20031-Eのメッセージが出力されます。同じcosminexus-jaxws.xml内では一意の値にする必要があります。同じname属性値を持つjaxwsdd:endpoint要素が複数ある場合，KDJW40007-Wのメッセージが出力されます。

(b)　implementation属性（cosminexus-jaxws.xml）

javax.jws.WebServiceアノテーションを持つクラスのクラス名を指定します。

空文字列を指定した場合，デプロイ時にKDJW20031-Eのメッセージが出力されます。また，存在しないクラスを指定した場合，デプロイ時にKDJW20014-Eのメッセージが出力されます。

複数のURLに対して同じWebサービス実装クラスまたはプロバイダ実装クラスをマッピングする場合は，port属性が一意になるように記述してください。特にWebサービス実装クラスの場合，port属性の記述がないときやport属性値が一意でないとき，メタデータとして不正なWSDLが発行されます。

(c)　port属性（cosminexus-jaxws.xml）

メタデータとして発行するWSDLのポート名（wsdl:port要素のname属性の値）のQNameを指定します。メタデータの発行については，「10.6　メタデータの発行」を参照してください。

この属性は省略できます。属性を省略した場合や空文字列が指定された場合，implementation属性で指定したクラスのjavax.jws.WebServiceアノテーション，またはjavax.xml.ws.WebServiceProviderアノテーションのportName属性の値が使用されます。portName属性が省略されている場合は，JSR-181仕様に従って，Webサービス実装クラスまたはプロバイダ実装クラスの単純名にサフィックスとして"Port"を付加した文字列が使用されます。

複数のURLに対して同じWebサービス実装クラスをマッピングする場合，port属性を指定しないとメタデータが正常に発行されません。

(d)　url-pattern属性（cosminexus-jaxws.xml）

implementation属性で指定したWebサービス実装クラスまたはプロバイダ実装クラスと対応づけるパス情報を指定します。url-pattern属性で指定した値に基づいて，ディスカバリが行われます。ディスカバリについては，「10.2.2(1)　ディスカバリ」を参照してください。

パス情報は，明確な値でなければなりません（アスタリスクなどのワイルドカードは使用できません）。また，web.xmlのurl-pattern要素の値と1対1になるように指定する必要があります。

例えば，url-pattern属性に"/path1"を指定した場合，"/path1"へのリクエストに対して，implementation属性で指定したクラスがマッピングされます。

同じcosminexus-jaxws.xml内では一意の値にする必要があります。同じurl-pattern属性値を持つjaxwsdd:endpoint要素が複数ある場合，KDJW40009-Wのメッセージが出力されます。この場合，同じurl-pattern属性値を持つjaxwsdd:endpoint要素の中で，最初のjaxwsdd:endpoint要素に記述されたマッピングだけが有効になります。

(3)　cosminexus-jaxws.xml使用時の設定例

次のWebサービスに対応したDDの記述例を示します。

表10‒5　Webサービス実装クラスと対応するURLの例

項番

Webサービス実装クラス

URL

1

com.sample.AddNumbersImplA

/test1

2

com.sample.AddNumbersImplB

/test2，/test3

web.xmlの例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;fromwsdl&quot;</description>
  <display-name>Sample_web_service_fromwsdl</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/test1</url-pattern>
    <url-pattern>/test2</url-pattern>
    <url-pattern>/test3</url-pattern>
  </servlet-mapping>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

cosminexus-jaxws.xmlの例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime'>
    <endpoint
        name="test1"
        implementation="com.sample.AddNumbersImplA"
        url-pattern="/test1"
    />
    <endpoint
        name="test2"
        implementation="com.sample.AddNumbersImplB"
        url-pattern="/test2"
        port="{http://sample.com}port1"
    />
    <endpoint
        name="test3"
        implementation="com.sample.AddNumbersImplB"
        url-pattern="/test3"
        port="{http://sample.com}port2"
    />
</endpoints>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

10.4　フォルトと例外の処理

JAX-WSエンジンは，Webサービス側およびWebサービスクライアント側とも，JAX-WS 2.2仕様に基づいてフォルトと例外をバインディングします。POJOとEJBの両方のWebサービスで動作します。

JAX-WSエンジンでのフォルトおよび例外の処理について説明します。

10.4.1　Webサービス側のフォルトおよび例外の処理

Webサービス側のJAX-WSエンジンでのフォルトおよび例外の処理について説明します。なお，Webサービスがプロバイダ実装クラスで実装されている場合，この処理は実行されません。

(1)　サービス固有例外の処理

WSDLのフォルトとJavaの例外は，JAX-WS 2.2仕様に従ってマッピングされます。WSDLのフォルトとJavaの例外クラスのマッピング例を次の図に示します。

図10‒7　WSDLのフォルトとJavaの例外クラスのマッピング例

マッピング例では，UserDefinedFaultフォルトがフォルトbean（com.example.sample.UserDefinedFault）と，ラッパ例外クラス（com.example.sample.UserDefinedException）にマッピングされていることがわかります。

フォルトと例外クラスのマッピングについては，「15.1.7　フォルトから例外クラスへのマッピング」，および「16.1.7　Javaのラッパ例外クラスからフォルトへのマッピング」を参照してください。

Webサービス側のJAX-WSエンジンによって，ラッパ例外クラスは次の表のようにSOAPフォルトにバインディングされます。

表10‒6　ラッパ例外クラスのバインディング

項番

SOAPフォルトの子要素

内容

SOAP 1.1仕様

SOAP 1.2仕様

1

faultcode

soapenv12:Code

SOAP 1.1仕様

QName soapenv:serverで固定です。

SOAP 1.2仕様

QName soapenv12:Receiverで固定です。

2

faultstring

soapenv12:Reason

ラッパ例外クラスに対してgetMessageメソッドを実行した結果になります。

3

faultactor

soapenv12:Role

ありません。

4

detail

soapenv12:Detail

フォルトbeanをマーシャルした結果になります。

ラッパ例外クラスをWebサービス実装クラスでスローする例を示します。

//フォルトbeanを生成し，マーシャルすべき情報を設定する
UserDefinedFault fault = new UserDefinedFault();
fault.additionalInfo = 257;
fault.detail = "Failed by some reason.";
fault.message = "Contact your administrator.";

//ラッパ例外クラスをスロー
throw new UserDefinedException(
  "Something happens.", fault );

送信されるSOAP 1.1仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <S:Fault xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <faultcode>S:Server</faultcode>
      <faultstring>Something happens.</faultstring>
      <detail>
        <ns2:UserDefinedFault xmlns:ns2="http://example.com/sample">
          <additionalInfo>257</additionalInfo>
          <detail>Failed by some reason.</detail>
          <message>Contact your administrator.</message>
        </ns2:UserDefinedFault>
      </detail>
    </S:Fault>
  </S:Body>
</S:Envelope>

注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <S:Fault xmlns:ns3="http://schemas.xmlsoap.org/soap/envelope/">
      <S:Code>
        <S:Value>S:Receiver</S:Value>
      </S:Code>
      <S:Reason>
        <S:Text xml:lang="ja">Something happens.</S:Text>
      </S:Reason>
      <S:Detail>
        <ns2:UserDefinedFault xmlns:ns2="http://example.com/sample">
          <additionalInfo>257</additionalInfo>
          <detail>Failed by some reason.</detail>
          <message>Contact your administrator.</message>
        </ns2:UserDefinedFault>
      </S:Detail>
    </S:Fault>
  </S:Body>
</S:Envelope>

注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

(2)　ランタイム例外のバインディング

Webサービス実装クラス内でjavax.xml.ws.WebServiceException以外のランタイム例外がスローされた場合，Webサービス側のJAX-WSエンジンによって，ランタイム例外がSOAPフォルトにバインディングされます（JAX-WS 2.2仕様に基づいてバインディング）。

ランタイム例外のバインディングの例を次の表に示します。

表10‒7　ランタイム例外のバインディング

項番

SOAPフォルトの子要素

内容

SOAP 1.1仕様

SOAP 1.2仕様

1

faultcode

soapenv12:Code

SOAP 1.1仕様

QName soapenv:serverで固定です。

SOAP 1.2仕様

QName soapenv12:Receiverで固定です。

2

faultstring

soapenv12:Reason

ランタイム例外に対してgetMessageメソッドを実行した結果になります。

3

faultactor

soapenv12:Role

ありません。

4

detail

soapenv12:Detail

ありません。

ランタイム例外のスローの例を示します。

//ランタイム例外をスロー
throw new IllegalArgumentException( "Something illegal." );

送信されるSOAP 1.1仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <S:Fault xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <faultcode>S:Server</faultcode>
      <faultstring>Something illegal.</faultstring>
    </S:Fault>
  </S:Body>
</S:Envelope

注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <S:Fault xmlns:ns3="http://schemas.xmlsoap.org/soap/envelope/">
      <S:Code>
        <S:Value>S:Receiver</S:Value>
      </S:Code>
      <S:Reason>
        <S:Text xml:lang="ja">Something illegal.</S:Text>
      </S:Reason>
    </S:Fault>
  </S:Body>
</S:Envelope>

注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

(3)　javax.xml.ws.WebServiceExceptionのバインディング

Webサービス実装クラスまたはプロバイダ実装クラス内でjavax.xml.ws.soap.SOAPFaultException以外のjavax.xml.ws.WebServiceExceptionがスローされた場合，Webサービス側のJAX-WSエンジンによって，javax.xml.ws.WebServiceExceptionがSOAPフォルトにバインディングされます（JAX-WS 2.2仕様に基づいてバインディング）。

javax.xml.ws.WebServiceExceptionのバインディングの例を次の表に示します。

表10‒8　javax.xml.ws.WebServiceExceptionのバインディング

項番

SOAPフォルトの子要素

内容

SOAP 1.1仕様

SOAP 1.2仕様

1

faultcode

soapenv12:Code

SOAP 1.1仕様

QName soapenv:serverで固定です。

SOAP 1.2仕様

QName soapenv12:Receiverで固定です。

2

faultstring

soapenv12:Reason

javax.xml.ws.soap.SOAPFaultExceptionに対してgetMessageメソッドを実行した結果になります。SOAP 1.2の場合，xml:lang属性にはJavaVMのデフォルトのロケールが設定されます。

3

faultactor

soapenv12:Role

ありません。

4

detail

soapenv12:Detail

ありません。

javax.xml.ws.WebServiceExceptionのスローの例を示します。

//javax.xml.ws.WebServiceExceptionをスロー
throw new javax.xml.ws.WebServiceException( "Web Service Exception." );

送信されるSOAP 1.1仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <S:Fault xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <faultcode>S:Server</faultcode>
      <faultstring>Web Service Exception.</faultstring>
    </S:Fault>
  </S:Body>
</S:Envelope>

注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <S:Fault xmlns:ns3="http://schemas.xmlsoap.org/soap/envelope/>
      <S:Code>
        <S:Value>S:Receiver</S:Value>
      </S:Code>
      <S:Reason>
        <S:Text xml:lang="ja">Something illegal.</S:Text>
      </S:Reason>
    </S:Fault>
  </S:Body>
</S:Envelope>

注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

(4)　javax.xml.ws.soap.SOAPFaultExceptionのバインディング

Webサービス実装クラスまたはプロバイダ実装クラス内で，javax.xml.ws.soap.SOAPFaultExceptionがスローされた場合，Webサービス側のJAX-WSエンジンによって，javax.xml.ws.soap.SOAPFaultExceptionがSOAPフォルトにバインディングされます（JAX-WS 2.2仕様に基づいてバインディング）。

javax.xml.ws.soap.SOAPFaultExceptionのバインディングの例を次の表に示します。

表10‒9　javax.xml.ws.soap.SOAPFaultExceptionのバインディング

項番

SOAPフォルトの子要素

内容

SOAP 1.1仕様

SOAP 1.2仕様

1

faultcode

soapenv12:Code

SOAP 1.1仕様

getFault().getFaultCodeAsQNameメソッドの結果になります。

ただし，nullの場合はQName soapenv:serverで固定です。

SOAP 1.2仕様

QName soapenv12:Senderで固定です。soapenv12:Codeの子要素のsoapenv12:Subcodeが結果を持ちます。

2

faultstring

soapenv12:Reason

getFaultReasonTextメソッドの結果になります。

ただし，nullの場合はgetMessageメソッドを実行した結果になります。

3

faultactor

soapenv12:Role

getFault().getFaultRoleメソッドの結果になります。

ただし，nullの場合はありません。

4

detail

soapenv12:Detail

getFault().getDetailメソッドを実行した結果をマーシャルした結果になります。

ただし，nullの場合はありません。

SOAP 1.1仕様の場合の，javax.xml.ws.soap.SOAPFaultExceptionのスローの例を示します。

SOAPFault soapFault = ...;
soapFault.setFaultCode( new QName( "http://sample.org", "UserDefined" ) );
soapFault.setFaultActor( "http://example.com/sample" );
soapFault.setFaultString( "SOAPFaultException happens." );
Detail detail = soapFault.addDetail();
SOAPElement soapElement = detail.addChildElement( new QName( "", "detailTest" ) );
soapElement.addTextNode( "TEST." );

//javax.xml.ws.soap.SOAPFaultExceptionをスロー
throw new SOAPFaultException( soapFault );

SOAP 1.2仕様の場合の，javax.xml.ws.soap.SOAPFaultExceptionのスローの例を示します。

SOAPFactory soapFactory = SOAPFactory.newInstance( SOAPConstants.SOAP_1_2_PROTOCOL );
SOAPFault soapFault = soapFactory.createFault();
soapFault.appendFaultSubcode( new QName( "http://sample.org", "UserDefined" ) );
soapFault.setFaultRole( "http://example.com/sample" );
soapFault.addFaultReasonText( "SOAPFaultException happens.", Locale.getDefault() );
Detail detail = soapFault.addDetail();
SOAPElement soapElement = detail.addChildElement( new QName( "", "detailTest" ) );
soapElement.addTextNode( "TEST." );

//javax.xml.ws.soap.SOAPFaultExceptionをスロー
throw new SOAPFaultException( soapFault );

送信されるSOAP 1.1仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <S:Fault xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <faultcode xmlns:ns0="http://sample.org">ns0:UserDefined</faultcode>
      <faultstring>SOAPFaultException happens.</faultstring>
      <faultactor>http://example.com/sample</faultactor>
      <detail><detailTest>TEST.</detailTest></detail>
    </S:Fault>
  </S:Body>
</S:Envelope>

注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <S:Fault xmlns:ns3="http://schemas.xmlsoap.org/soap/envelope/">
      <S:Code>
        <S:Value>S:Sender</S:Value>
        <S:Subcode>
          <S:Value xmlns:ns0="http://sample.org">ns0:UserDefined</S:Value>
        </S:Subcode>
      </S:Code>
      <S:Reason>
        <S:Text xml:lang="ja">SOAPFaultException happens.</S:Text>
      </S:Reason>
      <S:Role>http://example.com/sample</S:Role>
      <S:Detail>
        <detailTest>TEST.</detailTest>
      </S:Detail>
    </S:Fault>
  </S:Body>
</S:Envelope>

注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

10.4.2　Webサービスクライアント側のフォルトの処理

wsdl:fault要素に対応するSOAPフォルト，およびwsdl:fault要素に対応しないSOAPフォルトについてそれぞれ説明します。

wsdl:fault要素に対応するSOAPフォルト

Webサービスクライアント側のJAX-WSエンジンが，「10.4.1(1)　サービス固有例外の処理」に従ってマーシャルされたSOAPフォルトメッセージを受け取った場合，元のフォルトbeanとラッパ例外にアンマーシャルされ，Webサービスクライアントにスローされます。つまり，Webサービスでスローされたサービス固有例外は，透過的にWebサービスクライアントへ送信されます（この動作は，JAX-WS 2.2仕様に従っています）。

wsdl:fault要素に対応しないSOAPフォルト

Webサービスクライアント側のJAX-WSエンジンが，wsdl:fault要素に対応しないSOAPフォルトメッセージを受け取った場合，javax.xml.ws.soap.SOAPFaultExceptionにアンマーシャルされ，Webサービスクライアントにスローされます（この動作は，JAX-WS 2.2仕様に従っています）。

SOAP 1.2の場合，SOAPフォルトがsoapenv12:Text要素を複数持つとき，SOAPFaultExceptionオブジェクトが持つSOAPFaultオブジェクトにはReason Textが一つだけ設定されます。次に示す個所の値（文字列）およびロケールが設定されます。

値：最後のsoapenv12:Text要素の値

ロケール：JavaVMのデフォルトのロケール

10.4.3　Java例外の伝搬

WebサービスおよびWebサービスクライアントの両方が，Application ServerのJAX-WSエンジン上にデプロイされている場合，Webサービスで発生したJava例外をWebサービスクライアントに伝搬できます。POJOとEJBの両方のWebサービスで動作します。ここでは，Java例外の伝搬方法と動作について説明します。

注意事項

Java例外の伝搬は，SOAP 1.1仕様や，JAX-WS 2.2仕様で定められた機能ではないため，Application ServerのJAX-WS機能以外のWebサービス基盤製品と接続した場合に，意図しない動作をしたり，通信が失敗したりするおそれがあります。また，スタックトレースには，Webサービスの実装の内部情報（システムの設定情報や個人情報を扱っているのであればそのような情報など）も含まれることがあります。したがって，実運用でこの機能を使用することを想定して，Webサービスを実装することはお勧めしません。開発時に必要に応じて使用してください。

(1)　Java例外の伝搬方法

Webサービスで発生したJava例外を伝搬するには，動作定義ファイルでcom.cosminexus.jaxws.fault.SOAPFaultBuilder.captureStackTraceプロパティにtrueを設定します。

com.cosminexus.jaxws.fault.SOAPFaultBuilder.captureStackTraceプロパティについては，「10.1.2　共通定義ファイルの設定項目」を参照してください。

(2)　Java例外の伝搬時の動作（Webサービス側）

Webサービス側でのJava例外の伝搬時に，「10.4.1(2)」の「表10-7の項番4」，「10.4.1(3)」の「表10-8の項番4」および「10.4.1(4)」の「表10-9の項番4」にある要素の子要素として，Application ServerのJAX-WS機能独自の{http://jax-ws.dev.java.net/}exception要素が追加され，発生したJava例外のスタックトレースがマーシャルされます。

また，「10.4.1(1)」の「表10-6の項番4」にバインドされるフォルトbeanが存在しない場合，Webサービス側でのJava例外の伝搬時に，「10.4.1(1)」の「表10-6の項番4」にある要素の子要素として，Application ServerのJAX-WS機能独自の{http://jax-ws.dev.java.net/}exception要素が追加され，発生したJava例外のスタックトレースがマーシャルされます。

ランタイム例外のスローの例を示します。

//ランタイム例外をスロー
catch( NullPointerException ){
  throw new IllegalArgumentException( "Something illegal.", e );
}

このようにスローされた場合に，送信されるSOAP 1.1仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <S:Fault xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <faultcode>S:Server</faultcode>
      <faultstring>Something illegal.</faultstring>
      <detail>
        <ns2:exception xmlns:ns2="http://jax-ws.dev.java.net/"
          class="java.lang.IllegalArgumentException"
          note="To disable this feature, set com.cosminexus.jaxws.fault.SOAPFaultBuilder.captureStackTrace property to false">
          <message>Something illegal</message>
          <ns2:stackTrace>
            <ns2:frame class="com.example.sample.TestJaxWsImpl" file="TestJaxWsImpl.java" line="32" method="jaxWsTest1"/>
            <ns2:frame class="sun.reflect.NativeMethodAccessorImpl" file="NativeMethodAccessorImpl.java" line="native" method="invoke0"/>
            <ns2:frame class="sun.reflect.NativeMethodAccessorImpl" file="NativeMethodAccessorImpl.java" line="39" method="invoke"/>
            ...
            <ns2:frame class="java.lang.Thread" file="Thread.java" line="595" method="run"/>
          </ns2:stackTrace>
          <ns2:cause class="java.lang.NullPointerException"
              note="To disable this feature, set com.cosminexus.jaxws.fault.SOAPFaultBuilder.captureStackTrace property to false">
          <message>Something null.</message>
          <ns2:stackTrace>
            <ns2:frame class="com.example.sample.TestJaxWsImpl" file="TestJaxWsImpl.java" line="32" method="jaxWsTest1"/>
            <ns2:frame class="sun.reflect.NativeMethodAccessorImpl" file="NativeMethodAccessorImpl.java" line="native" method="invoke0"/>
            ...
            <ns2:frame class="sun.reflect.DelegatingMethodAccessorImpl" file="DelegatingMethodAccessorImpl.java" line="25" method="invoke"/>
            <ns2:frame class="java.lang.reflect.Method" file="Method.java" line="585" method="invoke"/>
            <ns2:frame class="org.apache.tomcat.util.threads.ThreadPool$ControlRunnable" file="ThreadPool.java" line="1510" method="run"/>
            <ns2:frame class="java.lang.Thread" file="Thread.java" line="595" method="run"/>
          </ns2:stackTrace>
          </ns2:cause>
        </ns2:exception>
      </detail>
    </S:Fault>
  </S:Body>
</S:Envelope>

送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <S:Fault xmlns:ns3="http://schemas.xmlsoap.org/soap/envelope/">
      <S:Code>
        <S:Value>S:Receiver</S:Value>
      </S:Code>
      <S:Reason>
        <S:Text xml:lang="ja">Something illegal.</S:Text>
      </S:Reason>
      <S:Detail>
        <detailTest>TEST.</detailTest>
        <ns2:exception xmlns:ns2="http://jax-ws.dev.java.net/"
           class="javax.xml.ws.soap.SOAPFaultException"
           note="To disable this feature, set com.cosminexus.jaxws.fault.SOAPFaultBuilder.captureStackTrace property to false">
           ...
           （SOAP 1.1仕様のSOAPフォルトと同じ）
           ...
        </ns2:exception>
      </S:Detail>
    </S:Fault>
  </S:Body>
</S:Envelope>

(3)　Java例外の伝搬時の動作（Webサービスクライアント側）

Webサービスクライアント側でのJava例外の伝搬時に，Webサービスクライアントにスローするラッパ例外クラス，またはjavax.xml.ws.soap.SOAPFaultExceptionのcauseに，{http://jax-ws.dev.java.net/}exception要素の情報からアンマーシャルしたcom.cosminexus.xml.ws.developer.ServerSideExceptionが設定されます。

Webサービスクライアントは，javax.xml.ws.soap.SOAPFaultExceptionのgetCauseメソッドを実行することで，Webサービス側で発生した例外のスタックトレースを含むcom.cosminexus.xml.ws.developer.ServerSideExceptionを取得できます。

10.4.4　例外をフォルトにバインディングする場合のHTTPステータスコード

Webサービス側のJAX-WSエンジンが例外をフォルトにバインディングしてWebサービスクライアントへ返す場合，HTTPレスポンスのステータスコードに"500 Internal Server Error"が設定されます。POJOとEJBの両方のWebサービスで動作します。

10.4.5　エラーページをカスタマイズする場合の注意事項

Webサービス側のJAX-WSエンジンが動作するJ2EEサーバや，Webサービスを含むWARファイルでエラーページをカスタマイズしている場合，HTTPステータスコード500はカスタマイズしないでください。Webサービス側のJAX-WSエンジンは，フォルトをWebサービスクライアントに返す場合，HTTPステータスコードに「500 Internal Server Error」を設定します。このため，HTTPステータスコード500をカスタマイズすると，SOAPフォルトではない不正なSOAPメッセージがWebサービスクライアントに送信されてしまいます。

10.5　インタフェースの透過性

WebサービスとWebサービスクライアントは，疎な関係にあり，相互のインタフェースはWSDLの定義内容だけです。Webサービス側は，WSDLを通じてWebサービスのインタフェース情報（メタデータ）を公開し，Webサービスクライアント側はそのメタデータを使用してSOAPメッセージを生成し，送受信します。

WebサービスおよびWebサービスクライアントの両方がApplication ServerのJAX-WSエンジンで動作する場合も，WSDL以外のインタフェース情報は交換されません。

Javaインタフェースの透過性はないため，SEIを起点としてWebサービスを開発した場合，Webサービス側とWebサービスクライアント側でメソッドシグネチャが異なることがあります。

ここでは，生成前のJavaメソッドと生成後のJavaメソッドの例を基に，メソッドシグネチャの違いについて説明します。

10.5.1　配列のパラメタを持つ場合

次に示すJavaメソッドを持つSEIを起点に，Webサービスを開発することを想定します。このJavaメソッドは，配列（int型）のパラメタを持ちます。

@WebMethod
public void test1( int[] param1 );

この場合にマッピングされるWSDLの一部を次に示します。

...
<types>
  <xsd:schema targetNamespace="http://cosminexus.com/jaxws">

    <xs:element name="test1" type="tns:test1"/>

    <xs:element name="test1Response" type="tns:test1Response"/>

    <xs:complexType name="test1">
      <xs:element name="arg0" type="xs:int" nillable="true"
        minOccurs="0" maxOccurs="unbounded" />
    </xs:complexType>

    <xs:complexType name="test1Response">
      <xs:sequence/>
    </xs:complexType>
  </xs:element>
</types>
<message name="test1">
  <part name="parameters" element="tns:test1"/>
</message>

<message name="test1Response">
  <part name="parameters" element="tns:test1Response"/>
</message>

<portType ...>
  <operation name="test1">
    <input message="tns:test1"/>
    <output message="tns:test1Response"/>
  </operation>
  ...
</portType>
...

パラメタは，maxOccurs="unbounded"のwrapper子要素にマッピングされます。

このWSDLを指定してcjwsimportコマンドを実行すると，生成されるサービスクラスのJavaメソッドは次のようになります。

@WebMethod
public String test1( java.util.List<Integer> arg0 );

maxOccurs="unbounded"のwrapper子要素は，java.util.Listクラスにマッピングされます。また，この場合，xsd:int型は，java.lang.Integerクラスにマッピングされます。

10.5.2　OUTパラメタを一つだけ持つ場合

次に示すJavaメソッドを持つSEIを起点に，Webサービスを開発することを想定します。このJavaメソッドは，OUTパラメタを一つだけ持ち，戻り値は持ちません。

@WebMethod
public void test1( @WebParam(mode=WebParam.Mode.OUT) Holder<String> param1 );

この場合にマッピングされるWSDLの一部を次に示します。

...
<types>
  <xsd:schema targetNamespace="http://cosminexus.com/jaxws">

    <xs:element name="test1" type="tns:test1"/>

    <xs:element name="test1Response" type="tns:test1Response"/>

    <xs:complexType name="test1">
      <xs:sequence/>
    </xs:complexType>

    <xs:complexType name="test1Response">
      <xs:sequence>
        <xs:element name="arg0" type="xs:string" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</types>
<message name="test1">
  <part name="parameters" element="tns:test1"/>
</message>

<message name="test1Response">
  <part name="parameters" element="tns:test1Response"/>
</message>

<portType ...>
  <operation name="test1">
    <input message="tns:test1"/>
    <output message="tns:test1Response"/>
  </operation>
  ...
</portType>
...

OUTパラメタは，wsdl:output要素から参照されるwrapper子要素にマッピングされます。

このWSDLを指定してcjwsimportコマンドを実行すると，生成されるサービスクラスのJavaメソッドは次のようになります。

@WebMethod
public String test1();

wsdl:output要素から参照されるwrapper子要素が1個だけなので，そのwrapper子要素は戻り値にマッピングされます。

10.5.3　non-wrapperスタイルの配列

次に示すJavaメソッドを持つSEIを起点に，Webサービスを開発することを想定します。このJavaメソッドは，non-wrapperスタイルで，java.lang.Stringクラスの配列のパラメタを持ちます。

@WebMethod
@javax.jws.soap.SOAPBinding(
  parameterStyle=javax.jws.soap.SOAPBinding.ParameterStyle.BARE)
public String test1( String[] param1 );

この場合にマッピングされるWSDLの一部を次に示します。

...
<types>
  <xsd:schema targetNamespace="http://jaxb.dev.java.net/array">
    <xsd:complexType name="stringArray" final="#all">
      <xsd:sequence>
        <xsd:element name="item" type="xsd:string" minOccurs="0"
          maxOccurs="unbounded" nillable="true" />
      </xsd:sequence>
    </xsd:complexType>
  </xsd:schema>

  <xsd:schema targetNamespace="http://cosminexus.com/jaxws"
    xmlns:ns1="http://jaxb.dev.java.net/array">
    <xsd:element name="test1" nillable="true" type="ns1:stringArray"/>
    <xsd:element name="test1Response" nillable="true" type="xsd:string"/>
  </xsd:schema>
</types>

<message name="test1">
  <part name="test1" element="tns:test1" />
</message>

<message name="test1Response">
  <part name="test1Response" element="tns:test1Response" />
</message>

<portType ...>
  <operation name="test1">
    <input message="tns:test1" />
    <output message="tns:test1Response" />
  </operation>
  ...
</portType>
...

パラメタは，{http://jaxb.dev.java.net/array}stringArray型のwrapper子要素にマッピングされます。

このWSDLを指定してcjwsimportコマンドを実行すると，生成されるサービスクラスのJavaメソッドは次のようになります。

@WebMethod
@javax.jws.soap.SOAPBinding(
  parameterStyle=javax.jws.soap.SOAPBinding.ParameterStyle.BARE)
public String test1(net.java.dev.jaxb.array.StringArray test1);

{http://jaxb.dev.java.net/array}stringArray型のwrapper子要素は，net.java.dev.jaxb.array.StringArrayクラスにマッピングされます。

10.6　メタデータの発行

Webサービス側のJAX-WSエンジンは，要求に応じてWebサービス（Webサービス実装クラスまたはプロバイダ実装クラス）のメタデータを記述したWSDLファイルを発行できます。発行されたWSDLファイルは，cjwsimportコマンドを使用してWebサービス，およびWebサービスクライアントの開発に必要なJavaコードを生成するときに利用できます。

ここでは，メタデータの発行を利用するに当たって，注意が必要な点について説明します。

10.6.1　メタデータの発行条件

POJOとEJBのWebサービスのそれぞれの発行条件を説明します。

(1)　POJOのWebサービスの場合

POJOのWebサービスのメタデータの発行条件を次の表に示します。Webサービス側のJAX-WSエンジンが，次の表に示す条件をすべて満たしたHTTPリクエストを受信したときにメタデータが発行されます。

表10‒10　POJOのWebサービスのメタデータの発行に必要なHTTPリクエスト

項番

項目

条件

1

HTTPメソッド

GETメソッド

2

URL

スキーマ

httpまたはhttps

3

ホスト名（:ポート番号）

メタデータの発行を要求するWebサービスが存在するホスト名（およびポート番号）

4

コンテキストパス

メタデータの発行を要求するWebサービスが含まれるWebアプリケーションのコンテキストパス

5

Webサービス名

メタデータの発行を要求するWebサービス（Webサービス実装クラスまたはプロバイダ実装クラスのサービス名）

6

クエリストリング

"wsdl"または"WSDL"（文字の大小は区別されます）

要求されたURLに対応するWebサービスに関連づけられたWSDLファイルが，HTTPレスポンスのコンテンツとして要求元に発行されます。リクエストURLには，次に示すようなクエリストリングを付加する必要があります。

GET http://sample.com:8085/fromjava/AddNumbersImplService?wsdl HTTP/1.1

GET http://sample.com:8085/fromjava/AddNumbersImplService?WSDL HTTP/1.1

(2)　EJBのWebサービスの場合

EJBのWebサービスのメタデータの発行条件を次の表に示します。Webサービス側のJAX-WSエンジンが，次の表に示す条件をすべて満たしたHTTPリクエストを受信したときにメタデータが発行されます。

表10‒11　EJBのWebサービスのメタデータの発行に必要なHTTPリクエスト

項番

項目

条件

1

HTTPメソッド

GETメソッド

2

URL

スキーマ

httpまたはhttps

3

ホスト名（:ポート番号）

メタデータの発行を要求するWebサービスが存在するホスト名（およびポート番号）

4

コンテキストパス

メタデータの発行を要求するWebサービスが含まれるWebアプリケーションのコンテキストパス

5

Webサービス名

メタデータの発行を要求するWebサービス（Webサービス実装クラスのサービス名）

6

EJBのクラス名

メタデータの発行を要求するWebサービスのEJBのクラス名

7

クエリストリング

"wsdl"または"WSDL"（文字の大小は区別されます）

要求されたURLに対応するWebサービスに関連づけられたWSDLファイルが，HTTPレスポンスのコンテンツとして要求元に発行されます。リクエストURLには，次に示すようなクエリストリングを付加する必要があります。

GET http://sample.com:8085/statelessjava/AddNumbersImplService/AddNumbersImpl?wsdl HTTP/1.1

GET http://sample.com:8085/statelessjava/AddNumbersImplService/AddNumbersImpl?WSDL HTTP/1.1

10.6.2　発行されるメタデータ

リクエスト時の条件と，発行されるメタデータの対応を次の表に示します。

表10‒12　リクエストの条件と発行されるメタデータの対応

項番

リクエスト時の条件

発行されるメタデータ

Webサービスの適用可否

POJO

EJB※

1

javax.jws.WebServiceアノテーション（Webサービス実装クラスの場合），またはjavax.xml.ws.WebServiceProviderアノテーション（プロバイダ実装クラスの場合）にwsdlLocation属性がある場合

wsdlLocation属性に指定された場所にあるWSDLファイルが返されます。

○

○

2

javax.jws.WebServiceアノテーション（Webサービス実装クラスの場合），またはjavax.xml.ws.WebServiceProviderアノテーション（プロバイダ実装クラスの場合）にwsdlLocation属性の指定はないが，デプロイされたWARファイルのWEB-INF/wsdlディレクトリにwsdl:service要素を持つWSDLファイルがある場合

デプロイされたWebアプリケーションのWEB-INF/wsdlディレクトリにあるWSDLファイルが返されます。

○

−

3

WSDLがWebアプリケーション内にない場合

（項番1および項番2以外の場合）

対象がWebサービス実装クラスの場合は，WSDLが新たに生成されて返されます。

対象がプロバイダ実装クラスの場合は，メタデータは発行されません。

○

○

（凡例）

○：適用されます。

−：適用されません。

注※

EJBのWebサービスの場合，Webサービス実装クラスだけに適用されます。

メタデータが発行される前提条件は，Webサービスのアプリケーションがエラーもなく，正常にデプロイされ実行が開始されている状態です。

メタデータの発行に関する注意事項を示します。

wsdlLocation属性には，「WEB-INF/wsdl」または「META-INF/wsdl」から始まるWSDLファイルへの相対パスを指定してください。wsdlLocation属性に指定されたWSDLファイルが，WEB-INF/wsdlディレクトリまたはMETA-INF/wsdlディレクトリにない場合，またはWSDLの構文として不正な場合は，Webサービスのデプロイ時にエラーとなります。

wsdlLocation属性に指定されたWSDLファイルにwsdl:service要素が含まれていない場合は，Webサービスのデプロイ時にエラーとなります。

項番1，項番2の場合であっても，WEB-INF/wsdlディレクトリまたはMETA-INF/wsdlディレクトリ以下にあるWSDLファイルが次のどちらかに該当すると，Webサービスのデプロイ時にエラーとなります。

wsdl:service要素を持つファイルが複数ある。

wsdl:portType要素を持つファイルが複数ある（Webサービス実装クラスの場合）。

項番1，項番2の場合であっても，そのWSDLファイルを基に，要求されたWebアプリケーションのWSDLとして内容を更新したものを返します。

プロバイダ実装クラスの場合，基本的にWSDLを持つ必要がありません。また，このため，標準仕様でもjavax.xml.ws.WebServiceProviderアノテーションとWSDLのマッピング規則は定義されていません。そのため，メタデータを発行したい場合，作成したWSDLをWARファイルに適切に含めておく必要があります（Webサービス実装クラスの場合とは異なり，JAX-WSエンジンによって自動生成されません）。また，WARファイルにcosminexus-jaxws.xmlを含めない場合，javax.xml.ws.WebServiceProviderアノテーションのportName属性とtargetNamespace属性は必須です。WSDLの定義内容に従って，適切な値を設定してください。cosminexus-jaxws.xmlについては，「10.3　cosminexus-jaxws.xmlによるカスタマイズ」を参照してください。

10.6.3　WSDLの更新

Webサービス側のJAX-WSエンジンは，Webサービスがデプロイされるときに，Webサービス実装クラスであれば必要に応じてWSDLファイルを自動生成します。自動生成しない場合でも，WARファイルに含まれるWSDLを基に，次の情報を反映したWSDLを返します。

ヘッダ情報

WSDLファイルが公開されたバージョン，および日時をヘッダ情報として追加します。追加されるヘッダ情報の例を次に示します。

<!-- Published by Cosminexus JAX-WS 0900 (2012.01.01 00:00). -->

ロケーション情報

soap:address要素のlocation属性や，xsd:include要素のschemaLocation属性などを更新します。

例えば，soap:address要素のlocation属性の値が"REPLACE_WITH_ACTUAL_URL"のようなWSDLでも，WARファイルに含めることで，soap:address要素のlocation属性の値は適切なURLに更新されます。

更新後のロケーション情報の例を次に示します。

ホスト名：sample.com

コンテキストルート：/fromjava

Webサービス呼び出しURL：/AddNumbersImplService

このような場合，更新後のURLは，"http://sample.com/fromjava/AddNumbersImplService"となります。

10.6.4　メタデータ発行の有効／無効

メタデータの発行の有効／無効は，com.cosminexus.jaxws.security.publish_wsdlプロパティの値で指定できます。POJOとEJBの両方のWebサービスで指定できます。com.cosminexus.jaxws.security.publish_wsdlプロパティについては，「10.1.2　共通定義ファイルの設定項目」を参照してください。

10.6.5　WARファイルに複数のWebサービス実装クラスまたはプロバイダ実装クラスを含む場合の注意

メタデータはWebサービス実装クラスまたはプロバイダ実装クラス単位で取得します。WARファイルに複数のWebサービス実装クラスまたはプロバイダ実装クラスを含む場合，Webサービス側のJAX-WSエンジンで新たに生成して返すWSDL定義のwsdl:binding要素およびwsdl:port要素は，リクエストで指定したURLのWebサービス実装クラスまたはプロバイダ実装クラスに対応したwsdl:binding要素とwsdl:port要素だけです。WARファイルに含まれるほかのWebサービス実装クラスまたはプロバイダ実装クラスに対応したwsdl:binding要素とwsdl:port要素は含まれません。

WARファイル中のすべてのWebサービス実装クラスまたはプロバイダ実装クラスに対応したwsdl:binding要素とwsdl:port要素を含むメタデータを公開したい場合，Webサービス（アプリケーション）開発者が適切なメタデータをあらかじめ作成し，WEB-INF/wsdlディレクトリに含める必要があります。

10.6.6　WSDL定義またはXML Schemaをインポート／インクルードしている場合の注意

WSDL定義またはXML Schemaをインポート，インクルードしている場合，Webサービスの開発で使用したWSDL定義やXML SchemaをそのままWARファイルに含めると，正常にメタデータが発行できなくなることがあります。

インポートまたはインクルード対象のファイルをWARファイルに含める場合，インポート元またはインクルード元のWSDL定義やXML Schemaに含まれるパス情報を確認し，次に示す方法でパス情報を適切に修正する必要があります。

相対パスの記述を含むWSDL定義やXML SchemaをWARファイルに含める場合

インポート，インクルード対象のファイルをWARファイルのWEB-INF/wsdlディレクトリ以下に含め，インポート元およびインクルード元のWSDL定義やXML Schemaのlocation属性，schemaLocation属性に指定したパス情報を，環境に合わせて適切な相対パスに修正します。

リモートのURLの記述を含むWSDL定義やXML SchemaをWARファイルに含める場合

WSDL定義を取得するWebサービスクライアントからアクセスできるURLの場合，修正は不要です。アクセスできないURLの場合，インポート，インクルード対象のファイルをWARファイルのWEB-INF/wsdlディレクトリ以下に含め，インポート元およびインクルード元のWSDL定義やXML Schemaのlocation属性，schemaLocation属性に指定したパス情報を，環境に合わせて適切な相対パスに修正します。

ローカルのURLの記述を含むWSDL定義やXML SchemaをWARファイルに含める場合

インポート，インクルード対象のファイルをWARファイルのWEB-INF/wsdlディレクトリ以下に含め，インポート元およびインクルード元のWSDL定義のlocation属性，schemaLocation属性に指定したパス情報を，環境に合わせて適切な相対パスに修正します。

10.6.7　WSDLのsoap12:binding要素のtransport属性についての注意

自動生成されて発行されるSOAP 1.2仕様のWSDLで，soap12:binding要素のtransport属性は，デフォルトでは次のURLです。

http://www.w3.org/2003/05/soap/bindings/HTTP/

次のURLに変更したい場合は，動作定義ファイルに定義を追加してください。

変更したいURL

http://schemas.xmlsoap.org/soap/http

追加する定義の内容

com.cosminexus.jaxws.publish_wsdl.soap12binding=WSI_BP20_TRANSPORT

10.7　Webサービスの情報表示

Webサービス実装クラス，またはプロバイダ実装クラスを呼び出すURLをブラウザ上で実行すると，Webサービスの情報を表示できます。

10.7.1　表示されるWebサービスの情報

Webサービスの情報を表示する場合，GETメソッドでURLを指定します。HTTPのGETメソッドを使用して，表示されるWebサービスの情報を次の表に示します。

表10‒13　表示されるWebサービスの情報

EndPoint

Information

Service Name：

サービスのQName

Port Name：

ポートのQName

Address：

Webサービスを呼び出すためのURL

WSDL：

WebサービスのWSDLを取得するためのURL

メタデータの発行については，「10.6　メタデータの発行」を参照してください。

Implementation Class：

Webサービス実装クラス名，またはプロバイダ実装クラス名

10.7.2　Webサービスの情報を表示する方法

Webサービスの情報を表示する場合，次の例に示すようなURLを含むHTTPリクエストをGETメソッドでWebサービス側のJAX-WSエンジンに送信します。

http://sample.com/fromjava/AddNumbersImplService

このURLでは，次の情報を指定しています。

sample.com：ホスト名

/fromjava：コンテキストルート

/AddNumbersImplService：Webサービスの呼び出し

また，この機能は，com.cosminexus.jaxws.security.display_webservice_infoプロパティで，有効／無効を指定できます。com.cosminexus.jaxws.security.display_webservice_infoプロパティについては，「10.1.2　共通定義ファイルの設定項目」を参照してください。

10.8　使用できるHTTPメソッド

HTTPメソッドとしてPOSTが使用できます。また，メタデータの発行およびWebサービスの情報表示ではGETが使用できます。POJOとEJBの両方のWebサービスで使用できます。

次に示すHTTPリクエストメソッドがWebサービス側のJAX-WSエンジンに到着した場合，HTTPステータスコード"405 Method Not Allowed"が返されます。

GET（メタデータの発行およびWebサービスの情報表示の場合を除く）

DELETE

HEAD

OPTION

PUT

TRACE

10.9　Webサービスの初期化と破棄

Webサービスの初期化と破棄について説明します。POJOとEJBの両方のWebサービスで動作します。

10.9.1　Webサービスの初期化

Webサービス側のJAX-WSエンジンでは，J2EEアプリケーションがJ2EEサーバによって開始されるときに，Webサービスを初期化します。具体的には次の処理が実行されます。

Webサービスのディスカバリをするための，URLと，Webサービス実装クラスまたはプロバイダ実装クラスとのマッピング情報の生成処理

POJOのWebサービスの実行に必要なリクエストbean，レスポンスbean，およびフォルトbeanのJavaBeansクラスがWARファイルに含まれない場合，またはEJBのWebサービスの実行に必要なリクエストbean，レスポンスbean，およびフォルトbeanのJavaBeansクラスがEARファイルに含まれない場合，JAX-WSエンジンがこれらのJavaBeansクラスを動的に生成

メタデータを発行するためのWSDLの確認処理（Webサービス実装クラスの場合）

Webサービス実装クラスまたはプロバイダ実装クラスにハンドラが関連づけられている場合のハンドラチェイン設定ファイルの読み込みと，ハンドラの初期化処理

（javax.annotation.PostConstructアノテーションでアノテートされたメソッドがある場合はそのメソッドの呼び出しも含む）

Webサービスの初期化の開始時に，ログおよび標準出力にKDJW40001-Iのメッセージが出力されます。Webサービスの初期化が正常に終了した場合，ログおよび標準出力にKDJW40003-Iのメッセージが出力されます。Webサービスの初期化でエラーが発生し，初期化に失敗した場合，ログおよび標準エラー出力にKDJW40002-Eのメッセージとエラーの原因となったエラーメッセージが出力されます。

Webサービスの初期化でエラーが発生した場合，ログにエラーが出力されますが，J2EEアプリケーションの開始自体は継続され，正常終了します。ただし，初期化に失敗しているので，デプロイされたWebサービスは動作しません。この場合，KDJW40002-Eのメッセージが出力されたかどうかを確認し，エラーが出力された場合には問題を修正し，再度Webサービスをデプロイしてください。

J2EEサーバの開始時に，デプロイされているJ2EEアプリケーションが自動的に開始される場合など，どのJ2EEアプリケーションに含まれるWebサービスの初期化に失敗したのか，調査が困難なことがあります。そのようなときは，「39.3.1　ログの種類」で示すログ，およびJ2EEサーバの稼働ログを確認することで，J2EEアプリケーション名とコンテキストルート名を特定できます。

"com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener"を含む，KDJE39103-Eメッセージの出力内容を確認する例を次に示します。

0095 2009/12/18 13:48:36.471     HEJB             0125FEFA 004413EE KDJE39103-E           An exception javax.xml.ws.WebServiceException was raised in notification of the listener class com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener. (J2EE application = Sample_application_fromwsdl, context root = /fromjava)

上記のようなログが出力されている場合，J2EEアプリケーション"Sample_application_fromwsdl"に含まれる，コンテキストルート名"fromjava"に関連づけられたWARファイル内のWebサービスの初期化が失敗しています。

ユーザプログラムに問題がある場合，基本的にKDJE39103-Eのメッセージのエラーが発生します。ただし，必要に応じて次のエラーメッセージについても確認してください。

KDJE39100-E

KDJE39101-E

KDJE39102-E

J2EEサーバの稼働ログについては，マニュアル「アプリケーションサーバ 機能解説 保守／移行編」の「5.2　アプリケーションサーバのログ」を参照してください。また，上記のメッセージについては，マニュアル「アプリケーションサーバ メッセージ(構築／運用／開発用)」の「7.2　KDJE30000からKDJE39999までのメッセージ」を参照してください。

10.9.2　Webサービスの破棄

Webサービス側のJAX-WSエンジンでは，J2EEアプリケーションがJ2EEサーバによって終了されるときに，Webサービスを破棄します。具体的には次の処理が実行されます。

Webサービスのディスカバリをするための，URLと，Webサービス実装クラスまたはプロバイダ実装クラスとのマッピング情報の削除処理

Webサービス実装クラスまたはプロバイダ実装クラスにハンドラが関連づけられている場合のハンドラの破棄処理

（javax.annotation.PreDestoryアノテーションでアノテートされたメソッドがある場合はそのメソッドの呼び出しも含む）

Webサービスの破棄の開始時に，ログおよび標準出力にKDJW40004-Iのメッセージが出力されます。Webサービスの破棄が正常に終了した場合，ログおよび標準出力にKDJW40006-Iのメッセージが出力されます。Webサービスの破棄でエラーが発生し，破棄に失敗した場合，ログおよび標準エラー出力にKDJW40015-Eのメッセージとエラーの原因となったエラーメッセージが出力されます。

Webサービスの破棄でエラーが発生した場合，ログにエラーが出力されますが，J2EEアプリケーションの終了処理自体は継続され，正常終了します。この場合，KDJW40015-Eのメッセージが出力されたかどうかを確認し，エラーが出力された場合には問題を修正してください。

10.10　プロキシサーバ経由の接続

Webサービスクライアントからプロキシサーバを経由して，外部のネットワークにあるWebサービスを利用できます。

ここでは，プロキシサーバを経由して外部に接続する場合に必要なプロパティの設定について説明します。

10.10.1　プロパティ値の指定

プロキシサーバを経由してWebサービスにアクセスするには，JavaVMのプロパティ，またはApplication ServerのJAX-WS機能固有のプロパティを指定して，プロキシサーバの情報を設定します。プロキシサーバ経由で接続するためのプロパティと指定内容を次の表に示します。

表10‒14　プロキシサーバ経由で接続するためのプロパティ

項番

プロパティ

指定内容

非SSLの場合

SSLの場合

1

http.proxyHost※1

プロキシサーバのホスト名またはIPアドレスを指定します。

空文字を指定した場合は，プロキシサーバに接続されません。

○

×

2

http.proxyPort※1

プロキシサーバのポート番号を設定します。

http.proxyHostが適切に設定されていた場合に，http.proxyPortに空文字を指定したときは，http.proxyHostに指定されているホストの80番ポートにアクセスされます。

http.proxyHostを指定していない場合は，http.proxyPortを指定しても，プロキシサーバに接続されません。

△

×

3

com.cosminexus.jaxws.http.proxyUser※2

プロキシサーバの認証ユーザIDを設定します。

http.proxyHostプロパティ，およびhttp.proxyPortプロパティが適切に設定されていた場合に，com.cosminexus.jaxws.http.proxyUserプロパティに空文字を指定したときは，匿名でプロキシサーバに接続します。

△

×

4

com.cosminexus.jaxws.http.proxyPassword※2

プロキシサーバの認証ユーザIDに対応するパスワードを設定します。

次のプロパティが適切に設定されていた場合に，com.cosminexus.jaxws.http.proxyPasswordプロパティに空文字を指定したときは，パスワードを設定しないでプロキシサーバに接続します。

http.proxyHost

http.proxyPort

com.cosminexus.jaxws.http.proxyUser

△

×

5

https.proxyHost※1

SSLプロトコルによる接続※3で使用するプロキシサーバのホスト名かIPアドレスを設定します。

SSLプロトコルによる接続でプロキシサーバを使用する場合は，必ず設定してください。なお，空文字を指定した場合は，プロキシサーバに接続されません。

×

○

6

https.proxyPort※1

SSLプロトコルによる接続※3で使用するプロキシサーバのポート番号を設定します。なお，https.proxyHostが適切に設定されていた場合に，https.proxyPortに空文字を指定したときは，https.proxyHostに指定されているホストの443番ポートにアクセスされます。

https.proxyHostを指定していない場合は，https.proxyPortを設定しても，プロキシサーバに接続されません。

×

△

7

com.cosminexus.jaxws.https.proxyUser※2

SSLプロトコルによる接続※3で使用するプロキシサーバの認証ユーザIDを設定します。

https.proxyHostプロパティ，およびhttps.proxyPortプロパティが適切に設定されていた場合に，com.cosminexus.jaxws.https.proxyUserプロパティに空文字を指定したときは，匿名でプロキシサーバに接続します。

×

△

8

com.cosminexus.jaxws.https.proxyPassword※2

SSLプロトコルによる接続※3で使用するプロキシサーバの認証ユーザIDに対応するパスワードを設定します。

次のプロパティが適切に設定されていた場合に，com.cosminexus.jaxws.https.proxyPasswordプロパティに空文字を指定したときは，パスワードを設定しないでプロキシサーバに接続します。

https.proxyHost

https.proxyPort

com.cosminexus.jaxws.https.proxyUser

×

△

9

http.nonProxyHosts※1

プロキシサーバを利用しないホスト名群を必要に応じて指定します。

このプロパティで指定したホストに接続する場合は，http.proxyHostまたはhttps.proxyHostに指定したプロキシサーバは経由されません。ホストを複数指定する場合は，「|」で区切って設定します。ホスト名とホスト名の間には，「|」以外の文字（空白など）は指定できません。

△

△

（凡例）

○：プロパティの指定が必須であることを示します。

△：必要に応じてプロパティを指定することを示します。

×：プロパティの指定が不要であることを示します。

注※1

JavaVMで標準でサポートされているシステムプロパティです。JavaVMのシステムプロパティについては，JavaVMのドキュメントを参照してください。

注※2

Application ServerのJAX-WS機能固有のプロパティです。このプロパティは簡易的なプロパティです。細かな制御をしたい場合，WebサービスクライアントでJ2SE 6.0標準のjava.net.Authenticatorクラスを利用した実装をすることをお勧めします。詳細については，「10.10.3　JAX-WS機能固有のプロパティを利用しない場合」を参照してください。

注※3

SSLプロトコルによる接続については，「10.11　SSLプロトコルによる接続」を参照してください。

10.10.2　プロパティの設定方法

Application ServerのJAX-WS機能固有のプロパティは，動作定義ファイルに設定します。動作定義ファイルの設定方法については「10.1　動作定義ファイル」を参照してください。JAX-WS機能固有のプロパティを利用する場合，「10.10.4　JAX-WS機能固有のプロパティを利用する場合の注意事項」の内容に注意してください。

JavaVMのシステムプロパティの設定方法は，Webサービスクライアントの実行形態によって異なります。

Webサービスクライアントをコマンドで実行する場合

Webサービスクライアントをコマンド（cjclstartap）で実行する場合は，Javaアプリケーション用ユーザプロパティファイル（usrconf.properties）に，JavaVMのプロパティを設定します。

WebサービスクライアントをJ2EEサーバ上で実行する場合

WebサービスクライアントをJ2EEサーバ上で実行する場合は，J2EEサーバ用ユーザプロパティファイル（usrconf.properties）に，JavaVMのプロパティを設定します。

プロパティの設定例を示します。

http.proxyHost=10.209.15.79
http.proxyPort=3128
https.proxyHost=10.209.15.79
https.proxyPort=3128
http.nonProxyHosts=10.209.15.80|www.xxx.co.jp

プロパティの設定を追加する位置についての決まりはありません。

10.10.3　JAX-WS機能固有のプロパティを利用しない場合

JAX-WS機能固有のプロパティは簡易的なプロパティです。そのため，細かな制御をしたい場合，WebサービスクライアントでJ2SE 6.0標準のjava.net.Authenticatorクラスを利用した実装をすることをお勧めします。詳細についてはJ2SE 6のドキュメントを参照してください。java.net.Authenticatorクラスを利用した実装例を次に示します。

java.net.Authenticator.setDefault( new java.net.Authenticator(){

  // getPasswordAuthenticationメソッドをオーバーライドする
  public java.net.PasswordAuthentication getPasswordAuthentication() {

    // ユーザ名を設定する
    String userName = ...

    // パスワードを設定する
    char[] password = ...

    // PasswordAuthenticationを生成する。
    java.net.PasswordAuthentication auth =
        new java.net.PasswordAuthentication( userName, password );

    return auth;
  }
} );

10.10.4　JAX-WS機能固有のプロパティを利用する場合の注意事項

Application Serverは，Java SE標準のjava.net.AuthenticatorクラスのsetDefault()メソッドを利用して，JAX-WS機能固有のプロパティの値をJavaVMに設定します。そのため，次の点に注意してください。

有効範囲

Webサービスクライアントが動作するプロセス全体（WebサービスクライアントがJ2EEサーバ上で動作する場合は，J2EEサーバ全体）で有効となり，Application Server以外のHTTP接続にも影響します。Application Server以外のHTTP接続にJAX-WS機能固有のプロパティによるプロキシの設定を適用したくない場合，JAX-WS機能固有のプロパティではなく，ユーザプログラム（Webサービスクライアント）で，java.net.AuthenticatorクラスのsetDefault()メソッドを利用した実装をする必要があります。詳細については，「10.10.3　JAX-WS機能固有のプロパティを利用しない場合」を参照してください。

競合

JAX-WS機能固有のプロパティを利用する場合，Webサービスクライアントが動作するプロセスでは，Application Server以外がjava.net.AuthenticatorクラスのsetDefault()メソッドを呼び出さないようにしてください。ライブラリなどでほかの製品を利用している場合は，特に注意してください。java.net.AuthenticatorクラスのsetDefault()メソッドを呼び出すタイミングによっては設定が競合し，動作が不正になるおそれがあります。ユーザプログラムやライブラリなど，ほかの製品がjava.net.AuthenticatorクラスのsetDefault()メソッドを呼び出す場合，JAX-WS機能固有のプロパティを利用しないでください。

セキュリティ例外

java.net.AuthenticatorクラスのsetDefault()メソッドがjava.lang.SecurityExceptionをスローする場合，KDJW10025-Wのメッセージがログに出力され，処理が続行されます。必要に応じて，詳細メッセージを確認し，エラーの要因を取り除いてください。

10.11　SSLプロトコルによる接続

Webサービスクライアントから，SSLプロトコルに対応したWebサービスに接続できます。

ここでは，SSLプロトコルによる接続に必要なプロパティの設定について説明します。

10.11.1　プロパティ値の指定

SSLプロトコルでWebサービスにアクセスするには，JDKにサポートされているプロパティに値を指定して，SSLプロトコルの情報を設定します。SSLプロトコルによる接続をするためのプロパティ，および指定内容を次の表に示します。

表10‒15　SSLプロトコルによる接続をするためのプロパティ

項番

プロパティ

指定内容

1

javax.net.ssl.trustStore

トラストストアを指定します。

2

javax.net.ssl.trustStorePassword

トラストストアのパスワードを指定します。

これらのプロパティは必要に応じて指定してください。なお，トラストストアを指定しない場合は，<JDKインストールディレクトリ>/lib/security/jssecacertsなどのデフォルト値が使用されます。

JDKのプロパティについては，JDKのドキュメントを参照してください。

10.11.2　プロパティの設定方法

プロパティの指定値を有効にするために，プロパティをシステムプロパティに設定します。プロパティの設定方法は，Webサービスクライアントの実行形態によって異なります。

Webサービスクライアントをコマンドで実行する場合

Webサービスクライアントをコマンド（cjclstartap）で実行する場合は，Javaアプリケーション用ユーザプロパティファイル（usrconf.properties）に，JavaVMのプロパティを設定します。

WebサービスクライアントをJ2EEサーバ上で実行する場合

WebサービスクライアントをJ2EEサーバ上で実行する場合は，J2EEサーバ用ユーザプロパティファイル（usrconf.properties）に，JavaVMのプロパティを設定します。

プロパティの設定例を示します。

javax.net.ssl.trustStore=<トラストストア>
javax.net.ssl.trustStorePassword=<トラストストアのパスワード>

プロパティの設定を追加する位置についての決まりはありません。

10.11.3　ホスト名検証についての注意事項

Webサービスクライアントから，SSLプロトコルに対応したWebサービスに接続する場合，エンドポイントアドレスに含まれるホスト名と，証明書のホスト名が一致しているかどうかが検証されます。使用されるHostnameVerifierはJDKのデフォルトの実装です。JDKのデフォルトのHostnameVerifierの動作についてはJDKのドキュメントを参照してください。

動作定義ファイル，またはメッセージコンテキストで設定を行うことでホスト名検証が行われないようにすることができます。ホスト名検証が行われないようにするためのプロパティ，および指定内容を次の表に示します。

表10‒16　ホスト名検証が行われないようにするためのプロパティ

項番

プロパティ

指定内容

必須

1

com.cosminexus.xml.ws.client.http.HostnameVerificationProperty

ホスト名検証を省略する場合，trueを指定します。省略しない場合，falseを指定します。

△

（凡例）

△：必要に応じてプロパティを指定することを示します。

ホスト名検証が行われないようにする場合の注意事項

メッセージコンテキストへの指定が有効になるのは，Webサービス呼び出し時だけで，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時には適用されません。

メタデータ取得時にホスト名検証の有無を設定する場合は，共通定義ファイルまたはプロセス別の定義ファイルに記述するか，別途WSDLをローカルマシンにダウンロードして使用してください（ローカルマシンにあるWSDLを使用する場合は，メタデータ取得時にリモートマシンへの接続が発生しません）。WSDLから別途インポートされるWSDLが存在する場合は，インポートされるWSDLもローカルマシン上にダウンロードしてください。

同じプロセスで動作する複数のWebサービスクライアントによって，ホスト名検証の有無が異なる場合は，プロセス別の定義ファイルや共通定義ファイルにプロパティを含めないで，メッセージコンテキストだけに含めるようにしてください。

同様に，同じシステムで動作する複数のプロセスによって，ホスト名検証の有無が異なる場合は，共通定義ファイルにプロパティを含めないで，プロセス別の定義ファイルかメッセージコンテキストだけに含めるようにしてください。

プロパティを動作定義ファイルに設定する方法については，「10.1.2　共通定義ファイルの設定項目」を参照してください。メッセージコンテキストに設定する方法については，「19.2.5　メッセージコンテキストの使用」を参照してください。

10.12　ベーシック認証による接続

Webサービスクライアントから，ベーシック認証に対応したWebサービスに接続できます。

ここでは，ベーシック認証による接続に必要なプロパティの設定について説明します。

10.12.1　プロパティ値の指定

ベーシック認証でWebサービスにアクセスするには，動作定義ファイル，またはメッセージコンテキストに値を指定します。ベーシック認証による接続をするためのプロパティ，および指定内容を次の表に示します。

表10‒17　ベーシック認証による接続をするためのプロパティ

項番

プロパティ

指定内容

必須

1

javax.xml.ws.security.auth.username

ユーザIDを設定します。

○

2

javax.xml.ws.security.auth.password

パスワードを設定します。

○

（凡例）

○：プロパティの指定が必須であることを示します。

ベーシック認証による接続をする場合の注意事項

メッセージコンテキストへの指定が有効になるのはWebサービス呼び出し時だけで，Webサービス呼び出し前のjavax.xml.ws.Serviceクラス生成で発生するメタデータ（WSDL）取得時には適用されません。

メタデータ取得時にベーシック認証の情報を設定する場合は，共通定義ファイルまたはプロセス別の定義ファイルに記述するか，別途WSDLをローカルマシンにダウンロードして使用してください（ローカルマシンにあるWSDLを使用する場合は，メタデータ取得時にリモートマシンへの接続が発生しません）。WSDLから別途インポートされるWSDLが存在する場合は，インポートされるWSDLもローカルマシン上にダウンロードしてください。

同じプロセスで動作する複数のWebサービスクライアントによって，ベーシック認証を行うか，行わないかが異なる場合は，プロセス別の定義ファイルや共通定義ファイルにこれらのプロパティを含めないで，メッセージコンテキストだけに含めるようにしてください。

同様に，同じシステムで動作する複数のプロセスによって，ベーシック認証を行うか，行わないかが異なる場合は，共通定義ファイルにこれらのプロパティを含めないで，プロセス別の定義ファイルかメッセージコンテキストだけに含めるようにしてください。

10.12.2　プロパティの設定方法

プロパティを動作定義ファイルに設定する方法については，「10.1.2　共通定義ファイルの設定項目」を参照してください。メッセージコンテキストに設定する方法については，「19.2.5　メッセージコンテキストの使用」を参照してください。

10.13　SOAPのバージョン選択

ここでは，Webサービス，およびWebサービスアプリケーションの開発時に必要となる，SOAPのバージョン選択について説明します。

10.13.1　SOAPのバージョン選択（Webサービス開発時）

WSDL起点，SEI起点，およびプロバイダ起点のWebサービス開発時のバージョン選択方法について説明します。

(1)　WSDL起点の場合

SOAP 1.1仕様またはSOAP 1.2仕様のどちらのメッセージを送受信するのかを，WSDLに記述するバインディングで決定します。

cjwsimportコマンドで生成したWebサービス実装クラスのスケルトンはバインディング単位のため，SOAP 1.1仕様またはSOAP 1.2仕様のどちらか専用となります。実行時に動的に変更することはできません。

一方，WSDLには複数のバインディングを記述できるので，一つのWSDLに，SOAP 1.1仕様およびSOAP 1.2仕様のポートを混在させることができます。

SOAP 1.1仕様およびSOAP 1.2仕様のポートを混在させる例を次に示します。

図10‒8　ポートを混在させる例

これは，一つのポートタイプをSOAP 1.1用とSOAP 1.2用にそれぞれバインドする例です。一つのポートタイプで，SOAP 1.1仕様およびSOAP 1.2仕様のどちらの形式のメッセージも受け付けられます。

(2)　SEI起点の場合

SOAP 1.1仕様またはSOAP 1.2仕様のどちらにバインドするのかを，アノテーションで指定します。Webサービス実装クラスの単位で指定してください。実行時に動的に変更することはできません。

アノテーションは省略できます。省略した場合は，SOAP 1.1仕様になります。

(3)　プロバイダ起点の場合

SOAP 1.1仕様またはSOAP 1.2仕様のどちらにバインドするのかを，アノテーションで指定します。プロバイダ実装クラスの単位で指定してください。実行時に動的に変更することはできません。

10.13.2　SOAPのバージョン選択（Webサービスクライアント開発時）

Webサービスクライアントは，Webサービスのメタデータ（WSDL，または接続しようとしているWebサービスに依存する情報など）に基づいて開発します。メタデータで定義される情報に基づき，適切なバージョンのSOAPで通信するWebサービスクライアントを実装してください。

スタブベース，ディスパッチベース，およびAPIベースのWebサービスクライアント開発時の，SOAPのバージョン選択方法について説明します。

(1)　スタブベースの場合

cjwsimportコマンドを実行すると，WSDLの定義に基づいて適切なスタブを自動生成します。そのため，SOAP 1.1仕様またはSOAP 1.2仕様のどちらで通信するのかを指定する必要はありません。

なお，ポートは必ず一つのバインディングにバインドされます。そのため，サービスクラスに含まれるポート取得メソッドは，SOAP 1.1仕様またはSOAP 1.2仕様のどちらか専用となります。

(2)　ディスパッチベースの場合

Webサービスのメタデータに基づいて適切なバージョンのSOAPを選択し，APIで指定してください。

(3)　APIベースの場合

Webサービスのメタデータに基づいて適切なバージョンのSOAPを選択し，APIで指定してください。

10.13.3　SOAPのバージョン選択（実行時）

Webサービス，およびWebサービスクライアント実行時のSOAPのバージョン選択方法について説明します。

(1)　Webサービスの場合

Webサービス実装クラスおよびプロバイダ実装クラスは，開発時の選択に基づいて，SOAP 1.1仕様またはSOAP 1.2仕様のどちらか専用となります。そのため，受信できるメッセージは，SOAP 1.1仕様またはSOAP 1.2仕様のどちらかです。両方のバージョンのSOAPに対応するメッセージを受信したい場合は，複数のWebサービス実装クラスまたはプロバイダ実装クラスを定義・実装する必要があります。

(2)　Webサービスクライアントの場合

スタブベースのWebサービスクライアントは，SOAP 1.1仕様またはSOAP 1.2仕様のどちらかのメッセージを送信します。開発時の誤りで次のどちらかの状態になった場合，SOAPのバージョンが一致しないSOAPメッセージを送信することになり，Webサービス側でエラーが発生します。

WebサービスがSOAP 1.2仕様のバインディングの場合にSOAP 1.1仕様用のスタブを生成している

WebサービスがSOAP 1.1仕様のバインディングの場合にSOAP 1.2仕様用のスタブを生成している

ディスパッチベースやAPIベースのWebサービスクライアントでは，SOAPのバージョンをAPIで指定します。指定値を設定ファイルで変更できるようにするなど，実装方法によってはどちらのSOAPのバージョンのメッセージを送信するかを動的に変更できます。

10.14　コマンドラインを利用したクライアントアプリケーションの実行

Webサービスでは，コマンドラインで動作するJavaアプリケーションを，クライアントアプリケーションとして利用できます。

ここでは，コマンドラインによるクライアントアプリケーションを利用するときに必要な設定，コマンドラインの指定例，および注意事項について説明します。

10.14.1　コマンドライン利用時の設定

コマンドラインによるクライアントアプリケーションを利用するために必要な設定について説明します。

(1)　Javaアプリケーション用オプション定義ファイルの設定

クライアントアプリケーションを実行するカレントディレクトリに，Javaアプリケーション用オプション定義ファイルを作成し，次に示すキーと値を追加してください。

add.class.path=<クライアントWebサービスのクラスファイルが格納されたJARまたはディレクトリのパス>

add.class.path=<Application Serverのインストールディレクトリ>/jaxws/lib/cjjaxws.jar

add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>

add.jvm.arg=-Dejbserver.server.prf.PRFID=<PRF識別子>※

ejb.client.log.directory=<ログファイルを出力するディレクトリパス>

注※

cprfstartコマンドで指定したPRF識別子と同じ識別子を指定してください。指定しない場合のデフォルト値は，PRF_IDです。

(2)　Javaアプリケーション用ユーザプロパティファイルの設定

クライアントアプリケーションを実行するカレントディレクトリに，Javaアプリケーション用ユーザプロパティファイルを作成し，必要に応じて設定してください。

(3)　パスの追加

環境変数PATHに，次に示すパスを追加してください。

<Application Serverのインストールディレクトリ>/PRF/bin

10.14.2　コマンドラインの実行

Webサービスクライアントをコマンドラインから実行する場合の指定例を示します。

(1)　PRFデーモンの起動

PRF識別子として，デフォルト値を使用する場合の指定例を次に示します。

<Application Serverのインストールディレクトリ>/PRF/bin/cprfstart

PRF識別子として，デフォルト値以外を使用する場合の指定例を次に示します。

<Application Serverのインストールディレクトリ>/PRF/bin/cprfstart <prfid>※

注※

<prfid>はPRF識別子を示します。PRF識別子は，Javaアプリケーション用オプション定義ファイルに指定したPRF識別子と同じ識別子を指定してください。

(2)　アプリケーションのクライアントの実行

Javaアプリケーションの開始コマンド（cjclstartap）で実行します。実行例を次に示します。

cjclstartap localhost.testMain

10.14.3　コマンドライン利用時の注意事項

コマンドラインを利用するときの注意事項について説明します。

ログは，Javaアプリケーション用オプション定義ファイルのejb.client.log.directoryプロパティに指定したファイルパスに出力されます。ログの出力については，「39.3.3(2)　コマンドラインインタフェースでWebサービスクライアントを利用する場合」を参照してください。

コマンドラインを利用している場合で，PRFトレースを取得するときは，アプリケーションを実行する前にPRFデーモンを起動しておく必要があります。PRFデーモンを起動していない場合は，PRFトレースが取得されないまま処理が続行されます。

10.15　HTTPステータスコード

サービス側JAX-WSエンジンが返す HTTPステータスコードの一覧を次の表に示します。

表10‒18　HTTPステータスコード一覧

項番

HTTPステータスコード

HTTPステータスコードを返す条件

1

200 OK

Request-Responseオペレーション型のWebサービスの呼び出しが正常終了した場合。

2

202 Accepted

one-wayオペレーション型のWebサービスの呼び出し，またはアドレッシング機能を利用している場合に，非同期呼び出しに対応したWebサービスの呼び出しが正常終了したとき。

3

404 Not Found

メタデータの発行が有効な場合に，クエリストリングの形式が不正であるとき。この場合，HTTPステータスコードが「405 Method Not Allowed」となることがあります。

メタデータの発行については，「10.6　メタデータの発行」を参照してください。

4

405 Method Not Allowed

次のどれかの場合。

使用できないHTTPメソッドが到着した場合

使用できるHTTPメソッドについては，「10.8　使用できるHTTPメソッド」を参照してください。

メタデータの発行が無効な場合に，メタデータの発行を要求するHTTPリクエストを受け取ったとき

メタデータの発行については，「10.6　メタデータの発行」を参照してください。

Webサービスの情報表示が無効な場合に，Webサービスの情報表示を要求するHTTPリクエストを受け取ったとき

Webサービスの情報表示については，「10.7　Webサービスの情報表示」を参照してください。

5

415 Unsupported Media Type

Content-Type HTTPヘッダが存在しないか，または不正な場合。

この場合，HTTPステータスコードが「500 Internal Server Error」となることがあります。

6

500 Internal Server Error

上記を除くエラーが発生した場合。Webサービスの実行結果がSOAPフォルトとなる場合もこのHTTPステータスコードが返ります。

10.16　HTTPヘッダ

JAX-WSエンジンのHTTPヘッダについて説明します。

Content-Typeヘッダのactionパラメタについて

JAX-WSエンジンは，Content-Typeヘッダのactionパラメタの値を引用符「"」で囲んで，HTTPリクエストおよびHTTPレスポンスのContent-Typeヘッダのactionパラメタの値として設定します。すでに引用符「"」で囲まれている値は，そのままContent-Typeヘッダのactionパラメタの値として設定します。

Webサービス側でもWebサービスクライアント側でも同様に動作します。

10.17　HTTPリクエストボディのgzip圧縮

HTTPリクエストボディをgzip圧縮すると，WebサービスクライアントとWebコンテナ間のHTTPリクエスト通信に掛かる時間を削減できます。HTTPリクエストボディを圧縮するには，Webサービスクライアントからリクエストメッセージを送信する際に，gzip形式で圧縮されたHTTPリクエストボディを送信することを示すHTTPヘッダを付ける必要があります。クライアントアプリケーションでHTTPヘッダを付ける処理を実装してください。

クライアントアプリケーションでの実装例を次に示します。

  Map<String, List<String>> httpHeaders =
    ( Map<String, List<String>> )context.get( MessageContext.HTTP_REQUEST_HEADERS );
  if( null == httpHeaders ){
    httpHeaders = new HashMap<String, List<String>>();
  }
  List<String> contentEncondings = httpHeaders.get( "Content-Encoding" );
  if( null == contentEncondings ){
    contentEncondings = new ArrayList<String>();
  }
  contentEncondings.add( "gzip" );
  httpHeaders.put( "Content-Encoding", contentEncondings );
  context.put( MessageContext.HTTP_REQUEST_HEADERS, httpHeaders );

10.18　HTTPレスポンス圧縮機能との連携

HTTPレスポンスボディをgzip圧縮してWebコンテナとWebサービスクライアント間のHTTPレスポンス通信に掛かる時間を削減するApplication Serverの機能をHTTPレスポンス圧縮機能といいます。

JAX-WSエンジンは，HTTPレスポンス圧縮機能と連携できます。HTTPレスポンス圧縮機能と連携するには，Webサービスクライアントからリクエストメッセージを送信する際に，gzip形式で圧縮されたHTTPレスポンスを受信できることを示すHTTPヘッダを付ける必要があります。クライアントアプリケーションでHTTPヘッダを付ける処理を実装してください。

クライアントアプリケーションでの実装例を次に示します。

  Map<String, List<String>> httpHeaders =
    ( Map<String, List<String>> )context.get( MessageContext.HTTP_REQUEST_HEADERS );
  if( null == httpHeaders ){
    httpHeaders = new HashMap<String, List<String>>();
  }
  List<String> acceptEncondings = httpHeaders.get( "Accept-Encoding" );
  if( null == acceptEncondings ){
    acceptEncondings = new ArrayList<String>();
  }
  acceptEncondings.add( "gzip" );
  httpHeaders.put( "Accept-Encoding", acceptEncondings );
  context.put( MessageContext.HTTP_REQUEST_HEADERS, httpHeaders );

10.19　EJBのWebサービス呼び出し

EJBをWebサービスとして呼び出せる条件と使用できる機能について説明します。

EJBの条件を次に示します。

EJBのバージョン

EJB 3.0以降でWebサービスとして呼び出せます。

EJBの種類

ステートレスセッションBeanのEJBをWebサービスとして呼び出せます。

インタフェース

EJB Webサービスでは，ビジネスインタフェースを用意する必要はありません。ホームインタフェースを併用できます。

EJB Webサービスが，ビジネスインタフェース，ホームインタフェース，およびコンポーネントインタフェースを持つ場合，Webサービス経由ではこれらのインタフェースを介してメソッドを呼び出すことはできません。

EJB Webサービスがビジネスインタフェースを持つ場合，EJB WebサービスはEJBのローカル呼び出しができます。EJB Webサービスがビジネスインタフェースを持たない場合，EJB WebサービスはWebサービスとして呼び出せますが，EJBとして呼び出すことはできません。

ホームインタフェースはjavax.ejb.RemoteHomeアノテーションまたはjavax.ejb.LocalHomeアノテーションによって指定される場合だけWebサービスとして呼び出せます。DDによって指定される場合はWebサービスとして呼び出せません。

10.19.1　EJBのWebサービス呼び出しでのEJB機能

EJBをWebサービスとして呼び出す際に，同時に使用できるEJBの機能を次に示します。ただし，EJBのWebサービス実装クラスだけで使用でき，ハンドラチェインでは使用できません。

インターセプタの使用

CMTおよびBMTのトランザクション管理

javax.annotation.security.PermitAllアノテーションおよびjavax.annotation.security.DenyAllアノテーションによるアクセス管理

リソース接続

javax.annotation.ResourceアノテーションによるWebサービスコンテキストのインジェクション

Webサービスコンテキストのインジェクションについては，「10.21.2　Webサービスコンテキストのインジェクション」を参照してください。

Timer Service

注意事項

タイムアウトメソッドは，サービスメソッドとして公開できません。タイムアウトメソッドをpublic以外の修飾子にするか，またはexclude要素の要素値が"true"のjavax.jws.WebMethodアノテーションをアノテートしてサービスメソッドから除外してください。

EJBをWebサービスとして呼び出す際に，同時に使用できないEJBの機能を次に示します。

クライアントからのトランザクションコンテキストの引き継ぎ

クライアントからのセキュリティコンテキストの引き継ぎ

10.19.2　EJBのWebサービス呼び出しで使用できるアプリケーションサーバ機能

JAX-WSは，EJBをWebサービスとして呼び出す際に，cosminexus.xmlで設定できるアプリケーションサーバの機能を同時に使用できます。使用できるアプリケーションサーバの機能を次に示します。

同時実行スレッド数の設定

実行待ちキューサイズの設定

セキュリティロールの設定

これらの機能を使用するには，WARファイル名を設定します。WARファイル名の設定については「3.5.4(3)　設定用WARファイル名」を参照してください。なお，これらのcosminexus.xmlの設定項目以外でも，EJB Webサービス以外のWebアプリケーションでは利用できます。

10.20　sun.net.www.http.HttpClientによるリクエスト再送抑止

Webサービスクライアント側のJAX-WS エンジンは，JDKのHTTPクライアント実装を利用して通信しています。JDKのHTTPクライアント実装は，RFC 2616に反してHTTP通信でエラーが発生し，サーバから正しいレスポンスを受け取れなかった場合，一度だけリクエストを再送します。JDKのシステムプロパティを使用するとリクエストの再送を抑止できます。

プロパティ値の指定

JDKのHTTPクライアント実装によるリクエスト再送を抑止するには，システムプロパティにsun.net.http.retryPost=falseを指定します。このシステムプロパティは，JDK 6以降で標準でサポートされているプロパティです。システムプロパティについては，JDK のドキュメントを参照してください。

プロパティの設定方法

SSLプロトコルによる接続をするためのシステムプロパティと同じ設定方法です。設定方法については，「10.11.2　プロパティの設定方法」を参照してください。

10.21　インジェクション

サービスクラスおよびポートのインジェクションとjavax.xml.ws.WebServiceRefアノテーション，およびWebサービスコンテキストのインジェクションについて説明します。

10.21.1　サービスクラスおよびポートのインジェクション

J2EEサーバ上で動作するWebサービスクライアントの，次に示すフィールドおよびメソッドにjavax.xml.ws.WebServiceRefアノテーションを指定すると，J2EEサーバが，Webサービスクライアントのインスタンス生成時にサービスクラスおよびポートの生成とインジェクションを行います。javax.xml.ws.WebServiceRefアノテーションについては，「19.3　アノテーションのサポート範囲」を参照してください。

サービスクラス型およびポート型のフィールド（staticおよびfinalを除く）

サービスクラス型およびポート型を引数とするsetterメソッド（staticおよびfinalを除く）

javax.xml.ws.WebServiceRefアノテーションによるインジェクションの利用には，次のような利点があります。

アプリケーションの開発では，javax.xml.ws.WebServiceRefアノテーションによるインジェクションを利用しない場合に比べコーディング量を削減できるため，Webサービスクライアントの作成が容易になります。

J2EEアプリケーションの開始時にWebサービスクライアントのインスタンスを生成すると，ポートのインジェクションを利用しない場合に比べ，Webサービスクライアント実行時の性能を改善できます。

Webサービスクライアントのインスタンスの生成については，「10.21.1(2)　Webサービスクライアントのインスタンス生成」を参照してください。

注意事項

javax.xml.ws.WebServiceRefアノテーションを指定できるのは，WebサービスクライアントをサーブレットまたはEJBとして実装する場合だけです。これ以外のアプリケーションとして実装するときは指定できません。例えば，コマンドラインアプリケーションのWebサービスクライアントで，サービスクラスやポートをインジェクトすることはできません。

サービスクラスおよびポートのインスタンスは，J2EEアプリケーションの開始時に一度だけ生成します。生成するインスタンスの数は，javax.xml.ws.WebServiceRefアノテーションを指定したサービスクラスおよびポートごとに一つだけです。

サービスクラスおよびポートのインジェクションは，Webサービスクライアントのインスタンスを生成するごとに行います。

WebサービスクライアントをEJBとして実装する場合，Stateless Session Beanでのプーリングを有効に設定することで，J2EEアプリケーションの開始時に複数のWebサービスクライアントのインスタンスを生成しておくことができます。この場合，javax.xml.ws.WebServiceRefアノテーションを指定したサービスクラスおよびポートのインスタンスを一つ生成して，それをWebサービスクライアントの各インスタンスにインジェクトします。Webサービスクライアントのインスタンス生成については，「10.21.1(2)　Webサービスクライアントのインスタンス生成」を参照してください。

WebサービスAからWebサービスBを呼び出す構成で，javax.xml.ws.WebServiceRefアノテーションを指定してWebサービスBのサービスクラスやポートを，WebサービスAにインジェクトすることはできません。

Webサービスクライアントが参照するクラスでjavax.xml.ws.WebServiceRefアノテーションは指定できません。

javax.xml.ws.WebServiceRefアノテーションによってサービスクラスやポートのインジェクションを行うJ2EEアプリケーションを，リロード機能を使用して入れ替えることはできません。入れ替える場合は，入れ替え前のJ2EEアプリケーションを停止・削除してから，入れ替えるJ2EEアプリケーションをインポート・開始してください。リロード機能の詳細については，マニュアル「アプリケーションサーバ 機能解説 基本・開発編(コンテナ共通機能)」を参照してください。

(1)　javax.xml.ws.WebServiceRefアノテーションの指定例

javax.xml.ws.WebServiceRefアノテーションの指定例を次に示します。

フィールドへの指定例

...
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.xml.ws.WebServiceRef;

import com.sample.AddNumbersImpl;
import com.sample.AddNumbersImplService;

public class TestClient extends HttpServlet {
    // サービスクラスの例
    // サービスクラス型のフィールドにサービスクラスのインスタンスをインジェクトする
    @WebServiceRef
    private AddNumbersImplService service;

    // ポートの例
    // ポート型のフィールドにポートのインスタンスをインジェクトする
    @WebServiceRef(AddNumbersImplService.class)
    private AddNumbersImpl port;

    @Override
    public void init() {
        // Webサービスクライアントの実行前にアプリケーションサーバがサービスクラスと
        // ポートをインジェクトするので，以下の処理は行う必要がない
        //service = new AddNumbersImplService();
        //port = service.getAddNumbersImplPort();
    }

    @Override
    public void doGet(HttpServletRequest request, HttpServletResponse response)
        throws ServletException {
        ...

setterメソッドへの指定例

...
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.xml.ws.WebServiceRef;

import com.sample.AddNumbersImpl;
import com.sample.AddNumbersImplService;

public class TestClient extends HttpServlet {
    private AddNumbersImplService service;
    private AddNumbersImpl port;

    @Override
    public void init() {
        // アプリケーション開始時にアプリケーションサーバがsetterメソッドを使用して
        // サービスクラスとポートをインジェクトするので，以下の処理は行う必要がない
        //service = new AddNumbersImplService();
        //port = service.getAddNumbersImplPort();
    }

    // サービスクラスの例
    @WebServiceRef
    public void setAddNumbersImplService(AddNumbersImplService service) {
        // 引数serviceにサービスクラスのインスタンスをインジェクトする
        this.service = service;
    }

    // ポートの例
    @WebServiceRef(AddNumbersImplService.class)
    public void setAddNumbersImpl(AddNumbersImpl port) {
        // 引数portにポートのインスタンスをインジェクトする
        this.port = port;
    }

    @Override
    public void doGet(HttpServletRequest request, HttpServletResponse response)
        throws ServletException {
        ...

(2)　Webサービスクライアントのインスタンス生成

J2EEアプリケーションの開始時にWebサービスクライアントのインスタンスを生成するには，次のように設定します。

サーブレットの場合

Webサービスクライアントが含まれるWARファイルのweb.xmlにload-on-startup要素を指定します。なお，load-on-startup要素を指定しないときは，最初のWebアプリケーション実行時にインスタンスを生成します。詳細については，マニュアル「アプリケーションサーバ 機能解説 基本・開発編(Webコンテナ)」を参照してください。

EJBの場合

Stateless Session Beanでのプーリングを有効に設定します。J2EEアプリケーション開始時に，Stateless Session Beanでのプーリングの最小値分だけインスタンス生成を実行します。なお，Stateless Session Beanでのプーリングを使用しないときは，最初のJ2EEアプリケーション実行時にインスタンスを生成します。詳細については，「アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」を参照してください。

注意事項

Webサービスクライアントと接続先のWebサービスが，同じJ2EEサーバ上にデプロイされている環境では，J2EEサーバの起動時にインジェクションに失敗します（KDJW40043-E）。

インジェクションが失敗する場合の対策方法を次に示します。

javax.xml.ws.WebServiceRefアノテーションのwsdlLocation要素に，相対パスまたは絶対パスでローカルに格納したWSDL文書を指定してください。

J2EEサーバを停止する前に，Webサービスクライアントが含まれるJ2EEアプリケーションを停止してください。J2EEサーバを再起動したあとに，Webサービスクライアントを開始してください。

WebサービスとWebサービスクライアントを別のJ2EEサーバにデプロイして，WebサービスをデプロイしたJ2EEサーバを起動したあとにWebサービスクライアントをデプロイしたJ2EEサーバを起動してください。

カタログ機能を使用して，サービスクラスまたはポートのインジェクションでローカルに格納したWSDL文書を参照するように設定してください。

(3)　ハンドラフレームワークの使用

javax.xml.ws.WebServiceRefアノテーションを指定してインジェクトしたサービスクラスまたはポートでハンドラフレームワークを使用する場合，APIを使用してハンドラチェインを設定します。ハンドラチェインの設定については，「36.9.2　Webサービスクライアント側のハンドラチェインの設定」を参照してください。なお，ハンドラチェインの設定は，ポートに対して一度だけ実行すればいいので，Webサービスクライアントの初期化処理での実行をお勧めします。Webサービスを呼び出すごとに設定する必要はありません。初期化処理を実行するメソッドを次に示します。

Webサービスクライアントをサーブレットとして実装する場合

initメソッドまたはjavax.annotation.PostConstructアノテーションを指定したメソッド

EJBとして実装する場合

javax.annotation.PostConstructアノテーションを指定したメソッド

(4)　フィーチャの有効化

ポート型のフィールドや，フィールドに対応するsetterメソッドに，javax.xml.ws.WebServiceRefアノテーションとフィーチャに対応するアノテーションを同時に指定すると，インジェクションを行うポートのフィーチャを有効化できます。ただし，フィーチャに対応するアノテーションを指定したフィールドまたはフィールドに対応するsetterメソッドに，javax.xml.ws.WebServiceRefアノテーションを指定しない場合は，フィーチャは有効になりません。また，サービスクラス型のフィールドやフィールドに対応するsetterメソッドに対しては，フィーチャに対応するアノテーションを指定できません。

フィーチャを有効化するときに，ポートに指定できるアノテーションを次に示します。各アノテーションについては，「16.2　JavaからWSDLへのマッピングのカスタマイズ」を参照してください。

javax.xml.ws.soap.Addressing

javax.xml.ws.soap.MTOM

com.sun.xml.ws.developer.StreamingAttachment

インジェクションを行うポートでMTOM/XOP仕様形式の添付ファイルを利用できるように，フィーチャを有効化する場合の指定例を次に示します。

フィールドへの指定例

...
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.xml.ws.WebServiceRef;

import com.sample.AddNumbersImpl;
import com.sample.AddNumbersImplService;

public class TestClient extends HttpServlet {
    // インジェクションを行うポートでMTOM/XOP仕様形式の添付ファイルを有効化
    @MTOM
    @WebServiceRef(AddNumberImplService.class)
    private AddNumbersImpl port;

    @Override
    public void init() {
        ...
    }

    @Override
    public void doGet(HttpServletRequest request, HttpServletResponse response)
        throws ServletException {
        ...

setterメソッドへの指定例

...
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.xml.ws.WebServiceRef;

import com.sample.AddNumbersImpl;
import com.sample.AddNumbersImplService;

public class TestClient extends HttpServlet {
    private AddNumbersImpl port;

    @Override
    public void init() {
        ...
    }

    // インジェクションを行うポートでMTOM/XOP仕様形式の添付ファイルを有効化
    @MTOM
    @WebServiceRef(AddNumberImplService.class)
    public void setAddNumbersImpl(AddNumbersImpl port) {
        this.port = port;
    }

    @Override
    public void doGet(HttpServletRequest request, HttpServletResponse response)
        throws ServletException {
        ...

(5)　要求コンテキストのプロパティ変更

インジェクションを行うポートの要求コンテキストのプロパティを変更する際は，Webサービスクライアントの初期化処理での実行をお勧めします。初期化処理を実行するメソッドを次に示します。

サーブレットとして実装する場合

initメソッドまたはjavax.annotation.PostConstructアノテーションを指定したメソッド

EJBとして実装する場合

javax.annotation.PostConstructアノテーションを指定したメソッド

注意事項

複数スレッドでポートを共有するWebサービスクライアントで，複数スレッドの動作中にポートの要求コンテキストのプロパティを変更すると，通信が失敗したり，不正なSOAPメッセージが送信されたりします。このため，複数スレッドで共有するポートの要求コンテキストのプロパティの変更は，複数スレッドが動作する前に実行する必要があります。

サーブレットとして実装したWebサービスクライアントの，ポートの要求コンテキストのプロパティを変更する例を次に示します。

...
import java.util.Map;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.WebServiceRef;

import com.sample.AddNumbersImpl;
import com.sample.AddNumbersImplService;

public class TestClient extends HttpServlet {

    @WebServiceRef(AddNumbersImplService.class)
    AddNumbersImpl port;

    @Override
    public void init() {
        // 初期化処理で，要求コンテキストを設定する
        Map<String, Object> context = ((BindingProvider)port).getRequestContext();
        context.put("com.cosminexus.jaxws.connect.timeout", 60000);
    }
    ...
}

10.21.2　Webサービスコンテキストのインジェクション

javax.xml.ws.WebServiceContextインタフェースは，JAX-WS 2.2仕様5.3節に記載されているサービスAPIの一つです。Webサービスコンテキストは，javax.annotation.Resourceアノテーションを用いて，リソースをインジェクトして使用します。

Webサービス実装クラスまたはプロバイダ実装クラスの，javax.xml.ws.WebServiceContext型のフィールドまたはjavax.xml.ws.WebServiceContext型を引数とするsetterメソッドに，javax.annotation.Resourceアノテーションを指定します。これによって，指定したフィールドまたは指定したsetterメソッドに対応するフィールドに，処理中のリクエストに関連する情報をインジェクトします。javax.xml.ws.WebServiceContextインタフェースのgetMessageContextメソッドでメッセージコンテキストを取得することで，メッセージコンテキストの情報にアクセスできます。ただし，EJBのWebサービス実装クラスにEJBとしてアクセスする場合，getMessageContextメソッドではメッセージコンテキストを取得できません。また，次のこともできます。

インバウンド時のサービス側ハンドラで追加したAPPLICATIONスコープのユーザ定義メッセージコンテキストプロパティを，Webサービス実装クラスまたはプロバイダ実装クラスから参照できます。

Webサービス実装クラスまたはプロバイダ実装クラスで追加したユーザ定義メッセージコンテキストプロパティを，アウトバウンド時のサービス側ハンドラから参照できます。

getMessageContextメソッドについては，「19.2.3(2)　javax.xml.ws.WebServiceContextインタフェース」を，メッセージコンテキストについては，「19.2.5　メッセージコンテキストの使用」を参照してください。

(1)　javax.annotation.Resourceアノテーションの指定

Webサービスコンテキストのインジェクションでjavax.annotation.Resourceアノテーションを使用する場合，Webサービス実装クラスまたはプロバイダ実装クラス（実装クラスの親クラスを含む）の次に示すフィールドまたはメソッドにjavax.annotation.Resourceアノテーションを指定できます。このフィールドとメソッド以外に指定した場合の動作は保証されません。また，フィールドとフィールドに対応するsetterメソッドに，同時に指定することはできません。

javax.xml.ws.WebServiceContext型のフィールド（staticおよびfinalのフィールドを除く）

javax.xml.ws.WebServiceContext型を引数とする公開対象にならないsetterメソッド※（staticおよびfinalのメソッドを除く）

注※

非publicのsetterメソッド，またはexclude要素がtrueのjavax.jws.WebMethodアノテーションが指定されているsetterメソッドです。

また，Webサービスコンテキストのインジェクションでjavax.annotation.Resourceアノテーションを使用する場合，javax.annotation.Resourceアノテーションで要素は指定できません。指定した場合の動作は保証されません。

javax.annotation.Resourceアノテーションの指定例を次に示します。

フィールドへの指定例

import javax.annotation.Resource;
import javax.jws.WebService;
import javax.servlet.ServletContext;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.WebServiceContext;

@WebService
public class AddNumbersImpl {
    // wsContextフィールドに現在処理中のリクエスト関連情報をインジェクトする
    @Resource
    private WebServiceContext wsContext;

    public int add(int number1, int number2) throws AddNumbersFault {
        // メッセージコンテキストを取得する
        MessageContext mContext = wsContext.getMessageContext();
        // プロパティを取得する
        ServletContext sContext = (ServletContext)mContext.get(MessageContext.SERVLET_CONTEXT);
        ...
    }
    ...
}

setterメソッドへの指定例

import javax.annotation.Resource;
import javax.jws.WebService;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.WebServiceContext;

@WebService
public class AddNumbersImpl {
    // setterメソッドに対応するwsContextフィールドに現在処理中のリクエスト関連情報をインジェクトする
    private WebServiceContext wsContext;

    @Resource
    private void setWebServiceContext(WebServiceContext wsContext) {
        this.wsContext = wsContext;
    }
    public int add(int number1, int number2) throws AddNumbersFault {
        // メッセージコンテキストを取得する
        MessageContext mContext = wsContext.getMessageContext();
        // プロパティを設定する
        mContext.put("userPropKey", "userPropValue");
        ...
    }
    ...
}

(2)　ユーザ定義メッセージコンテキストプロパティ追加時の注意事項

ユーザ定義メッセージコンテキストプロパティを追加するときの注意事項について説明します。

(a)　インバウンド時のサービス側ハンドラでプロパティを追加する場合

インバウンド時のサービス側ハンドラで追加したユーザ定義メッセージコンテキストプロパティを，Webサービス実装クラスまたはプロバイダ実装クラスから参照する場合，サービス側ハンドラではユーザ定義メッセージコンテキストプロパティを設定したあとに，javax.xml.ws.handler.MessageContextインタフェースのAPIであるsetScope（java.lang.String name, MessageContext.Scope scope）メソッドを使用して，ユーザ定義プロパティをAPPLICATIONスコープとして設定する必要があります。

なお，インバウンド時のサービス側ハンドラで追加したユーザ定義メッセージコンテキストプロパティを，アウトバウンド時のサービス側ハンドラから参照する場合，インバウンド時のサービス側ハンドラでは，ユーザ定義メッセージコンテキストプロパティの設定だけを実施し，setScope（java.lang.String name, MessageContext.Scope scope）メソッドを使用してスコープの設定をする必要はありません。setScope（java.lang.String name, MessageContext.Scope scope）メソッドについては，「19.2.4(8)　javax.xml.ws.handler.MessageContextインタフェース」を参照してください。

インバウンド時のサービス側ハンドラで，ユーザ定義メッセージコンテキストプロパティを追加する場合の例を次に示します。

import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPHandler;
import javax.xml.ws.handler.soap.SOAPMessageContext;

public class ServiceSOAPHandlerImpl implements SOAPHandler<SOAPMessageContext> {

    public boolean handleMessage(SOAPMessageContext smContext) {
        // メッセージ方向の取得
        boolean outbound = (boolean)smContext.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
        if(outbound) {
           // アウトバウンド処理
           ...
        } else {
           // インバウンド処理

           // プロパティをkey値("userPropKey"), value値("userPropValue")で
           // 設定する
           smContext.put("userPropKey", "userPropValue");
           // プロパティのスコープをAPPLICATIONスコープで設定する
           smContext.setScope("userPropKey", MessageContext.Scope.APPLICATION);
           ...
        }
        ...
    }
    ...
}

(b)　Webサービス実装クラスまたはプロバイダ実装クラスでプロパティを追加する場合

Webサービス実装クラスまたはプロバイダ実装クラスで追加したユーザ定義メッセージコンテキストプロパティを，アウトバウンド時のサービス側ハンドラから参照する場合，Webサービス実装クラスまたはプロバイダ実装クラスでは，ユーザ定義メッセージコンテキストプロパティの設定だけを実施してください。setScope（java.lang.String name, MessageContext.Scope scope）メソッドを使用してスコープの設定はしないでください。setScope(java.lang.String name, MessageContext.Scope scope)メソッドを使用した場合の動作は保証されません。

10.22　one-wayオペレーション

one-wayオペレーションは一方向の通信なので応答のSOAPメッセージは存在しません。しかし，one-wayメッセージの転送プロトコルにはHTTPを使用するため，WebサービスクライアントはHTTPボディにSOAPメッセージを含まないHTTPレスポンスが返るのを待ちます。一方，サービス側JAX-WSエンジンは，one-wayオペレーションのWebサービス実装クラスの場合，Webサービス実装クラスのメソッドを呼び出す前に，WebサービスクライアントにHTTPステータスコード"202 Accepted"のHTTPレスポンスを返します。

one-wayオペレーションのシーケンスを次の図に示します。

図10‒9　one-wayオペレーションのシーケンス

10.22.1　one-wayオペレーションの注意事項

プロバイダ実装クラスの場合，nullを返すと，invokeメソッドの呼び出し終了後にHTTPステータスコード"202 Accepted"のHTTPレスポンスを返します。

WSS（Web Services - Security），WS-RM 1.2機能，およびアドレッシング機能を使用する場合，one-wayオペレーションはサポートしていません。また，同時に使用した場合の動作は保証されません。

one-wayオペレーションは応答のSOAPメッセージが存在しないため，Webサービス実装クラスのone-wayオペレーションのメソッドの実装では，例外を明示的にスローしないようにしてください。

サービス側JAX-WSエンジンが，不正なSOAPメッセージを受信してアンマーシャルに失敗した場合，HTTPステータスコード"500 Internal Server Error"を設定したSOAPフォルトをWebサービスクライアントに送信します。

one-wayオペレーションを使用するWebサービスクライアントは，HTTPステータスコード"200 OK"および"202 Accepted"以外を受信するとjavax.xml.ws.WebServiceExceptionをスローします。

10.23　ラッパbeanの動的生成機能

ラッパbeanの動的生成機能とは，ラッパbean（リクエストbeanとレスポンスbean），およびフォルトbeanのJavaBeansクラスをJAX-WSエンジンが動的に生成する機能です。SEIを起点として開発したWebサービスで使用できます。Webサービスクライアントや，WSDLを起点とするWebサービスでは，ラッパbeanの動的生成機能はサポートしていません。

ここでは，ラッパbeanの動的生成機能のエラーチェックおよび性能について説明します。

10.23.1　hwsgenコマンドによるエラーチェックについて

SEIを起点としたWebサービスを開発する場合，javacコマンドでWebサービス実装クラスをコンパイルします。ただし，javacコマンドのコンパイルでは，次に示すマッピングのエラーチェックはされません。

デフォルトマッピング

詳細については，「1.4.2(1)(a)　デフォルトマッピング」を参照してください。

マッピングのカスタマイズ（アノテーション）

詳細については，「1.4.2(1)(b)　マッピングのカスタマイズ」を参照してください。

このため，Webサービス実装クラスにJAX-WS機能でサポートしていない定義内容が含まれると，Webサービスの開始に失敗したり，Webサービスの開始に成功してもメタデータの取得やSOAP通信に失敗したりする場合があります。これらの失敗を回避するには，javacコマンドでコンパイルしたWebサービス実装クラスに対してhwsgenコマンドを実行し，事前にエラーチェックをする必要があります。なお，Webサービスの開始に失敗すると，ログおよび標準エラー出力に，次のエラーメッセージが出力されます。

KDJW00003-E

KDJW00005-E

KDJW00006-E

KDJW00007-E

KDJW00008-E

KDJW20026-E

KDJW20027-E

KDJW20041-E

KDJW20042-E

KDJW40011-E

KDJW40013-E

10.23.2　性能について

Webサービスの起動性能は，JAX-WSエンジンがJavaBeansクラスをオンメモリ中に動的生成するオーバーヘッドが掛かるため，JavaBeansクラスを静的に生成した場合に比べると劣化します。しかし，WARファイルから読み込む必要がないため，ファイル読み込みのオーバーヘッドは軽減します。

また，JAX-WSエンジンが動的に生成するJavaBeansクラスは，hwsgenコマンドが静的に生成するJavaBeansクラスと同一のため，Webサービス開始後のSOAP通信では，JavaBeansクラスを動的または静的のどちらで生成しても，性能は変わりません。

10.24　MIME Multipart/Related構造のSOAPメッセージの受信

JAX-WSエンジンは，1048576バイト以上のサイズのMIMEボディを含むMIME Multipart/Related構造のSOAPメッセージを受信する際に，SOAPメッセージに含まれるMIMEボディを一時ファイルに出力することで，Javaヒープサイズの制約を受けることなく大きいサイズのSOAPメッセージを受信します。

一時ファイルは，ルートパートと添付ファイルパートのMIMEボディごとに出力します。なお，SOAPメッセージに添付ファイルが含まれない場合(ルートパートだけの場合)には，ルートパートのMIMEボディだけを一時ファイルに出力します。

MIME Multipart/Related構造のSOAPメッセージに含まれる添付ファイルは，wsi:swaRef形式の添付ファイル，MTOM/XOP仕様形式の添付ファイルまたはSAAJ1.3仕様のAPIを利用して扱えます。

10.24.1　一時ファイル

(1)　命名規則

JAX-WSエンジンが出力する一時ファイルのファイル名は，接頭辞に"MIME"，接尾辞に".tmp"が付いた名前となります。この名前はJAX-WSエンジンが自動で付与するため，任意のファイル名には変更できません。

JAX-WSエンジンが出力する一時ファイルのファイル名の例を次に示します。

MIME6838906861691549713.tmp

異なるプロセスのcjclstartapコマンドでWebサービスクライアントを実行する場合，一時ファイルのファイル名が重複することがあります。そのため，1048576バイト以上のサイズのMIMEボディを含むMIME Multipart/Related構造のSOAPメッセージを受信する場合は，cjclstartapコマンドのプロセスごとに一時ファイルの出力先を変える必要があります。システムプロパティの"java.io.tmpdir"キーで一時ファイルの出力先を指定してください。

(2)　出力と削除

一時ファイルは，1048576バイト以上のサイズのMIMEボディであるルートパートを受信したとき，および1048576バイト以上のサイズのMIMEボディである添付ファイルパートを受信し操作したときに，Javaのデフォルト一時ファイルディレクトリ(システムプロパティにある"java.io.tmpdir"キーに対応する値)へ出力されます。

ルートパートのMIMEボディに対応する一時ファイルは，SOAPメッセージをアンマーシャルしたあとJAX-WSエンジンによって削除されます。また，添付ファイルパートのMIMEボディに対応する一時ファイルは，添付ファイルをクローズするときに削除されます。javax.activation.DataHandler型にマッピングされる添付ファイルを使用する場合は，javax.activation.DataHandlerオブジェクトに対してinstanceof演算子を用いてcom.sun.xml.ws.developer.StreamingDataHandlerクラスであるか判別したあと，com.sun.xml.ws.developer.StreamingDataHandlerクラスにキャストしてからcom.sun.xml.ws.developer.StreamingDataHandler#close()メソッドでクローズする必要があります。

MIME Multipart/Related構造のSOAPメッセージを受信している場合，コネクションの切断やJVMがダウンしたとき，一時ファイルが残ることがあります。一時ファイルが残った場合，一時ファイルを削除してください。

(3)　見積もり方法

JAX-WSエンジンが出力する一時ファイルは，受信するMIME Multipart/Related構造のSOAPメッセージに含まれるMIMEボディと同じサイズです。一時ファイルの最大ディスク使用量は次に示す算出式で求めることができます。

一時ファイルの最大ディスク使用量（Webサービス）

一時ファイルの最大ディスク使用量＝<受信するMIMEボディの最大サイズ>×<受信するMIMEボディの最大数>×<Webサービスの同時実行数>

一時ファイルの最大ディスク使用量（Webサービスクライアント）

一時ファイルの最大ディスク使用量＝<受信するMIMEボディの最大サイズ>×<受信するMIMEボディの最大数>×<Webサービスの呼び出し回数>

11　RESTful Webサービス開発のポイント

この章では，RESTful Webサービス（Webリソース）開発の作業ごとに，あらかじめ理解しておく必要がある点と注意事項について説明します。

11.1　ルートリソースクラスの作成

ルートリソースクラスは，コンパイルしたJavaクラスファイル（*.class）として作成します。必要に応じてサブリソースクラスや例外マッピングプロバイダも同様に作成します。

コンパイルしたJavaクラスファイル（*.class）は，WARファイルを構成するディレクトリに含めます。次に示すどちらか，または両方に含めてください。

classesディレクトリ以下

libディレクトリ以下に含まれるJARファイル内

WARファイルには，少なくとも一つ以上のルートリソースクラスが含まれる必要があります。格納先については，「11.3.1　WARファイルの構成」を参照してください。

注意事項

通常，Webリソースはステートレスです。ルートリソースクラスのフィールドを，複数回のWebリソースの呼び出しで共有しないでください。

11.2　web.xmlの作成

ここでは，Webリソースで使用するWARファイルに含まれるweb.xmlについて説明します。

ファイル名称は"web.xml"とし，WARファイルを構成するWEB-INFディレクトリの直下に格納します。web.xmlの格納は必須です。

Webサービスの実行に必要な定義およびweb.xmlの例について説明します。

11.2.1　Webサービスの実行に必要な定義

web.xmlは，次に示す条件を満たすように作成してください。

バージョン

web.xmlのバージョンは，2.5以上にしてください。

サーブレット

web-app要素に，次に示すservlet要素を含めてください。

<servlet>
 <servlet-name>CosminexusJaxrsServlet</servlet-name>
  <servlet-class>
   com.cosminexus.jersey.spi.container.servlet.ServletContainer
  </servlet-class>
</servlet>

サーブレット初期化パラメタ

servlet要素に，次に示すinit-param要素を必要に応じて含めてください。init-param要素は大文字小文字を区別します。

<init-param>
 <param-name>
  com.sun.jersey.config.property.packages
 </param-name>
 <param-value>
  セミコロン，コンマ，またはスペースで区切られたパッケージ名のリスト
 </param-value>
</init-param>

servlet要素にinit-param要素を含める場合，init-param要素で指定したパッケージとそのサブパッケージに含まれるWebリソースを公開します。servlet要素にinit-param要素を含めない場合，WARに含まれるすべてのWebリソースを公開します。

注意事項

com.sun.jersey.config.property.packagesの<param-value>に，*（アスタリスク）は使用できません。

アスタリスクを使用した場合，または間違ったパッケージ名を指定した場合，エラーになります（KDJJ10020-E）。HTTPエラーコードには500が返ります。

com.sun.jersey.config.property.packagesの<param-value>に指定したパッケージとそのサブパッケージに含まれるクラスに，JDK8から導入されたラムダ式は使用できません。

サーブレットマッピング

web-app要素以下にservlet-mapping要素を記述してください。

servlet-mapping要素の記述例を次に示します。

<servlet-mapping>
 <servlet-name>CosminexusJaxrsServlet</servlet-name>
 <url-pattern>/*</url-pattern>
</servlet-mapping>

11.2.2　web.xmlの例

web.xmlの例を次に示します。

<web-app version="3.0"
  xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
 <servlet>
  <servlet-name>CosminexusJaxrsServlet</servlet-name>
  <servlet-class>
   com.cosminexus.jersey.spi.container.servlet.ServletContainer
  </servlet-class>
  <init-param>
   <param-name>com.sun.jersey.config.property.packages</param-name>
   <param-value>org.test.resources1;org.test.resources2</param-value>
  </init-param>
 </servlet>
 <servlet-mapping>
  <servlet-name>CosminexusJaxrsServlet</servlet-name>
  <url-pattern>/*</url-pattern>
 </servlet-mapping>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

この例で，WARファイルにorg.test.resources1.ResourceA, org.test.resources1.ResourceB, org.test.resources2.ResourceC，およびorg.test.resources3.ResourceDを含んでいると仮定すると，公開されるWebリソースは次のとおりです。

ResourceA

ResourceB

ResourceC

11.3　アーカイブの作成

WARファイルの構成およびEARファイルの作成について説明します。

11.3.1　WARファイルの構成

Webリソースで使用するWARファイルは，次の表に示す構成にする必要があります。

表11‒1　WARファイルの構成

ディレクトリ

備考

/

−

┣

┃

META-INF/

−

┗

MANIFEST.MF

−

┗

WEB-INF/

−

┣

web.xml

作成したweb.xmlです。

┣

classes/

コンパイルしたJavaクラスを格納します。

┗

lib/

コンパイルしたJavaクラスを含むJARファイルを格納します。

（凡例）

−：説明や補足事項が特にないことを示します。

11.3.2　EARファイルの作成

WebリソースをJ2EEサーバにデプロイするには，作成したWARファイルを含めたEARファイルを作成します。EARファイルを作成するには，application.xmlが必要になります。

EARファイルの構成については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「1.4.2　アーカイブ形式のJ2EEアプリケーション」を参照してください。

11.4　RESTful Webサービス用クライアントAPIを使用するクライアントの実装

ここでは，RESTful Webサービス用クライアントAPIを利用して実装するクライアント（以降，Webリソースクライアントと呼びます）について説明します。java.net.URLやjava.net.HttpURLConnectionなど，標準的なJava APIを利用してクライアントを実装する場合は，JDKのドキュメントを参照してください。

Webリソースクライアントの形態に制限はありません。そのため，例えば次に示すWebサービスを開発できます。

Javaアプリケーション（JavaアプリケーションからWebリソースを呼び出す）

JSP（JSPからWebリソースを呼び出す）

サーブレット（サーブレットからWebリソースを呼び出す）

EJB（EJBから，Webリソースを呼び出す）

SOAP Webサービス（SOAP WebサービスからWebリソースを呼び出す）

Webリソース（ルートリソースクラスやサブリソースクラスから，さらに別のWebリソースを呼び出す）

WebリソースクライアントはSOAP Webサービスを呼び出すクライアントとは異なり，Webリソースクライアントを実装する前に，コマンドを実行してスタブなどのJavaソースをあらかじめ作成する必要はありません。RESTful Webサービス用クライアントAPIの仕様に従って，実装してください。RESTful Webサービス用クライアントAPIの仕様については「25.　RESTful Webサービス用クライアントAPIのサポート範囲」を参照してください。

11.4.1　Webリソースクライアントのユースケース

ここでは，RESTful Webサービス用クライアントAPIの基本的なユースケースについて説明します。Webリソースを呼び出すには，次の三つの方法があります。

Java型を指定してHTTPリクエストおよびHTTPレスポンスを送受信する方法

Java型を指定してHTTPリクエストを送信し，汎用型（ClientResponse）でHTTPレスポンスを受信する方法

汎用型（ClientRequestおよびClientResponse）でHTTPリクエストおよびHTTPレスポンスを送受信する方法

それぞれのパターンについて次に説明します。

(1)　Java型を指定してHTTPリクエストおよびHTTPレスポンスを送受信する

Java型を指定してHTTPリクエストおよびHTTPレスポンスを送受信する場合のユースケースを次の図に示します。

図11‒1　Java型を指定してHTTPリクエストおよびHTTPレスポンスを送受信する場合のユースケース

注※1

マップに含まれるプロパティはさまざまな方法で参照・変更できます。詳細は「11.4.3　プロパティとフィーチャの設定」を参照してください。

注※2

クライアントAPIのさまざまなメソッドを利用してリクエストを生成できます。詳細は「11.4.3　プロパティとフィーチャの設定」を参照してください。

注※3

HTTPリクエストのエンティティボディを文字列の形式で，HTTP POSTメソッドを使用して送信し，同様に文字列の形式でHTTPレスポンスのエンティティボディを受信します。

クライアントAPIではDELETE，GET，HEAD，OPTIONS，PUTの各HTTPメソッドに対応するメソッドもあります。詳細は「11.4.3　プロパティとフィーチャの設定」を参照してください。

注※4

HttpURLConnectionが行います。JAX-RSエンジンはHTTPメッセージの作成まで行い，HTTP通信についてはJava SEのHttpURLConnectionに委譲しています。

図11-1に対応したコーディング例は次のとおりです。

Client client = Client.create();
Map<String, Object> properties = client.getProperties();
properties.put(ClientConfig.PROPERTY_READ_TIMEOUT, 10000);
WebResource proxy = client.resource( "http://example.org/helloworld" );
WebResource.Builder builder = proxy.accept( MediaType.APPLICATION_JSON_TYPE );
builder = builder.type( MediaType.TEXT_PLAIN_TYPE );
String response = builder.post( String.class, "Some Request" );

この例での処理の流れについて説明します。

Clientクラスのcreate()スタティックメソッドを使用してClientオブジェクトを生成します。

ClientクラスのgetProperties()メソッドで取得した変更可能なプロパティマップにプロパティを設定します。なお，プロパティは別の方法でも設定できます。プロパティとフィーチャの詳細については「11.4.3　プロパティとフィーチャの設定」を参照してください。

Clientクラスのresource()メソッドを呼び出してWebResourceオブジェクトを生成し，WebResourceオブジェクトのメソッドを呼び出してHTTPリクエストを作成していきます。WebResourceクラスはビルダパターンでデザインされており，HTTPリクエストを生成する各種メソッドが含まれています。

WebResource.Builderクラスのpost()メソッドを呼び出してHTTP通信を行います。WebResourceクラスには，DELETE，GET，HEAD，OPTIONS，PUTの各HTTPメソッドに対応するメソッドもあります。

(2)　Java型を指定してHTTPリクエストを送信し，汎用型（ClientResponse）でHTTPレスポンスを受信する

受信するHTTPレスポンスは汎用型，つまりClientResponseオブジェクトでも取得できます。ClientResponseオブジェクトで取得した場合，ユーザは受信したHTTPレスポンスの各種情報（HTTPヘッダ，エンティティボディ，およびステータスコード）を取得できます。

エンティティボディは，getEntity()メソッドを使用することで，Java型を指定して取得できます。ClientResponseクラスでサポートしているメソッドについては「25.1　クライアントAPIのインタフェースおよびクラスのサポート範囲」を参照してください。

受信するHTTPレスポンスをClientResponseオブジェクトで取得する方法は次のとおりです。

WebResourceオブジェクトを使用してHTTPリクエストを生成する場合は，HTTPレスポンスのJava型を指定するパラメタにClientResponse.classを指定してください。「11.4.1(1)　Java型を指定してHTTPリクエストおよびHTTPレスポンスを送受信する」で示したコーディング例では，String.classの代わりにClientResponse.classを指定してください。

Clientクラスを使用してHTTPリクエストを直接送信する場合は，HTTPレスポンスは常にClientResponseです。Clientクラスの詳細については，「11.4.1(3)　汎用型でHTTPリクエストおよびHTTPレスポンスを送受信する」を参照してください。

(3)　汎用型でHTTPリクエストおよびHTTPレスポンスを送受信する

汎用型（ClientRequestおよびClientResponse）でHTTPリクエストおよびHTTPレスポンスを送受信する場合のユースケースを次の図に示します。

図11‒2　汎用型でHTTPリクエストおよびHTTPレスポンスを送受信する場合のユースケース

注※1

マップに含まれるプロパティはさまざまな方法で参照・変更できます。詳細は「11.4.3　プロパティとフィーチャの設定」を参照してください。

注※2

クライアントAPIのさまざまなメソッドを利用してリクエストを生成できます。詳細は「11.4.3　プロパティとフィーチャの設定」を参照してください。

注※3

HTTPリクエストのエンティティボディを文字列の形式で，HTTP POSTメソッドを使用して送信し，同様に文字列の形式でHTTPレスポンスのエンティティボディを受信します。

クライアントAPIではDELETE，GET，HEAD，OPTIONS，PUTの各HTTPメソッドに対応するメソッドもあります。詳細は「11.4.3　プロパティとフィーチャの設定」を参照してください。

注※4

HttpURLConnectionが行います。JAX-RSエンジンはHTTPメッセージの作成まで行い，HTTP通信についてはJava SEのHttpURLConnectionに委譲しています。

上記の図に対応したコーディング例は次のとおりです。

Client client = Client.create();
Map<String, Object> properties = client.getProperties();
properties.put(ClientConfig.PROPERTY_READ_TIMEOUT, 10000);
ClientRequest ro;
ClientRequest.Builder builder = ClientRequest.create();
builder.accept( MediaType.APPLICATION_JSON_TYPE );
builder.type( MediaType.TEXT_PLAIN_TYPE );
builder.entity("Some Request");
ro = builder.build(new URI("http://example.org/helloworld"), "POST");
ClientResponse clientResponse = client.handle(ro);
//The actual response in the form of String
String response = clientResponse.getEntity(String.class);

この例での処理の流れについて説明します。

Clientクラスのcreate()スタティックメソッドを使用してClientオブジェクトを生成します。

ClientクラスのgetProperties()メソッドで取得した変更可能なプロパティマップにプロパティを設定します。プロパティとフィーチャの詳細については，「11.4.3　プロパティとフィーチャの設定」を参照してください。

ClientRequestクラスのcreate()メソッドを呼び出してClientRequest.Builderオブジェクトを生成し，ClientRequest.Builderオブジェクトのメソッドを呼び出してHTTPリクエストを作成していきます。ClientRequest.Builderクラスはビルダパターンでデザインされており，HTTPリクエストを生成する各種メソッドが含まれています。

ClientRequest.Builderクラスのbuild()メソッドを呼び出しClientRequestオブジェクトを生成します。次にClientクラスのhandle()メソッドを呼び出してHTTP通信を行います。

11.4.2　RESTful Webサービス用クライアントAPIの仕組み

RESTful Webサービス用クライアントAPIは，HttpURLConnection/HttpsURLConnectionクラスをラップしており，実際のHTTP通信についてはJDKが行っています。なお，以降では特に明記のないかぎり，HttpURLConnection/HttpsURLConnectionをまとめてHttpURLConnectionと呼びます。

仕組みについて次の図に示します。

図中の1.および2.では次の処理を行っています。

1.

接続タイムアウトなどのプロパティを設定します。

HTTPヘッダを追加します。

HTTPリクエストのエンティティボディを，HttpURLConnectionから取得した出力ストリームを介して送信します。

2.

HTTPヘッダを取得します。

HTTPレスポンスのエンティティボディを，HttpURLConnectionから取得した入力ストリームを介して受信します。

(1)　RESTful Webサービス用クライアントAPIとユーザプログラムの関係

RESTful Webサービス用クライアントAPIは，エンティティボディリーダやエンティティボディライタを使用して，JavaオブジェクトやHTTPリクエストを相互にマーシャル・アンマーシャルしています。このため，ユーザプログラムが入力ストリームや出力ストリームを直接操作する必要はありません。

(2)　RESTful Webサービス用クライアントAPIとJDKの関係

RESTful Webサービス用クライアントAPIは，トランスポート層の処理をHttpURLConnectionに委譲しています。また，プロパティやHTTPヘッダを設定するためのさまざまなビルトインメソッドを提供していますが，ビルトインメソッドに指定した値はそのままHttpURLConnectionに設定します。そのため，実際のHTTP通信やビルトインメソッドに指定した値を使用した処理はJDKが行います。

11.4.3　プロパティとフィーチャの設定

Clientオブジェクトにはプロパティとフィーチャを格納した変更可能なプロパティマップが含まれています。

これ以降，プロパティとフィーチャは区別しないで「プロパティ」と総称します。

(1)　プロパティマップの初期化

変更可能なプロパティマップは，Clientオブジェクトの生成時に初期化されます。プロパティマップを初期化する方法について次に説明します。

方法1

DefaultClientConfigオブジェクトをパラメタに指定して，Clientクラスのcreate(ClientConfig cc)スタティックメソッドを呼び出し，Clientオブジェクトを生成します。この場合，Clientオブジェクトの変更可能なプロパティマップは，DefaultClientConfigオブジェクトが持つプロパティによって初期化※されます。

注※

DefaultClientConfigオブジェクトにプロパティが含まれれば，その値で初期化されます。DefaultClientConfigオブジェクトに含まれないプロパティは，動作定義ファイルの設定で初期化されます。

方法2

Clientクラスのcreate()スタティックメソッドでClientオブジェクトを生成します。この場合，Clientオブジェクトの変更可能なプロパティマップは，動作定義ファイルによって初期化されます。

動作定義ファイルの詳細については，「13.1　動作定義ファイル」を参照してください。

(2)　変更可能なプロパティマップの構造

HttpURLConnectionクラスに関連する四つのプロパティは，ClientクラスのgetProperties()メソッドで取得したプロパティマップを変更したり，プロパティそれぞれに対応するsetterメソッドを使用して設定したりできます。

なお，HttpURLConnectionに関連する四つのプロパティ以外は，対応するsetterメソッドがありません。プロパティを設定する場合はClientクラスのgetProperties()メソッドで取得したプロパティマップを変更してください。

変更可能なプロパティマップの構造について次の図に示します。

なお，サポートしているプロパティの一覧については「25.1.1　サポートするプロパティとフィーチャ」を参照してください。

図11‒3　変更可能なプロパティマップの構造

HTTP通信に先立って，JAX-RSエンジンは図中のHttpURLConnectionクラスに関連する四つのプロパティの値をそのままHttpURLConnectioinにコピーします（値の検証はしません）。したがって，値が不正な場合，HTTP通信の実行前または実行中にHttpURLConnectionクラスが例外をスローすることがあります。なお，値がnullの場合はコピーされないで，無視されます。

ClientRequestクラスにも同じ形式の変更可能なプロパティマップがあります。したがって，Clientクラスのhandle()メソッドを使用してHTTP通信を行う場合，ユーザプログラムはClientRequestオブジェクトを介してプロパティを設定することもできます。仕組みを次の図で説明します。

図11‒4　変更可能なプロパティマップのコピーの仕組み

JAX-RSエンジンは，同じプロパティがClientオブジェクトのプロパティマップに存在しない場合だけ，ClientRequestオブジェクトのプロパティマップに含まれるプロパティをClientオブジェクトのプロパティマップにコピーします。

11.4.4　HTTPヘッダの設定

クライアントAPIには，HTTPリクエストオブジェクトにHTTPヘッダを設定するためのさまざまなメソッドを提供しています。サポートしているメソッドの詳細については「25.1　クライアントAPIのインタフェースおよびクラスのサポート範囲」を参照してください。なお，この説明でのHTTPリクエストオブジェクトとは，次のどちらかを指します。

WebResourceオブジェクトまたはClientRequestオブジェクト

WebResource.BuilderオブジェクトまたはClientRequest.Builderオブジェクト

HTTPリクエストオブジェクトには，HTTPヘッダと対応する値を保持するMultivaluedMapオブジェクトが含まれています。

HTTPヘッダを保持するMultivaluedMapオブジェクトがどのように初期化されるのかを次の図で説明します。

図11‒5　MultivaluedMapオブジェクトの初期化の仕組み

この図では，ユーザプログラムはClientRequestクラスのcreate()スタティックメソッドまたはClientクラスのresource()メソッドを使用してHTTPリクエストオブジェクトを生成しています。

この場合，MultivaluedMapオブジェクトは空の状態で初期化されます。

MultivaluedMapオブジェクトにHTTPヘッダを設定する例を次の図に示します。

例1

例2

例3

例4

例1〜例4のどの方法でも，ユーザプログラムは，"text/xml"と"text/plain"を値とするAccept HTTPヘッダを持つHTTPリクエストオブジェクトを生成できます。Accept-Language HTTPヘッダとCookie HTTPヘッダについても同様です。なお，Accept-Language HTTPヘッダとCookie HTTPヘッダの場合はacceptメソッドをそれぞれacceptLanguage()メソッドまたはcookie()メソッドに読み替えてください。

Content-Type HTTPヘッダの場合，例1と例3の動作は次に示すとおりになります。

例1

例3

どちらの場合でも，HTTPリクエストオブジェクトに設定されるContent-Type HTTPヘッダの値は"text/plain"です。なお，Content-Type HTTPヘッダは値を一つしか持てないため，例2と例4の方法は利用できません。

HTTP通信に先立って，HTTPリクエストオブジェクトに追加されたすべてのHTTPヘッダとその値は，HttpURLConnectionオブジェクトに設定されます。仕組みを次の図で説明します。

それぞれのHTTPヘッダには，HTTPリクエストオブジェクトに含まれる対応するHTTPヘッダの値が設定されます。なお，この場合，HTTPリクエストオブジェクトに含まれる対応するHTTPヘッダの値がnullでなければ，toString()メソッドの戻り値に設定されます。JAX-RSエンジンはHTTPヘッダの値を検証しません。標準仕様に従ってHTTPヘッダの値をHTTPリクエストオブジェクトに設定してください。

なお，HTTP通信を行うまでに，特定のHTTPヘッダをHTTPリクエストオブジェクトに設定しなかった場合の動作は，HTTPヘッダをHttpURLConnectionオブジェクトに設定しなかった場合と同様です。

11.4.5　注意事項

Webリソースクライアント実装時の注意事項について説明します。

(1)　オブジェクトの再利用

Clientオブジェクトの生成には処理コストが掛かるので，一度生成したClientオブジェクトは再利用することをお勧めします。WebResourceオブジェクトを複数回生成したり，Clientクラスのメソッドを利用してWebリソースを複数回呼び出したりする場合に，Clientオブジェクトを複数回生成する必要はありません。

同様に，WebResourceの生成にも処理コストが掛かるので，一度生成したWebResourceオブジェクトは再利用することをお勧めします。同じWebリソース（URL）に対するHTTPリクエストやビルダを複数回生成する場合に，WebResourceオブジェクトを複数回生成する必要はありません。

ただし，Clientクラスの設定を行うメソッドや，オブジェクトを破棄するClientクラスのメソッドはスレッドセーフではありません。次の内容に注意してください。

複数スレッドでClientオブジェクトを共有する場合，共有するClientオブジェクトに対する設定は，複数スレッドが動作する前に実行してください。

Clientオブジェクトの破棄は，複数スレッドの動作が完了したあとに実行してください。

複数スレッドの動作中にこれらの操作を行った場合，通信が失敗したり，不正なHTTPリクエストが送信されたりすることがあります。

WebリソースクライアントをサーブレットやEJBなどで実装する場合は，サーブレットやEJBなどの初期化メソッドでClientオブジェクトを生成し，必要な設定を行ってください。Clientオブジェクトの破棄についても同様に，破棄メソッドでClientオブジェクトの破棄を行ってください。

サーブレットでRESTful Webサービス用クライアントAPIを利用する例を次に示します。

@WebServlet("/example")
public class ClientServlet extends HttpServlet {

  // 共有されるClientオブジェクト
  private Client client = null;

  // 共有されるWebResourceオブジェクト
  private WebResource proxy = null;

  @PostConstruct
  public void postConstruct() {
    // RESTful Webサービス用クライアントAPIを利用するために
    // Clientオブジェクトを生成する
    this.client = Client.create();
    // クライアントの設定: Clientオブジェクトからプロパティバッグを取得する
    Map<String, Object> properties = this.client.getProperties();
    // クライアントの設定: 読み込みタイムアウトを設定する
    properties.put(ClientConfig.PROPERTY_READ_TIMEOUT, 10000);
    //  ClientオブジェクトからWebResourceオブジェクトを生成する
    this.proxy = this.client.resource( "http://..." );
  }

 @PreDestroy
  public void preDestory() {
    //  Clientオブジェクトを破棄する
    if( this.client != null ){
      this.client.destroy();
      this.client = null;
    }
  }

  @Override
  public void doGet( HttpServletRequest request, HttpServletResponse response )
    throws ServletException, IOException{
    ...
    ClientResponse clientResponse = null;
    // Invoke resource
    try {
      // クッキーを設定後，WebリソースからHTTPレスポンスを取得する
      Cookie cookie = new Cookie("cookie", "cookie%20value");
      clientResponse = this.proxy.cookie(cookie).get(ClientResponse.class);
    }catch (Exception e) {
      printStackTrace( e, out );
    }
    ...
  }
}

RESTful Webサービス用クライアントAPIのスレッドセーフ性の詳細については，「25.16　RESTful Webサービス用クライアントAPIのスレッドセーフ性」を参照してください。

(2)　プロキシ・SSL接続・ベーシック認証の設定

プロキシ，SSL接続，およびベーシック認証の設定については，それぞれ次の個所を参照してください。

プロキシの設定

「10.10　プロキシサーバ経由の接続」

SSL接続の設定

「10.11　SSLプロトコルによる接続」

ベーシック認証の設定

「10.12　ベーシック認証による接続」

(3)　Windows環境での注意事項

Webリソースクライアントから大量のリクエストを送信するような環境では，次の例外が記録されることがあります。

java.net.BindException: Address already in use: connect  [errno=10048, syscall=select]

この例外は，例えばサーブレットとして実装したWebリソースクライアントに対して大量のリクエストが到着したときなどに発生します。

このような場合は，次に示すどちらか，または両方の対策を実施してください。

OSで使用できるポート番号の範囲を広げる

例）レジストリのMaxUserPortの設定を見直す

TIME_WAITの継続時間を短くする

例）レジストリのTcpTimedWaitDelayの設定を見直す

ただし，OSのバージョンやエディション，セキュリティ更新プログラムの適用状況によって仕様が異なるため，詳細については各OSのドキュメントを参照してください。また，これらの設定はOS全体に影響が及ぶため，注意が必要です。

(4)　リクエスト再送抑止

Webリソースクライアント側のJAX-RSエンジンは，JDKのHTTPクライアント実装を利用して通信しています。JDKのHTTPクライアント実装は，RFC 2616に反してHTTP通信でエラーが発生し，サーバから正しいレスポンスを受け取れなかった場合，一度だけリクエストを再送します。JDKのシステムプロパティを使用するとリクエストの再送を抑止できます。詳細は，「10.20　sun.net.www.http.HttpClientによるリクエスト再送抑止」を参照してください。なお，参照する場合は「Webサービスクライアント」を「RESTful Webサービスクライアント」に，「JAX-WSエンジン」を「JAX-RSエンジン」に読み替えてください。

(5)　コマンドラインを利用したクライアントアプリケーションの実行

コマンドラインで動作するJavaアプリケーションをクライアントアプリケーションとして利用するときに必要な設定，コマンドラインの指定例，注意事項については，「10.14　コマンドラインを利用したクライアントアプリケーションの実行」を参照してください。なお，RESTful Webサービスクライアントでは，Javaアプリケーション用オプション定義ファイルに次のキーと値も追加してください。

add.class.path=<インストールディレクトリ>/jaxws/lib/cjjaxrs.jar

(6)　通信失敗時のJava例外

Webサービスとの通信が失敗した場合，次の例外が記録されることがあります。

java.net.ConnectException: ["Connection refused: connect"または"接続を拒否されました"]

このメッセージは，OSや環境によって出力内容が異なる場合があります。

12　RESTful Webサービス開発の例

この章では，RESTful Webサービス（Webリソース）を開発する場合の例を説明します。

12.1　開発例の構成

この章で説明する開発例では，RESTful Webサービス（Webリソース）を開発します。ルートリソースクラスのほか，サブリソースクラスと例外マッピングプロバイダも実装します。

開発するWebリソースの構成を次の表に示します。なお，この開発例は次のディレクトリにサンプルとして提供されています。

<インストールディレクトリ>¥jaxrs¥samples¥tutorial¥

表12‒1　Webリソースの構成

項番

項目

値

1

デプロイするJ2EEサーバの名称

jaxrsserver

2

Webサーバのホスト名とポート番号

webhost:8085

3

ネーミングサーバのURL

corbaname::testserver:900

4

コンテキストルート

tutorial

5

ルートリソースクラスのコンテキストパス

root

6

ルートリソースクラス

com.sample.resources.Resource

7

サブリソースクラス

com.sample.resources.SubResource

8

例外マッピングプロバイダ

com.sample.providers.RuntimeExceptionMapper

Webリソース開発時のカレントディレクトリの構成を次の表に示します。

表12‒2　カレントディレクトリの構成

ディレクトリ

説明

c:¥temp¥jaxrs¥works¥tutorial

カレントディレクトリです。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

server¥

Webリソースの開発で使用します。

┣

┃

┃

┃

┃

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

┗

application.xml

「12.3.4　application.xmlを作成する」で作成します。

┣

┃

src¥

Webリソースのソースファイル（*.java）を格納します。「12.3.1　ルートリソースクラスを作成する」で使用します。

┣

┃

┃

┃

┃

┃

WEB-INF¥

WARファイルのWEB-INFディレクトリに対応します。

┣

web.xml

「12.3.3　web.xmlを作成する」で作成します。

┗

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「12.3.2　Javaソースをコンパイルする」で使用します。

┣

tutorial.ear

「12.3.5　EARファイルを作成する」で作成します。

┗

tutorial.war

┗

client¥

Webリソースクライアントの開発で使用します。

┣

┃

┃

┃

┃

┃

src¥

Webリソースクライアントのソースファイル（*.java）を格納します。「12.5.1　Webリソースクライアントの実装クラスを作成する（クライアントAPIを利用する）」または「12.5.2　Webリソースクライアントの実装クラスを作成する（java.net.HttpURLConnectionを利用する）」で作成します。

┣

┃

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「12.3.2　Javaソースをコンパイルする」で作成します。

┣

┃

┃

usrconf.cfg

「12.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

┗

usrconf.properties

「12.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

カレントディレクトリのパスは，開発する環境に合わせて変更してください。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebリソースとWebリソースクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

12.2　開発例の流れ

この章で説明する開発例では，次の流れで開発および実行します。

Webリソースの開発

ルートリソースクラスを作成する（12.3.1）

Javaソースをコンパイルする（12.3.2）

web.xmlを作成する（12.3.3）

application.xmlを作成する（12.3.4）

EARファイルを作成する（12.3.5）

デプロイと開始

EARファイルをデプロイする（12.4.1）

Webサービスを開始する（12.4.2）

Webリソースクライアントの開発

Webリソースクライアントの実装クラスを作成する（12.5.1または12.5.2）

Webリソースクライアントの実装クラスをコンパイルする（12.5.3）

Webリソースの呼び出し

Javaアプリケーション用オプション定義ファイルを作成する（12.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（12.6.2）

Webリソースクライアントを実行する（12.6.3）

12.3　Webリソースの開発例

ここでは，Webリソースの開発例を説明します。

12.3.1　ルートリソースクラスを作成する

ルートリソースクラスを作成します。ここでは，次のリソースメソッド，サブリソースメソッド，サブリソースロケータ，およびインジェクションの対象となるコンストラクタ，フィールド，beanプロパティを持つルートリソースクラスを作成します。

表12‒3　作成するルートリソースクラス

項目

要求メソッド識別子

/root以下のコンテキストパス

備考

リソースメソッド

resourceMethod1

@GET

−

−

resourceMethod7

@POST

−

フォーム値をインジェクトするFormParamアノテーションでアノテートされたパラメタを持ちます。

MIMEタイプ"*/*"のHTTPエンティティを受け取ります。

MIMEタイプ"application/xml"のHTTPエンティティを返します。

サブリソースメソッド

subResourceMethod2

@GET

/getQueryParam

−

subResourceMethod3

@POST

/getUriInfoAndEntity

エンティティパラメタを持ちます。

subResourceMethod4

@GET

/getHttpHeaders

HttpHeadersをインジェクトするContextアノテーションでアノテートされたパラメタを持ちます。

subResourceMethod5

@GET

/getMatrixParam

マトリクスパラメタをインジェクトするMatrixParamアノテーションでアノテートされたパラメタを持ちます。

subResourceMethod6

@GET

/getCookieParam

CookieをインジェクトするCookieParamアノテーションでアノテートされたパラメタを持ちます。

subResourceMethod8

@GET

/getPathParam

パスパラメタをインジェクトするPathParamアノテーションでアノテートされたパラメタを持ちます。

subResourceMethod ThrowingException

@GET

/{path:[A-Z][a-z]+}/exception

例外をスローします。スローされた例外は例外マッピングプロバイダRuntimeExceptionMapperによってHTTPエンティティにマッピングされます。

pojoJsonMappingMethod

@POST

/pojoJsonMapping

JSON形式のデータを処理します。

サブリソースロケータ

subResourceMethod9

−

/subresourceLocator

サブリソースクラスSubResourceに処理を委譲します。

コンストラクタ

−

−

UriInfoをインジェクトするContextアノテーションでアノテートされたパラメタを持ちます。

フィールド

−

−

RequestをインジェクトするContextアノテーションでアノテートされています。

beanプロパティ

−

−

クエリパラメタをインジェクトするQueryParamアノテーションでアノテートされています。

（凡例）−：該当する内容がないことを示します。

ルートリソースクラスの作成例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.CookieParam;
import javax.ws.rs.FormParam;
import javax.ws.rs.MatrixParam;
import javax.ws.rs.PathParam;
import javax.ws.rs.QueryParam;
import javax.ws.rs.DefaultValue;
import javax.ws.rs.Encoded;
import javax.ws.rs.Consumes;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.Request;
import javax.ws.rs.core.UriInfo;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.ResponseBuilder;

//サンプル：ルートリソースクラス
//このクラスはURI "/root"でアクセスされる
@Path("/root")
public class Resource {

    //コンテキスト（javax.ws.rs.core.Requestオブジェクト）の
    //フィールドへのインジェクション
    private @Context
    Request request;

    //setter()メソッドを使用したクエリパラメタのインジェクション
    @QueryParam("queryParam")
    public void setQueryParam(String queryParam) {
        this.queryParam = queryParam;
    }
    //上記のsetter()メソッドでインジェクトされたクエリパラメタを
    //格納するprivateフィールド
    private String queryParam;

    //コンテキスト（javax.ws.rs.core.UriInfoオブジェクト）の
    //コンストラクタパラメタへのインジェクション
    public Resource(@Context UriInfo uriInfo) {
        this.uriInfo = uriInfo;
    }
    //上記のコンストラクタでインジェクトされたUriInfoオブジェクトを
    //格納するprivateフィールド
    private UriInfo uriInfo;

    //サンプル：リソースメソッド1
    //  フィールドにインジェクトされたコンテキストの値
    //  （javax.ws.rs.core.Requestオブジェクト）を返す
    //このメソッドはHTTP GETリクエストを処理する
    @GET
    public String resourceMethod1() {
        String returnString = "RequestMethod: " + request.getMethod();
        return returnString;
    }

    //サンプル：サブリソースメソッド2
    //  setter()メソッドにインジェクトされたクエリパラメタの値を返す
    //このメソッドはHTTP GETリクエストを処理する
    @GET
    //このメソッドはURI "/root/getQueryParam"でアクセスされる
    @Path("getQueryParam")
    public String subResourceMethod2() {
        String returnString = "QueryParameter: " + queryParam;
        return returnString;
    }

    //サンプル：サブリソースメソッド3
    //  コンストラクタパラメタにインジェクトされた
    //  コンテキストの値（javax.ws.rs.core.UriInfoオブジェクト）と，
    //  受信したHTTPリクエストのエンティティボディを返す
    //このメソッドはHTTP POSTリクエストを処理する
    @POST
    //このメソッドはURI "/root/getUriInfoAndEntity"でアクセスされる
    @Path("getUriInfoAndEntity")
    public String subResourceMethod3(
            //エンティティパラメタ（アノテートされていないパラメタ）は
            //HTTPリクエストのエンティティボディからマッピングされる
            String entity) {
        String returnString = "UriInfo: " + uriInfo.getPath() + "; Entity: " + entity;
        return returnString;
    }

    //サンプル：サブリソースメソッド4
    //  サブリソースメソッドパラメタにインジェクトされた
    //  コンテキストの値（javax.ws.rs.core.HttpHeadersオブジェクト）を返す
    //このメソッドはHTTP GETリクエストを処理する
    @GET
    //このメソッドはURI "/root/getHttpHeaders"でアクセスされる
    @Path("getHttpHeaders")
    public String subResourceMethod4(
            //javax.ws.rs.core.HttpHeadersオブジェクトの
            //サブリソースメソッドパラメタへのインジェクション
            @Context HttpHeaders httpHeaders) {
        String returnString = "HttpHeaders: " +
            httpHeaders.getRequestHeader("header").get(0).toString();
        return returnString;
    }
    //サンプル：サブリソースメソッド5
    //  サブリソースメソッドパラメタにインジェクトされた
    //  マトリクスパラメタの値を返す
    //このメソッドはHTTP GETリクエストを処理する
    @GET
    //このメソッドはURI "/root/getMatrixPara"でアクセスされる
    @Path("getMatrixParam")
    public String subResourceMethod5(
            //デフォルト値はマトリクスパラメタに与えられる
            @DefaultValue("defaultValue")
            //マトリクスパラメタの
            //サブリソースメソッドパラメタへのインジェクション
            @MatrixParam("matrix") String matrixParam) {
        String returnString = "MatrixParam: " + matrixParam;
        return returnString;
    }

    //サンプル：サブリソースメソッド6
    //  サブリソースメソッドパラメタにインジェクトされたCookieの値を返す
    //このメソッドはHTTP GETリクエストを処理する
    @GET
    //このメソッドはURI "/root/getCookieParam"でアクセスされる
    @Path("getCookieParam")
    public String subResourceMethod6(
            //自動URI復号化を無効にする
            @Encoded
            //Cookieのサブリソースメソッドパラメタへのインジェクション
            @CookieParam("cookie") String cookieParam ) {
        String returnString = "CookieParam: " + cookieParam;
        return returnString;
    }
    //サンプル：リソースメソッド7
    //  リソースメソッドパラメタにインジェクトされた値を返す
    //このメソッドはMIMEメディアタイプで定義された内容を使用する
    @Consumes("*/*")
    //このメソッドはMIMEメディアタイプ"application/xml"で定義された
    //内容を使用する
    @Produces("application/xml")
    //このメソッドはHTTP POSTリクエストを処理する
    @POST
    public Response resourceMethod7(
            //formパラメタのリソースメソッドパラメタへのインジェクション
            @FormParam("form") String formParam ) {
        ResponseBuilder rb = Response.status(200)
            .entity("<FormParam>" + formParam + "</FormParam>" )
            .type("application/xml");
        return rb.build();
    }

    //サンプル：サブリソースメソッド8
    //  サブリソースメソッドパラメタにインジェクトされた
    //  パスパラメタの値を返す
    //このメソッドはHTTP GETリクエストを処理する
    @GET
    //このメソッドはURI "/root/getPathParam/{path:[A-Z][a-z]+}"で
    //アクセスされる
    //"getPathParam/{path:[A-Z][a-z]+}"は変数を含むURIテンプレートである
    //"{path:[A-Z][a-z]+}"は正規表現を使用している
    @Path("getPathParam/{path:[A-Z][a-z]+}")
    public String subResourceMethod8(
            //パスパラメタの
            //サブリソースメソッドパラメタへのインジェクション
            @PathParam("path") String pathParam ) {
        String returnString = "PathParam: " + pathParam;
        return returnString;
    }

    //サンプル：サブリソースロケータ9
    //サブリソースクラスはURI "/root/subresourceLocator"でアクセスされる
    @Path("/subresourceLocator")
    public SubResource subResourceMethod9() {
        //サブリソースロケータはHTTPリクエストを処理するために
        //リソースクラスインスタンスを返す
        return new SubResource();
    }

    //サンプル：サブリソースメソッド10
    //  例外をスローする
    //スローされた例外は例外マッピングプロバイダによって
    //HTTPレスポンスにマッピングされる
    //このメソッドはHTTP GETリクエストを処理する
    @Path("/exception")
    //このメソッドはURI "/root/exception"でアクセスされる
    @GET
    public String subResourceMethodThrowingException() {
        throw new RuntimeException();
    }

    //サンプル: サブリソースメソッド11
    //  JSON形式のデータを処理する
    //このメソッドはHTTP POSTリクエストを処理する
    @Path("pojoJsonMapping")
    //このメソッドは URI "root/PojoJsonMapping"でアクセスされる
    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public CustomType pojoJsonMappingMethod(CustomType record) {
        // クライアントから受け取ったrecordオブジェクトの内容を確認する
        if(!record.getName().equals("Old Record Name")){
            throw new RuntimeException();
        }
        List<Integer> oldGrades = new ArrayList<Integer>();
        oldGrades.add(1);
        oldGrades.add(2);
        oldGrades.add(3);
        if(!record.getGrades().equals(oldGrades)){
            throw new RuntimeException();
        }

        // クライアントに送り返すCustomTypeオブジェクトを新規に生成する
        CustomType newRecord = new CustomType();
        newRecord.setName("New Record Name");
        List<Integer> newGrades = new ArrayList<Integer>();
        newGrades.add(5);
        newGrades.add(6);
        newGrades.add(7);
        newRecord.setGrades(newGrades);

        return newRecord;
    }
}

作成したルートリソースクラス（Resource.java）は，UTF-8形式でc:¥temp¥jaxrs¥works¥tutorial¥server¥src¥com¥sample¥resources¥ディレクトリに保存します。

サブリソースクラスの作成例を次に示します。このサブリソースクラスはHTTP GETリクエストを受け付けるリソースメソッドを持ちます。なお，サブリソースクラスの作成は任意です。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.HeaderParam;

//サンプル：サブリソースクラス
public class SubResource {

    //このメソッドはHTTP GETリクエストを処理する
    @GET
    public String getHandlerForSubResource(
            //サブリソースメソッドパラメタへの
            //ヘッダパラメタのインジェクション
            @HeaderParam("header") String headerParam) {
        return "Header: " + headerParam;
    }
}

作成したサブリソースクラス（SubResource.java）は，UTF-8形式でc:¥temp¥jaxrs¥works¥tutorial¥server¥src¥com¥sample¥resources¥ディレクトリに保存します。

例外マッピングプロバイダの作成例を次に示します。この例外マッピングプロバイダは，HTTPヘッダheaderに"RuntimeException occurs"の値を持つステータスコード501のHTTPレスポンスに，ランタイム例外をマッピングします。なお，例外マッピングプロバイダの作成は任意です。

package com.sample.providers;

import javax.ws.rs.core.Response;
import javax.ws.rs.ext.Provider;
import javax.ws.rs.ext.ExceptionMapper;

//サンプル：例外マッピングクラス
//このクラスはRuntimeExceptionをHTTPレスポンスにマッピングする
@Provider
public class RuntimeExceptionMapper implements
        ExceptionMapper<RuntimeException> {
    //このメソッドはアプリケーションがランタイム例外を
    //スローしたときに呼び出される
    public Response toResponse(RuntimeException re) {
        //HTTPレスポンスのステータスとして"HTTP/1.1 501 Not Implemented"を
        //設定する
        //HTTPレスポンスのヘッダに"header: RuntimeException occurs"を
        //設定する
        return Response.status(501)
            .header("header", "RuntimeException occurs").build();
    }
}

作成した例外マッピングプロバイダ（RuntimeExceptionMapper.java）は，UTF-8形式でc:¥temp¥jaxrs¥works¥tutorial¥server¥src¥com¥sample¥providers¥ディレクトリに保存します。

JSON形式のデータにマッピングされるPOJOの作成例を次に示します。なお，JSONマッピング用のPOJOの作成は任意です。

package com.sample.resources;

import java.util.List;

public class CustomType {

    private String name;
    private List<Integer> grade;

    public CustomType() {
    }
    public CustomType (String name, List<Integer> grades){
        this.name = name;
        this.grade = grades;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public List<Integer> getGrades() {
        return grade;
    }
    public void setGrades(List<Integer> grades) {
        this.grade = grades;
    }
    @Override
    public String toString() {
        return "Record [Name=" + name + ", Grades=" + grade.toString() + "]";
    }
}

作成したJSONマッピング用のPOJO（CustomType.java）は，UTF-8形式でc:¥temp¥jaxrs¥works¥tutorial¥server¥src¥com¥sample¥resources¥ディレクトリに保存します。

12.3.2　Javaソースをコンパイルする

javacコマンドを使用して，作成した各Javaソースをコンパイルします。コンパイルの例を次に示します。

> cd c:¥temp¥jaxrs¥works¥tutorial¥server¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥jaxrs¥lib¥cjjaxrs.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxp.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmstax.jar;.¥classes" -d WEB-INF¥classes¥ src¥com¥sample¥resources¥Resource.java src¥com¥sample¥resources¥SubResource.java src¥com¥sample¥providers¥RuntimeExceptionMapper.java src¥com¥sample¥resources¥CustomType.java

javacコマンドが正常に終了すると，c:¥temp¥jaxrs¥works¥tutorial¥server¥WEB-INF¥classes¥ディレクトリ以下のパッケージ名に対応するサブディレクトリに，クラスファイル (*.class) が生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

12.3.3　web.xmlを作成する

WARファイルの構成要素として必要なweb.xmlを作成します。

web.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">

    <description>Sample web service &quot;tutorial&quot;</description>
    <display-name>Sample_web_service_jaxrs_tutorial</display-name>
    <servlet>
        <servlet-name>CosminexusJaxrsServlet</servlet-name>
        <servlet-class>
            com.cosminexus.jersey.spi.container.servlet.ServletContainer
        </servlet-class>
        <init-param>
            <param-name>com.sun.jersey.config.property.packages</param-name>
            <param-value>com.sample.resources;com.sample.providers</param-value>
        </init-param>
        <!-- POJO JSON support web.xml configuration -->
        <init-param>
            <param-name>com.sun.jersey.api.json.POJOMappingFeature</param-name>
            <param-value>true</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>CosminexusJaxrsServlet</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

作成したweb.xmlは，UTF-8形式でc:¥temp¥jaxrs¥works¥tutorial¥server¥WEB-INF¥ディレクトリに保存します。web.xmlの設定項目については，「3.4　web.xmlの作成」を参照してください。

12.3.4　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。

application.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

    <description>Sample application &quot;tutorial&quot;</description>
    <display-name>Sample_application_jaxrs_tutorial</display-name>
    <module>
        <web>
            <web-uri>tutorial.war</web-uri>
            <context-root>tutorial</context-root>
        </web>
    </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxrs¥works¥tutorial¥server¥META-INF¥ディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

12.3.5　EARファイルを作成する

jarコマンドを使用して，これまでに作成したファイルを含めたEARファイルを作成します。

EARファイルの作成例を次に示します。

> cd c:¥temp¥jaxrs¥works¥tutorial¥server¥
> jar cvf tutorial.war .¥WEB-INF
> jar cvf tutorial.ear .¥jaxrs_sample.war .¥META-INF¥application.xml

jarコマンドが正常に終了すると，c:¥temp¥jaxrs¥works¥tutorial¥server¥ディレクトリにtutorial.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

12.4　デプロイと開始の例

ここでは，Webリソースのデプロイと開始の例を説明します。

12.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxrs¥works¥tutorial¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxrsserver -nameserver corbaname::testserver:900 -f tutorial.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

12.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxrs¥works¥tutorial¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxrsserver -nameserver corbaname::testserver:900 -name Sample_application_jaxrs_tutorial

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

12.5　Webリソースクライアントの開発例

ここでは，Webリソースクライアントの開発例を説明します。Webリソースクライアントは，RESTful Webサービス用クライアントAPIか，またはjava.net.URLやjava.net.HttpURLConnectionなどの標準的なJava APIを利用して開発します。

12.5.1　Webリソースクライアントの実装クラスを作成する（クライアントAPIを利用する）

RESTful Webサービス用クライアントAPIを利用するクライアントの実装クラスを作成します。

例を次に示します。

package com.sample.client;

import java.net.URI;
import java.net.URLEncoder;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;

import com.cosminexus.jersey.api.client.Client;
import com.cosminexus.jersey.api.client.WebResource;
import com.cosminexus.jersey.api.client.ClientRequest;
import com.cosminexus.jersey.api.client.ClientResponse;
import com.cosminexus.jersey.api.client.config.ClientConfig;
import com.cosminexus.jersey.api.client.config.DefaultClientConfig;
import com.cosminexus.jersey.api.client.ClientHandlerException;
import com.cosminexus.jersey.api.json.JSONConfiguration;
import javax.ws.rs.core.Cookie;

//サンプル：Webリソースのクライアントの実行
public class SampleClient {

    public static void main(String[] args) {

        final String HOST = args[0];
        final String PORT = args[1];

        SampleClient sampleClient = new SampleClient();

        try{
            sampleClient.demonstration13(HOST, PORT);
            sampleClient.demonstration14(HOST, PORT);
            sampleClient.demonstration15(HOST, PORT);

            System.out.println("¥n----- Successfully Ended -----");

        }catch(Exception e){
            //詳細な例外のメッセージを表示する
            System.out.println(e.getMessage());
        }
    }
    private void demonstration13(String HOST, String PORT) {

        System.out.println("¥n Demonstration 13 started.");
        System.out.println(" This demonstrates how to use Client API " +
                "to receive a response as a ClientResponse.");
        System.out.println(" This demonstrates usage of @Encoded at " +
                "@CookieParam. ¥n Automatic URI decoding should be disabled.");

        String url = null;
        Client client = null;
        ClientResponse response = null;

        String responseEntity = "";
        Map<String, List<String>> headers = null;
        int status;

        //Webリソースを呼び出す
        try {
            //呼び出す対象のWebリソースのURIを設定する
            url = new String("http://" + HOST + ":" + PORT+
                    "/tutorial/root/getCookieParam");
            Cookie cookie = new Cookie("cookie", "cookie%20value");
            //クライアントAPIを利用するため，Clientオブジェクトを生成する
            client = Client.create();
            //HTTPリクエストを作成して送信しHTTPレスポンスを受信する
            //- ClientオブジェクトからWebResourceオブジェクトを生成する
            //- Cookieヘッダに"cookie=cookie%20value"を設定する
            //- HTTP GETリクエストを送信しClientResponseとして
            //  HTTPレスポンスを受信する
            response = client.resource(url)
                             .cookie(cookie)
                             .get(ClientResponse.class);
            //HTTPレスポンスのヘッダを取得する
            headers = response.getHeaders();
            //HTTPレスポンスのステータスコードを取得する
            status = response.getStatus();
            //HTTPレスポンスのエンティティを取得する
            responseEntity = response.getEntity(String.class);
        }catch (Exception e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 13 failed.");
        }
        System.out.println(" The target URL is ¥"" + url + "¥".");
        System.out.println(" The HTTP method  is " + "¥"GET¥"" + ".");
        System.out.println(" Connection and interaction ended successfully.");

        //ステータスコードとエンティティの期待値を設定する
        int statusExpect = 200;
        String responseEntityExpect = "CookieParam: cookie%20value";

        //ステータスコードとエンティティが期待値と同じかチェックする
        if (status == statusExpect
                & responseEntity.equals(responseEntityExpect)) {
            //HTTPレスポンスのヘッダを表示する
            System.out.println(" Response headers are " + headers.toString() + ".");
            //HTTPレスポンスのエンティティを表示する
            System.out.println(" Response entity is " + responseEntity + ",");
            System.out.println(" which means target resource completed " +
                    "the process described above without any problem.");

            System.out.println(" Demonstration 13 ended successfully.");
        }else {
            System.out.println(" The response is not as expected.");
            throw new RuntimeException(" Demonstration 13 failed.");
        }

    }

    private void demonstration14(String HOST, String PORT) {

        System.out.println("¥n Demonstration 14 started.");
        System.out.println(" This demonstrates how to send a ClientRequest " +
                "and receive a ClientResponse by using " +
                "Client#handle(ClientRequest request).");
        System.out.println(" This demonstrates usage of @Consumes and " +
                "@Produces.");
        URI url = null;
        Client client = null;
        ClientRequest.Builder requestBuilder = null;
        ClientRequest request = null;
        ClientResponse response = null;

        String responseEntity = "";
        Map<String, List<String>> headers = null;
        int status;

        //Webリソースを呼び出す
        try {
            //呼び出す対象のWebリソースのURIを設定する
            url = new URI("http://" + HOST + ":" + PORT+ "/tutorial/root");
            //HTTPリクエストのエンティティを作成する
            String data = URLEncoder.encode("form", "UTF-8") + "="
                + URLEncoder.encode("formValue", "UTF-8");
            //クライアントAPIを利用するため，Clientオブジェクトを生成する
            client = Client.create();
            //ClientRequest.Builderオブジェクトを生成する
            requestBuilder = ClientRequest.create();
            //- HTTPリクエストの"Content-Type"ヘッダに
            //  "application/x-www-form-urlencoded"を設定する
            //- HTTPリクエストのエンティティを設定する
            requestBuilder.type("application/x-www-form-urlencoded")
                          .entity(data);
            //ClientRequest.BuilderからClientRequestを作成する
            request = requestBuilder.build(url, "POST");
            //Client#handle()メソッドを呼び出してHTTP POSTリクエストを送信し
            //ClientResponseとしてHTTPレスポンスを受信する
            response = client.handle(request);
            //HTTPレスポンスのヘッダを取得する
            headers = response.getHeaders();
            //HTTPレスポンスのステータスコードを取得する
            status = response.getStatus();
            //HTTPレスポンスのエンティティを取得する
            responseEntity = response.getEntity(String.class);
        }catch (ClientHandlerException e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 14 failed.");
        }catch (Exception e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 14 failed.");
        }
        System.out.println(" The target URL is ¥"" + url + "¥".");
        System.out.println(" The HTTP method  is " + "¥"POST¥"" + ".");
        System.out.println(" Connection and interaction ended successfully.");

        //ステータスコードとエンティティの期待値を設定する
        int statusExpect = 200;
        String responseEntityExpect = "<FormParam>formValue</FormParam>";

        //ステータスコードとエンティティが期待値と同じかチェックする
        if (status == statusExpect
                & responseEntity.equals(responseEntityExpect)) {
            //HTTPレスポンスのヘッダを表示する
            System.out.println(" Response headers are " + headers.toString() + ".");
            //HTTPレスポンスのエンティティを表示する
            System.out.println(" Response entity is " + responseEntity + ",");
            System.out.println(" which means target resource completed " +
                    "the process described above without any problem.");

            System.out.println(" Demonstration 14 ended successfully.");
        }else {
            System.out.println(" The response is not as expected.");
            throw new RuntimeException(" Demonstration 14 failed.");
        }

    }
    private void demonstration15(String HOST, String PORT) {

        System.out.println("¥n Demonstration 15 started.");
        System.out.println(" This demonstrates JSON support of CJR.");
        System.out.println(" This demonstrates POJO and JSON mapping.");

        String url = null;
        Client client = null;
        CustomType response = null;

        //Webリソースを呼び出す
        try {
            //呼び出す対象のWebリソースのURIを設定する
            url = new String("http://" + HOST + ":" + PORT +
                    "/tutorial/root/PojoJsonMapping");
            //JSON POJOマッピングを有効にする設定を行う
            ClientConfig cc = new DefaultClientConfig();
            cc.getFeatures()
              .put(JSONConfiguration.FEATURE_POJO_MAPPING, Boolean.TRUE);
            //クライアントAPIを利用するため，Clientオブジェクトを生成する
            //(設定を有効にするためClientConfigオブジェクトを渡す)
            client = Client.create(cc);
            //CustomTypeオブジェクトを生成する
            CustomType record = new CustomType();
            record.setName("Old Record Name");
            List<Integer> grades = new ArrayList<Integer>();
            grades.add(1);
            grades.add(2);
            grades.add(3);
            record.setGrades(grades);
            //HTTPリクエストを作成する
            //- ClientオブジェクトからWebResourceオブジェクトを生成する
            //- Content-Typeヘッダに"application/json"を設定する
            //- エンティティにCustomTypeオブジェクトを設定する
            //- HTTP POSTリクエストを送信しCustomTypeとして
            //  HTTPレスポンスを受信する
            response = client.resource(url)
                             .type("application/json")
                             .entity(record)
                             .post(CustomType.class);
        }catch (Exception e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 15 failed.");
        }
        System.out.println(" The target URL is ¥"" + url + "¥".");
        System.out.println(" The HTTP method  is " + "¥"POST¥"" + ".");
        System.out.println(" Connection and interaction ended successfully.");

        //エンティティの期待値を設定する
        String responseNameExpect = "New Record Name";
        List<Integer> responseGradesExpect = new ArrayList<Integer>();
        responseGradesExpect.add(5);
        responseGradesExpect.add(6);
        responseGradesExpect.add(7);

        //エンティティが期待値と同じかチェックする
        if (response.getName().equals(responseNameExpect)
                & response.getGrades().equals(responseGradesExpect)) {
            //HTTPレスポンスのエンティティを表示する
            System.out.println(" Response is " + response.toString() + ",");
            System.out.println(" which means target resource completed " +
                    "the process described above without any problem.");

            System.out.println(" Demonstration 15 ended successfully.");
        }else {
            System.out.println(" The response is not as expected.");
            throw new RuntimeException(" Demonstration 15 failed.");
        }

    }
    private static class CustomType {

        private String name;
        private List<Integer> grade;

        public CustomType() {
        }

        public CustomType (String name, List<Integer> grades){
            this.name = name;
            this.grade = grades;
        }

        public String getName() {
            return name;
        }

        public void setName(String name) {
            this.name = name;
        }

        public List<Integer> getGrades() {
            return grade;
        }

        public void setGrades(List<Integer> grades) {
            this.grade = grades;
        }

        @Override
        public String toString() {
            return "Record [Name=" + name + ", Grades=" + grade.toString() + "]";
        }

    }
}

作成したSampleClient.javaは，UTF-8形式でc:¥temp¥jaxrs¥works¥tutorial¥client¥src¥com¥sample¥client¥ディレクトリに保存します。

12.5.2　Webリソースクライアントの実装クラスを作成する（java.net.HttpURLConnectionを利用する）

HttpURLConnectionクラスを利用するクライアントの実装クラスを作成します。

例を次に示します。

package com.sample.client;

import java.net.URL;
import java.net.URLEncoder;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.io.BufferedReader;
import java.io.IOException;
import java.util.List;
import java.util.Map;

//サンプル：Webリソースのクライアントの実行
public class SampleClient {

    public static void main(String[] args) {

        final String HOST = args[0];
        final String PORT = args[1];

        SampleClient sampleClient = new SampleClient();

        try{
            sampleClient.demonstration1(HOST, PORT);
            sampleClient.demonstration2(HOST, PORT);

            System.out.println("¥n----- Successfully Ended -----");

        }catch(Exception e){
            //詳細な例外のメッセージを表示する
            System.out.println(e.getMessage());
        }
    }

    private void demonstration1(String HOST, String PORT) {

        System.out.println("¥n Demonstration 1 started.");
        System.out.println(" This demonstrates injection of " +
                "javax.ws.rs.core.Request instance " +
                "onto resource class field by using @Context.");

        URL url = null;
        HttpURLConnection httpConn = null;

        Map<String, List<String>> headers = null;
        List<String> status = null;
        String responseEntity = "";

        //Webリソースを呼び出す
        try {
            //呼び出す対象のWebリソースのURIを設定する
            url = new URL("http://" + HOST + ":" + PORT+
                    "/tutorial/root");
            //初回接続をセットアップする
            httpConn = (HttpURLConnection) url.openConnection();
            //HTTP()メソッドを"GET"に設定する
            httpConn.setRequestMethod("GET");
            //接続を開始する
            httpConn.connect();
        }catch (MalformedURLException e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 1 failed.");
        }catch (IOException e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 1 failed.");
        }catch (Exception e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 1 failed.");
        }

        System.out.println(" The target URL is ¥"" + url + "¥".");
        System.out.println(" The HTTP method  is " + "¥"GET¥"" + ".");

        try {
            //HTTPレスポンスのヘッダを取得する
            headers = httpConn.getHeaderFields();
            //ヘッダからHTTPステータスを取得する
            status = headers.get(null);
            //入力ストリームリーダを取得してHTTPレスポンスの
            //エンティティボディを読み込む
            BufferedReader rd = new BufferedReader(new InputStreamReader(
                httpConn.getInputStream()));
            String line = "";
            while ((line = rd.readLine()) != null) {
                responseEntity += line;
            }
            //入力ストリームリーダを閉じる
            rd.close();
            //接続を終了する
            httpConn.disconnect();
        }catch (Exception e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 1 failed.");
        }

        System.out.println(" Connection and interaction ended successfully.");

        //ステータスコードとエンティティボディの期待値を設定する
        String statusExpect = "[HTTP/1.1 200 OK]";
        String responseEntityExpect = "RequestMethod: GET";

        //ステータスコードとエンティティボディが期待値と同じかチェックする
        if (status.toString().equals(statusExpect)
                & responseEntity.equals(responseEntityExpect)) {
            //HTTPヘッダを表示する
            System.out.println(" Response headers are " + headers.toString() + ".");
            //エンティティボディを表示する
            System.out.println(" Response entity is " + responseEntity + ",");
            System.out.println(" which means target resource completed " +
                    "the process described above without any problem.");

            System.out.println(" Demonstration 1 ended successfully.");
        }else {
            System.out.println(" The response is not as expected.");
            throw new RuntimeException(" Demonstration 1 failed.");
        }

    private void demonstration2(String HOST, String PORT) {

        System.out.println("¥n Demonstration 2 started.");
        System.out.println(" This demonstrates injection of QueryParam " +
                "onto resource bean setter method by using @QueryParam.");

        URL url = null;
        HttpURLConnection httpConn = null;
        String responseEntity = "";
        Map<String, List<String>> headers = null;
        List<String> status = null;

        //Webリソースを呼び出す
        try {
            //呼び出す対象のWebリソースのURIを設定する
            //URIにクエリパラメタを付与する

            url = new URL("http://" + HOST + ":" + PORT+
                    "/tutorial/root/getQueryParam?queryParam=queryValue");
            //初回接続をセットアップする
            httpConn = (HttpURLConnection) url.openConnection();
            //HTTP()メソッドを"GET"に設定する
            httpConn.setRequestMethod("GET");
            //接続を開始する
            httpConn.connect();
        }catch (MalformedURLException e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 2 failed.");
        }catch (IOException e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 2 failed.");
        }catch (Exception e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 2 failed.");
        }

        System.out.println(" The target URL is ¥"" + url + "¥".");
        System.out.println(" The HTTP method  is " + "¥"GET¥"" + ".");

        try {
            //HTTPヘッダを取得する
            headers = httpConn.getHeaderFields();
            //HTTPヘッダからのステータスコードを取得する
            status = headers.get(null);
            //入力ストリームリーダを取得してHTTPレスポンスの
            //エンティティボディを読み込む
            BufferedReader rd = new BufferedReader(new InputStreamReader(
                httpConn.getInputStream()));
            String line = "";
            while ((line = rd.readLine()) != null) {
                responseEntity += line;
            }
            //入力ストリームリーダを閉じる
            rd.close();
            //接続を終了する
            httpConn.disconnect();
        }catch (Exception e) {
            System.out.println(" ERROR: " + e.getClass() + " was thrown. ");
            //スタックトレースを表示する
            e.printStackTrace();
            throw new RuntimeException(" Demonstration 2 failed.");
        }

        System.out.println(" Connection and interaction ended successfully.");

        //ステータスコードとエンティティボディの期待値を設定する
        String statusExpect = "[HTTP/1.1 200 OK]";
        String responseEntityExpect = "QueryParameter: queryValue";

        //ステータスコードとエンティティボディが期待値と同じかチェックする
        if (status.toString().equals(statusExpect)
                & responseEntity.equals(responseEntityExpect)) {
            //HTTPヘッダを表示する
            System.out.println(" Response headers are " + headers.toString() + ".");
            //エンティティボディを表示する
            System.out.println(" Response entity is " + responseEntity + ",");
            System.out.println(" which means target resource completed " +
                    "the process described above without any problem.");

            System.out.println(" Demonstration 2 ended successfully.");
        }else {
            System.out.println(" The response is not as expected.");
            throw new RuntimeException(" Demonstration 2 failed.");
        }

    }
    }

}

作成したSampleClient.javaは，UTF-8形式でc:¥temp¥jaxrs¥works¥tutorial¥client¥src¥com¥sample¥client¥ディレクトリに保存します。

12.5.3　Webリソースクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebリソースクライアントをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxrs¥works¥tutorial¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥jaxrs¥lib¥cjjaxrs.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥com¥sample¥client¥SampleClient.java

javacコマンドが正常に終了すると，c:¥temp¥jaxrs¥works¥tutorial¥client¥classes¥ディレクトリ以下のパッケージ名に対応するサブディレクトリに，クラスファイル（*.class）が生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

12.6　Webリソースの呼び出し例

ここでは，Webリソースの呼び出し例を説明します。

12.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxrs¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>
add.jvm.arg=-Dejbserver.server.prf.PRFID=<PRF ID>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。<PRF ID>の部分は，PRFデーモンの識別子を指定します。

作成したJavaアプリケーション用オプション定義ファイルは，c:¥temp¥jaxrs¥works¥tutorial¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

12.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxrs¥works¥tutorial¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

12.6.3　Webリソースクライアントを実行する

cjclstartapコマンドを使用して，Webリソースクライアントを実行します。

Webリソースクライアントの実行例を次に示します。

> cd c:¥temp¥jaxrs¥works¥tutorial¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  com.sample.client. SampleClient webhost 8085

cjclstartapコマンドが正常に終了すると，Webリソースクライアントの実行結果が表示されます。Webリソースクライアントの開発方法ごとの，実行結果の表示例を次に示します。

クライアントAPIを利用する場合

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxrs¥works¥tutorial¥client, PID = 2636)

Demonstration 13 started.
 This demonstrates how to use Client API to receive a response as a ClientResponse.
 This demonstrates usage of @Encoded at @CookieParam.
 Automatic URI decoding should be disabled.
 The target URL is "http://webhost:8085/tutorial/root/getCookieParam".
 The HTTP method is "GET".
 Connection and interaction ended successfully.
 Response headers are {Transfer-Encoding=[chunked], Date=[Tue, 27 Dec 2011 0
7:59:41 GMT], Content-Type=[text/html], Server=[CosminexusComponentContainer]}.
 Response entity is CookieParam: cookie%20value,
 which means target resource completed the process described above without any problem.
 Demonstration 13 ended successfully.

 Demonstration 14 started.
 This demonstrates how to send a ClientRequest and receive a ClientResponse by using Client#handle(ClientRequest request).
 This demonstrates usage of @Consumes and @Produces.
 The target URL is "http://webhost:8085/tutorial/root".
 The HTTP method is "POST".
 Connection and interaction ended successfully.
 Response headers are {Transfer-Encoding=[chunked], Date=[Tue, 27 Dec 2011 0
7:59:41 GMT], Content-Type=[application/xml], Server=[CosminexusComponentContainer]}.
 Response entity is <FormParam>formValue</FormParam>,
 which means target resource completed the process described above without any problem.
 Demonstration 14 ended successfully.

 Demonstration 15 started.
 This demonstrates JSON support of CJR.
 This demonstrates POJO and JSON mapping.
 The target URL is "http://webhost:8085/tutorial/root/PojoJsonMapping".
 The HTTP method is "POST".
 Connection and interaction ended successfully.
 Response is Record [Name=New Record Name, Grades=[5, 6, 7]],
 which means target resource completed the process described above without any problem.
 Demonstration 15 ended successfully.

----- Successfully Ended -----
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

HttpURLConnectionを利用する場合

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxrs¥works¥tutorial¥client, PID = 2636)

Demonstration 1 started.
 This demonstrates injection of javax.ws.rs.core.Request instance onto resource class field by using @Context.
 The target URL is "http://webhost:8085/tutorial/root".
 The HTTP method is "GET".
 Connection and interaction ended successfully.
 Response headers are {null=[HTTP/1.1 200 OK], Transfer-Encoding=[chunked], Date=[Tue, 27 Dec 2011 0
7:59:41 GMT], Content-Type=[text/html], Server=[CosminexusComponentContainer]}.
 Response entity is RequestMethod: GET,
 which means target resource completed the process described above without any problem.
 Demonstration 1 ended successfully.

 Demonstration 2 started.
 This demonstrates injection of QueryParam onto resource bean setter method by using @QueryParam.
 The target URL is "http://webhost:8085/tutorial/root/getQueryParam?queryParam=queryValue".
 The HTTP method  is "GET".
 Connection and interaction ended successfully.
 Response headers are {null=[HTTP/1.1 200 OK], Transfer-Encoding=[chunked], Date=[Tue, 27 Dec 2011 0
7:59:41 GMT], Content-Type=[text/html], Server=[CosminexusComponentContainer]}.
 Response entity is QueryParameter: queryValue,
 which means target resource completed the process described above without any problem.
 Demonstration 2 ended successfully.

----- Successfully Ended -----
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

13　JAX-RS機能の設定と動作

この章では，RESTful Webサービス（Webサービス）を開発，運用するときのJAX-RS機能の各種設定，Webリソースクライアントからの接続の概要，および運用に当たって理解が必要なJAX-RSエンジンの動作について説明します。

13.1　動作定義ファイル

ログの設定などは動作定義ファイルに記述します。動作定義ファイルは，次の2種類があります。

共通定義ファイル

システム共通の動作を設定するための定義ファイルです。一つだけあります。

プロセス別の定義ファイル

プロセス固有の動作を設定する場合に作成する定義ファイルです。固有の設定が必要なプロセスごとに作成します。例えば，J2EEサーバごとに設定を変更したい場合や，Webリソースクライアントごとに設定を変更したい場合に作成します。

なお，Webリソース側の一部の定義については，web.xmlのフィルタの定義や初期化パラメタで上書きできます。web.xmlについては，「11.2　web.xmlの作成」を参照してください。また，クライアント側の一部の定義はクライアントAPIで上書きできます。クライアントAPIで上書きできる定義については，「25.1.1　サポートするプロパティとフィーチャ」を参照してください。

ここでは，動作定義ファイルの記述規則，および各定義ファイルの設定について説明します。

13.1.1　動作定義ファイルの記述規則

動作定義ファイルの記述形式，記述規則および動作定義の優先度は，JAX-WS機能と同じです。詳細は，「10.1.1　動作定義ファイルの記述規則」を参照してください。

13.1.2　共通定義ファイルの設定項目

共通定義ファイルを使用して，システム共通の動作定義を設定します。共通定義ファイルのファイル名，保存ディレクトリ名，および設定項目について説明します。

(1)　ファイル名

共通定義ファイルのファイル名を示します。

cjrconf.properties

(2)　保存先ディレクトリ

共通定義ファイルの保存先ディレクトリを示します。保存先ディレクトリは固定です。

<Application Serverのインストールディレクトリ>¥jaxrs¥conf

(3)　設定項目

設定するキー名称と指定内容の一覧を次の表に示します。

表13‒1　共通定義ファイルの設定項目

項番

設定項目

キー名称

指定内容

デフォルト値

1

稼働ログの出力レベル

com.cosminexus.jaxrs.logger.runtime.message.level

稼働ログの出力レベルを指定します。

ERROR，WARN，INFO，DEBUG，NONEのどれかを指定します。各指定値に対応した出力内容については，「39.3.4　ログの重要度と出力条件」を参照してください。

INFO

2

稼働ログの面数

com.cosminexus.jaxrs.logger.runtime.message.file_num

稼働ログの面数を指定します。

数字（1〜16）を指定します。

2

3

稼働ログの容量

com.cosminexus.jaxrs.logger.runtime.message.file_size

稼働ログの容量を指定します。

4096〜16777216の数字（単位：バイト）を指定します。

2097152

4

保守ログの出力

com.cosminexus.jaxrs.logger.runtime.maintenance.level

保守ログを出力するかどうかを指定します。

ALLを指定した場合

保守ログが出力されます。

NONEを指定した場合

保守ログが出力されません。

ALL

5

保守ログの面数

com.cosminexus.jaxrs.logger.runtime.maintenance.file_num

保守ログの面数を指定します。

1〜16の数字を指定します。

2

6

保守ログの容量

com.cosminexus.jaxrs.logger.runtime.maintenance.file_size

保守ログの容量を指定します。

4096〜16777216の数字（単位：バイト）を指定します。

16777216

7

例外ログの出力レベル

com.cosminexus.jaxrs.logger.runtime.exception.level

例外ログの出力レベルを指定します。ERROR，WARN，INFO，DEBUG，NONEのどれかを指定します。各指定値に対応した出力内容については，「39.3.4　ログの重要度と出力条件」を参照してください。

INFO

8

例外ログの面数

com.cosminexus.jaxrs.logger.runtime.exception.file_num

例外ログの面数を指定します。1〜16の数字を指定します。

2

9

例外ログの容量

com.cosminexus.jaxrs.logger.runtime.exception.file_size

例外ログの容量を指定します。4096〜16777216の数字（単位：バイト）を指定します。

16777216

10

通信ログの出力

レベル（Webリソース側）※1

com.cosminexus.jaxrs.logger.runtime.transport.server.level

Webリソース側での通信ログの出力レベルを指定します。※2

NONEを指定した場合

通信ログが出力されません。

ALLを指定した場合

送受信したHTTPヘッダとエンティティボディの両方が常に通信ログに出力されます。

HEADERを指定した場合

送受信したメッセージのHTTPヘッダが常に通信ログに出力されます。

NONE

11

通信ログの出力

レベル（Webリソースクライアント側）

com.cosminexus.jaxrs.logger.runtime.transport.client.level

Webリソースクライアント側での通信ログの出力レベルを指定します。※2

NONEを指定した場合

通信ログが出力されません。

ALLを指定した場合

送受信したHTTPヘッダとエンティティボディの両方が常に通信ログに出力されます。

HEADERを指定した場合

送受信したメッセージのHTTPヘッダが常に通信ログに出力されます。

NONE

12

通信ログの面数

com.cosminexus.jaxrs.logger.runtime.transport.file_num

通信ログの面数を指定します。1〜16の数字で指定します。

2

13

通信ログの容量

com.cosminexus.jaxrs.logger.runtime.transport.file_size

通信ログの容量を指定します。4096〜16777216の数字（単位：バイト）を指定します。

16777216

14

通信ログの文字エンコーディング

com.cosminexus.jaxrs.logger.runtime.transport.encoding

通信ログの文字エンコーディングを指定します。J2SE 6.0でサポートされているエンコーディングについては，J2SE 6.0のドキュメントを確認してください。

DEFAULTを指定した場合，通信ログのエンコーディングはデフォルトのプラットフォームエンコーディングとなります。

DEFAULT

15

WADLの発行の抑止※1

com.sun.jersey.config.feature.DisableWADL

WADLの発行を抑止するかどうかを指定します。※2

trueを指定した場合

WADLの発行を抑止します。

falseを指定した場合

WADLの発行を抑止しません。

false

16

JSON POJOマッピングの有効化※1，※3

com.sun.jersey.api.json.POJOMappingFeature

JSON POJOマッピングを有効にするかどうかを指定します。※2

trueを指定した場合

JSON POJOマッピングを有効にします。

falseを指定した場合

JSON POJOマッピングを有効にしません。

false

17

自動リダイレクト※3

com.sun.jersey.client.property.followRedirects

HTTPリダイレクト（HTTPステータスコードが300番台の要求）に自動的に従うべきかどうかを設定します。

trueを指定した場合

HTTPリダイレクトに自動的に従います。

falseを指定した場合

HTTPリダイレクトに自動的には従いません。

この項目を指定したときの動作は，Java SEのHttpURLConnectionクラスのsetInstanceFollowRedirectsメソッドで引数にこの項目の設定値を指定して呼び出した場合と同じになります。※2

true

18

クライアントソケットの接続タイムアウト値※3

com.sun.jersey.client.property.connectTimeout

クライアントソケットの接続タイムアウト値を指定します。

このプロパティで指定したタイムアウト値は，Webリソース呼び出し時に適用されます。

0〜2147483647の数字（単位：ミリ秒）を指定します。0を指定した場合，タイムアウトされません。

OSのTCP接続に関連する設定を変更している場合，OSの設定値が優先されることがあります。

0

19

クライアントソケットの読み込みタイムアウト値※3

com.sun.jersey.client.property.readTimeout

クライアントソケットの読み込みタイムアウト値を指定します。

このプロパティで指定したタイムアウト値は，Webリソース呼び出し時に適用されます。

0〜2147483647の数字（単位：ミリ秒）を指定します。0を指定した場合，タイムアウトされません。

OSのTCP接続に関連する設定を変更している場合，OSの設定値が優先されることがあります。

0

20

チャンク転送エンコーディング※3

com.sun.jersey.client.property.chunkedEncodingSize

チャンク転送エンコーディングを使用するかどうかを，0〜2147483647の数字（単位：バイト）で指定します。0を指定した場合，デフォルト値が適用されます。

この項目を指定したときの動作は，Java SEのHttpURLConnectionクラスのsetChunkedStreamingModeメソッドで引数にこの項目の設定値を指定して呼び出した場合と同じになります。

4096

21

例外発生時のレスポンスエンティティのバッファリング※3

com.sun.jersey.client.property.bufferResponseEntityOnException

UniformInterfaceExceptionが発生した場合，HTTPレスポンスにエンティティがあれば，自動的にバッファリングし，ストリームを閉じるかどうかを指定します。※2

trueを指定した場合

HTTPレスポンスのエンティティを自動的にバッファリングし，ストリームを閉じます。

falseを指定した場合

HTTPレスポンスのエンティティのストリームは自動的には閉じられません。

true

注※1

Webリソース側では，プロパティに指定した値より，サーブレット初期化パラメタに指定した値が優先されます。

注※2

プロパティの値は大文字と小文字とが区別されません。無効な値が指定されている場合は，デフォルト値と見なされます。

注※3

クライアント側では，プロパティに指定した値より，クライアントAPIで指定した値が優先されます。

(4)　設定を変更する場合

プロセス別の定義ファイルを使用していないすべてのJ2EEサーバを停止してから，共通定義ファイルの設定を変更してください。プロセス別の定義ファイルについては，「10.1.3　プロセス別の定義ファイルの設定」を参照してください。

ログ関連の設定を変更する場合，必要に応じてログを退避してから設定を変更してください。

13.1.3　プロセス別の定義ファイルの設定（JAX-RS）

プロセス別に固有の定義をする場合に，プロセス別の定義ファイルを作成します。

プロセス別の定義ファイルのファイル名，および保存先のディレクトリ名は任意です。システムプロパティで保存先のパスを指定することで，プロセス別の定義が有効になります。プロセス別の定義ファイルの指定例を次に示します。

com.cosminexus.jaxrs.confpath=d:/tmp/example.properties

プロセス別の定義を変更する場合，対象としているプロセス（J2EEアプリケーションまたはJavaアプリケーション）を停止してから，プロセス別の定義ファイルの定義を変更してください。

ログ関連の定義を変更する場合，必要に応じてログを退避してから，定義を変更してください。

13.2　JAX-RSエンジンの動作

Application ServerのJAX-RSエンジンの動作，およびApplication ServerのJAX-RSエンジンのサポート範囲について説明します。

JAX-RSエンジンはRESTful Webサービス（Webリソース）の通信基盤となるエンジンです。WebリソースクライアントおよびWebリソースでの動作は次のとおりです。

Webリソースクライアント側のJAX-RSエンジン

WebリソースクライアントからRESTful Webサービス用クライアントAPIを介してJavaオブジェクトを受け取り，HTTPリクエストを生成します。生成したHTTPリクエストは呼び出し先のWebリソースに送信します。また，WebリソースからHTTPレスポンスを受け取り，Javaオブジェクトを生成します。生成したJavaオブジェクトはWebリソースクライアントに返します。

Webリソース側のJAX-RSエンジン

HTTPリクエストを受け取り，対象となるリソースクラスを見つけ出し（ディスカバリ），そして要求に対応するメソッドを呼び出します（ディスパッチ）。ディスカバリとディスパッチの際には，リソースクラスが持つアノテーションに基づき，必要なインジェクションを実行します。また，JAX-RSエンジンは対象となるリソースクラスからHTTPレスポンスを生成して返します。

13.2.1　ディスカバリとディスパッチ

ここでは，Webリソースのディスカバリ，ディスパッチ，およびフォルトと例外クラスのマッピングについて説明します。

(1)　ディスカバリ

ディスカバリでは，HTTPリクエストで要求されたURLから，リソースクラスをマッピングする処理が行われます。ここでは，次のURLが要求された場合のマッピングについて説明します。

http://example.org/sample/rootA

コンテキストルートを"sample"とした場合，コンテキストルートの後ろの"/rootA"（下線部）はパス情報を表します。このパス情報を基に，リソースクラスがマッピングされます。

パス情報とのマッピングの例を次に示します。なお，この例では，リソースクラスとして，サブリソースクラスを使用しないで，ルートリソースクラスだけを使用します。また，各ルートリソースクラスはリソースメソッドだけを持ちます。

図13‒1　ディスカバリ

JAX-RSエンジンは，デプロイされているルートリソースクラスのうち，Pathアノテーションの値がパス情報に等しいものを呼び出します。

パス情報と，呼び出されるルートリソースクラスの対応を示します。

パス情報がrootAの場合

ルートリソースクラスA（org.foo.Test1.java）が呼び出されます。

パス情報がrootBの場合

ルートリソースクラスB（org.foo.Test2.java）が呼び出されます。

パス情報がrootCの場合

ルートリソースクラスC（org.foo.Test3.java）が呼び出されます。

なお，サブリソースクラスがデプロイされていて，対応するサブリソースロケータのPathアノテーションの値がパス情報に等しい場合は，そのサブリソースクラスを呼び出します。

(2)　HTTPメッセージのディスパッチ

JAX-RSエンジンは，受信したHTTPメッセージの内容（Content-Type HTTPヘッダ）と受け入れできるメディアタイプ（Accept HTTPヘッダ）に応じて，リソースメソッドを呼び出し，実行します。ディスパッチはConsumesアノテーションおよびProducesアノテーションで指定されたメディアタイプによって実行されます。

なお，リソースクラスにサブリソースメソッドが含まれている場合は，ディスカバリとディスパッチの判定が同時に行われます。

13.3　メタデータの発行

JAX-RSエンジンは，RESTful Webサービス（Webリソース）のWADL（メタデータ）を自動的に発行します。

ここでは，WADLの発行を利用するに当たって，注意が必要な点について説明します。

13.3.1　メタデータの発行条件

WebリソースのWADLを発行するメソッドは，次に示す二つです。

HTTP GETメソッド

HTTP OPTIONSメソッド

HTTP GETメソッドを使用してWebリソースのWADLを発行する条件を次の表に示します。JAX-RSエンジンが，次の表に示す条件をすべて満たしたHTTPリクエストを受信したときにWADLが発行されます。

表13‒2　 Webリソースのメタデータの発行に必要なHTTPリクエスト（GET）

項番

項目

条件

1

HTTPメソッド

GETメソッド

2

URL

スキーマ

httpまたはhttps

3

ホスト名（:ポート番号）

メタデータの発行を要求するWebリソースが存在するホスト名（およびポート番号）

4

コンテキストパス

メタデータの発行を要求するWebリソースが含まれるWebアプリケーションのコンテキストパス

5

コンテキストパスの後ろのパス

"application.wadl"

例えば，Webリソースを含むWebアプリケーション（WARファイル）のコンテキストルートが，"sample" で，Webアプリケーションが"example.org"というホストで公開されていると仮定すると，URLは「http://example.org/sample/application.wadl」です。この場合，発行されるWADLには，web.xmlのcom.sun.jersey.config.property.packages初期化パラメタ（init-param要素）に指定されたすべてのWebリソースが含まれます。web.xmlにcom.sun.jersey.config.property.packages初期化パラメタ（init-param要素）が記述されていない場合は，WARファイルに含まれるすべてのWebリソースが含まれます。web.xmlのcom.sun.jersey.config.property.packages初期化パラメタ（init-param要素）については「11.2　web.xmlの作成」を参照してください。

WebリソースのWADLの例を次に示します。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
 <doc xmlns:jersey="http://jersey.dev.java.net/" jersey:generatedBy="Cosminexus JAX-RS 09-00"/>
 <resources base="http://example.org/sample/">
  <resource path="root">
   <method name="GET" id="resourceMethod">
    <response>
     <representation mediaType="*/*"/>
    </response>
   </method>
   <method name="POST" id="postHandler">
    <request>
     <representation mediaType="*/*">
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       style="query" name="form"/>
     </representation>
    </request>
    <response>
     <representation mediaType="text/html"/>
    </response>
   </method>
   <resource path="subresourceMethod">
    <method name="GET" id="subResourceMethod">
     <request>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" default="1"
       type="xs:string" style="matrix" name="matrix"/>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       name="cookie"/>
     </request>
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
   <resource path="exception">
    <method name="GET" id="subResourceMethodThrowingException">
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
   <resource path="subresourceLocator/{id}">
    <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
     style="template" name="id"/>
    <method name="GET" id="getHandlerForSubResource">
     <request>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       style="header" name="HeaderKey"/>
     </request>
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
  </resource>
 </resources>
</application>

HTTP OPTIONSメソッドを使用してWebリソースのメタデータを発行する条件を次の表に示します。Webサービス側のJAX-RSエンジンが，次の表に示す条件をすべて満たしたHTTPリクエストを受信したときにメタデータが発行されます。

表13‒3　 Webリソースのメタデータの発行に必要なHTTPリクエスト（OPTIONS）

項番

項目

条件

1

HTTPメソッド

OPTIONSメソッド

2

URL

スキーマ

http

3

ホスト名（:ポート番号）

メタデータの発行を要求するWebリソースが存在するホスト名（およびポート番号）

4

コンテキストパス

メタデータの発行を要求するWebリソースが含まれるWebアプリケーションのコンテキストパス

5

Webリソースのパス

Webリソースで使われているPathアノテーションの値

例えば，WebリソースAのPathアノテーションの値が「/rootA」，ホスト名が「example.org」，コンテキストパスが「sample」だとします。この場合，メタデータを発行するURLは「http://example.org/sample/rootA」となります。

このとき，発行されるWADLには，要求されたWebリソースだけが含まれます。

ポイント

対象となるWebリソースのメソッドがOPTIONSアノテーションを持ち，HTTP OPTIONS要求を処理できる場合，JAX-RSエンジンはWADLを発行しないで，そのWebリソースのHTTP OPTIONSリクエストを処理するメソッドを呼び出します。WebリソースがHTTP OPTIONSリクエストを処理できなければ，JAX-RSエンジンは自動でWADLを生成します。

HTTP OPTIONSメソッドを使用したWADLの例を次に示します。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
 <doc xmlns:jersey="http://jersey.dev.java.net/" jersey:generatedBy="Cosminexus JAX-RS 09-00"/>
 <resources base="http://example.org/sample/">
  <resource path="/root">
   <method name="GET" id="resourceMethod">
    <response>
     <representation mediaType="*/*"/>
    </response>
   </method>
   <method name="POST" id="postHandler">
    <request>
     <representation mediaType="*/*">
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       style="query" name="form"/>
     </representation>
    </request>
    <response>
     <representation mediaType="text/html"/>
    </response>
   </method>
   <resource path="subresourceMethod">
    <method name="GET" id="subResourceMethod">
     <request>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" default="1"
       type="xs:string" style="matrix" name="matrix"/>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       name="cookie"/>
     </request>
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
   <resource path="exception">
    <method name="GET" id="subResourceMethodThrowingException">
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
   <resource path="subresourceLocator/{id}">
    <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
     style="template" name="id"/>
    <method name="GET" id="getHandlerForSubResource">
     <request>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       style="header" name="HeaderKey"/>
     </request>
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
  </resource>
 </resources>
</application>

com.sun.jersey.config.feature.DisableWADLプロパティにtrueまたはfalseを設定することで，WADLの発行の有無を選択できます。このプロパティは次の個所に指定します。

cjrconf.propertiesファイル

web.xmlのサーブレット初期化パラメタ

どちらも指定された場合，サーブレット初期化パラメタが優先されます。

WADLの発行の有無を次の表に示します。

表13‒4　WADLの発行の有無

項番

サーブレット初期化パラメタ

値

JAX-RSエンジンの動作

1

com.sun.jersey.config.feature.DisableWADL

true

WADLを発行しません。

値の大文字と小文字を区別しません。

false

WADLを発行します。

値の大文字と小文字を区別しません。

trueまたはfalse以外の値

共通定義ファイル（cjrconf.properties）で取得したプロパティの値が使用されて，WADLを発行します。なお，web.xmlで指定した値は無視されます。

13.4　プロキシサーバ経由の接続

Webリソースクライアントからプロキシサーバを経由して，外部のネットワークにあるWebリソースを利用できます。

ここでは，プロキシサーバを経由して外部に接続する場合に必要なプロパティの設定について説明します。

13.4.1　プロパティ値の指定

プロキシサーバを経由してWebリソースにアクセスするには，JavaVMのプロパティを指定して，プロキシサーバの情報を設定します。プロキシサーバ経由で接続するためのJavaVMのプロパティと指定内容を次の表に示します。なお，JavaVMのシステムプロパティの詳細については，JavaVMのドキュメントを参照してください。

表13‒5　プロキシサーバ経由で接続するためのJavaVMのプロパティ

項番

JavaVMのプロパティ

指定内容

非SSLの場合

SSLの場合

1

http.proxyHost

プロキシサーバのホスト名またはIPアドレスを指定します。

空文字を指定した場合は，プロキシサーバに接続されません。

○

×

2

http.proxyPort

プロキシサーバのポート番号を設定します。

http.proxyHostが適切に設定されていた場合に，http.proxyPortに空文字を指定したときは，http.proxyHostに指定されているホストの80番ポートにアクセスされます。

http.proxyHostを指定していない場合は，http.proxyPortを指定しても，プロキシサーバに接続されません。

△

×

3

https.proxyHost

SSLプロトコルによる接続※で使用するプロキシサーバのホスト名かIPアドレスを設定します。

SSLプロトコルによる接続でプロキシサーバを使用する場合は，必ず設定してください。なお，空文字を指定した場合は，プロキシサーバに接続されません。

×

○

4

https.proxyPort

SSLプロトコルによる接続※で使用するプロキシサーバのポート番号を設定します。なお，https.proxyHostが適切に設定されていた場合に，https.proxyPortに空文字を指定したときは，https.proxyHostに指定されているホストの443番ポートにアクセスされます。

https.proxyHostを指定していない場合は，https.proxyPortを設定しても，プロキシサーバに接続されません。

×

△

5

http.nonProxyHosts

プロキシサーバを利用しないホスト名群を必要に応じて指定します。

このプロパティで指定したホストに接続する場合は，http.proxyHostまたはhttps.proxyHostに指定したプロキシサーバは経由されません。ホストを複数指定する場合は，「|」で区切って設定します。ホスト名とホスト名の間には，「|」以外の文字（空白など）は指定できません。

△

△

（凡例）

○：プロパティの指定が必須であることを示します。

△：必要に応じてプロパティを指定することを示します。

×：プロパティの指定が不要であることを示します。

注※

SSLプロトコルによる接続については，「10.11　SSLプロトコルによる接続」を参照してください。

13.4.2　プロパティの設定方法

JavaVMのシステムプロパティの設定方法については，「10.10.2　プロパティの設定方法」を参照してください。

13.4.3　匿名でないプロキシサーバを経由して接続する場合

匿名でないプロキシサーバを経由してWebリソースにアクセスする場合は，WebリソースクライアントでJ2SE 6.0標準のjava.net.Authenticatorクラスを利用して実装することをお勧めします。詳細についてはJ2SE 6のドキュメントを参照してください。

java.net.Authenticatorクラスを利用した実装例については「10.10.3　JAX-WS機能固有のプロパティを利用しない場合」を参照してください。

13.5　SSLプロトコルによる接続

Webリソースクライアントから，SSLプロトコルに対応したWebリソースに接続できます。

SSLプロトコルでWebリソースにアクセスするには，JDKにサポートされているプロパティに値を指定して，SSLプロトコルの情報を設定します。SSLプロトコルによる接続で使用するプロパティ，および指定内容を次の表に示します。

表13‒6　SSLプロトコルによる接続で使用するプロパティ

項番

プロパティ

指定内容

1

javax.net.ssl.trustStore

トラストストアを指定します。

2

javax.net.ssl.trustStorePassword

トラストストアのパスワードを指定します。

これらのプロパティは必要に応じて指定してください。なお，トラストストアを指定しない場合は，<JDKインストールディレクトリ>/lib/security/jssecacertsなどのデフォルト値が使用されます。

JDKのプロパティについては，JDKのドキュメントを参照してください。プロパティの設定方法や注意事項については「10.11.2　プロパティの設定方法」および「10.11.3　ホスト名検証についての注意事項」を参照してください。

13.6　ベーシック認証による接続

Webリソースクライアントから，ベーシック認証に対応したWebリソースに接続できます。

ここでは，ベーシック認証による接続に必要な実装について説明します。

13.6.1　ベーシック認証による接続に必要な実装

ベーシック認証でWebリソースにアクセスするには，必要なHTTPヘッダを追加する処理を実装してください。RESTful Webサービス用クライアントAPIを利用する場合の実装例を次に示します。

// ベーシック認証のユーザIDとパスワード
String username = ...
String password = ...
// Clientオブジェクトを生成する
Client client = Client.create();
// Authorization HTTPヘッダを持つHTTPリクエストを生成し
// Webリソースへポストする
client.resource( "http://example.org/helloworld" )
 .header( HttpHeaders.AUTHORIZATION,
    "Basic " + encode(username + ":" + password))
 .post( String.class, "Some Request" );
...
String encode( String value ){
 String encoded;
 // Base64アルゴリズムでvalueパラメタをエンコードし
 // 結果をencodedパラメタに設定する
 ...
 return encoded;
}

13.7　トラブルシュート

ここでは，WebリソースおよびWebリソースクライアントのトラブルシュートで特に注意が必要な点について説明します。一般的な注意事項や，障害の種類や対策，ログについては，「39.　障害対策」を参照してください。

また，それぞれの具体的な説明については「17.　Webリソースとプロバイダ」および「25.　RESTful Webサービス用クライアントAPIのサポート範囲」を参照してください。

13.7.1　Webリソース初期化時の構文チェック（KDJJ20003-WとKDJJ10006-E）

ルートリソースクラスと例外マッピングプロバイダは，Webアプリケーション（WARファイル）に含まれるWebリソースが最初に呼び出される際にJAX-RSエンジンによって初期化されます。サブリソースクラスは対応するサブリソースロケータが初期化します。

ここでは初期化時の構文チェックで誤りが検出された場合について説明します。

(1)　重大な誤りがある場合

リソースクラスにpublicコンストラクタが一つも宣言されていない場合など，初期化を完了できないような重大な構文の誤りを検出したとき，エラーメッセージがログに出力されます（KDJJ10006-E※）。ルートリソースクラスと例外マッピングプロバイダではHTTPステータスコード500のHTTPレスポンスが返され，J2EEサーバにjava.lang.RuntimeExceptionがスローされます。J2EEサーバへの例外スローについては，「13.7.4　J2EEサーバへの例外のスロー」を参照してください。サブリソースクラスでは，例外マッピングプロバイダで処理可能なjava.lang.RuntimeExceptionがスローされます。

注※

追加の情報がある場合はほかのエラーメッセージも出力されます。

KDJJ10006-Eのエラーメッセージには詳細情報（サブメッセージ）のリストが含まれます。サブメッセージは，それぞれ構文の誤りの具体的な内容です。サブメッセージを参照して構文の誤りを取り除いてください。KDJJ10006-Eのエラーメッセージの注意事項を次に示します。

構文の誤りが複数ある場合は，すべての誤りを取り除いてください。

Webアプリケーション（WARファイル）にルートリソースクラス，サブリソースクラス，または例外マッピングプロバイダが複数含まれている場合，どれか一つに対してでもKDJJ10006-Eのエラーメッセージが出力されているとき，ほかのどのルートリソースクラス，サブリソースクラス，および例外マッピングプロバイダも利用できません。KDJJ10006-Eのエラーメッセージが出力されなくなるまで，Webアプリケーション（WARファイル）に含まれるルートリソースクラス，サブリソースクラス，または例外マッピングプロバイダのすべてを確認してください。

(2)　軽微な誤りがある場合

HTTP GETリクエストを受け付けるリソースメソッドの戻り値がvoidである場合など，軽微な構文の誤りを検出したとき，ほかに重大な誤りがなければ警告メッセージがログに出力され（KDJJ20003-W），ほかに一つでも重大な誤りがあればエラーメッセージがログに出力されます（KDJJ10006-E）。

KDJJ10006-Eのエラーメッセージがログに出力される場合については「13.7.1(1)　重大な誤りがある場合」を参照してください。

KDJJ20003-Wの警告メッセージがログに出力される場合は，処理はそのまま続行され，軽微な構文の誤りが検出されたメソッドを除いて正常に初期化されます。軽微な構文の誤りが検出されたメソッドについては，KDJJ20003-Wの警告メッセージが出力されなくなるまで，構文を確認してください。

13.7.2　受信したHTTPリクエストの処理で検出されるエラー

HTTPリクエストに対し，ディスパッチするリソースメソッドが一つもない場合など，HTTPリクエストを処理できないとき，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionまたはその他の例外がスローされます。追加の情報がある場合はエラーメッセージも出力されます。

13.7.3　例外マッピングプロバイダで処理できる例外

例外マッピングプロバイダで処理できる例外がスローされる場合，例外マッピングプロバイダを作成し，Webアプリケーション（WARファイル）に適切に含めれば，その例外の送信するHTTPレスポンスへのマッピングをカスタマイズできます。例外マッピングプロバイダの処理については，「17.1.8　例外ハンドリング」を参照してください。

13.7.4　J2EEサーバへの例外のスロー

Webリソース側のJAX-RSエンジンは，JAX-RS仕様が規定するサーブレットベースの仕組みをサポートしています。このため，JAX-RSエンジンで発生する例外は必要に応じて，Webリソースを含むWebアプリケーション（WARファイル）がデプロイされているJ2EEサーバにもスローされます。

Webリソースの運用中に障害が発生した場合は，JAX-RS機能のログファイルのほか，J2EEサーバのログも確認してください。

13.7.5　クライアントAPIの使用時に発生する例外（KDJJ18888-E）

クライアントAPIの使用中にClientHandlerExceptionまたはUniformInterfaceExceptionが発生した場合，ログにはKDJJ18888-Eのエラーメッセージが出力されます。

第3編　リファレンス

14　コマンド

SOAP Webサービスに必要なSEIやJavaBeanクラスは，cjwsimportコマンドで生成できます。また，hwsgenコマンドを使用すると，コンパイル済みのJavaソースからWSDLを生成できます。

この章では，cjwsimportコマンドおよびhwsgenコマンドの使用方法について説明します。

14.1　コマンドの詳細

14.1.1　cjwsimportコマンド

cjwsimportコマンドは，JAX-WS 2.2仕様で規定されているマッピング規則に従い，WSDLファイルからJavaにマッピングするコマンドです。cjwsimportコマンドを実行すると，WSDLファイルからWebサービスおよびWebサービスクライアントの実装に必要なJavaソースが生成され，コンパイルされます。

ここでは，cjwsimportコマンドを実行するときの形式や指定内容について説明します。

(1)　形式

cjwsimportコマンドの指定形式を次に示します。

cjwsimport [オプション群] <WSDLファイルのURLまたはファイルパス>

指定例

ローカルにあるWSDLファイルを相対パス（wsdl/input.wsdl）で指定

cjwsimport -d generated wsdl/input.wsdl

ローカルにあるWSDLファイルを絶対パス（/tmp/wsdl/input.wsdl）で指定

cjwsimport -d generated /tmp/wsdl/input.wsdl

ローカルにあるWSDLファイルをURL（file:///tmp/wsdl/input.wsdl）で指定

cjwsimport -d generated file:///tmp/wsdl/input.wsdl

リモートにあるWSDLファイルをURL（http://example.com:8080/fromjava/test?wsdl）で指定

cjwsimport -d generated http://example.com:8080/fromjava/test?wsdl

cjwsimportコマンド実行時の注意

cjwsimportコマンドは，「%」，「&」および「^」の文字を含んだディレクトリをカレントディレクトリとして実行することはできません。「%」，「&」および「^」の文字を含んだディレクトリをカレントディレクトリとして実行した場合の動作は保証されません。

WSDLファイル指定時の注意

引数にはWSDLファイルのファイルパス（相対パスまたは絶対パス）またはWSDLへのURLを一つ指定します。WSDLファイル以外のファイルを指定した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51200-E）。

WSDLをファイルパスで指定する場合，「&」および「^」を含んだ文字をファイルパスに使用しないでください。使用した場合の動作は保証されません。また，空白を含むファイルパスを指定する場合，ファイルパス全体を引用符（"）で囲んでください。ファイルパス全体を引用符で囲まない場合の動作は保証されません。

WSDLをURLで指定する場合は，RFC 2396仕様で規定されている文字，およびRFC 2396仕様の規則に従った文字列を使用してください。さらに，文字列はRFC 2396仕様の規則に従って，UTF-8でパーセントエンコーディングする必要があります。RFC 2396仕様の規則に従わない，またはエンコードしない文字や文字列を指定した場合の動作は保証されません。

WSDLをjarプロトコルで指定することはできません。jarプロトコルで指定した場合の動作は保証されません。

WSDLファイルをファイルパスまたはWSDLへのURLで指定する場合は，正しいファイルパスまたはURLを指定してください。WSDLのファイルパスまたはWSDLへのURLの指定を誤り，WSDLファイルが見つからない場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51180-EまたはKDJW51189-E）。

引数に指定するWSDLファイルの拡張子は任意です（.wsdl以外の拡張子を指定してもかまいません）。

大文字，小文字は区別されません。

指定する文字列の長さに制限はありません。ただし，OSの制限を超えた場合はエラーになります。

アクセス権限がないWSDLファイルを指定した場合，JDKのエラーとなり処理が終了されます。

(2)　オプション一覧

cjwsimportコマンドのオプション群には，次の表に示すオプションを指定できます。

表14‒1　cjwsimportコマンドのオプション一覧

オプション

設定項目

指定内容

-d <ディレクトリ>

クラスファイルの出力先ディレクトリ

コンパイル済みクラスファイル（*.class）の出力先ディレクトリを指定します。

指定できる値については，表外の「-dオプション／-sオプション指定時の注意事項」を参照してください。

このオプションを指定しない場合は，カレントディレクトリに出力されます。

-keep

なし

ソースファイル（*.java）を生成する場合に指定します。

-s <ディレクトリ>

ソースファイルの出力先ディレクトリ

ソースファイル（*.java）を出力する場合の出力先ディレクトリを指定します。

指定できる値については，表外の「-dオプション／-sオプション指定時の注意事項」を参照してください。

出力先ディレクトリは，-dオプションおよび-sオプションの指定によって変わります。オプションの指定と出力先については，表14-3を参照してください。

-verbose

なし

コマンド実行時の詳細な処理経過を出力する場合に指定します。

-b <パス>

外部バインディングファイルのパス

外部バインディングファイルを使用する場合に，外部バインディングファイルのパスを指定します。

指定できる値については，表外の「-bオプション指定時の注意事項」を参照してください。

-p <パッケージ>

Javaコードのパッケージ名

Javaソースのパッケージ名を指定します。

このオプションを指定した場合，バインディング宣言で指定したパッケージ名のカスタマイズや，標準仕様で定義されたデフォルトのパッケージ名の生成アルゴリズムは上書きされます。

-generateService

Webサービス実装クラスの生成

Webサービス実装クラス（スケルトンクラス）を生成する場合に指定します。

生成されるファイルについては，「14.1.1(4)　生成されるファイル」を参照してください。

-help

なし

ヘルプを表示する場合に指定します。

このオプションを指定した場合，-versionを除くすべてのオプションの指定が無視され，ヘルプが表示されて終了します。

-version

なし

バージョン情報を表示する場合に指定します。

このオプションを指定した場合，ほかのオプションの指定が無視され，バージョン情報が表示されて終了します。

-wsdllocation

javax.xml.ws.WebServiceClientアノテーションの，wsdlLocation要素に設定する値

javax.xml.ws.WebServiceClientアノテーションの，wsdlLocation要素に設定する値を指定します。

-catalog <ファイル>

カタログファイルのパス

カタログ機能を利用する場合に指定します。指定できる値については表外の「-catalogオプション指定時の注意事項」を参照してください。

ファイル生成時のディレクトリの作成

cjwsimportコマンドを実行すると，指定した出力先ディレクトリに，生成されるファイルのパッケージ名に対応するディレクトリが作成され，そのディレクトリにファイルが出力されます。

WSDLファイル（test.wsdl）の「要求メッセージのwrapper要素が参照する型」の名前空間URIに，「http://example.com/sample」が記述されている場合のコマンド指定例および出力先（リクエストbeanの場合）を示します。

コマンド指定例

cjwsimport -d ./output -keep input/test.wsdl

出力先（リクエストbean）

リクエストbeanのコンパイル済みクラスファイルとソースファイルは，次のディレクトリに出力されます。

./output/com/example/sample/

オプションに指定できる値や，指定を省略した場合の動作など，オプションの指定値についての注意事項を次に示します。

オプション共通の注意事項

全オプション共通の注意事項を示します。

オプション群と引数の指定順序は任意です。また，各オプションの指定順序も任意です。

引数を持つオプションは，必ず引数を指定してください。引数を指定しない場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51001-E）。

-catalogオプション以外は，同じオプションを重複して指定した場合，最後に指定したオプションが有効になります。

大文字，小文字を区別します。

指定する文字列の長さに制限はありません。ただし，OSの制限を超えた場合はエラーになります。

パスを指定するオプションには，「&」および「^」を含んだ文字列を使用しないでください。使用した場合の動作は保証されません。また，空白を含むパスを指定する場合，パス全体を引用符「"」で囲んでください。パス全体を引用符で囲まない場合の動作は保証されません。

指定できないオプションを指定した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51001-E）。

-dオプション／-sオプション指定時の注意事項

-dオプションおよび-sオプションの指定値についての注意事項を示します。

指定値の大文字，小文字は区別されません。

指定した出力先ディレクトリがない場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51181-E）。

出力先ディレクトリに誤ってファイルを指定した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51182-E）。

アクセス権限がないWSDLファイルを指定した場合，JDKのエラーとなり処理が終了されます。

-d／-s／-keepオプションの指定有無とファイルの出力先

-dオプション，-sオプション，および-keepオプションの指定によって，コンパイル済みクラスファイルと，ソースファイルの出力先ディレクトリが異なります。

オプションの指定有無とコンパイル済みクラスファイルの出力先ディレクトリを次の表に示します。

表14‒2　オプションの指定有無とコンパイル済みクラスファイルの出力先ディレクトリ

オプションの指定有無

ソースファイルの出力有無と出力先ディレクトリ

-d

-s

-keep

○

−

−

-dオプションで指定したディレクトリに出力されます。

×

−

−

カレントディレクトリに出力されます。

（凡例）

○：オプションが指定されていることを示します。

×：オプションが指定されていないことを示します。

−：オプションの指定有無は，出力先ディレクトリに影響しないことを示します。

オプションの指定有無とソースファイルの出力先ディレクトリを次の表に示します。

表14‒3　オプションの指定有無とソースファイルの出力先ディレクトリ

オプションの指定有無

ソースファイルの出力有無と出力先ディレクトリ

-d

-s

-keep

○

○

−

-sオプションで指定したディレクトリに出力されます。

○

×

○

-dオプションで指定したディレクトリに出力されます。

○

×

×

出力されません。

×

○

−

-sオプションで指定したディレクトリに出力されます。

×

×

○

カレントディレクトリに出力されます。

×

×

×

出力されません。

（凡例）

○：オプションが指定されていることを示します。

×：オプションが指定されていないことを示します。

−：オプションの指定有無は，出力先ディレクトリに影響しないことを示します。

-bオプション指定時の注意事項

-bオプションの指定値についての注意事項を示します。

指定値の大文字，小文字は区別されません。

外部バインディングファイルはファイルパスで指定してください。URL形式で指定した場合の動作は保証されません。

指定した外部バインディングファイルがない場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51184-E）。

外部バインディングファイル以外のファイルを指定した場合，動作は保証されません。

誤ってディレクトリを指定した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51185-E）。

アクセス権限がないWSDLファイルを指定した場合，JDKのエラーとなり処理が終了されます。

指定した外部バインディングファイルがカスタマイズ対象とするWSDLファイルと，cjwsimportコマンドの引数に指定したカスタマイズ対象のWSDLファイルは同じファイルを指定してください。同じでない場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51190-E）。

外部バインディングファイルの拡張子の指定は任意です。

-pオプション指定時の注意事項

-pオプションの指定値についての注意事項を示します。

パッケージ名は，半角英数字（0〜9，A〜Z，a〜z），アンダースコア（_），およびピリオド（.）で指定します。それ以外の文字を指定した場合，動作は保証されません。

"xxx.yyy.zzz"のようにピリオド（.）で区切られた各ラベル（"xxx"，"yyy"，"zzz"）は，Javaの識別子に使用できる文字列を指定してください。使用できない文字を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます。

-wsdllocationオプション指定時の注意事項

-wsdllocationオプションは，URI形式で指定してください。それ以外の形式で指定した場合の動作は保証されません。

-wsdllocationオプションで指定する値にjarプロトコルは指定できません。指定した場合の動作は保証されません。WSDLを示すURLとしてjarプロトコルを指定する場合は，サービスクラスの生成時にURLをパラメタに取るコンストラクタを使用してください。

-catalogオプション指定時の注意事項

-catalogオプションの指定値についての注意事項を示します。

-catalogオプションを重複して指定した場合の動作は保証されません。

指定値の大文字，小文字は区別されません。

カタログファイルはファイルパスで指定してください。また，指定形式は，java.io.Fileクラスの仕様に従います。URL形式で指定した場合の動作は保証されません。

カタログファイルのファイルパスは，半角英数字（0〜9，A〜Z，a〜z），空白，ピリオド（.），アンダースコア（_），コロン（:），スラッシュ（/），および¥で指定します。それ以外の文字を指定した場合，動作は保証されません。

カタログファイルは任意のファイル名を設定できます。

指定したカタログファイルが存在しない場合，標準エラー出力とログに警告メッセージが出力され，カタログ機能が無効な状態で処理が続行されます（KDJW51219-W）。

カタログファイル以外のファイルを指定した場合，動作は保証されません。

誤ってディレクトリを指定した場合，標準エラー出力とログに警告メッセージが出力され，カタログ機能が無効な状態で処理が続行されます（KDJW51220-W）。

サポートしていない構文で記述したカタログファイルを指定した場合，標準エラー出力とログに警告メッセージが出力され，カタログ機能が無効な状態で処理が続行されます（KDJW51221-W）。

アクセス権限のないカタログファイルを指定した場合，JDKのエラーとなりカタログ機能が無効な状態で処理が続行されます。

無視される値に指定した場合の動作について

コマンドの指定値のうち，指定しても無視されるとしているものに値を指定した場合，あとの処理でエラーになる可能性があります。

(3)　WSIMPORT_OPTS環境変数の指定

WSIMPORT_OPTS環境変数にオプション文字列を指定すると，cjwsimportコマンドを起動するjavaコマンドにオプションを追加できます。デフォルトの設定では，WSIMPORT_OPTS環境変数には何も指定されていないので，必要に応じて任意の文字列を指定してください。

例えば，WSIMPORT_OPTS環境変数を利用して，SSL通信に必要なJDKのシステムプロパティを指定し，従来HTTPSを利用しないとWSDLにアクセスできないWSDLに対しても，cjwsimportコマンドを実行できます。例を次に示します。

> set WSIMPORT_OPTS=-Djavax.net.ssl.trustStore=<トラストストア> -Djavax.net.ssl.trustStorePassword=<トラストストアのパスワード>
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" https://securehost:443/fromwsdl/TestJaxWsService?wsdl

(4)　生成されるファイル

cjwsimportコマンドの実行時に生成されるファイルを次の表に示します。

表14‒4　cjwsimportコマンドの生成ファイル一覧

項番

Javaコード

内容

-generateServiceオプションによる出力

指定あり

指定なし

1

リクエストbeanクラス

要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

指定したWSDLファイルがwrapperスタイルでない場合は出力されません。

○

○

2

レスポンスbeanクラス

応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

指定したWSDLファイルがwrapperスタイルでない場合は出力されません。

○

○

3

フォルトbeanクラス

フォルトメッセージが参照する型に対応するJavaBeanクラスです。

指定したWSDLファイルでフォルトが定義されていない場合は出力されません。

○

○

4

ラッパ例外クラス

フォルトbeanクラスのラッパ例外クラスです。

○

○

5

ObjectFactoryクラス

JAXB 2.2仕様のファクトリクラスです。

○

○

6

JAXB 2.2仕様のそのほかのクラス

JAXB 2.2仕様のそのほかのクラスです。XML Schema仕様の構文で記述した各種要素，型に対応するJavaインタフェースおよびJavaクラスです。

○

○

7

package-info.java

パッケージ情報です。

○

○

8

SEI

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

○

○

9

スケルトンクラス

SEIを実装（implements）したスケルトンクラスです。このクラスに実装を追加します。

○

×

10

サービスクラス

Webサービスにアクセスするためのクラスです。

×

○

（凡例）

○：ファイルが出力されることを示します。

×：ファイルが出力されないことを示します。

ファイル生成時の注意事項

生成されるファイルの出力先ディレクトリにスケルトンクラスと同名のファイルがある場合は，標準エラー出力とログに警告メッセージが出力されます（KDJW51203-W）。このとき，スケルトンクラスは出力されないで，処理は続行されます。

また，生成されるファイルの出力先ディレクトリにWebサービス実装クラス以外の同名のファイルがある場合，ファイルが上書きされます。

Javadocのヘッダ情報の出力

生成されるファイルでは，Application Serverに関する情報が，Javadocとしてヘッダ情報に出力されます。

(5)　処理中の動作

cjwsimportコマンドを実行すると，標準出力とログにコマンド実行を示すメッセージ（KDJW50001-I）が出力され，Javaソースの生成処理およびJavaソースのコンパイル処理が行われます。それぞれの処理について，次に示します。

Javaソースの生成処理

Javaソースの生成開始時には，標準出力とログに生成開始を示すメッセージが出力されます（KDJW50004-I）。Javaソースの生成に失敗した場合，エラーの原因となったエラーメッセージが標準エラー出力とログに出力されます（KDJW50005-E）。

Javaソースのコンパイル処理

Javaソースのコンパイル開始時には，標準出力とログにコンパイル開始を示すメッセージが出力されます（KDJW50006-I）。Javaソースのコンパイルに失敗した場合は，エラーの原因となったエラーメッセージが標準エラー出力とログに出力されます（KDJW50007-E）。

(6)　終了コード

cjwsimportコマンドの終了コードを示します。

0：正常終了

処理の途中で続行できないエラーが検出されなければ，標準出力とログに終了したことを示すメッセージが表示され，処理が終了されます（KDJW50002-I）。

1：異常終了

処理の途中で続行できないエラーが一つでも検出された場合は，標準出力とログにエラーメッセージが表示され，処理が終了されます（KDJW50003-E）。異常終了時の対処については，「14.1.1(7)　異常終了時の対処」を参照してください。

処理の途中で続行できる軽微なエラーが検出された場合は，警告メッセージが出力され，処理が続行されます。

なお，設定した出力レベル（重要度）によって，ログが出力されない場合があります。ログの出力レベルの設定については，「10.1.2　共通定義ファイルの設定項目」を参照してください。

(7)　異常終了時の対処

cjwsimportコマンドの実行時に異常終了した場合，エラーメッセージが出力され，処理が終了されます。この場合，出力されたエラーの要因を取り除き，cjwsimportコマンドを再実行します。

複数のエラーがある場合でも，最初に検出されたエラーが表示されます。この場合，cjwsimportコマンドを繰り返し実行して，表示されたエラーの要因を一つずつ取り除いてください。

14.1.2　hwsgenコマンド

hwsgenコマンドは，サービス実装クラスのクラスファイルを基に，Webサービスのデプロイに必要なJavaコード（JavaBeanクラス）と，リソースファイル（WSDLおよびXSD）を生成するコマンドです。なお，サービス実装クラスには，サービス実装クラスが参照しているクラスやSEIも含むものとします。

ここでは，hwsgenコマンドを実行するときの形式や指定内容について説明します。

(1)　形式

hwsgenコマンドの指定形式を次に示します。

hwsgen [オプション群] サービス実装クラスの完全修飾名

指定例

デプロイ前にWSDLを確認する場合

hwsgen -wsdl -cp . com.example.UserInfoImpl

既存のWebサービスからWebサービス（サービス名がMyService）のJavaコードおよびリソースファイルを生成する場合

hwsgen -servicename {http://example.com/}MyService -cp . com.example.UserInfoImpl

既存のWebサービスからWebサービス（ポート名がMyServicePort）のJavaコードおよびリソースファイルを生成する場合

hwsgen -portname {http://example.com/}MyServicePort -cp . com.example.UserInfoImpl

hwsgenコマンド実行時の注意

hwsgenコマンドは，「&」および「^」の文字を含んだディレクトリをカレントディレクトリとして実行することはできません。「&」および「^」の文字を含んだディレクトリをカレントディレクトリとして実行した場合の動作は保証されません。

次に示すディレクトリ以下に，hwsgenコマンドが生成する以外のソースファイルが存在しないことを確認してください。

ソースファイルを出力する場合：ソースファイルの出力先ディレクトリ

ソースファイルを出力しない場合：hwsgenコマンドが使用する作業ディレクトリ

ソースファイルの出力先と作業ディレクトリについては，「-d／-s／-keepオプションの組み合わせと出力先ディレクトリ／作業ディレクトリ」を参照してください。

サービス実装クラス指定時の注意

サービス実装クラスのソースファイルは，クラスファイルとは別のディレクトリに配置してください。ソースファイルがクラスファイルと同じディレクトリに配置されていると，エラーが発生するおそれがあります。

引数には，サービス実装クラスのクラスファイルを完全修飾名で指定します。

クラスが有効に扱われたのかは，警告メッセージで確認してください。

インナークラスであるサービス実装クラスは，引数に指定しないでください。指定した場合の動作は保証されません。

上記以外のSEIおよびWebサービス実装クラスに関する注意事項は，「16.1　JavaからWSDLへのデフォルトマッピング」および「16.2　JavaからWSDLへのマッピングのカスタマイズ」を参照してください。

(2)　オプション一覧

hwsgenコマンドのオプション群には，次の表に示すオプションを指定できます。

表14‒5　 hwsgenコマンドのオプション一覧

オプション

設定項目

指定内容

-d <ディレクトリ>

コンパイル済みクラスファイルの出力先ディレクトリのパス

コンパイル済みクラスファイル（*.class）の出力先ディレクトリを指定します。

指定できる値については，表外の「-d／-s／-rオプション指定時の注意事項」を参照してください。

ほかのオプションが指定されている場合，このオプションで指定したディレクトリにコンパイル済みクラスファイル以外のファイルが出力されることがあります。詳細は，表外の「-d／-s／-keepオプションの組み合わせと出力先ディレクトリ／作業ディレクトリ」および「-d／-r／-servicename／-portname／-wsdlオプションの組み合わせと出力先ディレクトリ」を参照してください。

-s <ディレクトリ>

ソースファイルの出力先ディレクトリのパス

ソースファイル（*.java）を出力する場合の出力先ディレクトリを指定します。

-r <ディレクトリ>

リソースファイルの出力先ディレクトリのパス

リソースファイル（*.wsdlおよび*.xsd）を出力する場合の出力先ディレクトリを指定します。

-keep

なし

ソースファイル（*.java）を保持するかどうかを指定します。

-wsdl

なし

リソースファイル（*.wsdlおよび*.xsd）を出力するかどうかを指定します。

-servicename <サービス名>

サービス名

変更後のサービス名を指定します。

-portname <ポート名>

ポート名

変更後のポート名を指定します。

-classpath <クラスパス>

サービス実装クラスが含まれるクラスパス

引数に指定するサービス実装クラスが含まれるクラスパスを指定します。

-cp <クラスパス>

-verbose

なし

コマンド実行時の詳細な処理経過を出力する場合に指定します。

-help

なし

ヘルプを表示する場合に指定します。

このオプションを指定した場合，-versionを除くすべてのオプションの指定が無視され，ヘルプが表示されて終了します。

-version

なし

バージョン情報を表示する場合に指定します。

このオプションを指定した場合，ほかのオプションの指定が無視され，バージョン情報が表示されて終了します。

オプションに指定できる値や，指定を省略した場合の動作など，オプションの指定値についての注意事項を次に示します。

オプション共通の注意事項

全オプション共通の注意事項を示します。

オプション群と引数の指定順序は任意です。また，各オプションの指定順序も任意です。

引数を持つオプションは，必ず引数を指定してください。

同じオプションを重複して指定した場合は，最後に指定したオプションが有効になります。ただし，不正な値を指定したオプションがある場合は，エラーが発生することがあります。

大文字，小文字は区別されます。

指定する文字列の長さに制限はありません。ただし，OSの制限を超えた場合はエラーになります。

オプションに空白を含むパスを指定する場合，パス全体を引用符（"）で囲んでください。パス全体を引用符で囲まない場合の動作は保証されません。

-d／-s／-rオプション指定時の注意事項

-dオプション，-sオプション，および-rオプションの指定値についての注意事項を示します。

指定値の大文字，小文字は区別されません。

-dオプションに指定する出力先ディレクトリのパスには，次の文字は使用しないでください。使用した場合の動作は保証されません。

#　%　&　^　;　`　{　}　[　]

-rオプションに指定する出力先ディレクトリのパスには，次の文字は使用しないでください。使用した場合の動作は保証されません。

%　&　^　`　{　}　[　]

-sオプションに指定する出力先ディレクトリのパスには，次の文字は使用しないでください。使用した場合の動作は保証されません。

&　^

アクセス権限がないディレクトリを指定した場合，JDKのエラーとなり処理が終了されます。

-wsdlオプション指定時の注意事項

SOAPバインディングのバージョンは，hwsgenコマンドでは-wsdlオプションで次のように指定してください。記述例を次に示します。

SOAPバインディングのバージョンがSOAP 1.1の場合

hwsgen -wsdl -cp . com.example.UserInfoImpl
または
hwsgen -wsdl:soap1.1 -cp . com.example.UserInfoImpl

SOAPバインディングのバージョンがSOAP 1.2の場合

hwsgen -wsdl:Xsoap1.2 -extension -cp . com.example.UserInfoImpl

-servernameオプションと-portnameオプションは,hwsgenコマンドでは-wsdlオプションと組み合わせて使用してください。

-servicenameオプション指定時の注意事項

-servicenameオプションは，QName形式で記述します。-servicenameオプションの記述例を次に示します。

{名前空間URI}サービス名

名前空間

名前空間URIは，括弧（{ }）で囲んでください。

名前空間URIは，半角英数字で指定してください。半角英数字以外を指定した場合の動作は保証されません。

プロトコル

-servicenameオプションに記述する名前空間URIとして有効なのは，http://またはurn:で始まるドメイン名だけです。https://やfile://などで始まる名前空間URIは，不正と見なされます。

-servicenameオプションに記述する名前空間URIを相対パスで指定することはできません。

指定できない情報

-servicenameオプションに記述する名前空間URIには，クエリストリング，アンカー，ポート番号，ユーザ名，およびパスワードは記述できません。

記述できる文字列

区切り文字のスラッシュ（/）またはピリオド（.）で区切られたセグメントには，次の表に示すすべての条件を満たす文字列を記述できます。

表14‒6　名前空間に記述できる文字列の条件（-servicenameオプション指定時）

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z）だけを使用した文字列

http://鈴木.com/

http://133.145.224.19/

http://[1080:2C14;D30:BA04:275:806:270C:418A]/

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列

http://xxx.com/abstract

動作は保証されません。

3

先頭が数字でない文字列

http://1xxx.com

サービス名

サービス名は，半角英数字およびアンダースコアで指定してください。半角英数字またはアンダースコア以外の文字を指定した場合の動作は保証されません。

サービス名は，Javaで規定された識別子の命名規則に従って指定することをお勧めします。指定したサービス名がJavaで規定された識別子の命名規則に従っていない場合，cjwsimportコマンドを実行してWebサービスクライアントを開発するときにコンパイルエラーが発生します。

-portnameオプション指定時の注意事項

-portnameオプションは，QName形式で記述します。-portnameオプションの記述例を次に示します。

{名前空間URI}ポート名

名前空間

名前空間URIは，括弧（{ }）で囲んでください。

名前空間URIは，WSDLファイルのservice要素と同じ名前空間URIを指定してください。

名前空間URIは，半角英数字で指定してください。半角英数字以外を指定した場合の動作は保証されません。

プロトコル

-portnameオプションに記述する名前空間URIとして有効なのは，http://またはurn:で始まるドメイン名だけです。https://やfile://などで始まる名前空間URIは，不正と見なされます。

-portnameオプションに記述する名前空間URIを相対パスで指定することはできません。

指定できない情報

-portnameオプションに記述する名前空間URIには，クエリストリング，アンカー，ポート番号，ユーザ名，およびパスワードは記述できません。

記述できる文字列

区切り文字のスラッシュ（/）またはピリオド（.）で区切られたセグメントには，次の表に示すすべての条件を満たす文字列を記述できます。

表14‒7　名前空間に記述できる文字列の条件（-portnameオプション指定時）

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z）だけを使用した文字列

http://鈴木.com/

http://133.145.224.19/

http://[1080:2C14;D30:BA04:275:806:270C:418A]/

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列

http://xxx.com/abstract

動作は保証されません。

3

先頭が数字でない文字列

http://1xxx.com

ポート名

ポート名は，半角英数字およびアンダースコアで指定してください。半角英数字またはアンダースコア以外の文字を指定した場合の動作は保証されません。

-classpath／-cpオプション指定時の注意事項

-classpathオプションおよび-cpオプションの指定値についての注意事項を示します。

オプションを省略した場合は，環境変数CLASSPATHがクラスパスとして使用されます。オプションを指定した場合は，環境変数CLASSPATHは無視されます。

環境変数CLASSPATHで指定した値はそのまま適用されるため，空白を含む場合でも，引用符（"）で囲む必要はありません。引用符で囲む形式で指定した場合の動作は保証されません。

オプションを省略し，環境変数CLASSPATHも指定していない場合は，カレントディレクトリがクラスパスとして使用されます。

クラスパスは，相対パス，絶対パスのどちらでも指定できます。

クラスパスとしてJARファイルを指定することもできます。

複数のクラスパスを指定する場合は，クラスパスの間にセミコロンを記述してください。

指定するクラスパスには，次の文字は使用しないでください。使用した場合の動作は保証されません。

#　%　&　^

-help／-versionオプション指定時の注意事項

hwsgenコマンドのヘルプ情報およびバージョン情報に出力される"wsgen"は，"hwsgen"に読み替えてください。また，ヘルプ情報に出力されるオプションのうち，-inlineSchemasオプションと-Xnocompileオプションは非サポートです。

-d／-s／-keepオプションの組み合わせと出力先ディレクトリ／作業ディレクトリ

コンパイル済みクラスファイル（*.class）は，-dオプションが指定されている場合は-dオプションで指定したディレクトリに，-dオプションが指定されていない場合はカレントディレクトリに出力されます。

ソースファイル（.java）が出力されるかどうか，また，出力される場合の出力先ディレクトリ，およびhwsgenコマンドが利用する作業ディレクトリは，オプションの組み合わせによって次の表のとおり異なります。なお，リソースファイルだけを利用したい場合は，ソースファイルを出力しなくてもかまいません。

表14‒8　ソースファイルの出力有無と出力先ディレクトリ

オプションの指定有無

ソースファイルの出力有無と出力先ディレクトリ／作業ディレクトリ

-d

-s

-keep

○

○

○

-sオプションで指定したディレクトリが作業ディレクトリとして利用され，ソースファイルが出力されます。

○

○

×

○

×

○

-dオプションで指定したディレクトリが作業ディレクトリとして利用され，ソースファイルが出力されます。

○

×

×

-dオプションで指定したディレクトリが作業ディレクトリとして利用されます。ソースファイルは出力されません。

×

○

○

--sオプションで指定したディレクトリが作業ディレクトリとして利用され，ソースファイルが出力されます。

×

○

×

×

×

○

カレントディレクトリが作業ディレクトリとして利用され，ソースファイルが出力されます。

×

×

×

カレントディレクトリが作業ディレクトリとして利用されます。ソースファイルは出力されません。

（凡例）

○：オプションが指定されていることを示します。

×：オプションが指定されていないことを示します。

-d／-r／-servicename／-portname／-wsdlオプションの組み合わせと出力先ディレクトリ

リソースファイル（*.wsdlおよび*.xsd）が出力されるかどうか，また，出力される場合の出力先ディレクトリは，オプションの組み合わせによって次の表のとおり異なります。

表14‒9　リソースファイルの出力有無と出力先ディレクトリ

オプションと指定有無

出力有無

出力先

-d

オプション

-r

オプション

-servicename，

-portname，

オプション

-wsdl

オプション

指定あり

指定あり

指定あり

指定あり

○

-rオプションで指定したディレクトリ

指定なし

指定なし

指定あり

指定なし

指定なし

指定あり

指定あり

○

-dオプションで指定したディレクトリ

指定なし

指定なし

指定あり

○

-dオプションで指定したディレクトリ

指定なし

×

−

指定なし

指定あり

指定あり

指定あり

○

-rオプションで指定したディレクトリ

指定なし

指定なし

指定あり

指定なし

指定なし

指定あり

指定あり

○

カレントディレクトリ

指定なし

指定なし

指定あり

○

カレントディレクトリ

指定なし

×

−

（凡例）

−：リソースファイルの出力がないため，該当しないことを示します。

○：リソースファイルが出力されることを示します。

×：リソースファイルが出力されないことを示します。

(3)　生成されるファイル

hwsgenコマンドの実行時に生成されるファイルを次の表に示します。

表14‒10　hwsgenコマンドの生成ファイル一覧

項番

生成ファイル

内容

1

リクエストbeanクラス

要求メッセージのJavaBeansクラスです。生成されるサービス実装クラスがwrapper形式の場合に出力されます。

2

レスポンスbeanクラス

応答メッセージのJavaBeansクラスです。生成されるサービス実装クラスがwrapper形式の場合に出力されます。

3

フォルトbeanクラス

フォルトに対応するJavaBeansクラスです。指定されたJavaコードにラッパ例外クラスが定義されていて，フォルトbeanが存在しない場合に出力されます。

4

WSDL

WSDLファイルです。

5

XSD

XMLスキーマ定義ファイルです。

ファイル生成時のディレクトリの作成

hwsgenコマンドを実行すると，指定した出力先ディレクトリに，生成されるファイルのパッケージ名に対応するディレクトリが作成され，そのディレクトリにファイルが出力されます。

指定例および出力先を次に示します。

コマンド指定例

hwsgen -d ./output -s ./output -keep -cp . com.example.UserInfoImpl

出力先

hwsgenコマンドに指定したサービス実装クラスのクラスファイルにJavaBeanクラスがある場合は，JavaBeanクラスのソースファイルおよびコンパイル済みクラスファイルが次のjaxwsサブパッケージに出力されます（パッケージ名をアノテーションでカスタマイズしている場合を除く）。

./output/com/example/jaxws/

また，リソースファイルの生成物は，hwsgenコマンドの引数で指定したディレクトリに出力されます。指定例および出力先を次に示します。

コマンド指定例

hwsgen -r ./output -cp . com.example.UserInfoImpl

出力先

./output/

ファイル生成時の注意事項

生成されるファイルの出力先ディレクトリに同名のファイルがある場合，ファイルが上書きされます。

Javadocのヘッダ情報の出力

生成されるファイルでは，Application Serverに関する情報が，Javadocとしてヘッダ情報に出力されます。

(4)　入力サービス実装クラスと出力リソースファイルの関係

入力サービス実装クラスと出力リソースファイルの関係を次の表に示します。

表14‒11　入力サービス実装クラスと出力リソースファイルの関係

入力サービス実装クラス

出力リソース

WSDL

XSD

ファイル数

ファイル名

ファイル数※1

ファイル名

SEIなし

1

wsdl:service要素のname属性値

1〜N※2

wsdl:service要素のname属性値＋接尾辞（_schemaN）※2

SEIあり（サービス実装クラスと同じ名前空間）

1

wsdl:service要素のname属性値

1〜N※2

wsdl:service要素のname属性値＋接尾辞（_schemaN）※2

SEIあり（サービス実装クラスと異なる名前空間）

2

抽象WSDLファイルの場合※3

wsdl:portType要素のname属性値

実装WSDLファイルの場合※4

wsdl:service要素のname属性値

1〜N※2

wsdl:portType要素のname属性値＋接尾辞（_schemaN）※2

注※1

スキーマの名前空間が異なると，そのたびにファイルが生成されます。

注※2

Nはスキーマの名前空間の数です。生成できるファイルの上限数は，OSに依存します。

注※3

抽象WSDLとは，「wsdl:types要素, wsdl:message要素, wsdl:portType要素」のWSDLを指します。

注※4

実装WSDLとは，「wsdl:binding要素，wsdl:service要素」のWSDLを指します。

(5)　処理中の動作

hwsgenコマンドを実行すると，JavaBeansの生成と削除，WSDLおよびXSDの生成が実行されます。ただし，オプションの指定内容によっては，生成したJavaBeansのソースファイルが削除されない場合もあります。オプションについては，「14.1.2(2)　オプション一覧」を参照してください。

(6)　終了コード

hwsgenコマンドの終了コードを示します。

0：正常終了

1：異常終了

処理の途中で続行できる軽微なエラーが検出された場合は，警告メッセージが出力され，処理が続行されます。

複数のエラーが検出された場合は，最初に検出されたエラーが標準出力とログに終了したことを示すメッセージが表示され，処理が終了されます。

エラーが検出される前に生成されたディレクトリやファイルは，コマンドが異常終了しても削除されずに残ります。

(7)　異常終了時の対処

hwsgenコマンドの実行時に異常終了した場合，エラーメッセージが出力され，処理が終了されます。この場合，出力されたエラーの要因を取り除き，hwsgenコマンドを再実行します。

複数のエラーがある場合でも，最初に検出されたエラーが表示されます。この場合，hwsgenコマンドを繰り返し実行して，表示されたエラーの要因を一つずつ取り除いてください。

なお，サービス実装クラスのクラスファイルの不正が原因で異常終了した場合は，クラスファイルの生成元であるJavaソースを修正し，コンパイルし直す必要があります。

14.2　UACが有効なWindowsでコマンドラインインタフェースを使用する場合の注意事項

OSがWindowsでUAC（ユーザアカウント制御）が有効な場合に，cjwsimportコマンドおよびhwsgenコマンドを実行するときの注意事項を説明します。

14.2.1　管理者がコマンドラインインタフェースを使用する場合

管理者がコマンドラインインタフェースを使用する場合，インストール時の注意事項はありません。

インストール後にコマンドラインインタフェースを実行するときには，管理者としてコマンドプロンプトを起動する必要があります。権限を管理者に昇格させてコマンドプロンプトを起動する方法については，OSのドキュメントを参照してください。

14.2.2　管理者以外がコマンドラインインタフェースを使用する場合

管理者以外がコマンドラインインタフェースを使用する場合の注意事項を説明します。

(1)　インストール時の注意事項

管理者以外がコマンドラインインタフェースを使用する場合は，Application Serverをデフォルトのインストールディレクトリにインストールしてください。デフォルトのインストールディレクトリ以外のディレクトリにインストールした場合，コマンドラインインタフェースのすべてのログ出力先ディレクトリに対して，コマンドラインインタフェースを実行する管理者以外のユーザも書き込みできるようにアクセス権を設定する必要があります。アクセス権の設定は，管理者が実行します。設定方法については，OSのドキュメントを参照してください。

(2)　コマンド実行時の注意事項

管理者以外のユーザがコマンドラインインタフェースを実行する場合の注意事項を示します。

カレントディレクトリは，UACの保護対象外のディレクトリを指定します。

オプション設定で生成するファイルの出力先には，UACの保護対象外のディレクトリを指定します。

Application Serverがデフォルトのインストールディレクトリにインストールされている場合，コマンドラインインタフェースのログは，次のディレクトリにリダイレクトされます。

%LoadlAppData%¥VirtualStore¥Program Filesディレクトリ以下の対応するディレクトリ

リダイレクトについては，OSのドキュメントを参照してください。

15　WSDLからJavaへのマッピング

cjwsimportコマンドを実行すると，JAX-WS 2.2仕様に従ってWSDLからJavaソースへマッピングされます。

この章では，WSDLからJavaへのデフォルトマッピング，およびマッピングのカスタマイズについて説明します。

15.1　WSDLからJavaへのデフォルトマッピング

cjwsimportコマンドの実行時に，WSDLからJavaソースへマッピングされます。このときの対応関係を次の表に示します。

表15‒1　WSDLからJavaソースへのマッピング一覧

項番

WSDL

Java ソース

参照先

1

名前空間

パッケージ名

15.1.1

2

ポートタイプ

SEI名

15.1.2

3

オペレーション

メソッド名

15.1.3

4

パート

パラメタおよび戻り値

15.1.4，15.1.5

5

型

パラメタおよび戻り値

15.1.6

6

フォルト

例外クラス

15.1.7

7

バインディング

javax.jws.soap.SOAPBindingアノテーション

15.1.8

8

サービス

javax.jws.WebServiceアノテーションのserviceName属性

15.1.9

15.1.1　名前空間からパッケージ名へのマッピング

WSDLの名前空間（wsdl:definitions要素のtargetNamespace属性）からパッケージ名へのマッピングについて説明します。

(1)　マッピング

WSDLの名前空間とパッケージ名は，JAX-WS 2.2仕様に従ってマッピングされます。詳細は，JAX-WS 2.2仕様を参照してください。

マッピング例を次の図に示します。

図15‒1　名前空間とパッケージ名のマッピング例

(2)　名前空間の条件

WSDLに記述する名前空間の条件について説明します。

プロトコル

名前空間は，http://またはurn:のプロトコルで記述してください。http://またはurn:のプロトコル以外（https://，file://など）を記述した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51002-E）。

また，相対パスで記述した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51003-E）。

名前空間の記述形式

名前空間には次に示す形式は記述できません。次に示す形式で記述した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51004-E）。

空文字列

クエリストリング（例）http://example.com/?a=b

アンカー（例）http://example.com/index.html#anchor

ポート番号（例）http://example.com:8080/

ユーザ名／パスワード（例）http://user:password@example.com

記述できる文字列

区切り文字のスラッシュ（/）またはピリオド（.）で区切られたセグメントには，次の表に示すすべての条件を満たす文字列を記述できます。ただし，バインディング宣言でカスタマイズする場合は，RFC 2396仕様の規則に従った文字列を記述できます。

表15‒2　名前空間に記述できる文字列の条件

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z）だけを使用した文字列

http://鈴木.com

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列

http://xxx.com/abstract

Javaのパッケージ名にマッピングするときに，Java予約語の先頭にアンダースコア（_）が付きます。

（例）com.xxx._abstract

3

先頭が数字でない文字列

http://1xxx.com

Javaのパッケージ名にマッピングするときに，先頭が数字である文字列の先頭にアンダースコア（_）が付きます。

（例）com._1xxx

15.1.2　ポートタイプからSEI名へのマッピング

WSDLのポートタイプ名（wsdl:portType要素のname属性）からSEI名へのマッピングについて説明します。

(1)　マッピング

WSDLのポートタイプとSEI名は，JAX-WS 2.2仕様に従ってマッピングされます。マッピング例を次の図に示します。

図15‒2　ポートタイプとSEI名のマッピング例

マッピングするときに，WSDLのポートタイプ名の先頭文字は大文字に変換されます。変換例を次に示します。

（変換前）portTypeName　　　（変換後）PortTypeName

(2)　ポートタイプ名の条件

WSDLのポートタイプ名と名前空間を指定する場合は，パッケージ名も含めてSEI名が"javax.xml.ws.Provider"にならないようにする必要があります。そのため，ポートタイプ名には"Provider"または"provider"を指定しないでください。また，名前空間には"http://ws.xml.javax"を指定しないでください。

ポートタイプには，次の表に示すすべての条件を満たす文字列を記述できます。ただし，バインディング宣言でカスタマイズする場合は，XML Schema仕様のxsd:NCName型として使用できる文字列を記述できます。

表15‒3　ポートタイプに記述できる文字列の条件

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z），およびアンダースコア（_）だけを使用した文字列

鈴木_portType

動作は保証されません（エラーメッセージは出力されません）。

2

先頭が数字でない文字列

1User_portType

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

(3)　ポートタイプの記述個数

WSDLに記述できるポートタイプは，1〜255個です。ポートタイプの記述数と動作の対応を次の表に示します。

表15‒4　ポートタイプの記述数と動作の対応

項番

要素

記述数

不正な文字列を指定した場合の動作

1

wsdl:portType

0個

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51008-E）。

2

1〜255個

正常終了します。

3

256個以上

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51008-E）。

15.1.3　オペレーションからメソッド名へのマッピング

WSDLのオペレーション（wsdl:operation要素のname属性）からJavaのメソッド名へのマッピングについて説明します。

(1)　マッピング

WSDLのオペレーションとJavaのメソッド名は，JAX-WS 2.2仕様に従ってマッピングされます。マッピング例を次の図に示します。

図15‒3　オペレーションとメソッド名のマッピング例

マッピングするときに，WSDLのオペレーション名の先頭文字は小文字に変換されます。getやsetのプレフィクスは付加されません。変換例を次に示します。

（変換前）OperationName　　　（変換後）operationName

(2)　オペレーション名の条件

オペレーション名には，次の表に示すすべての条件を満たす文字列を記述できます。ただし，バインディング宣言でカスタマイズする場合は，XML Schema仕様のxsd:NCName型として使用できる文字列を記述できます。

表15‒5　オペレーション名に記述できる文字列の条件

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z），およびアンダースコア（_）だけを使用した文字列

鈴木_operation

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列※

abstract

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51007-E）。

3

先頭が数字以外の文字列

1User_operation

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

注※

「Abstract」のように，Java予約語の先頭文字を大文字にした文字列も記述できません（マッピングによって先頭文字が小文字に変換されるため）。

(3)　オペレーションとその子要素の記述個数

WSDLに記述できるオペレーションは，ポートタイプ1個につき1〜255個です。また，オペレーションの子要素には，wsdl:input要素を1個，wsdl:output要素を0個または1個，およびwsdl:fault要素を0〜255個記述できます。

オペレーションの記述数と，動作の対応を次の表に示します。

表15‒6　オペレーションの記述数と動作の対応

項番

要素

記述数

不正な文字列を指定した場合の動作

1

wsdl:operation

0個

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

2

1〜255個

正常終了します。

3

256個以上

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

オペレーションの子要素の記述数と，動作の対応を次の表に示します。

表15‒7　オペレーションの子要素の記述数と動作の対応

項番

要素

記述数

不正な文字列を指定した場合の動作

1

wsdl:input

0個

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

2

1個

正常終了します。

3

2個以上

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

4

wsdl:output

0個

wsdl:fault要素の記述数が0個の場合

one-wayオペレーションにマッピングして，正常終了します。

wsdl:fault要素の記述数が1個以上の場合

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

5

1個

request-responseオペレーションにマッピングして，正常終了します。

6

2個以上

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

7

wsdl:fault

0〜255個

正常終了します。

8

256個以上

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

15.1.4　メッセージのパートからパラメタおよび戻り値へのマッピング（wrapperスタイルの場合）

WSDLのメッセージのパート（wsdl:message要素のwsdl:part子要素）からJavaのメソッドのパラメタおよび戻り値へのマッピングについて説明します。

ここでは，wrapperスタイルの場合について説明します。

wrapperスタイルの条件について

wrapperスタイルは次に示す条件をすべて満たす場合に，wrapperスタイルとして扱われます。条件を満たさない場合は，non-wrapperスタイルとして扱われます。

WSDLのオペレーションのsoap:body要素から参照するinputメッセージは，パートを1個だけ含んでいる。

パートを2個以上含んでいる場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51019-E）。

WSDLのオペレーションから参照するoutputメッセージ（存在する場合）は，パートを1個だけ含んでいる。

パートを2個以上含んでいる場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51020-E）。

inputメッセージのパートは，ローカル名がオペレーション名と等しいグローバル要素を参照している。

outputメッセージ（存在する場合）のパートは，グローバル要素を参照している。

inputメッセージとoutputメッセージ（存在する場合）のパートから参照されている要素の型は，xsd:sequenceで定義したxsd:complexTypeである。

wrapper要素は子要素を含むだけであり，xsd:any要素，xsd:anyAttribute属性，xsd:choise要素，substitutionGroup属性，またはattribute要素のようなほかの構成要素を含まない。

wrapper要素はnillableでない。

(1)　マッピング

request-responseオペレーションのWSDLからのマッピングの場合

request-responseオペレーションのWSDL（wsdl:input要素，およびwsdl:output要素を1個と，wsdl:fault要素を0個以上定義する）のメッセージのパートから参照するwrapper子要素と，Javaメソッドのパラメタおよび戻り値がマッピングされます。マッピング例を次の図に示します。

図15‒4　メッセージのパートとパラメタおよび戻り値のマッピング例（request-responseオペレーション）

one-wayオペレーションのWSDLからのマッピングの場合

one-wayオペレーションのWSDL（wsdl:input要素を1個だけ定義）のメッセージのパートから参照するwrapper子要素と，Javaメソッドのパラメタがマッピングされます。マッピング例を次の図に示します。

図15‒5　メッセージのパートとパラメタのマッピング例（one-wayオペレーション）

マッピングするときに，request-responseオペレーションまたはone-wayオペレーションのどちらの場合でも，WSDLのwrapper子要素名の先頭文字は小文字に変換されます。

（変換前）WrapperName　　　（変換後）wrapperName

パートの種類とJavaソースへのマッピングの関係

パートの種類（in，inout，out）と，Javaソースへのマッピングの関係を次の表に示します。

表15‒8　パートの種類とJavaソースへのマッピングの関係（wrapperスタイル）

項番

WSDLパートの種類

Javaへのマッピング

マッピング先

マッピング方法

1

in

パラメタ

javax.xml.ws.Holder<T>クラスでマッピングされません。java.lang.Stringなどのクラスでマッピングされます。

2

inout

パラメタ

javax.xml.ws.Holder<T>クラスでマッピングされます。※

3

out

パラメタ

javax.xml.ws.Holder<T>クラスでマッピングされます。※

4

戻り値

javax.xml.ws.Holder<T>クラスでマッピングされません。java.lang.Stringなどのクラスでマッピングされます。

注※

wrapper子要素の型がxsd:intなど，JAXB仕様でJavaのプリミティブ型にマッピングされる型の場合，プリミティブに対応するため，送信時のHolderのインスタンスにnullでない値を設定してください。

(2)　wrapper子要素名の条件

wrapper子要素名には，次の表に示すすべての条件を満たす文字列を記述できます。ただし，バインディング宣言でカスタマイズする場合は，XML Schema仕様のxsd:NCName型として使用できる文字列を記述できます。

表15‒9　wrapper子要素名に記述できる文字列の条件（wrapperスタイル）

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z），およびアンダースコア（_）だけを使用した文字列

鈴木_wrapper

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列※

abstract

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51018-E）。

3

先頭が数字以外の文字列

1User_wrapper

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます。

注※

「Abstract」のように，Java予約語の先頭文字を大文字にした文字列も記述できません（マッピングによって先頭文字が小文字に変換されるため）。

(3)　複数のwrapper子要素が同一のwrapper子要素となる条件

inputメッセージまたはoutputメッセージに出現するwrapper子要素をWSDL内に複数記述した場合，wrapper子要素のローカル名とXML Schemaの型が同じか異なるかによって，wrapper子要素の扱いは次の表のとおり異なります。

表15‒10　wrapper子要素のローカル名とXML Schemaの型によって異なるwrapper子要素の扱い

項番

wrapper子要素のローカル名

wrapper子要素のXML Schema型

wrapper子要素の扱い

1

ローカル名が同じ場合

XML Schema型が同じ場合

同じwrapper子要素として扱われます。それぞれのwrapper子要素が，xsd:element要素のref属性で間接的に同じグローバル要素を参照している場合も，同じwrapper子要素として扱われます。

2

XML Schema型が異なる場合

別のwrapper子要素として扱われます。

3

ローカル名が異なる場合

XML Schema型が同じ場合

別のwrapper子要素として扱われます。

4

XML Schema型が異なる場合

(4)　複数のwrapper 子要素を記述した場合の注意事項

複数の同じwrapper子要素と，異なるwrapper子要素を複合型の子要素として同時にWSDLファイルに定義している場合，そのWSDLファイルを指定してcjwsimportコマンドに実行したときに，SEIがnon-wrapperスタイルでマッピングされます。

SEIがnon-wrapperスタイルでマッピングされるWSDLファイルの例を次に示します。

<wsdl:definitions name="TestJaxWsService"
                  xmlns:soap=http://schemas.xmlsoap.org/wsdl/soap/
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:tns="http://example.com/example"
                  targetNamespace="http://example.com/example">

   <xsd:element name="getUserData" type="tns:getUserData"/>
    ...
   <xsd:complexType name="getUserData">
     <xsd:sequence>
       <xsd:element name="in0"  type="xsd:string"/>
       <xsd:element name="in0"  type="xsd:string"/>
       <xsd:element name="hoge" type="xsd:string"/>
     </xsd:sequence>
   </xsd:complexType>
   ...
  </xsd:schema>
 </wsdl:types>
...
 <wsdl:message name="getUserDataRequest">
  <wsdl:part name="inputParameters" element="tns:getUserData"/>
 </wsdl:message>
 ...
</wsdl:definitions>

(5)　パラメタへのマッピングの注意事項

wrapper子要素をJavaへマッピングするときに，メソッドのパラメタの型は異なっていてもパラメタ名が同じになると，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます。

inおよびinoutのwrapper子要素からマッピングされたパラメタは，wrapper要素内の対応するwrapper子要素の出現順序でマッピングされます。outのwrapper子要素からマッピングされたパラメタは，wrapper要素内の対応するwrapper子要素の出現順序でマッピングされます。

in，inout，outのwrapper子要素が混在している場合，inとinoutのwrapper子要素が，wrapper要素内の対応するwrapper子要素の出現順序でマッピングされます。そのあとにoutのwrapper子要素が，wrapper要素内の対応するwrapper子要素の出現順序でマッピングされます。

Javaプリミティブ型，Java配列型，ユーザ定義型であるout（戻り値にマッピングされるものは除く），およびinoutのパラメタは，JavaソースではHolder型（javax.xml.ws.Holder<T>）にマッピングされます。その例を次に示します。

（例）

outおよびinoutのパートのデータ型：java.lang.String

Javaへのマッピング後のデータ型：javax.xml.ws.Holder<java.lang.String>

Javaへマッピング後のパラメタの数は，0〜254個で指定してください。255個以上指定した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51016-E）。

(6)　戻り値へのマッピングの注意事項

outのwrapper子要素が1個の場合，またはoutのwrapper子要素のローカル名が"return"の場合，その値がメソッドの戻り値へマッピングされます。ただし，型は異なっていてもローカル名が"return"であるwrapper子要素を複数記述した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます。

15.1.5　メッセージのパートからパラメタおよび戻り値へのマッピング（non-wrapperスタイルの場合）

WSDLのメッセージのパート（wsdl:message要素のwsdl:part子要素）からJavaのメソッドのパラメタおよび戻り値へのマッピングについて説明します。

ここでは，non-wrapperスタイルの場合について説明します。

(1)　マッピング

request-responseオペレーションのWSDLからのマッピングの場合

request-responseオペレーションのWSDL（wsdl:input要素，およびwsdl:output要素を1個と，wsdl:fault要素を0個以上定義）のメッセージのパートと，Javaメソッドのパラメタおよび戻り値のマッピング例を次の図に示します。

図15‒6　メッセージのパートとパラメタおよび戻り値のマッピング例（request-responseオペレーション）

one-wayオペレーションのWSDLからのマッピングの場合

one-wayオペレーションのWSDL（wsdl:input要素を1個だけ定義）のメッセージのパートと，Javaメソッドのパラメタのマッピング例を次の図に示します。なお，マッピングしたJavaメソッドには，javax.jws.Onewayアノテーションを付与します。

図15‒7　メッセージのパートとパラメタのマッピング例（one-wayオペレーション）

マッピングするときに，request-responseオペレーションまたはone-wayオペレーションのどちらの場合でも，メッセージのパート名（wsdl:part要素のname属性）の先頭文字は小文字に変換されます。

（変換前）PartName　　　（変換後）partName

パートの種類とJavaソースへのマッピングの関係

パートの種類（in／inout／out）と，Javaソースへのマッピングの関係を次の表に示します。

表15‒11　パートの種類とJavaソースへのマッピングの関係（non-wrapperスタイル）

項番

WSDLパートの種類

Javaへのマッピング

マッピング先

マッピング方法

1

in

パラメタ

javax.xml.ws.Holder<T>クラスでマッピングされません。java.lang.Stringなどのクラスでマッピングされます。

2

inout

パラメタ

javax.xml.ws.Holder<T>クラスでマッピングされます。

3

out

パラメタ

javax.xml.ws.Holder<T>クラスでマッピングされます。

4

戻り値

javax.xml.ws.Holder<T>クラスでマッピングされません。java.lang.Stringなどのクラスでマッピングされます。

(2)　パート名の条件

パート名には，次の表に示すすべての条件を満たす文字列を記述できます。ただし，バインディング宣言でカスタマイズする場合は，XML Schema仕様のxsd:NCName型として使用できる文字列を記述できます。

表15‒12　パート名に記述できる文字列の条件（non-wrapperスタイル）

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z），およびアンダースコア（_）だけを使用した文字列

鈴木_part

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列※

abstract

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51017-E）。

3

先頭が数字以外の文字列

1User_part

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

注※

「Abstract」のように，Java予約語の先頭文字を大文字にした文字列も記述できません（マッピングによって先頭文字が小文字に変換されるため）。

(3)　複数のパートから同じグローバル要素を参照している場合の扱い

WSDL内でinputメッセージまたはoutputメッセージに出現するパートを複数記述した場合，パート名が同じで，かつ参照先のグローバル要素が同じときにだけ，同じパートとして扱われます。

パート名，参照先のグローバル要素のどちらかが異なる場合は，別のパートとして扱われます。

(4)　パラメタへのマッピングの注意事項

inおよびinoutのパートは，inputメッセージ内の対応するパートの出現順序でマッピングされます。outのパートは，outputメッセージ内の対応するパートの出現順序でマッピングされます。

in，inout，outのパートが混在している場合，inとinoutのパートはinputメッセージ内の対応するパートの出現順序でマッピングされ，そのあとに，outのパートがoutputメッセージ内の対応するパートの出現順序でマッピングされます。

Javaプリミティブ型やJava配列型，ユーザ定義型であるout（戻り値にマッピングされるものは除く）およびinoutのパートは，JavaソースではHolder型（javax.xml.ws.Holder<T>）にマッピングされます。その例を次に示します。

（例）

outおよびinoutのパートのデータ型：java.lang.String

Javaへマッピング後のデータ型：javax.xml.ws.Holder<java.lang.String>

(5)　戻り値へのマッピングの注意事項

outputメッセージでoutのパートが1個だけの場合，メソッドの戻り値へマッピングされます。outのパートが2個以上の場合，戻り値にマッピングされません。

15.1.6　スキーマ型からJava型へのマッピング

WSDLのスキーマ（wsdl:types要素のxsd:schema子要素）で定義した型からJava型へのマッピングについて説明します。

(1)　マッピング

WSDLのスキーマの型とJava型は，JAXB 2.2仕様に従ってマッピングされます。

スキーマの型とJava型のマッピングでは，クラスベースのマッピングが行われます。クラスベースのマッピングの動作を次に示します。

ユーザ定義型に対応するJavaBeansクラスが生成されます。

ユーザ定義要素に対応するクラスは生成されません。

ObjectFactoryクラスが出力されます。また，ユーザ定義要素に対するcreateメソッドでは，対応するJAXBElement<型に対するJavaBeansクラス>が返されます。

マッピング例を次の図に示します。

図15‒8　スキーマ型とJava型のマッピング例

参考

クラスベースのマッピングとは

JAXBのglobalBindings要素のgenerateValueClass属性がtrueで，かつgenerateElementClass属性がfalseの状態（指定なしのデフォルトの状態）と同等のマッピングを指します。

15.1.7　フォルトから例外クラスへのマッピング

WSDLのフォルト（wsdl:fault要素から参照されるwsdl:message要素のname属性）から例外クラスへのマッピングについて説明します。

(1)　マッピング

cjwsimportコマンドを実行すると，WSDLのフォルトは，JAX-WS 2.2仕様に従ってJava型にマッピングされます。マッピング例を次の図に示します。

図15‒9　フォルトと例外クラスのマッピング例

フォルトbeanへのマッピング

JAX-WS 2.2仕様に従ったフォルトbeanが生成されます。フォルトのパートから参照されるグローバル要素宣言が，フォルトbeanにマッピングされます。

生成されるラッパ例外クラス

JAX-WS 2.2仕様に従ったラッパ例外クラスが生成されます。生成されたラッパ例外クラスは，java.lang.Exceptionクラスを継承し，javax.xml.ws.WebFaultアノテーションを持ちます。また，生成されたラッパ例外クラスは，次のメソッドを持ちます。

FaultMessageName(String message, FaultBean faultInfo)※のコンストラクタ

引数として，メッセージ文字列とフォルトbeanクラスを持ちます。また，このコンストラクタ中で親クラスjavax.xml.ws.WebFaultのコンストラクタが呼び出されます。

FaultMessageName(String message, FaultBean faultInfo, Throwable cause)※のコンストラクタ

引数として，メッセージ文字列とフォルトbeanクラス，およびプロトコル固有の例外情報を持ちます。また，このコンストラクタ中で親クラスjavax.xml.ws.WebFaultのコンストラクタが呼び出されます。

getFaultInfo()メソッド

引数はありません。戻り値はフォルトbeanクラスです。

注※

"FaultMessageName"は，フォルトから参照されるメッセージ名（wsdl:message要素のname属性）を表します。また，引数の"FaultBean"は，フォルトbeanクラスの名前を表します。

(2)　フォルト名の条件

フォルト名には，次の表に示すすべての条件を満たす文字列を記述できます。ただし，バインディング宣言でカスタマイズする場合は，XML Schema仕様のxsd:NCName型として使用できる文字列を記述できます。

表15‒13　フォルト名に記述できる文字列の条件

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z），およびアンダースコア（_）だけを使用した文字列

鈴木_fault

動作は保証されません（エラーメッセージは出力されません）。

2

先頭が数字以外の文字列

1User_fault

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

(3)　フォルトから参照されるメッセージのパートの個数

フォルトは，パートが1個だけ記述されているメッセージを参照できます。フォルトから参照されるメッセージのパートの個数と動作を次の表に示します。

表15‒14　フォルトから参照されるメッセージのパートの個数と動作

項番

記述数

動作

1

0個

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51025-E）。

2

1個

正常終了します。

3

2個以上

標準エラー出力とログにエラーメッセージが出力され，処理が続行されます（KDJW51025-E）。

(4)　同じオペレーションのフォルトから同じメッセージを参照している場合の扱い

異なる複数のオペレーションのフォルトから同じメッセージを参照している場合，すべて同じフォルトとして扱われます。したがって，Javaへマッピングするときに，共通のラッパ例外クラスとしてマッピングされます。その例を次の図に示します。

図15‒10　同じオペレーションのフォルトから同じメッセージを参照している場合のマッピング例

フォルトを記述しているオペレーションと，フォルトから参照されるメッセージの関係を次の表に示します。

表15‒15　フォルトを記述しているオペレーションと参照先のメッセージの関係

項番

フォルトを記述しているオペレーション

フォルトから参照されるメッセージ

フォルトの扱い

1

異なる

同じ

同じフォルトとして扱われます。

2

異なる

別のフォルトとして扱われます。

3

同じ

同じ

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51026-E）。

4

異なる

別のフォルトとして扱われます。

15.1.8　バインディング拡張要素からパラメタへのマッピング

WSDLのバインディングのバインディング拡張要素（wsdl:binding要素）からメソッドのパラメタへのマッピングについて説明します。

(1)　マッピング

WSDLのバインディングのバインディング拡張要素とJavaメソッドのパラメタは，JAX-WS 2.2仕様に従ってマッピングされます。マッピング例を次の図に示します。

図15‒11　バインディング拡張要素とパラメタのマッピング例

SOAPバインディング

バインディング拡張要素に，SOAPバインディングを記述できます。

注意事項

soap:header要素を複数記述している場合，それぞれのsoap:header要素に対応するメッセージから参照されるグローバル要素のローカル名は，すべてユニークにしてください。ローカル名が同じ場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51205-E）。

soap:bindingまたはsoap12:binding要素のtransport属性値からjavax.xml.ws.BindingTypeアノテーションへのマッピング

WSDLのwsdl:binding要素の子要素であるsoap:binding要素またはsoap12:binding要素のtransport属性値から，javax.xml.ws.BindingTypeアノテーションへのマッピングを次の表に示します。

表15‒16　transport属性値から，javax.xml.ws.BindingTypeアノテーションへのマッピング

項番

SOAPバージョン

transport属性値

BindingTypeアノテーションの値

1

SOAP 1.1

http://schemas.xmlsoap.org/soap/http

http://schemas.xmlsoap.org/soap/http※1

2

http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true

−※2

3

SOAP 1.2

http://schemas.xmlsoap.org/soap/http※3

http://www.w3.org/2003/05/soap/bindings/HTTP/

4

http://www.w3.org/2003/05/soap/bindings/HTTP/

http://www.w3.org/2003/05/soap/bindings/HTTP/

5

http://www.w3.org/2003/05/soap/bindings/HTTP/?mtom=true

−※2

（凡例）

−：なし。

注※1

デフォルト値と同じ値なので，実際にはjavax.xml.ws.BindingTypeアノテーションが省略されます。

注※2

cjwsimportコマンド実行時にエラーになります（KDJW51147-E）。

注※3

transport属性値については標準仕様であいまいなため，JAX-WSではこのURLを使用できます。

MIMEバインディング

MIMEバインディングはサポートしていません。

15.1.9　サービスおよびポートからサービスクラスへのマッピング

WSDLのサービス（wsdl:service要素のname属性）およびポート（wsdl:port要素のname属性）から，サービスクラスへのマッピングについて説明します。

(1)　マッピング

WSDLのサービスおよびポートと，サービスクラスは，JAX-WS 2.2仕様に従ってマッピングされます。マッピング例を次の図に示します。

図15‒12　サービスおよびポートとサービスクラスのマッピング例

また，WSDLのサービスおよびポートは，スケルトンクラスにもマッピングされます。マッピング例を次の図に示します。

図15‒13　サービスおよびポートとスケルトンクラスのマッピング例

生成されるサービスクラス

生成されるサービスクラスは，javax.xml.ws.Serviceクラスを継承し，javax.xml.ws.WebServiceClientアノテーションを持ちます。また，生成されるサービスクラスが持つメソッドを次に示します。

表15‒17　サービスクラスが持つメソッド

項番

戻り値の型

メソッド名／説明

サポート

1

−

ServiceName()※1

○

説明

このコンストラクタ中で親クラスjavax.xml.ws.Service※2 (java.net.URL wsdlDocumentLocation, javax.xml.namespace.QName serviceName)のコンストラクタが呼び出されます。

wsdlDocumentLocationおよびserviceNameは，WSDLからマッピングされた定義を使用します。

カタログ機能が有効な場合は，WSDLからマッピングした定義を，カタログファイルで指定した別のURIにマッピングし，wsdlDocumentLocationとして使用します。カタログ機能については「27.　カタログ機能」を参照してください。

例外

javax.xml.ws.WebServiceException

2

−

ServiceName(javax.xml.ws.WebServiceFeature... features)※1

×

3

−

ServiceName(java.net.URL wsdlLocation)※1

○

説明

このコンストラクタ中で親クラスjavax.xml.ws.Service※2 (java.net.URL wsdlDocumentLocation, javax.xml.namespace.QName serviceName)のコンストラクタが呼び出されます。

serviceNameは，WSDLからマッピングされた定義を使用します。

カタログ機能が有効な場合は，この引数に指定したWSDLロケーションを示すURLを，別のWSDLロケーションを示すURIにマッピングします。カタログ機能については「27.　カタログ機能」を参照してください。

引数

wsdlLocation：

WSDLロケーションを示すURLです。

例外

javax.xml.ws.WebServiceException

4

−

ServiceName(java.net.URL wsdlLocation, javax.xml.ws.WebServiceFeature... features)※1

×

5

−

ServiceName(java.net.URL wsdlLocation, javax.xml.namespace.QName serviceName)※1

○

説明

このコンストラクタ中で親クラスjavax.xml.ws.Service※2 (java.net.URL wsdlDocumentLocation, javax.xml.namespace.QName serviceName)のコンストラクタが呼び出されます。

引数

wsdlLocation：

WSDLロケーションを示すURLです。カタログ機能が有効な場合は，この引数に指定したWSDLロケーションを示すURLを，別のWSDLロケーションを示すURIにマッピングします。カタログ機能については「27.　カタログ機能」を参照してください。

serviceName：

サービスのQNameです。

例外

javax.xml.ws.WebServiceException

6

−

ServiceName(java.net.URL wsdlLocation, javax.xml.namespace.QName serviceName, javax.xml.ws.WebServiceFeature... features)

×

7

SEIを実装するプロキシ

getPortName()※3

○

説明

親クラスjavax.xml.ws.ServiceのgetPort※2 (javax.xml.namespace.QName portName, java.lang.Class<T> serviceEndpointInterface)メソッドが呼び出されます。

portNameおよびserviceEndpointInterfaceは，WSDLからマッピングされた定義を使用します。

このメソッドにはjavax.xml.ws.WebEndpointアノテーションが付与されます。

例外

javax.xml.ws.WebServiceException

8

SEIを実装するプロキシ

getPortName(javax.xml.ws.WebServiceFeature... features)※3

○

説明

親クラスjavax.xml.ws.ServiceのgetPort※2 (javax.xml.namespace.QName portName, java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)メソッドが呼び出されます。

portNameおよびserviceEndpointInterfaceは，WSDLからマッピングされた定義を使用します。

このメソッドにはjavax.xml.ws.WebEndpointアノテーションが付与されます。

引数

features：

可変長のjavax.xml.ws.WebServiceFeature型です。

例外

javax.xml.ws.WebServiceException

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

注※1

"ServiceName"は，サービスクラス名（wsdl:service要素のname属性）を表します。

注※2

親クラスjavax.xml.ws.Serviceについては，「19.2.2(4)　javax.xml.ws.Serviceクラス」を参照してください。

注※3

"PortName"は，ポート名（wsdl:port要素のname属性）の先頭文字を大文字にした名前を表します。

(2)　サービス名およびポート名の条件

サービス名およびポート名には，次の表に示すすべての条件を満たす文字列を記述できます。ただし，バインディング宣言でカスタマイズする場合は，XML Schema仕様のxsd:NCName型として使用できる文字列を記述できます。

表15‒18　サービス名およびポート名に記述できる文字列の条件

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z），およびアンダースコア（_）だけを使用した文字列

鈴木_service

鈴木_port

動作は保証されません（エラーメッセージは出力されません）。

2

先頭が数字以外の文字列

1User_service

1User_port

標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

15.1.10　スケルトンクラスへのマッピング

SEIを実装したスケルトンクラスについて説明します。

(1)　マッピング

cjwsimportコマンドを使用すると，WSDLのサービスとポートからスケルトンクラスにマッピングできます。WSDLのサービスとポートからスケルトンクラスへのマッピング例を次の図に示します。

図15‒14　WSDLのサービスとポートからスケルトンクラスへのマッピング例

スケルトンクラスにマッピングする場合は，WSDLのポートタイプ名（wsdl:portType要素のname属性）に"Impl"サフィックスを付与します。

15.1.11　WSDLからJavaへのマッピングに関する注意事項

WSDLからJavaへのマッピングでの注意事項について説明します。

(1)　Javaメソッドのオーバーロード

1個のポートタイプに複数のオペレーションを記述する場合，オペレーション名はすべてユニークでなければなりません。したがって，WSDLからJavaへのマッピングでは，Javaメソッドのオーバーロードはできません。オペレーション名が重複している場合はカスタマイズして，それぞれユニークな名称にしてください。

(2)　名前衝突時のマッピング

cjwsimportコマンドを実行するときに，SEI名，クラス名，メソッド名，およびパラメタ名で名前衝突が発生することがあります。ここでは，名前衝突時のマッピングについて説明します。

(a)　SEI名およびクラス名の衝突時のマッピング

WSDLからJavaソースへのマッピングで，SEI名およびクラス名（非例外Javaクラス名，例外クラス名，サービスクラス名，スケルトンクラス名）で名前が衝突した場合，優先順位に従って名前衝突が解決されます。

名前衝突時の優先順位と解決方法を次の表に示します。項番は優先順位を表します（項番1がいちばん高い）。

表15‒19　名前衝突の優先順位と解決方法

項番

種別

名前衝突時の解決方法

1

SEI名

優先順位がいちばん高いため，名前は変更されません。

2

非例外Javaクラス名

クラス名に"_Type"サフィックスが付加されます。

3

例外クラス名

クラス名に"_Exception"サフィックスが付加されます。

4

サービスクラス名

クラス名に"_Service"サフィックスが付加されます。

5

スケルトンクラス名

クラス名に"_Impl"サフィックスが付加されます。

SEI名と非例外Javaクラス名が衝突した場合の名前解決の例を示します。

図15‒15　SEI名と非例外Javaクラス名の衝突時の名前解決例

名前解決によってサフィックスが付加されたクラス名と，同名のクラス名が定義されていた場合は，再度，名前衝突が発生します。この場合，定義済みのクラス名からアンダースコアを削除することで解決します。

サフィックスが付加されたあとに，名前衝突する場合の名前解決例を示します。

図15‒16　サフィックス付加後に名前衝突する場合の名前解決例

さらに，アンダースコアの削除によって変更されたクラス名と，同名のクラス名が定義されていた場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51030-E※）。

注※

非例外Javaクラスの場合は，異なるメッセージが出力されます。

(b)　メソッド名およびパラメタ名の衝突時のマッピング

WSDLからJavaソースへのマッピングで，メソッド同士およびメソッドのパラメタ同士で名前が衝突した場合は，名前衝突は解決されないでエラーになります。

(3)　JAXBアノテーションのサポートについて

cjwsimportコマンドは，JAX-WS 2.2仕様のComformance 2.17に対応しています。cjwsimportコマンド実行時に，必要に応じて次に示すJAXBアノテーションがSEIに付与されます。

javax.xml.bind.annotation.XmlAttachmentRef

javax.xml.bind.annotation.XmlList

javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter

javax.xml.bind.annotation.XmlMimeType

なお，Application ServerのJAX-WS機能ではMIMEバインディングはサポートしていないため，javax.xml.bind.annotation.XmlMimeTypeアノテーションは付与されません。MIMEバインディングを指定した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51188-E）。

15.2　WSDLからJavaへのマッピングのカスタマイズ

バインディング宣言を使用することで，WSDLからJavaソースへのマッピングをカスタマイズできます。バインディング宣言によるカスタマイズ方法には，次の方法があります。

埋め込みによるバインディング宣言でのカスタマイズ

外部バインディングファイルによるカスタマイズ

それぞれの方法について，カスタマイズ方法と注意事項について説明します。

15.2.1　埋め込みによるバインディング宣言でのカスタマイズ

埋め込みによるバインディング宣言でのカスタマイズは，jaxws:bindings要素を使用して，直接バインディング宣言をWSDL文書に記述し，カスタマイズします。

埋め込みによるバインディング宣言を使用して，パッケージ名をカスタマイズする例を次の図に示します。

図15‒17　パッケージ名のカスタマイズ例（埋め込みによるバインディング宣言）

埋め込みによるバインディング宣言でカスタマイズする場合の留意点について説明します。

(1)　jaxws:bindings要素の指定

jaxws:bindings要素は，埋め込みによるバインディング宣言のコンテナとして使用します。

ただし，jaxws:bindings要素はjaxws:bindings要素の子要素に記述できません。jaxws:bindings要素の子要素に記述した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51034-E）。

jaxws:bindings要素の属性と，属性の指定有無による動作を次の表に示します。

表15‒20　jaxws:bindings要素の属性と指定有無による動作の対応（埋め込みによるバインディング宣言）

項番

要素

属性の指定

動作

1

wsdlLocation

あり

属性は指定できません。指定しても無視されます。

2

なし

正常終了します。

3

node

あり

属性は指定できません。指定しても無視されます。

4

なし

正常終了します。

5

version

あり

属性には"2.0"だけ指定できます。"2.0"以外を指定した場合は値が無視され，"2.0"が指定されていると見なされます。

6

なし

正常終了します。

(2)　使用できるバインディング宣言

埋め込みによるバインディング宣言を使用する場合に，Application ServerのJAX-WS機能で使用できるバインディング宣言の一覧を次の表に示します。各バインディング宣言については，JAX-WS 2.2仕様を参照してください。

表15‒21　使用できるバインディング宣言（埋め込みによるバインディング宣言）

要素名

属性名

説明

wsdl:definitions/jaxws:bindings要素

version

version属性には，WSDLのカスタマイズのバージョンを記述します。

jaxws:bindings要素の子要素

−

jaxws:bindings要素の子要素です。

┣

┃

┃

┃

┃

┃

┃

jaxws:package

┃

┃

┃

name

name属性には，wsdl:definitions要素のtargetNamespace属性に対応するJavaパッケージ名を記述します。

┗

jaxws:javadoc

−

Javaパッケージに付加するJavadoc文字列です。

┣

┃

┃

jaxws:enableWrapperStyle

−

WSDLのすべてのオペレーションに対するwrapperスタイルの有効／無効を表します。

┗

jaxws:enableAsyncMapping

−

WSDLのすべてのオペレーションに対する非同期マッピングの有効／無効を表します。

wsdl:definitions/wsdl:portType

/jaxws:bindings要素の子要素

−

wsdl:definitions/wsdl:portType要素に含まれるjaxws:bindings要素の子要素です。

┣

┃

┃

┃

┃

┃

jaxws:class

┃

┃

name

name属性には，wsdl:portType要素に対応するSEIの完全修飾名を記述します。

┗

jaxws:javadoc

−

SEIに付加するJavadoc文字列を記述します。

┣

┃

┃

jaxws:enableWrapperStyle

−

wsdl:portType要素に対するwrapperスタイルの有効／無効を表します。

┗

jaxws:enableAsyncMapping

−

wsdl:portType要素に対する非同期マッピングの有効／無効を表します。

wsdl:definitions/wsdl:portType/wsdl:operation

/jaxws:bindings要素の子要素

−

wsdl:definitions/wsdl:portType/wsdl:operation要素に含まれるjaxws:bindings要素の子要素です。

┣

┃

┃

┃

┃

┃

jaxws:method

┃

┃

name

name属性には，wsdl:operation要素に対応するJavaメソッド名を記述します。

┗

jaxws:javadoc

−

メソッドに付加するJavadoc文字列です。

┣

┃

┃

jaxws:enableWrapperStyle

−

wsdl:operation要素に対するwrapperスタイルの有効／無効を表します。

┣

┃

┃

jaxws:enableAsyncMapping

−

wsdl:operation要素に対する非同期マッピングの有効／無効を表します。

┗

jaxws:parameter

part

part属性には，wsdl:message要素のwsdl:part子要素を識別するXPath表現を記述します。

childElementName

childElementName属性には，wsdl:part要素によって参照されるグローバル型定義またはグローバル要素宣言の子要素名を記述します。

name

name属性には，part属性およびchildElementName属性によって識別される要素のパラメタ名を記述します。

wsdl:definitions/wsdl:portType/wsdl:operation/wsdl:fault

/jaxws:bindings要素の子要素

−

wsdl:definitions/wsdl:portType/wsdl:operation/wsdl:fault要素に含まれるjaxws:bindings要素の子要素です。

┗

jaxws:class

┃

name

name属性には，wsdl:fault要素に対応する例外クラスの完全修飾名を記述します。

┗

jaxws:javadoc

−

例外クラスに付加するJavadoc文字列です。

wsdl:definitions/wsdl:binding/wsdl:operation要素/jaxws:bindings要素の子要素

−

wsdl:definitions/wsdl:binding/wsdl:operation要素に含まれるjaxws:bindings要素の子要素です。

┗

jaxws:parameter

part

part属性には，wsdl:message要素のwsdl:part子要素を識別するXPath表現を記述します。

childElementName

childElementName属性には，wsdl:part要素によって参照されるグローバル型定義またはグローバル要素宣言の子要素名を記述します。

name

name属性には，part属性およびchildElementName属性によって識別される要素のパラメタ名を記述します。

wsdl:definitions/wsdl:service

/jaxws:bindings要素の子要素

−

wsdl:definitions/wsdl:service/要素に含まれるjaxws:bindings要素の子要素です。

┗

jaxws:class

┃

┃

name

name属性には，wsdl:service要素に対応するサービスクラスの完全修飾名を記述します。

┗

jaxws:javadoc

−

サービスクラス名に付加するJavadoc文字列です。

wsdl:definitions/wsdl:service/wsdl:port

/jaxws:bindings要素の子要素

−

wsdl:definitions/wsdl:service/wsdl:port要素に含まれるjaxws:bindings要素の子要素です。

┗

jaxws:method

┃

┃

name

name属性には，wsdl:port要素に対応するgetterメソッド名を記述します。

┣

┃

jaxws:javadoc

−

getterメソッドに付加するJavadoc文字列です。

┗

jaxws:provider

−

"true"を指定した場合，SEIは生成されません。生成されたサービスインタフェースでポートのgetterメソッドが省略されます。

jaxws:provider要素については，「15.2.7　jaxws:provider要素を記述した場合の動作」を参照してください。

（凡例）

−：バインディング宣言に使用できる属性がないことを示します。

この表に示すように，WSDLでjaxws:bindings要素およびその子要素を記述できる位置は，JAX-WS 2.2仕様で規定されています。規定されていない位置にそれらの要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

各jaxws:bindings要素の子要素として記述できない要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51040-E）。

また，jaxws:bindings要素の属性およびその子要素に記述できない属性を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

(3)　要素および属性の重複

jaxws:bindings要素およびその子要素内で属性が重複して記述されている場合，標準エラー出力とログにXML Processorのエラーメッセージが出力され，処理が終了されます。

埋め込みによるバインディング宣言を使用して，同じカスタマイズ対象へのカスタマイズを重複して指定できません。また，jaxws:bindings要素の子要素も重複して指定できません。指定した場合の動作は保証されません。

(4)　jaxws:enableWrapperStyle要素の優先順位

jaxws:enableWrapperStyle要素は，WSDLの次の個所に記述できます。複数の個所に同時に記述した場合の優先順位を示します。

wsdl:portType/wsdl:operation/jaxws:bindings/jaxws:enableWrapperStyle

wsdl:portType/jaxws:bindings/jaxws:enableWrapperStyle

wsdl:definitions/jaxws:bindings/jaxws:enableWrapperStyle

番号は優先順位を表します。項番1がいちばん高く，優先順位の高い要素値が有効になります。

15.2.2　外部バインディングファイルによるカスタマイズ

外部バインディングファイルによるカスタマイズは，WSDLとは別にバインディング宣言をまとめて記述したファイルを用意し，そのファイルをWSDL文書と同時に読み込み，カスタマイズする方法です。外部バインディングファイルは，複数読み込むことができます。

外部バインディングファイルを使用して，パッケージ名をカスタマイズする例を次の図に示します。

図15‒18　パッケージ名のカスタマイズ例（外部バインディングファイル）

外部バインディングファイルでカスタマイズする場合の留意点について説明します。

(1)　jaxws:bindings要素の指定

外部バインディングファイルの場合も埋め込みによるバインディング宣言と同様に，jaxws:bindings要素をコンテナとして使用します。

ただし，埋め込みによるバインディング宣言とは異なり，jaxws:bindings要素をjaxws:bindings要素の子要素として記述できます。

jaxws:bindings要素の属性と，属性の指定有無による動作を次の表に示します。

表15‒22　jaxws:bindings要素の属性と指定有無による動作の対応（外部バインディングファイル）

項番

記述位置

要素

属性の指定

動作

1

ルートのjaxws:bindings※1

wsdlLocation

あり

属性は必ず指定してください。指定したロケーションのWSDLをカスタマイズ対象のWSDLファイルとします。指定方法については，「15.2.2(1)(a)　wsdlLocation属性の記述形式」を参照してください。

2

なし

属性を指定していない場合，外部バインディングファイルは無視されます（カスタマイズされないで正常終了します）。

3

node

あり

XPath 1.0形式で属性を指定できます。指定した要素をカスタマイズ対象とします。指定方法については，「15.2.2(1)(b)　node属性の記述形式」を参照してください。

4

なし

カスタマイズ対象の要素をWSDLのルート（wsdl:definitions要素）とします。

5

version

あり

"2.0"を指定できます。指定方法については，「15.2.2(1)(c)　version属性の記述形式」を参照してください。

6

なし

"2.0"が指定されていると見なされます。

7

非ルートのjaxws:bindings※2

wsdlLocation

あり

属性は指定できません。指定しても無視されます。

8

なし

正常終了します。

9

node

あり

属性は必ず指定してください。指定した要素をカスタマイズ対象とします。指定方法については，「15.2.2(1)(b)　node属性の記述形式」を参照してください。

10

なし

カスタマイズ対象がないため，カスタマイズされないで正常終了します。

11

version

あり

属性は指定できません。指定しても無視されます。

12

なし

正常終了します。

注※1

「ルートのjaxws:bindings」とは，外部バインディングファイルの最上位に記述されたjaxws:bindings要素を表します。

注※2

「非ルートのjaxws:bindings」とは，ルートのjaxws:bindingsの子要素以下に記述されたjaxws:bindings要素を表します。

(a)　wsdlLocation属性の記述形式

jaxws:bindings要素のwsdlLocation属性に指定する値は，URLで指定します。URLによって指定するファイルは，リモートファイルでもローカルファイルでも，どちらでもかまいません。ローカルファイルの場合は，相対パスで指定することもできます。

誤った形式で記述した場合，またはファイルがない場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51043-E）。

URLは，RFC 2396仕様の規則に従った文字列を使用してください。RFC 2396仕様の規則に従っていない文字列を使用する場合は，RFC 2396仕様の規則に従ってUTF-8でパーセントエンコーディングする必要があります。ただし，"&"はパーセントエンコーディングをしても使用できません。RFC 2396 仕様の規則に従わないで，エンコードもしていない文字や文字列を指定した場合の動作は保証されません。また，wsdlLocation属性に，WSDLファイル以外のファイルを指定した場合の動作は保証されません。

wsdlLocation属性の正しい記述例を示します。

<jaxws:bindings xmlns:jaxws=http://java.sun.com/xml/ns/jaxws
  wsdlLocation="file:///D:/tmp/example.wsdl" version="2.0">
 ...
</jaxws:bindings>

(b)　node属性の記述形式

jaxws:bindings要素のnode属性に指定する値は，XPath 1.0形式で指定します。

誤った形式で記述した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51038-E）。

node属性の記述例を次に示します。この例では，wsdl:definitions/wsdl:portType要素のname属性が，AddNumbersImplの要素に対するバインディング宣言であることを示しています。

<jaxws:bindings node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']">
 ...
</jaxws:bindings>

非ルートのjaxws:bindings要素のnode属性では，ルートのjaxws:bindings要素のnode属性で指定しているカスタマイズ対象要素からの相対パス（XPath 1.0形式）を指定できます。この場合の記述例を示します。

<jaxws:bindings node="wsdl:definitions/wsdl:portType[@name='UserInfoPortType']"
 ...
  <jaxws:bindings node="../wsdl:service[@name='UserInfoService']">
    ...
  </jaxws:bindings>
</jaxws:bindings>

(c)　version属性の記述形式

jaxws:bindings要素のversion属性の値は，"2.0"を指定します。

"2.0"以外の値を記述した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51039-E）。

version属性の正しい記述例を示します。

<jaxws:bindings xmlns:jaxws=http://java.sun.com/xml/ns/jaxws
  wsdlLocation="file:///D:/tmp/example.wsdl" version="2.0">
  ...
</jaxws:bindings>

(2)　使用できるバインディング宣言

外部バインディングファイルを使用する場合に，Application ServerのJAX-WS機能で使用できるバインディング宣言の一覧を次の表に示します。各バインディング宣言については，JAX-WS 2.2仕様を参照してください。

表15‒23　使用できるバインディング宣言（外部バインディングファイル）

要素名

属性名

説明

jaxws:bindings要素

wsdlLocation

wsdlLocation属性には，カスタマイズ対象のWSDLファイルのファイルパス（URL）を記述します。

node

node属性には，WSDL内のカスタマイズ対象の要素を記述します。

version

version属性には，WSDLのカスタマイズのバージョンを記述します。

jaxws:bindings要素の子要素

−

jaxws:bindings要素の子要素です。

┣

┃

┃

┃

┃

┃

jaxws:package

┃

┃

name

name属性には，wsdl:definitions要素のtargetNamespace属性に対応するJavaパッケージ名を記述します。

┗

jaxws:javadoc

−

Javaパッケージに付加するJavadoc文字列です。

┣

┃

jaxws:enableWrapperStyle

−

各要素に対するwrapperスタイルの有効／無効を表します。

┣

┃

jaxws:enableAsyncMapping

−

各要素に対する非同期マッピングの有効／無効を表します。

┣

┃

┃

┃

jaxws:class

┃

name

name属性には，各要素に対応するクラス名を記述します。

┗

jaxws:javadoc

−

クラスに付加するJavadoc文字列です。

┣

┃

┃

┃

jaxws:method

┃

name

name属性には，各要素に対応するJavaメソッド名を記述します。

┗

jaxws:javadoc

−

メソッドに付加するJavadoc文字列です。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

jaxws:parameter

part

part属性には，wsdl:message要素のwsdl:part子要素を識別するXPath表現を記述します。

childElementName

childElementName属性には，wsdl:part要素によって参照するグローバル型定義，またはグローバル要素宣言の子要素名を記述します。

name

name属性には，part属性およびchildElementName属性によって識別される要素のパラメタ名を記述します。

┗

jaxws:provider

−

"true"を指定した場合，SEIは生成されません。生成されたサービスインタフェースでポートのgetterメソッドが省略されます。

jaxws:provider要素については，「15.2.7　jaxws:provider要素を記述した場合の動作」を参照してください。

（凡例）

−：バインディング宣言に使用できる属性がないことを示します。

この表に示すように，WSDLでjaxws:bindings要素およびその子要素を記述できる位置は，JAX-WS 2.2仕様で規定されています。規定されていない位置にそれらの要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

各jaxws:bindings要素の子要素として記述できない要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51040-E）。

また，jaxws:bindings要素の属性およびその子要素に記述できない属性を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。

なお，JAXB仕様のバインディング宣言は記述できません。記述した場合の動作は保証されません。

(3)　要素および属性の重複

jaxws:bindings要素およびその子要素内で属性が重複して記述されている場合，標準エラー出力とログにXML Processorのエラーメッセージが出力され，処理が終了されます。

外部バインディングファイルを使用して，同じカスタマイズ対象へのカスタマイズを重複して指定することはできません。指定した場合の動作は保証されません。

(4)　wsdl:import要素で読み込むWSDLに対するカスタマイズ

wsdl:import要素でインポートするWSDLに対して外部バインディングファイルでカスタマイズする場合，jaxws:bindings要素のwsdlLocation属性でwsdl:import要素でインポートするWSDLを指定してください。

wsdl:import要素でインポートするWSDLをカスタマイズするときに，誤ってwsdl:import元のWSDLを指定すると，jaxws:bindings要素のnode属性で示したカスタマイズ対象が見つかりません。このときに，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51187-E）。

15.2.3　埋め込みによるバインディング宣言と外部バインディングファイルの同時指定

埋め込みによるバインディング宣言と外部バインディングファイルは，カスタマイズ対象が異なる場合は，それぞれのカスタマイズ内容が有効になります。

埋め込みによるバインディング宣言と外部バインディングファイルのカスタマイズ対象が同じ場合，埋め込みによるバインディング宣言は無効となります。

15.2.4　jaxws:bindings要素に指定できる値

jaxws:bindings要素に指定できる要素および属性の一覧を次の表に示します。

表15‒24　jaxws:bindings要素の属性の指定可否

要素名

属性名

指定可否

wsdl:definitions/jaxws:bindings要素の子要素

┣

┃

jaxws:package

name

○

┗

jaxws:javadoc

−

○

┣

jaxws:enableWrapperStyle

−

○

┣

jaxws:enableAsyncMapping

−

○

┗

jaxws:enableMIMEContent

−

×

wsdl:portType/jaxws:bindings要素の子要素

┣

┃

┃

jaxws:class

name

○

┗

jaxws:javadoc

−

○

┣

jaxws:enableWrapperStyle

−

○

┗

jaxws:enableAsyncMapping

−

○

wsdl:portType/wsdl:operation/jaxws:bindings要素の子要素

┣

┃

┃

┃

jaxws:method

name

○

┗

jaxws:javadoc

−

○

┣

jaxws:enableWrapperStyle

−

○

┣

jaxws:enableAsyncMapping

−

○

┗

jaxws:parameter

part

○

childElementName

○

name

○

wsdl:portType/wsdl:operation/wsdl:fault/jaxws:bindings要素の子要素

┗

jaxws:class

name※

○

┗

jaxws:javadoc

−

○

wsdl:binding/jaxws:bindings要素の子要素

┗

jaxws:enableMIMEContent

−

×

wsdl:binding/wsdl:operation/jaxws:bindings要素の子要素

┣

jaxws:enableMIMEContent

−

×

┗

jaxws:parameter

part

○

childElementName

○

name

○

wsdl:service/jaxws:bindings要素の子要素

┗

jaxws:class

name

○

┗

jaxws:javadoc

−

○

wsdl:service/wsdl:port/jaxws:bindings要素の子要素

┣

┃

jaxws:method

name

○

┗

jaxws:javadoc

−

○

┗

jaxws:provider

−

○

（凡例）

−：バインディング宣言に使用できる属性がないことを示します。

○：要素および属性が指定できることを示します。

×：要素および属性が指定できないことを示します（非サポート）。

注※

フォルト名をカスタマイズする場合，カスタマイズ後のフォルト名がほかのフォルト名と重複しないようにしてください。重複した場合，動作は保証されません。

指定できないバインディング要素を指定した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51188-E）。

要素および属性に指定できる値について説明します。

(1)　name属性に指定できる値

name属性には，次に示す値だけ指定できます。これ以外の値を指定した場合の動作は保証されません。

Java識別子として使用できる値

半角英数字（0〜9，A〜Z，a〜z）

アンダースコア（_），ドルマーク（$）

ピリオド（.）※

注※

wsdl:portType要素，wsdl:fault要素，またはwsdl:service要素をカスタマイズする場合にだけ使用できます。

クラス名やメソッド名をname属性でカスタマイズする場合，カスタマイズした名称がほかの名称と重複するとエラーとなるため，重複しないように注意してください。

wsdl:portType要素に対応するSEI名，wsdl:fault要素に対応する例外クラス名，またはwsdl:service要素に対応するサービス名をjaxws:class要素でカスタマイズする場合，パッケージ名を含むクラス名を指定すると，指定したパッケージ名のJavaクラスになります。パッケージ名を含まないクラス名を指定すると，WSDLの名前空間（wsdl:definitions要素のtargetNamespace属性）からマッピングされたパッケージ名を付与したJavaクラスになります。

(2)　jaxws:javadoc要素に指定できる値

jaxws:javadoc要素には，次に示す値だけ指定できます。これ以外の値を指定した場合の動作は保証されません。

半角英数字（0〜9，A〜Z，a〜z）

半角記号（"/*"，"//"，"¥"，"¥n¥r"）※1

半角カタカナ

全角ひらがな，全角カタカナ，全角英数字

第一水準の全角漢字

Java予約語

空白および空文字※2

注※1

半角記号（"*/"）は，Javadocの終端として扱われるため使用できません。

注※2

空白および空文字の行は，ソースコード生成時に削除されます。

(3)　jaxws:enableWrapperStyle要素に指定できる値

jaxws:enableWrapperStyle要素には，boolean値（"true"または"false"）を指定できます。これ以外の値を指定した場合の動作は保証されません。

なお，WSDLをwrapperスタイルで記述し，かつこの要素の値を"true"に指定した場合にだけ，wrapperスタイルが有効になります。

(4)　jaxws:enableAsyncMapping要素に指定できる値

jaxws:enableAsyncMapping要素には，boolean値（"false"）だけ指定できます。これ以外の値を指定した場合の動作は保証されません。

(5)　part属性に指定できる値

part属性には，次に示す値だけ指定できます。これ以外の値を指定した場合の動作は保証されません。

存在するwsdl:message要素のwsdl:part子要素のXPath表現

存在するsoap:headerから参照するwsdl:messageのwsdl:part子要素のXPath表現

wsdl:operation要素内で使用されていないwsdl:message要素のwsdl:part子要素のXPath表現

(6)　childElementName属性に指定できる値

存在する型定義の修飾名のQNameだけ指定できます。存在しない型定義の修飾名のQNameを指定した場合，エラーにならないで正常終了します。このとき，カスタマイズ対象は無視されます。

(7)　jaxws:provider要素に指定できる値

boolean値（"true"または"false"）を指定できます。これ以外の値を指定した場合の動作は保証されません。

(8)　非サポートの要素

Application ServerのJAX-WS機能で非サポートのバインディング要素は指定できません。指定した場合の動作は保証されません。

15.2.5　カスタマイズ対象となった要素の値

埋め込みによるバインディング宣言または外部バインディングファイルによってカスタマイズ対象となったWSDL文書の要素の値は，Javaにマッピングされません。したがって，WSDL 1.1仕様としてカスタマイズ対象に記述できる文字であればどのような文字を記述してもかまいません。

15.2.6　名前衝突時の対応

カスタマイズすることでSEI名，クラス名，メソッド名，およびパラメタ名で名前衝突が発生するおそれがあります。名前衝突の解決方法（優先順位など）は，デフォルトマッピングの場合と同様です。名前衝突の解決方法については，「15.1.11(2)　名前衝突時のマッピング」を参照してください。

ただし，SEI名およびクラス名に関しては，優先順位が低い方をカスタマイズした場合は名前衝突したときに名前解決されますが，優先順位が高い方をカスタマイズした場合は名前衝突したときに名前衝突は解決されません。このとき，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51030-E※）。

注※

非例外Javaクラスの場合は，異なるメッセージが出力されます。

15.2.7　jaxws:provider要素を記述した場合の動作

wsdl:port要素にjaxws:provider要素を記述してcjwsimportコマンドを実行した場合，wsdl:port要素用のSEIは生成されません。警告メッセージが出力され，処理が続行されます（KDJW51206-W）。この場合，javax.xml.ws.Providerインタフェースを使用してプロバイダ実装クラスを生成してください。

また，生成したサービスクラスでwsdl:port要素のgetterメソッドが省略されます。

cjwsimportコマンドに-generateServiceオプションを指定し，wsdl:port要素にjaxws:provider要素を記述した場合，スケルトンクラスは生成されません。警告メッセージが出力され，処理が続行されます（KDJW51207-W）。

15.2.8　SEI名をカスタマイズする場合の注意事項

次の条件でカスタマイズする場合，SEI名には"Provider"以外を指定し，パッケージ名には"http://ws.xml.javax"以外を指定して，SEI名がパッケージ名を含めて"javax.xml.ws.Provider"にならないようにしてください。

パッケージ名：jaxws:package要素

SEI名：jaxws:class要素

"javax.xml.ws.Provider"は，wsdl:port要素にjaxws:provider要素を記述した場合の予約語として利用しており，サービス実装クラスでjavax.xml.ws.Providerインタフェースを利用するときに指定します。

15.2.9　jaxws:parameter要素でinoutパラメタ名をカスタマイズする場合の注意事項

jaxws:parameter要素でinoutパラメタ名をカスタマイズする場合は，inputメッセージとoutputメッセージの両方のパラメタ名をカスタマイズしてください。どちらか片方だけをカスタマイズした場合の動作は保証されません。

15.2.10　SEI名をjaxws:class要素でカスタマイズした場合のスケルトンクラス名

SEI名をjaxws:class要素でカスタマイズした場合，スケルトンクラス名は，カスタマイズしたSEI名に"Impl"サフィックスを付与してマッピングされます。

16　JavaからWSDLへのマッピング

hwsgenコマンドを実行すると，JAX-WS 2.2仕様に従ってJavaソースからWSDLへマッピングされます。

この章では，JavaからWSDLへのデフォルトマッピング，およびマッピングのカスタマイズについて説明します。

16.1　JavaからWSDLへのデフォルトマッピング

JavaソースからWSDLへマッピングする場合の対応関係を次の表に示します。

表16‒1　JavaソースからWSDLへのマッピング一覧

項番

Javaソース

WSDL

参照先

1

パッケージ名

WSDLの名前空間

16.1.1

2

SEI名

ポートタイプ

16.1.3

3

SEIのメソッド名

オペレーション

16.1.4

4

SEIのメソッドのパラメタおよび戻り値

パート

16.1.5，16.1.6

5

SEIのラッパ例外クラス

フォルト

16.1.7

6

SEIおよびWebサービス実装クラス

バインディング

16.1.8

7

Webサービス実装クラス

サービスとポート

16.1.9

16.1.1　パッケージ名から名前空間へのマッピング

Javaのパッケージ名からWSDLの名前空間（wsdl:definitions要素のtargetNamespace属性）へのマッピングについて説明します。

(1)　マッピング

SEIおよびWebサービス実装クラスのパッケージ名と，WSDLの名前空間は，JAX-WS 2.2仕様に従ってマッピングされます。マッピング例を次の図に示します。

図16‒1　Javaのパッケージ名と名前空間のマッピング例

(2)　パッケージ名の条件

Javaのパッケージ名のピリオド（.）で区切られたセグメントには，次の表に示すすべての条件を満たす文字列を記述できます。ただし，javax.jws.WebServiceアノテーションのtargetNamespace要素を使用する場合，Java言語仕様で定められているJava識別子の命名規則に従った文字列を記述できます。

表16‒2　Javaのパッケージ名の各セグメントに記述できる文字列の条件

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z）だけを使用した文字列

package com.鈴木

動作は保証されません（エラーメッセージは出力されません）。

2

Java言語仕様で定められているJava識別子の命名規則に従った文字列

package com.abstract;

javacコマンド実行時にコンパイルエラーとなり，終了します。

(3)　javax.jws.WebServiceアノテーションのtargetNamespace要素の利用

入力となるSEIまたはWebサービス実装クラスがデフォルトパッケージの場合，javax.jws.WebServiceアノテーションのtargetNamespace要素で名前空間名を記述してください。

javax.jws.WebServiceアノテーションのtargetNamespace要素については，「16.2.9　javax.jws.WebServiceアノテーション」を参照してください。

16.1.2　Webサービス実装クラスからSEIへのマッピング

Webサービス実装クラスからSEIへのマッピングに当たり，前提となる条件および留意点について説明します。

(1)　Webサービス実装クラスの条件

Webサービス実装クラスの条件を示します。

SEIのすべてのメソッドを実装する必要があります。

Webサービスのオペレーションとして，Objectクラスのfinalizeメソッドをオーバーライドするようなfinalizeメソッドは定義できません。

publicなデフォルトコンストラクタを定義する必要があります。

javax.jws.WebServiceアノテーションを記述する必要があります。javax.jws.WebServiceアノテーションを記述していない場合は，Webサービス実装クラスではないと判断されます。

javax.jws.WebServiceアノテーションをstaticなインナークラスで定義できます。

Webサービス実装クラスのアクセス修飾子はpublicにしてください。finalやabstractは指定できません。

(2)　javax.jws.WebServiceアノテーションのendpointInterface要素の利用

Webサービス実装クラスからSEIへのマッピングでは，javax.jws.WebServiceアノテーションのendpointInterface要素を利用して，Webサービス実装クラスとSEIを関連づけることができます。

Webサービス実装クラスだけ定義する場合，endpointInterface要素は使用しません。この場合，Webサービス実装クラスが持つ情報から，SEIに定義する抽象的な情報が抽出され，仮想のSEIがあるものと見なされます（暗黙のSEI）。

javax.jws.WebServiceアノテーションのendpointInterface要素については，「16.2.9　javax.jws.WebServiceアノテーション」を参照してください。

16.1.3　SEI名からポートタイプへのマッピング

JavaのSEI名からWSDLのポートタイプ名（wsdl:portType要素のname属性）へのマッピングについて説明します。

(1)　マッピング

JavaのSEI名とWSDLのポートタイプは，JAX-WS 2.2仕様に従ってマッピングされます。

サービス実装クラスのjavax.jws.WebServiceアノテーションでendpointInterface要素を使用していない場合，Webサービス実装クラス名と同じ名称の暗黙のSEIが存在するものと見なされ，WSDLのポートタイプにマッピングされます。マッピング例を次の図に示します。

図16‒2　SEI名とポートタイプのマッピング例

(2)　SEIの条件

Webサービス実装クラスの条件を示します。

javax.jws.WebServiceアノテーションを記述する必要があります。

java.rmi.Remoteインタフェースを継承してもかまいません。

(3)　SEI名の条件

SEI名には，次の表に示すすべての条件を満たす文字列を記述できます。ただし，javax.jws.WebServiceアノテーションのname要素を使用する場合，Java言語仕様で定められているJava識別子の命名規則に従った文字列を記述できます。

表16‒3　SEI名に記述できる文字列の条件

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z），およびアンダースコア（_）だけを使用した文字列

鈴木_sei

動作は保証されません（エラーメッセージは出力されません）。

2

Java言語仕様で定められているJava識別子の命名規則に従った文字列

abstract

javacコマンド実行時にコンパイルエラーとなり，終了します。

16.1.4　SEIのメソッド名からオペレーションへのマッピング

SEIのメソッド名からWSDLのオペレーション（wsdl:operation要素のname属性）へのマッピングについて説明します。

(1)　マッピング

SEIのメソッド名とWSDLのオペレーションは，JAX-WS 2.2仕様に従ってマッピングされます。マッピング例を次の図に示します。

図16‒3　SEIのメソッド名とオペレーションのマッピング例

SEIのメソッドを公開対象とするには，次に示す条件を満たす必要があります。

アクセス修飾子がpublicである

static修飾子またはfinal修飾子が適用されていない

javax.jws.WebMethodアノテーションでアノテートされている場合，javax.jws.WebMethodアノテーションのexclude要素がtrueではない

SEIのメソッド名からオペレーションへのマッピング規則を次に示します。

javax.jws.WebMethodアノテーションの有無に関係なく，SEIのすべての公開対象メソッドがWSDLのオペレーションにマッピングされます。

javax.jws.WebServiceアノテーションのendpointInterface要素を使用していない場合，Webサービス実装クラスの公開対象メソッドを暗黙のSEIが持っているものと見なされ，WSDLのオペレーションにマッピングされます。暗黙のSEIにマッピングされるメソッドについては，「16.2.6　javax.jws.WebMethodアノテーション」を参照してください。

Webサービス実装クラスが別のWebサービス実装クラスを継承している場合，次の条件に合うすべてのメソッドがWSDLのオペレーションにマッピングされます。

（条件）

Webサービス実装クラスおよび親のWebサービス実装クラスが持つjavax.jws.WebMethodアノテーションのexclude要素が，trueではない公開対象メソッド。

Webサービス実装クラスが別のWebサービス実装クラスを継承し，親クラスのメソッドをオーバーライドしている場合，Webサービス実装クラスでオーバーライドした公開対象メソッドがWSDLのオペレーションにマッピングされます。親クラスでオーバーライドされたメソッドはマッピングされません。

SEIに定義できる公開対象メソッドおよびWebサービス実装クラスの公開対象メソッドは，255個まで定義できます。

SEIのメソッド名からマッピングされるwsdl:operation要素のname属性の値は，WSDL内でユニークである必要があります。

(2)　メソッド名の条件

メソッド名には，次の表に示すすべての条件を満たす文字列を記述できます。

表16‒4　メソッド名に記述できる文字列の条件

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z），およびアンダースコア（_）だけを使用した文字列

鈴木_sei

動作は保証されません（エラーメッセージは出力されません）。

2

Java言語仕様で定められているJava識別子の命名規則に従った文字列

abstract

javacコマンド実行時にコンパイルエラーとなり，終了します。

ただし，次に示すアノテーションをすべて使用する場合，Java言語仕様で定められているJava識別子の命名規則に従った文字列を記述できます。

javax.jws.WebMethodアノテーションのoperationName要素

javax.xml.ws.RequestWrapperアノテーションのlocalName要素およびclassName要素（wrapperスタイルの場合）

javax.xml.ws.ResponseWrapperアノテーションのlocalName要素およびclassName要素（wrapperスタイルの場合）

javax.jws.WebParamアノテーションのname要素（non-wrapperスタイルの場合）

javax.jws.WebResultアノテーションのname要素（non-wrapperスタイルの場合）

(3)　オーバーロードによる名前衝突

メソッドのオーバーロードを使用している場合，デフォルトマッピングでは名前衝突が発生するため，名前がユニークになるようにアノテーションでカスタマイズする必要があります。

オーバーロードによる名前衝突が発生する個所と，参照先を次の表に示します。

表16‒5　オーバーロードによる名前衝突の発生個所と参照先

項番

名前衝突の発生個所

アノテーションの参照先

wrapperスタイル

non-wrapperスタイル

1

オペレーション名

16.2.6(2)

2

inputのグローバル要素※

16.2.16(1)，16.2.16(2)

16.2.7(2)，16.2.7(5)

3

outputのグローバル要素※

16.2.17(1)，16.2.17(2)

16.2.8(2)，16.2.8(4)

4

リクエストbeanクラス名

16.2.16(3)

5

レスポンスbeanクラス名

16.2.17(3)

注※

ローカル名または名前空間のどちらかをカスタマイズすれば，名前衝突は発生しません。

16.1.5　パラメタおよび戻り値からメッセージのパートへのマッピング（wrapperスタイルの場合）

SEIのメソッドのパラメタからWSDL（wsdl:part要素のname属性）へのマッピングについて説明します。

ここでは，wrapperスタイルの場合について説明します。

(1)　マッピング

wrapperスタイルの場合，SEIのメソッド名およびSEIのメソッド名と同じ名称のリクエストbeanが生成されます。また，接尾辞"Response"を付加したレスポンスbeanが生成されます。リクエストbeanおよびレスポンスbeanの生成には，hwsgenコマンドで自動生成する方法と，Webサービスの開始時に動的に生成する方法があります。動的に生成する方法の場合は，Webサービスの開始時にエラーが発生しないように，コンパイルしたWebサービス実装クラスに対してhwsgenコマンドを実行することで，事前にエラーチェックができます。詳細については，「10.23.1　hwsgenコマンドによるエラーチェックについて」を参照してください。

メソッドのパラメタとメッセージのパートのマッピング例を次の図に示します。

図16‒4　メソッドのパラメタとメッセージのパートのマッピング例（wrapperスタイル）

メソッドの戻り値とメッセージのパートのマッピング例を次の図に示します。

図16‒5　メソッドの戻り値とメッセージのパートのマッピング例（wrapperスタイル）

メソッドのパラメタおよび戻り値からメッセージのパートへのマッピング規則を次に示します。

パラメタおよび戻り値は，wrapper要素の子要素として空の名前空間（""）でマッピングされます。wrapper要素は，SEIと同じ名前空間でマッピングされます。

inパラメタおよびinoutパラメタは，argN※という名称でリクエストbeanのプロパティとしてマッピングされます。

outパラメタおよびinoutパラメタは，argN※という名称でレスポンスbeanのプロパティとしてマッピングされます。

また，戻り値は，returnという名称で，レスポンスbeanのプロパティとしてマッピングされます。このとき，予約語にならないように，フィールド名の接頭辞にはアンダースコア（_）が付加されます。

マッピングされたリクエストbeanおよびレスポンスbeanのプロパティには，javax.xml.bind.annotation.XmlElementアノテーションがアノテートされます。

アノテートされたjavax.xml.bind.annotation.XmlElementアノテーションには，リクエストbeanのプロパティではname要素にargN※という名称が，namespace要素に空の名前空間("")が設定されます。レスポンスbeanのプロパティではname要素にreturnという名称が，namespace要素に空の名前空間("")が設定されます。

パラメタからWSDLのパートへのマッピングでは，"parameters"という固定値でinputメッセージのパート名にマッピングされます。

戻り値からWSDLのパートへのマッピングでは，"parameters"という固定値でoutputメッセージのパート名にマッピングされます。

注※

argNのNは，パラメタの順番に依存した0以上の整数を表します。

javax.xml.bind.annotation.XmlElementアノテーションについては，「16.2.10　javax.xml.bind.annotation.XmlElementアノテーション」を参照してください。

(2)　パラメタに指定できるJava型

Holder（javax.xml.ws.Holder）型以外のJava型と，Holder型を指定するときの条件および注意事項について説明します。

(a)　Holder型以外のJava型

Holder型以外のJava型は，JAXB 2.2仕様に従ってWSDLのスキーマの型にマッピングされます。Holder型以外のJava型を指定するときの注意事項について説明します。

Javaプリミティブ型は，outおよびinoutパラメタに指定できません。

Javaプリミティブ型は，javax.xml.ws.Holderクラスの型パラメタとしても指定できません。指定した場合，javacコマンドの実行時にエラーとなり終了します。

Java型をoutおよびinoutパラメタに指定する場合，javax.xml.ws.Holderクラスの型パラメタとして指定できます。

(b)　javax.xml.ws.Holder型

javax.xml.ws.Holder型を指定するときの注意事項について説明します。

javax.xml.ws.Holderクラスの型パラメタに，javax.jws.WebParamアノテーションを指定する場合，mode要素でMode.OUTまたはMode.INOUTを指定する必要があります。

次の場合の動作は保証されません。

javax.xml.ws.Holderクラスをメソッドの引数以外に指定した場合

javax.xml.ws.Holderクラスの配列を使用した場合

javax.xml.ws.Holderクラスの型パラメタに型を指定していない場合

javax.xml.ws.Holderクラスの型パラメタに，javax.xml.ws.Holderクラスやそれを継承したクラスを指定した場合

Webサービス開始時にリクエストbeanとレスポンスbeanを動的に生成する際，javax.xml.ws.Holderクラスの型パラメタにbyte型以外の多次元配列とbyte型の3次元以上の配列を指定した場合

(c)　Java型のマッピング

Java型をマッピングするときの注意事項について説明します。

javax.jws.WebParamアノテーションのmode要素でカスタマイズしていない場合，javax.xml.ws.Holderクラスの型パラメタ以外の引数は，inパラメタとしてマッピングされ，javax.xml.ws.Holderクラスの型パラメタは，inoutパラメタとしてマッピングされます。outパラメタとしてマッピングする方法については，「16.2.7(4)　mode要素（javax.jws.WebParam）」を参照してください。

inputメッセージ名は，オペレーション名でマッピングされます。outputメッセージ名は，オペレーション名に接尾辞"Response"を付加した値でマッピングされます。

SEIのメソッドのパラメタは，Javaの仕様に従って254個まで定義できます。255個以上定義した場合は，javacコマンドの実行時にコンパイルエラーとなり終了します。

(3)　Javaメソッドのパラメタの条件

Javaメソッドのパラメタ名は，WSDLにマッピングされないため，Java言語仕様で定めるJava識別子の命名規則に従って記述してください。

(4)　パラメタと戻り値の組み合わせ

inパラメタ，inoutパラメタ，outパラメタ，および戻り値は，自由に組み合わせて記述できます。

(5)　名前衝突時の動作

wrapper beanクラス名とグローバル要素の名前についての規則，および名前衝突したときの動作について説明します。

wrapper beanクラス名

生成されるwrapper beanクラス名は，パッケージ内でユニークな名前である必要があります。ただし，大文字／小文字の違いは無視されます。

すでに存在するクラスと名前が重複していた場合は，上書きされます。ただし，そのクラスがjavacコマンドの引数に含まれていた場合は，javacコマンド実行時にエラーチェックされます。

グローバル要素（ローカル名および名前空間）

グローバル要素（ローカル名および名前空間）は，WSDL内でユニークである必要があります。ユニークでない場合の動作は保証されません。

(6)　java.util.Mapクラスの使用

SEIの引数または戻り値にjava.util.Mapクラスを使用する場合，SEIのjava.util.Map型の引数または戻り値に対して，次の作業をする必要があります。

value typeを作成します。

JAXB 2.2仕様に従い，java.util.Map（bound type）に対応するvalue type（マーシャル／アンマーシャルできるJavaBeanクラス）を作成します。

アダプタを作成します。

javax.xml.bind.annotation.adapters.XmlAdapterを継承するjava.util.Map(bound type)およびvalue typeを相互変換するアダプタを作成し，unmarshalメソッドおよびmarshalメソッドを実装します。

javax.xml.bind.annotation.adapters.XmlJavaTypeAdapterアノテーションでアノテートします。

java.util.Map型の引数または戻り値を，2.のアダプタを値に持つXmlJavaTypeAdapterアノテーションでアノテートします。

javacコマンドを実行します。

アノテート済みのSEIをjavacコマンドでコンパイルします。

value type，アダプタ，xmlJavaTypeAdapterアノテーションが適用されたリクエストbeanクラス／レスポンスbeanクラスの関係と実装例を次に示します。

図16‒6　java.util.Mapの使用例

16.1.6　パラメタおよび戻り値からメッセージのパートへのマッピング（non-wrapperスタイルの場合）

SEIのメソッドのパラメタからWSDL（wsdl:part要素のname属性）へのマッピングについて説明します。

ここでは，non-wrapperスタイルの場合について説明します。

(1)　マッピング

non-wrapperスタイルの場合，SEIのメソッドパラメタはオペレーション名と同じ値の名称で，WSDLのパートおよびグローバル要素にマッピングされます。戻り値は，オペレーション名に接尾辞"Response"を付加した名称で，WSDLのパートおよびグローバル要素にマッピングされます。なお，non-wrapperスタイルでは，リクエストbeanおよびレスポンスbeanは必要ありません。このため，hwsgenコマンドによるリクエストbeanおよびレスポンスbeanの自動生成はしませんが，コンパイルしたWebサービス実装クラスに対してhwsgenコマンドを実行することで，事前にエラーチェックができます。詳細については，「10.23.1　hwsgenコマンドによるエラーチェックについて」を参照してください。

マッピング例を次の図に示します。

図16‒7　メソッドのパラメタおよび戻り値とメッセージのパートのマッピング例（non-wrapperスタイル）

(2)　パラメタに指定できるJava型

パラメタに指定できるJava型については，wrapper型の場合と同様です。「16.1.5(2)　パラメタに指定できるJava型」を参照してください。

(3)　パラメタ名の条件

Javaメソッドのパラメタ名は，WSDLにマッピングされないため，Java言語仕様で定めるJava識別子の命名規則に従って記述してください。

(4)　パラメタと戻り値の組み合わせ

SOAPヘッダであるメソッドのパラメタは，幾つでも指定できます。ただし，SOAPボディであるメソッドのパラメタは，戻り値との関係で指定可否および指定個数が決まります。メソッドの戻り値の条件と，パラメタの指定方法を次の表に示します。

表16‒6　メソッドの戻り値の条件とパラメタの指定方法

項番

戻り値の条件

パラメタの指定方法

戻り値の有無

指定位置

1

なし

−

inパラメタおよびinoutパラメタはどちらか1個指定できます。

outパラメタおよびinoutパラメタはどちらか1個指定できます。

2

あり

SOAPヘッダ

inパラメタおよびinoutパラメタはどちらか1個指定できます。

outパラメタおよびinoutパラメタはどちらか1個指定できます。

3

あり

SOAPボディ

inパラメタを1個指定できます。※1

outパラメタおよびinoutパラメタは指定できません。

(5)　アノテーションの指定とパート名へのマッピングの関係

メソッドのパラメタからWSDLのパート（wsdl:part要素のname属性）へのマッピングは，javax.jws.WebParamアノテーションおよびjavax.jws.WebMethodアノテーションの要素値の指定によって異なります。

アノテーションの指定内容と，マッピング方法の関係を次の表に示します。

表16‒7　アノテーションの指定とWSDLのパート名へのマッピングの関係

項番

アノテーションの要素指定の有無

WSDLのパート名へのマッピング方法

javax.jws.WebParam

@partName

javax.jws.WebParam

@name

javax.jws.WebMethod

@operationName

1

指定あり

−

−

指定ありのアノテーションの要素値がwsdl:part要素のname属性にマッピングされます。

2

指定なし

指定あり

−

3

指定なし

指定あり

Javaのメソッド名がwsdl:part要素のname属性にマッピングされます。

4

指定なし

（凡例）

−：要素の指定有無がマッピングに影響しないことを示します（指定しても指定しなくてもマッピング方法は同じです）。

(6)　名前衝突時の動作

パート名およびグローバル要素の名前衝突時の動作について説明します。

パート名の衝突

non-wrapperスタイルでは，JavaソースからマッピングされるWSDLのwsdl:part要素の名前をWSDL内でユニークにする必要があります。ユニークではない場合の動作は保証されません。

グローバル要素（ローカル名および名前空間）の衝突

グローバル要素（ローカル名および名前空間）はWSDL内でユニークにする必要があります。ユニークではない場合の動作は保証されません。

(7)　java.util.Mapクラスの使用

java.util.Mapクラスを使用する方法については，「16.1.5(6)　java.util.Mapクラスの使用」を参照してください。

16.1.7　Javaのラッパ例外クラスからフォルトへのマッピング

Javaのラッパ例外クラスからWSDLのフォルト（wsdl:fault要素，一つのwsdl:part子要素を持つwsdl:message要素，およびXML Schemaのグローバル要素宣言）へのマッピングについて説明します。

(1)　マッピング

Javaのラッパ例外クラスとフォルトは，JAX-WS 2.2仕様に従ってマッピングされます。マッピング例を次の図に示します。

図16‒8　例外クラスとフォルトのマッピング例

ラッパ例外クラスからフォルトへのマッピング規則を次に示します。

ラッパ例外クラスがjavax.xml.ws.WebFaultアノテーションを持つ場合で，かつフォルトbeanを返すgetFaultInfoメソッドを持つ場合，すでにフォルトbeanがあるため，コマンド実行時にフォルトbeanは生成されません。

ラッパ例外クラスがjavax.xml.ws.WebFaultアノテーションもgetFaultInfoメソッドも持たない場合，ラッパ例外クラスの名前の接尾辞に"Bean"を付加した名前のフォルトbeanが生成されます。

生成されるフォルトbeanは，ラッパ例外クラスとその親クラスが持つ，Throwableから継承されるgetMessageというgetterと同じ型／名称のプロパティを持ちます。

生成したフォルトbeanには，javax.xml.bind.annotation.XmlTypeアノテーションがアノテートされます。

アノテートされたjavax.xml.bind.annotation.XmlTypeアノテーションには，name要素に例外クラス名が，namespace要素にSEIの名前空間が，propOrder要素にラッパ例外クラスが持つすべてのプロパティ名が設定されます。propOrder要素のプロパティ名は，各文字のUnicode値に従って昇順にソートされたString型配列で設定されます。

javax.xml.bind.annotation.XmlTypeアノテーションについては，「16.2.12　javax.xml.bind.annotation.XmlTypeアノテーション」を参照してください。

フォルトメッセージ名には，ラッパ例外クラス名と同じ値でマッピングされます。また，フォルトメッセージのパート名には，faultという固定値でマッピングされます。

一つのメソッドでスローする例外は，255個まで定義できます。

メソッドがスローする例外クラスが見つからない場合は，コンパイルエラーが発生します。

(2)　ラッパ例外クラスの条件

ラッパ例外クラスの条件を示します。

ラッパ例外クラスは，java.lang.Exception，java.lang.RuntimeException，java.rmi.RemoteExceptionの例外クラスを継承してもかまいません。ただし，java.lang.RuntimeExceptionとjava.rmi.RemoteException，およびそのサブクラスはラッパ例外クラスとして扱われません。

同じSEI内の複数のメソッドで，同じラッパ例外クラスをスローしてもかまいません。

(3)　ラッパ例外クラス名の条件

ラッパ例外クラス名には，次の表に示すすべての条件を満たす文字列を記述できます。ラッパ例外クラス名は，アノテーションを指定してもWSDL内で使用されるため，次の表の条件に従う必要があります。

表16‒8　ラッパ例外クラス名に記述できる文字列の条件

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z），およびアンダースコア（_）だけを使用した文字列

鈴木_exception

動作は保証されません（エラーメッセージは出力されません）。

2

Java言語仕様で定められているJava識別子の命名規則に従った文字列

abstract

javacコマンド実行時にコンパイルエラーとなり，終了します。

(4)　名前衝突時の動作

フォルトbeanの名前は，パッケージ内でユニークにする必要があります。ただし，大文字／小文字の違いは無視されます。

フォルトbeanからマッピングするグローバル要素（ローカル名および名前空間）は，WSDL内でユニークにする必要があります。ユニークでない場合の動作は保証されません。

16.1.8　SEIからバインディングへのマッピング

JavaのSEIからWSDLのバインディング（wsdl:binding要素のname属性）へのマッピングについて説明します。

(1)　マッピング

JavaのSEIおよびWebサービス実装クラスと，WSDLのバインディングは，JAX-WS 2.2仕様に従ってマッピングされます。マッピング例を次の図に示します。

図16‒9　SEIとバインディングのマッピング例

SEIからバインディングへのマッピング規則を次に示します。

JavaのSEIおよびWebサービス実装クラスは，WSDLの一つのwsdl:binding要素と，0個以上のwsdl:port拡張要素にマッピングされます。

WSDLのバインディング名は，ポートタイプ名の接頭辞に"Binding"を付加した名前になります。ポートタイプ名の形式については，「16.1.3　SEI名からポートタイプへのマッピング」を参照してください。

(2)　SOAPトランスポートと転送バインディング

javax.xml.ws.BindingTypeアノテーションでカスタマイズしていない場合，デフォルトマッピングでは，SOAP 1.1overHTTPでバインディングされます。

これは，wsdl:binding要素の子要素であるsoap:binding要素のtransport属性に，http://schemas.xmlsoap.org/soap/httpが指定されることを意味します。

16.1.9　Webサービス実装クラスからサービスおよびポートへのマッピング

Webサービス実装クラスからWSDLのサービス（wsdl:service要素のname属性）およびポート（wsdl:port要素のname属性）へのマッピングについて説明します。

(1)　マッピング

Webサービス実装クラスと，WSDLのサービスおよびポートは，JAX-WS 2.2仕様に従ってマッピングされます。マッピング例を次の図に示します。

図16‒10　Webサービス実装クラスと，サービスおよびポートのマッピング例

Webサービス実装クラスからサービスおよびポートへのマッピング規則を次に示します。

WSDLのサービス名をjavax.jws.WebServiceアノテーションのserviceName要素でカスタマイズしていない場合，Webサービス実装クラスの名前の接尾辞に，"Service"を付加したものをwsdl:service要素のname属性の値とします。

WSDLのポート名をjavax.jws.WebServiceアノテーションのportName要素でカスタマイズしていない場合，javax.jws.WebServiceアノテーションのname要素値の接尾辞に，"Port"を付加したものをwsdl:port要素のname属性の値とします。

javax.jws.WebServiceアノテーションのportName属性およびname属性でカスタマイズしていない場合，Webサービス実装クラスの名前の接尾辞に，"Port"を付加したものをwsdl:port要素のname属性の値とします。

(2)　Webサービス実装クラス名の条件

Webサービス実装クラス名には，次の表に示すすべての条件を満たす文字列を記述できます。

表16‒9　Webサービス実装クラス名に記述できる文字列の条件

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z），およびアンダースコア（_）だけを使用した文字列

鈴木_service

動作は保証されません（エラーメッセージは出力されません）。

2

Java言語仕様で定められているJava識別子の命名規則に従った文字列

abstract

javacコマンド実行時にコンパイルエラーとなり，終了します。

16.1.10　JavaからWSDLへのマッピングに関する注意事項

JavaからWSDLへのマッピングでの注意事項について説明します。

(1)　ジェネリクスの型削除

JavaBean（リクエストbean，レスポンスbean，フォルトbean）生成時には，ジェネリクスの型が削除されます。ジェネリクスの型削除の例を次の表に示します。

表16‒10　ジェネリクスの型削除の例

型削除前

型削除後

T※

NumbersData

List<E>

List<java.lang.Object>

List<? extends NumbersData>

List<NumbersData>

List<? super NumbersData>

List< java.lang.Object >

Map<K, V>

Map< java.lang.Object, java.lang.Object >

Map<? extends NumbersKey, ? extends NumbersData>

Map<NumbersKey, NumbersData>

Map<? super NumbersKey, ? super NumbersData>

Map< java.lang.Object, java.lang.Object >

Iterator<E>

Iterator< java.lang.Object >

Iterator<? extends NumbersData>

Iterator<NumbersData>

Iterator<? super NumbersData>

Iterator< java.lang.Object >

List<List<? extends NumbersData>>

List<List<NumbersData>

注※

Tの型定義は，<T extends NumbersData>の場合を示します。

メソッド引数や戻り値をjavax.jws.WebParamやjavax.jws.WebResultアノテーションでカスタマイズしている場合も，ジェネリクスの型は削除されます（カスタマイズも有効）。また，メソッド引数や戻り値がwrapperスタイルであっても，ジェネリクスの型は削除されます。なお，メソッド引数や戻り値がnon-wrapperスタイルの場合にはジェネリクスの型は削除されません。

(2)　JAXBアノテーションのサポートについて

Application ServerのJAX-WS機能は，JAX-WS 2.2仕様のComformance 3.14に対応しています。コマンド実行時には，必要に応じて次に示すJAXBアノテーションが解釈されます。

javax.xml.bind.annotation.XmlAttachmentRef

javax.xml.bind.annotation.XmlList

javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter

javax.xml.bind.annotation.XmlMimeType

Application ServerのJAX-WS機能ではMIMEバインディングはサポートされません。

Application ServerのJAX-WS機能が提供するアノテーションプロセッサでは，javax.xml.bind.annotation.XmlListアノテーションはwrapperスタイルの場合には解釈されますが，non-wrapperスタイルの場合には解釈されません。

これらのJAXBアノテーションで，SEIおよびサービス実装クラス以外の引数や戻り値をアノテートした場合の動作は保証されません。

Application ServerのJAX-WS機能が提供するアノテーションプロセッサでは，javax.xml.bind.annotation.XmlJavaTypeAdapterアノテーションおよびjavax.xml.bind.annotation.XmlMimeTypeアノテーションは，SEIまたはサービス実装クラスの引数や戻り値，またはJavaBeanのフィールドをアノテートした場合に解釈されます。パッケージや，インタフェース，またはクラスをアノテートした場合の動作は保証されません。

開発したWebサービスを呼び出すときに，Webサービスの引数や戻り値のサブクラスを使用するとエラーが発生します。正常に呼び出すには，SEIおよびWebサービス実装クラスを定義するときに，javax.xml.bind.annotation.XmlSeeAlsoアノテーションによってサブクラスを関連づける必要があります。

(3)　ジェネリクス型の制限

wrapperスタイルの場合にはメソッド引数や戻り値にジェネリクス型を使用できますが，non-wrapperスタイルの場合にはジェネリクス型を使用できません。

(4)　ジェネリクスを使用したクラスまたはインタフェースの使用について

サービス実装クラスは，型変数をパラメタ化したクラスまたはインタフェースを継承できません。継承する場合，サービス実装クラスで再定義したメソッドにexclude要素の要素値が"true"のjavax.jws.WebMethodアノテーションをアノテートしてサービスメソッドから除外する必要があります。

型変数をパラメタ化したクラスまたはインタフェースを継承したサービス実装クラスをコンパイルすると，サービス実装クラス内で再定義したメソッド名と同じ名前の合成ブリッジ・メソッド（synthetic bridge methods）をJDKのコンパイラが暗黙的に生成します。コンパイルしたサービス実装クラスから生成したメタデータ（WSDL）にはユニークでなければならないオペレーション名を2つマッピングすることになるため，メタデータ（WSDL）の解析に失敗します。オペレーション名のマッピングについては，「16.1.4　SEIのメソッド名からオペレーションへのマッピング」を参照してください。

16.2　JavaからWSDLへのマッピングのカスタマイズ

アノテーションを使用することで，JavaからWSDLへのマッピングをカスタマイズできます。

アノテーションを使用したカスタマイズ例を次の図に示します。

図16‒11　アノテーションを使用したカスタマイズ例

アノテーションには，SEIに定義できるもの，Webサービス実装クラスに定義できるもの，および両方に定義できるものがあります。ただし，javax.jws.WebServiceアノテーションのendpointInterface要素を使用しない場合は，Webサービス実装クラスの情報から抽象的な情報が抽出されて暗黙のSEIがあるものと見なされます。このときにかぎり，SEIに定義するアノテーションを，Webサービス実装クラスに定義することが許容されます。

アノテーションの要素を明示的にデフォルト値と同じ値でカスタマイズしても，要素値が指定されていない場合と同じように処理されます。

16.2.1　アノテーション一覧

カスタマイズ時に使用できるアノテーション，および自動生成されるアノテーションを次の表に示します。各アノテーションについては，JAX-WS 2.2仕様を参照してください。

表16‒11　カスタマイズ時に使用するJAX-WSのアノテーションの一覧

項番

アノテーション

説明

定義の可否

アノテーション名

要素名

1

com.sun.xml.ws.developer.StreamingAttachment

dir

受信した添付ファイルを含むSOAPメッセージに含まれるMIMEボディを一時ファイルとして出力する際に，一時ファイルを生成するディレクトリ名です。

○

parseEagerly

受信した添付ファイルを含むSOAPメッセージを詳細に解析するかどうかを設定します。

○

memoryThreshold

受信した添付ファイルを含むSOAPメッセージに含まれるMIMEボディをメモリ上に展開するかどうかを判定するためのしきい値です。

○

2

javax.jws.HandlerChain

file

ハンドラチェインファイルの場所を指すURLおよび相対パスです。

○

3

javax.jws.Oneway

−

Webサービスでone-wayオペレーションを使用する場合に指定します。

○

4

javax.jws.soap.SOAPBinding

parameterStyle

メソッドのパラメタのスタイル（Document wrappedまたはDocument Bareスタイル）です。

○

style

メッセージのエンコードスタイルです。Application ServerのJAX-WS機能ではdocumentだけ指定できます。

○

use

メッセージのフォーマットスタイルです。Application ServerのJAX-WS機能ではliteralだけ指定できます。

○

5

javax.jws.WebMethod

action

SOAPアクションを決定する文字列です。

○

exclude

Webメソッドとして，公開の可否を指定します。

○

operationName

メソッドに一致するwsdl:operation要素名です。

○

6

javax.jws.WebParam

header

メッセージのヘッダから，パラメタを取得するかどうかを表します。

○

mode

パラメタの流れの方向（in，inout，およびout）です。

○

name

パラメタを表すXML要素のローカル名です。

○

partName

パラメタを表すwsdl:part要素名です。

○

targetNamespace

XMLの名前空間名です。

○

7

javax.jws.WebResult

header

メッセージのヘッダから，戻り値を取得するかどうかを表します。

○

name

戻り値を表すXML要素のローカル名です。

○

partName

戻り値を表すwsdl:part要素名です。

○

targetNamespace

XMLの名前空間名です。

○

8

javax.jws.WebService

endpointInterface

Webサービスの抽象Webサービス規約を定義する，SEIの完全修飾名です。

○

name

Webサービス名を表すwsdl:portType要素名です。

○

portName

Webサービスのポート名を表すwsdl:port要素名です。

○

serviceName

Webサービスのサービス名を表すwsdl:service要素名です。

○

targetNamespace

Webサービスの名前空間名です。

○

wsdlLocation

WebサービスのWSDLを示すURLです。

○※1，※3

9

javax.xml.ws.Action

fault

アドレッシング・ヘッダのwsa:Action要素の値です。Webサービスがフォルトメッセージを送信する場合に必要です。

○

input

アドレッシング・ヘッダのwsa:Action要素の値です。Webサービスがリクエストメッセージを受信する場合に必要です。

○

output

アドレッシング・ヘッダのwsa:Action要素の値です。Webサービスがレスポンスメッセージを送信する場合に必要です。

○

10

javax.xml.ws.BindingType

value

SEIを公開するときに使用するバインディングです。

○

11

javax.xml.ws.FaultAction

className

例外クラス名です。

○

value

アドレッシング・ヘッダのwsa:Action要素の値です。classNameに指定した例外クラス名に該当するフォルトメッセージを，Webサービスから送信する場合に必要です。

○

12

javax.xml.ws.RequestWrapper

className

リクエストbeanクラス名です。

○

localName

対象要素のローカル名です。

○

targetNamespace

対象要素の名前空間名です。

○

partName

リクエストwrapper要素を参照するinputメッセージのパート名です。

○

13

javax.xml.ws.ResponseWrapper

className

レスポンスbeanクラス名です。

○

localName

対象要素のローカル名です。

○

targetNamespace

対象要素の名前空間名です。

○

partName

レスポンスwrapper要素を参照するoutputメッセージのパート名です。

○

14

javax.xml.ws.ServiceMode

value

サービスモードです。

○

15

javax.xml.ws.soap.Addressing

enabled

アドレッシング機能を有効にするかどうかを設定します。

○

required

Webサービスを呼び出す場合にアドレッシング・ヘッダを必須とするかどうかを設定します。

○

response

エンドポイントが匿名のレスポンスまたは非匿名のレスポンスを必須とするかどうかを設定します。

○

16

javax.xml.ws.soap.MTOM

enabled

MTOM/XOP仕様形式の添付ファイルを使用するかどうかを設定します。

○

threshold

バイナリデータをMTOM/XOP仕様形式の添付ファイルとして送信するためのしきい値を設定します。

○

17

javax.xml.ws.WebFault

faultBean

フォルトbeanクラス名です。

○

name

対象要素のローカル名です。

○

targetNamespace

対象要素の名前空間名です。

○

messageName

フォルトメッセージ名です。

○

18

javax.xml.ws.WebServiceProvider

targetNamespace

Webサービスの名前空間名です。

○

portName

Webサービスのポート名です。

○

serviceName

Webサービスのサービス名です。

○

wsdlLocation

WebサービスのWSDLを示すURLです。

○※3

19

javax.xml.ws.RespectBinding※1

enabled

wsdl:binding要素の内容が有効かどうかを表します。

○※1

20

javax.xml.ws.WebEndpoint※2

name

ポートのローカル名です。

×※2

21

javax.xml.ws.WebServiceClient※2

name

Webサービスのローカル名です。

×※2

targetNamespace

Webサービスの名前空間名です。

×※2

wsdlLocation

WebサービスのWSDLを示すURLです。

×※2，※3

（凡例）

−：要素がないことを示します。

○：アノテーションおよび要素が指定できることを示します。

×：アノテーションおよび要素が指定できないことを示します（非サポート）。

注※1

指定した値は無視されます（警告メッセージは表示されません）。

注※2

WSDLから生成されたクラスに自動的に付与されるアノテーションになるため，指定できません。

注※3

カタログ機能でのマッピングはサポートしていません。

Application ServerのWebサービスで定義できるJAXBのアノテーションの一覧を次に示します。なお，各アノテーションについては，JAXBの標準仕様を参照してください。

javax.xml.bind.annotation.XmlAttachmentRef

javax.xml.bind.annotation.XmlList

javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter

javax.xml.bind.annotation.XmlMimeType

javax.xml.bind.annotation.XmlSeeAlso

javax.xml.bind.annotation.XmlElement

javax.xml.bind.annotation.XmlType

JSR-181仕様およびJAX-WS 2.2仕様のアノテーションのうち，次の表に示すアノテーションは指定できません。指定した場合，動作は保証されません。

表16‒12　サポート外のアノテーションの一覧

項番

アノテーション

備考

1

javax.xml.ws.WebServiceRefs

JSR109仕様に関連する機能はサポートしていません。

2

javax.xml.ws.spi.WebServiceFeatureAnnotation

このアノテーションを使用するためのAPI（フィーチャをパラメタに取るメソッド）はサポートしていません。

3

javax.jws.soap.InitParam

JSR181仕様で推奨していません（廃止対象）。

4

javax.jws.soap.SOAPMessageHandler

JSR181仕様で推奨していません（廃止対象）。

5

javax.jws.soap.SOAPMessageHandlers

JSR181仕様で推奨していません（廃止対象）。

16.2.2　com.sun.xml.ws.developer.StreamingAttachmentアノテーション

com.sun.xml.ws.developer.StreamingAttachmentアノテーションについて，次に説明します。

Webサービス側

ストリーミングを使用するWebサービスに指定するアノテーションです。Webサービス実装クラスだけに指定できます。SEIに指定した場合は無視されます。また，プロバイダ実装クラスに指定した場合，動作は保証されません。

Webサービスクライアント側

ポートをインジェクトするフィールドまたはsetterメソッドに指定するアノテーションです。詳細については，「10.21.1(4)　フィーチャの有効化」を参照してください。それ以外のフィールドやメソッドに指定した場合は無視されます。

cjwsimportコマンドが生成するWebサービス実装クラスのスケルトンクラスを使用して，ストリーミングを使用するWebサービスを作成する場合，Webサービス実装クラスのスケルトンクラスにはcom.sun.xml.ws.developer.StreamingAttachmentアノテーションをマッピングしないので，com.sun.xml.ws.developer.StreamingAttachmentアノテーションを指定する必要があります。なお，Webサービス実装クラスにcom.sun.xml.ws.developer.StreamingAttachmentアノテーションを指定しても，サービス側JAX-WSエンジンが発行するWSDLファイルやhwsgenコマンドが生成するWSDLファイルには，ストリーミングが使用されていることを示す要素や属性は出現しません。

com.sun.xml.ws.developer.StreamingAttachmentアノテーションはWebサービス開始時に参照する値であるため，hwsgenコマンドの実行時には解釈しません。

com.sun.xml.ws.developer.StreamingAttachmentアノテーションを使用した例を次の図に示します。

図16‒12　com.sun.xml.ws.developer.StreamingAttachmentアノテーションを使用した例（Webサービス側）

(1)　dir要素（com.sun.xml.ws.developer.StreamingAttachment）

dir要素は，Webサービスでストリーミングを使用する場合に，受信した添付ファイルを含むMIME Multipart/Related構造のSOAPメッセージに含まれるMIMEボディを一時ファイルとして出力するときに使用するディレクトリを指定します。デフォルト値は空文字（"")です。

dir要素の要素値に空文字("")またはnullを指定した場合，一時ファイルの出力先はJavaのデフォルトの一時ファイルディレクトリ（システムプロパティにある"java.io.tmpdir"キーに対応する値）となります。また，存在しないディレクトリ名，アクセス権のないディレクトリ名，または存在するファイル名を指定した場合，Webサービス開始時にメッセージを出力し，受信した添付ファイルを含むMIME Multipart/Related構造のSOAPメッセージに含まれるMIMEボディをメモリ上に展開します（KDJW10026-W）。

(2)　parseEagerly要素（com.sun.xml.ws.developer.StreamingAttachment）

parseEagerly要素は，Webサービスでストリーミングを使用する際に，受信した添付ファイルを含むMIME Multipart/Related構造のSOAPメッセージを詳細に解析するかどうかを指定します。デフォルト値はfalseです。

(3)　memoryThreshold要素（com.sun.xml.ws.developer.StreamingAttachment）

memoryThreshold要素は，Webサービスでストリーミングを使用する際に，受信した添付ファイルを含むMIME Multipart/Related構造のSOAPメッセージに含まれるMIMEボディを一時ファイルとして出力するかどうかを判定するためのしきい値(単位：バイト)を指定します。memoryThreshold要素には，16KB（16384L）より大きい値または-1を指定します。これら以外の値を指定した場合，動作は保証されません。-1を指定した場合，常にMIMEボディをメモリ上に展開します。デフォルト値は「1048576L」です。

受信したMIME Multipart/Related構造のSOAPメッセージに含まれるMIMEボディをメモリ上に展開するかどうかの判定については，「32.3　一時ファイル（ストリーミング）」を参照してください。

16.2.3　javax.jws.HandlerChainアノテーション

javax.jws.HandlerChainアノテーションは，クラスまたはインタフェース宣言に定義した場合に有効になります。

SEIとWebサービス実装クラスに同時にjavax.jws.HandlerChainアノテーションを指定した場合，Webサービス実装クラスに指定したアノテーションが優先されます。

(1)　file要素（javax.jws.HandlerChain）

file要素では，ハンドラチェイン設定ファイルを指定します。javax.jws.HandlerChainアノテーションでアノテートしたクラス，またはインタフェースからの相対パスで指定します。Application ServerのJAX-WS機能では，URL形式での指定はサポートしていません。

参照できなかったり，開けなかったりするパスを指定した場合は，Webサービスの初期化時に，標準エラー出力とログにエラーメッセージが出力されます（KDJW00010-E）。

なお，file要素は，Webサービスの呼び出しで参照される値になるため，hwsgenコマンドの実行時には解釈されません。file要素の使用例については，「36.9.1　Webサービス側のハンドラチェインの設定」を参照してください。

16.2.4　javax.jws.Onewayアノテーション

javax.jws.Onewayアノテーションは，Webサービスでone-wayオペレーションを使用する場合に指定します。javax.jws.OnewayアノテーションをアノテートしたWebサービス実装クラスのメソッドは，入力メッセージだけを持ち，出力メッセージは持ちません。

javax.jws.Onewayアノテーションを使用したマッピング例を次の図に示します。

図16‒13　javax.jws.Onewayアノテーションを使用したマッピング例

javax.jws.OnewayアノテーションをアノテートしたWebサービス実装クラスのメソッドは，次に示す条件を満たす必要があります。

戻り値の型はvoidを指定してください。

BAREスタイルのWebサービスの場合，SOAPヘッダ以外のinパラメタを一つだけ指定してください。

javax.jws.WebParamアノテーションのMode要素を使用する場合，javax.jws.WebParam.Mode.INを使用してください。

Webサービス実装クラスのメソッドで，java.lang.RuntimeExceptionとjava.rmi.RemoteExceptionおよびそのサブクラス以外の例外が，一つも宣言されていないことを確認してください。

引数の型をHolder型で指定しないでください。

javax.jws.Onewayアノテーションを使用するときの注意事項について説明します。

Webサービス実装クラスで，javax.jws.Onewayアノテーションとjavax.xml.ws.soap.Addressingアノテーションを併用しないでください。one-wayオペレーションはレスポンスメッセージが存在しませんが，アドレッシング機能はレスポンスメッセージの送信先を指定します。このため，同時に使用した場合の動作は保証されません。

one-wayオペレーションは応答のSOAPメッセージが存在しないため，Webサービス実装クラスのjavax.jws.Onewayアノテーションをアノテートしたメソッドの実装では，例外を明示的にスローしないようにしてください。

16.2.5　javax.jws.soap.SOAPBindingアノテーション

javax.jws.soap.SOAPBindingアノテーションは，SOAPメッセージのプロトコルのマッピングをカスタマイズするときに使用できます。

(1)　style要素（javax.jws.soap.SOAPBinding）

Application ServerのJAX-WS機能が提供するアノテーションプロセッサでは，DOCUMENT/LITERALスタイルだけ使用できます。

javax.jws.soap.SOAPBindingアノテーションを，クラスまたはインタフェース宣言とメソッド宣言で同時に指定した場合，メソッド宣言で指定した値が優先されます。

(2)　use要素（javax.jws.soap.SOAPBinding）

Application ServerのJAX-WS機能が提供するアノテーションプロセッサでは，DOCUMENT/LITERALスタイルだけ使用できます。

(3)　parameterStyle要素（javax.jws.soap.SOAPBinding）

wrapperスタイルの場合，parameterStyle要素にSOAPBinding.ParameterStyle.WRAPPEDを指定します。また，non-wrapperスタイルの場合，parameterStyle要素にSOAPBinding.ParameterStyle.BAREを指定します。

16.2.6　javax.jws.WebMethodアノテーション

javax.jws.WebMethodアノテーションは，オペレーションのマッピングをカスタマイズするときに使用できます。

javax.jws.WebMethodアノテーションを使用したカスタマイズ例を次の図に示します。

図16‒14　javax.jws.WebMethodアノテーションを使用したカスタマイズ例

(1)　exclude要素（javax.jws.WebMethod）

Webサービス実装クラスが持つpublicメソッドのうち，オペレーションとして公開したくないpublicメソッドは，exclude要素の要素値が"true"のjavax.jws.WebMethodアノテーションでアノテートすることで，マッピングされるオペレーションから除外できます。継承した親クラスが持つメソッドの場合，そのメソッドをオーバーライドし，exclude要素の要素値が"true"のjavax.jws.WebMethodアノテーションでアノテートすることで，マッピングされるオペレーションから除外できます。

exclude要素を指定するときの注意事項について説明します。

Webサービス実装クラスでこの要素の要素値に"true"を指定した場合，Webサービス実装クラスのjavax.jws.WebMethodアノテーションに，ほかの要素を指定できません。

SEIでこの要素を指定する場合，要素値には"false"を指定してください。

Webサービス実装クラスで親クラスのメソッドをオーバーライドしている場合で，親クラスとWebサービス実装クラス（子クラス）の両方にこの要素を指定した場合，Webサービス実装クラス（子クラス）に指定した要素が優先されます。

Webサービス実装クラスでjavax.jws.WebServiceアノテーションのendpointInterface要素を指定していない場合，Webサービス実装クラスが持つstatic修飾子またはfinal修飾子を適用していないすべてのpublicメソッドが暗黙のSEIにマッピングされます。また，Webサービス実装クラスが持つstatic修飾子またはfinal修飾子を適用していないpublicメソッドに，exclude要素が"true"ではないjavax.jws.WebMethodアノテーションを一つでも指定しているとき，次の表の条件を満たすWebサービス実装クラスのメソッドが，暗黙のSEIにマッピングされます。

表16‒13　アノテーションの指定と暗黙のSEIへのマッピング

項番

Webサービス実装クラスのメソッド

（WebMethodアノテーション）

暗黙のSEIが持つメソッド

1

なし

マッピングされます。

2

あり（exclude要素なし）

マッピングされます。

3

exclude=false

マッピングされます。

4

exclude=true

マッピングされません。

(2)　operationName要素（javax.jws.WebMethod）

operationName要素は，オペレーション名のマッピングをカスタマイズするときに指定します。operationName要素に要素値を指定すると，オペレーション名をマッピングのデフォルト値に持つメッセージ名がカスタマイズできます。non-wrapperスタイルの場合は，グローバル要素名およびパート名もカスタマイズできます。

operationName要素を指定するときの注意事項について説明します。

operationName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

Java言語仕様で規定されるJava識別子の命名規則に従った値を指定してください。Java識別子の命名規則に従っていない場合，Webサービスクライアントの開発で，cjwsimportコマンドを実行するときにコンパイルエラーとなります。

wrapperスタイルの場合，javax.xml.ws.RequestWrapperアノテーションのlocalName要素は「オペレーション名」と同じである必要があります。ただし，javax.xml.ws.RequestWrapperアノテーションが存在しない場合，またはjavax.xml.ws.RequestWrapperアノテーションのlocalName要素に空文字（""）が指定されている場合，同一かどうかの比較処理は行われません。

(3)　action要素（javax.jws.WebMethod）

action要素は，SOAPオペレーションのアクションにマッピングされます。action要素には，RFC 2396で規定されたxsd:anyURIを満たす文字を指定できますが，指定した値はランタイムでは無視されます。

16.2.7　javax.jws.WebParamアノテーション

javax.jws.WebParamアノテーションは，引数のマッピングをカスタマイズするときに使用できます。

javax.jws.WebParamアノテーションを使用したカスタマイズ例を次の図に示します。

図16‒15　javax.jws.WebParamアノテーションを使用したカスタマイズ例

(1)　header要素（javax.jws.WebParam）

引数をヘッダパラメタとしてマッピングする場合，header要素の要素値に"true"を指定します。

header要素は，non-wrapperスタイルで指定できます。

(2)　name要素（javax.jws.WebParam）

name要素は，wrapperスタイルの場合，引数からマッピングするwrapper要素の子要素の名前をカスタマイズするときに使用します。non-wrapperスタイルの場合，引数からマッピングするグローバル要素のローカル名をカスタマイズするときに使用します。non-wrapperスタイルでpartName要素を指定していない場合，name要素の要素値を指定することで，パート名もカスタマイズできます。

name要素を指定するときの注意事項について説明します。

name要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

wrapperスタイルの場合，Java言語仕様で規定されるJava識別子の命名規則に従った値を指定してください。Java識別子の命名規則に従っていない場合は，Webサービスクライアントの開発でcjwsimportコマンドを実行するときにコンパイルエラーとなります。

(3)　partName要素（javax.jws.WebParam）

partName要素は，パート名のマッピングをカスタマイズするときに指定します。

partName要素を指定するときの注意事項について説明します。

partName要素は，non-wrapperスタイルで有効です。wrapperスタイルでpartName要素を指定した場合は無視されます。

partName要素とname要素を同時に指定した場合，有効となる要素を次に示します。

wrapperスタイルの場合：name要素の値が有効になります。

non-wrapperスタイルの場合：partName要素の値が有効になります。

partName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

non-wrapperスタイルの場合，Java言語仕様で規定されるJava識別子の命名規則に従った値を指定してください。Java識別子の命名規則に従っていない場合は，Webサービスクライアントの開発でcjwsimportコマンドを実行するときにコンパイルエラーとなります。

(4)　mode要素（javax.jws.WebParam）

mode要素では，パラメタの流れる方向を表す値を指定します。指定できる値を次に示します。

WebParam.Mode.IN

WebParam.Mode.OUT

WebParam.Mode.INOUT

(5)　targetNamespace要素（javax.jws.WebParam）

targetNamespace要素は，引数からマッピングするグローバル要素の名前空間をカスタマイズするときに使用します。

targetNamespace要素には，http://またはurn:のプロトコルを名前空間として指定します。指定できる名前空間の形式および文字列を示します。

プロトコル

名前空間のプロトコルは，http://またはurn:のプロトコルで記述してください。

名前空間の記述形式

名前空間には次に示す形式は記述できません。

クエリストリング（例）http://example.com/?a=b

アンカー（例）http://example.com/index.html#anchor

ポート番号（例）http://example.com:8080/

ユーザ名／パスワード（例）http://user:password@example.com

記述できる文字列

区切り文字のスラッシュ（/）またはピリオド（.）で区切られたセグメントには，次の表に示すすべての条件を満たす文字列を記述できます。

表16‒14　名前空間に記述できる文字列の条件（javax.jws.WebParam）

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z）だけを使用した文字列

http://鈴木.com

http://133.145.224.19/

http://[1080:2C14;D30:BA04:275:806:270C:418A]/

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列

http://xxx.com/abstract

動作は保証されません。

3

先頭が数字でない文字列

http://1xxx.com

16.2.8　javax.jws.WebResultアノテーション

javax.jws.WebResultアノテーションは，戻り値のマッピングをカスタマイズするときに使用できます。

javax.jws.WebResultアノテーションを使用したカスタマイズ例を次の図に示します。

図16‒16　javax.jws.WebResultアノテーションを使用したカスタマイズ例

(1)　header要素（javax.jws.WebResult）

戻り値をヘッダパラメタとしてマッピングする場合，header要素の要素値に"true"を指定します。

header要素は，non-wrapperスタイルで指定できます。

(2)　name要素（javax.jws.WebResult）

name要素は，wrapperスタイルの場合，戻り値からマッピングするwrapper要素の子要素の名前をカスタマイズするときに使用します。non-wrapperスタイルの場合，引数からマッピングするグローバル要素のローカル名をカスタマイズするときに使用します。non-wrapperスタイルでpartName要素を指定していない場合，name要素の要素値を指定することで，パート名もカスタマイズできます。

name要素を指定するときの注意事項について説明します。

name要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

wrapperスタイルの場合，Java言語仕様で規定されるJava識別子の命名規則に従った値を指定してください。Java識別子の命名規則に従っていない場合は，Webサービスクライアントの開発でcjwsimportコマンドを実行するときにコンパイルエラーとなることがあります。

引数が254個あるwrapperスタイルのメソッドで，name要素を"return"以外の値にカスタマイズした場合，cjwsimportコマンドの実行時に引数の数が255個になり，コンパイルエラーとなるおそれがあります。

(3)　partName要素（javax.jws.WebResult）

partName要素は，パート名のマッピングをカスタマイズするときに指定します。

partName要素を指定するときの注意事項について説明します。

partName要素は，non-wrapperスタイルで有効です。wrapperスタイルでpartName要素を指定した場合は無視されます。

partName要素とname要素を同時に指定した場合，有効となる要素を次に示します。

wrapperスタイルの場合：name要素の値が有効になります。

non-wrapperスタイルの場合：partName要素の値が有効になります。

partName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

non-wrapperスタイルの場合，Java言語仕様で規定されるJava識別子の命名規則に従った値を指定してください。Java識別子の命名規則に従っていない場合は，Webサービスクライアントの開発でcjwsimportコマンドを実行するときにコンパイルエラーとなります。

引数が254個あるwrapperスタイルのメソッドで，name要素を"return"以外の値にカスタマイズした場合，cjwsimportコマンドの実行時に引数の数が255個になり，コンパイルエラーとなるおそれがあります。

(4)　targetNamespace要素（javax.jws.WebResult）

targetNamespace要素は，戻り値からマッピングするグローバル要素の名前空間をカスタマイズするときに使用します。

targetNamespace要素には，http://またはurn:のプロトコルを名前空間として指定します。指定できる名前空間の形式および文字列を示します。

プロトコル

名前空間のプロトコルは，http://またはurn:のプロトコルで記述してください。

名前空間の記述形式

名前空間には次に示す形式は記述できません。

クエリストリング（例）http://example.com/?a=b

アンカー（例）http://example.com/index.html#anchor

ポート番号（例）http://example.com:8080/

ユーザ名／パスワード（例）http://user:password@example.com

記述できる文字列

区切り文字のスラッシュ（/）またはピリオド（.）で区切られたセグメントには，次の表に示すすべての条件を満たす文字列を記述できます。

表16‒15　名前空間に記述できる文字列の条件（javax.jws.WebResult）

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z）だけを使用した文字列

http://鈴木.com

http://133.145.224.19/

http://[1080:2C14;D30:BA04:275:806:270C:418A]/

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列

http://xxx.com/abstract

動作は保証されません。

3

先頭が数字でない文字列

http://1xxx.com

16.2.9　javax.jws.WebServiceアノテーション

javax.jws.WebServiceアノテーションは，SEIおよびWebサービス実装クラスに必須です。

javax.jws.WebServiceアノテーションを使用したカスタマイズ例を次の図に示します。

図16‒17　javax.jws.WebServiceアノテーションを使用したカスタマイズ例

なお，javax.xml.ws.WebServiceProviderアノテーションとjavax.jws.WebServiceアノテーションは，どちらか一方しか指定できません。

(1)　targetNamespace要素（javax.jws.WebService）

SEIでtargetNamespace要素を指定した場合，指定した名前空間は，types要素，message要素，およびportType要素に対して有効です。

Webサービス実装クラスでこの要素を指定した場合，指定した名前空間は，binding要素およびservice要素に対して有効です。Webサービス実装クラスで，javax.jws.WebServiceアノテーションのendpointInterface要素を使用しない場合，暗黙のSEIとWebサービス実装クラスの両方に同じ名前空間を指定したものと見なされます。

targetNamespace要素には，http://またはurn:のプロトコルを名前空間として指定します。指定できる名前空間の形式および文字列を示します。

プロトコル

名前空間のプロトコルは，http://またはurn:のプロトコルで記述してください。

名前空間の記述形式

名前空間には次に示す形式は記述できません。

クエリストリング（例）http://example.com/?a=b

アンカー（例）http://example.com/index.html#anchor

ポート番号（例）http://example.com:8080/

ユーザ名／パスワード（例）http://user:password@example.com

記述できる文字列

区切り文字のスラッシュ（/）またはピリオド（.）で区切られたセグメントには，次の表に示すすべての条件を満たす文字列を記述できます。

表16‒16　名前空間に記述できる文字列の条件（javax.jws.WebService）

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z）だけを使用した文字列

http://鈴木.com

http://133.145.224.19/

http://[1080:2C14;D30:BA04:275:806:270C:418A]/

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列

http://xxx.com/abstract

動作は保証されません。

3

先頭が数字でない文字列

http://1xxx.com

(2)　endpointInterface要素（javax.jws.WebService）

endpointInterface要素を指定するときの注意事項について説明します。

endpointInterface要素は，Webサービス実装クラスのjavax.jws.WebServiceアノテーションで，javax.jws.WebServiceアノテーションを持つSEIを指定します。

Webサービス実装クラスのjavax.jws.WebServiceアノテーションにendpointInterface要素を指定している場合，javax.jws.WebServiceアノテーションのname要素を同時に指定できません。

SEIには，javax.jws.WebServiceアノテーションのendpointInterface要素を指定できません。

Webサービス実装クラスのjavax.jws.WebServiceアノテーションにendpointInterface要素を指定している場合，Webサービス実装クラス内に次に示すアノテーションは指定できません。

javax.jws.WebMethod

javax.jws.WebParam

javax.jws.WebResult

javax.jws.Oneway

javax.jws.SOAPBinding

(3)　name要素（javax.jws.WebService）

name要素は，ポートタイプ名のマッピングをカスタマイズするときに指定します。name要素に要素値を指定すると，ポートタイプ名をマッピングのデフォルト値に持つすべての要素もカスタマイズできます。

name要素を指定するときの注意事項について説明します。

SEIのjavax.jws.WebServiceアノテーションで使用する場合，name要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

Webサービス実装クラスのjavax.jws.WebServiceアノテーションにendpointInterface要素を指定している場合，Webサービス実装クラスでjavax.jws.WebServiceアノテーションのname要素を同時に指定できません。

(4)　serviceName要素（javax.jws.WebService）

serviceName要素は，サービス名のマッピングをカスタマイズするときに指定します。

serviceName要素を指定するときの注意事項について説明します。

SEIには，javax.jws.WebServiceアノテーションのserviceName要素は指定できません。

Webサービス実装クラスのjavax.jws.WebServiceアノテーションで使用する場合，serviceName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合，動作は保証されません。

Java言語仕様で規定されるJava識別子の命名規則に従った値を指定してください。Java識別子の命名規則に従っていない場合は，Webサービスクライアントの開発でcjwsimportコマンドを実行するときにコンパイルエラーとなります。

(5)　portName要素（javax.jws.WebService）

portName要素は，ポート名のマッピングをカスタマイズするときに指定します。

SEIには，javax.jws.WebServiceアノテーションのportName要素は指定できません。

Webサービス実装クラスのjavax.jws.WebServiceアノテーションで使用する場合，portName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません。

(6)　wsdlLocation要素（javax.jws.WebService）

wsdlLocation要素は，Webサービスの呼び出しで参照される値になるため，hwsgenコマンドの実行時には解釈されません。

16.2.10　javax.xml.bind.annotation.XmlElementアノテーション

javax.xml.bind.annotation.XmlElementアノテーションは，SEIのサービスメソッドの引数や戻り値に指定します。指定すると，生成されるリクエストbean，またはレスポンスbeanのプロパティのjavax.xml.bind.annotation.XmlElementアノテーションにマッピングされます。

javax.xml.bind.annotation.XmlElementアノテーションは，wrapperスタイルで指定します。non-wrapperスタイルで指定した場合の動作の保証はされません。

javax.xml.bind.annotation.XmlElementアノテーションを使用したマッピングの例を次の図に示します。

図16‒18　javax.xml.bind.annotation.XmlElementアノテーションを使用したマッピングの例

(1)　name要素（javax.xml.bind.annotation.XmlElement）

name要素は，生成されるリクエストbeanまたはレスポンスbeanのプロパティをアノテートするjavax.xml.bind.annotation.XmlElementアノテーションのname要素にマッピングされます。

javax.xml.bind.annotation.XmlElementアノテーションが，javax.jws.WebParamアノテーションまたはjavax.jws.WebResultアノテーションと同時に存在する場合の注意事項を次に示します。

javax.jws.WebParamアノテーションと同時に存在する場合

javax.xml.bind.annotation.XmlElementアノテーションとjavax.jws.WebParamアノテーションのname要素を同じ値にする必要があります。ただし，name要素に"##default"を指定したとき，またはjavax.jws.WebParamアノテーションのname要素に空文字("")を指定したとき，同一かどうかの比較処理は行われません。

javax.jws.WebResultアノテーションと同時に存在する場合

javax.xml.bind.annotation.XmlElementアノテーションとjavax.jws. WebResultアノテーションのname要素を同じ値にする必要があります。ただし，name要素に"##default"を指定したとき，またはjavax.jws.WebResultアノテーションのname要素に空文字("")を指定したとき，同一かどうかの比較処理は行われません。

(2)　namespace要素（javax.xml.bind.annotation.XmlElement）

namespace要素は，生成されるリクエストbeanまたはレスポンスbeanのプロパティをアノテートするjavax.xml.bind.annotation.XmlElementアノテーションのnamespace要素にマッピングされます。

javax.xml.bind.annotation.XmlElementアノテーションが，javax.jws.WebParamアノテーションまたはjavax.jws.WebResultアノテーションと同時に存在する場合の注意事項を次に示します。

javax.jws.WebParamアノテーションと同時に存在する場合

この要素とjavax.jws.WebParamアノテーションのtargetNamespace要素を同じ値にする必要があります。ただし，namespace要素に"##default"を指定したとき，またはjavax.jws.WebParamアノテーションのtargetNamespace要素に空文字("")を指定したとき，同一かどうかの比較処理は行われません。

javax.jws.WebResultアノテーションと同時に存在する場合

この要素とjavax.jws. WebResultアノテーションのtargetNamespace要素を同じ値にする必要があります。ただし，namespace要素に"##default"を指定したとき，またはjavax.jws.WebResultアノテーションのtargetNamespace要素に空文字("")を指定したとき，同一かどうかの比較処理は行われません。

(3)　nillable要素（javax.xml.bind.annotation.XmlElement）

nillable要素は，生成されるリクエストbeanまたはレスポンスbeanのプロパティをアノテートするjavax.xml.bind.annotation.XmlElementアノテーションのnillable要素にマッピングされます。

nillable要素には，trueまたはfalseの値を指定できます。falseの値を指定した場合，生成されるリクエストbeanまたはレスポンスbeanのプロパティのjavax.xml.bind.annotation.XmlElementアノテーションにnillable要素はマッピングされません。

(4)　required要素（javax.xml.bind.annotation.XmlElement）

required要素は，生成されるリクエストbeanまたはレスポンスbeanのプロパティをアノテートするjavax.xml.bind.annotation.XmlElementアノテーションのrequired要素にマッピングされます。

required要素には，trueまたはfalseの値を指定できます。falseの値を指定した場合，生成されるリクエストbeanまたはレスポンスbeanのプロパティのjavax.xml.bind.annotation.XmlElementアノテーションにrequired要素はマッピングされません。

16.2.11　javax.xml.bind.annotation.XmlMimeTypeアノテーション

javax.xml.bind.annotation.XmlMimeTypeアノテーションは，Java型とMIMEタイプの関連づけに使用されるJAXBのアノテーションで，javax.xml.ws.soap.MTOMアノテーションを使用する場合で，Java型とMIMEタイプを関連づけるときに使用します。

javax.xml.bind.annotation.XmlMimeTypeアノテーションは，SEIや暗黙のSEIがあるWebサービス実装クラスが持つサービスメソッドの引数，戻り値，またはユーザ定義型のgetterメソッドに指定できます。それ以外の個所（暗黙のSEIがないWebサービス実装クラスが持つサービスメソッドの引数，戻り値，ユーザ定義例外のフィールドなど）に指定した場合は動作が保証されません。

javax.xml.bind.annotation.XmlMimeTypeアノテーションをSEIなどにアノテートしている場合，Webサービス側のJAX-WSエンジンが発行するWSDLファイルやhwsgenコマンドが生成するWSDLファイルは，javax.xml.bind.annotation.XmlMimeTypeアノテーションをアノテートしたJava型に対応するスキーマの要素に，アノテーションのvalue要素に指定した値を持つxmime:expectedContentTypes属性が付与されます。

javax.xml.bind.annotation.XmlMimeTypeアノテーションを使用した例を次の図に示します。

図16‒19　javax.xml.bind.annotation.XmlMimeTypeアノテーションを使用した例

Java型とMIMEタイプを関連づけない場合，javax.xml.bind.annotation.XmlMimeTypeアノテーションをアノテートする必要はありません。そのとき，MTOM/XOP仕様形式の添付ファイルで送信されるメッセージの添付ファイルパートにあるContent-Typeフィールドの値は，Java型に対応する初期値が使用されます。

javax.xml.bind.annotation.XmlMimeTypeアノテーションを使用しない例を次の図に示します。

図16‒20　javax.xml.bind.annotation.XmlMimeTypeアノテーションを使用しない例

javax.xml.bind.annotation.XmlMimeTypeアノテーションをアノテートし，MIMEタイプを関連づけることができるJava型とその指定個所を次の表に示します。なお，それ以外の型にjavax.xml.bind.annotation.XmlMimeTypeアノテーションをアノテートした場合の動作は保証されません。

表16‒17　MIMEタイプを関連づけることができるJava型とその指定個所

項番

Java型

関連づけの可否

指定個所

メソッド引数

メソッド戻り値

ユーザ定義型のフィールド

ユーザ定義例外のフィールド

1

java.awt.Image

○※1

○

○

△※2

×※3

2

javax.xml.transform.Source

○

○

○

△※2

×※3

3

javax.activation.DataHandler

○

○

○

△※2

×※3

4

java.awt.Imageの配列型

△※4

○

○

△※2

×※3

5

javax.activation.DataHandlerの配列型

△※4

○

○

△※2

×※3

6

java.util.List<Image>

○

○

○

△※2

×※3

7

java.util.List<DataHandler>

○

○

○

△※2

×※3

8

javax.xml.ws.Holder<Image>

○

○

×※5

×※5

×※5

9

javax.xml.ws.Holder<Source>

○

○

×※5

×※5

×※5

10

javax.xml.ws.Holder<DataHandler>

○

○

×※5

×※5

×※5

（凡例）

○：指定できます。

△：条件付きで指定できます。

×：指定できません。

注※1

JAXB仕様に従います。java.awt.ImageクラスはJava SE仕様でのグラフィカルイメージを表現する抽象クラスで，データ形式の規定はありません。この関連づけを使用して画像データをインスタンス化した場合，具象クラスのインスタンスには復号化した情報だけが保持される可能性があります。そのため，JPEG形式のように符号化するときに情報が削減される可能性のある画像を添付ファイルとして送信する場合，受信側のインスタンスが送信側のインスタンスや元のデータと異なることがあります。

画像を元の形式のまま扱いたい場合は，javax.activation.DataHandlerにマッピングされるMIMEタイプ（application/octet-streamなど）を使用してください。

注※2

JavaプロパティにMIMEタイプを関連づける場合，javax.xml.bind.annotation.XmlMimeTypeアノテーションをgetterメソッドにアノテートしてください。フィールドおよびsetterメソッドにアノテートした場合，動作は保証されません。JavaプロパティにMIMEタイプを関連づける例を次に示します。

package com.sample;

import java.awt.Image;

public class UserData {

    private Image image;

    public void setImage(Image image) {
        this.image = image;
    }

    @javax.xml.bind.annotation.XmlMimeType("image/png")
    public Image getImage() {
        return image;
    }
}

注※3

ユーザ定義例外のフィールドにjavax.xml.bind.annotation.XmlMimeTypeアノテーションを指定した場合，動作は保証されません。

注※4

1次元配列だけ使用でき，多次元配列は使用できません。多次元配列を使用した場合，動作は保証されません。

注※5

Holder型は引数にだけ指定できます。戻り値には指定できません。

(1)　value要素（javax.xml.bind.annotation.XmlMimeType）

value要素は，javax.xml.bind.annotation.XmlMimeTypeアノテーションをアノテートしたJava型に関連づけるMIMEタイプのテキスト表現を指定します。

指定するMIMEタイプは，アノテーションをアノテートしたJava型に対して適切なMIMEタイプでなければなりません。指定するMIMEタイプが適切ではない場合や複数のMIMEタイプをコンマ区切りで記述した場合，動作は保証されません。また，指定するMIMEタイプには，"text/xml"および"application/xml"のcharsetパラメタを除いて，パラメタを記述しないでください。"text/xml"および"application/xml"のcharsetパラメタ以外のパラメタを記述した場合，動作は保証されません。

Java型に指定できるMIMEタイプを次の表に示します。

表16‒18　Java型に指定できるMIMEタイプ

項番

Java型

value要素に指定できるMIMEタイプ

1

java.awt.Image，java.awt.Imageの配列型，java.util.List<Image>，またはjavax.xml.ws.Holder<Image>

image/png※1

2

image/jpeg※1

3

image/*※2

4

javax.xml.transform.Sourceまたはjavax.xml.ws.Holder<Source>

text/xml※3

5

application/xml

6

javax.activation.DataHandler，javax.activation.DataHandlerの配列型，java.util.List<DataHandler>，またはjavax.xml.ws.Holder<DataHandler>

上記以外※4

注※1

表中にないimageタイプを送信する場合は，javax.activation.DataHandlerクラスを使用して送信してください。

注※2

MIMEタイプに"image/*"を指定した場合，送信するSOAPメッセージの添付ファイルパートにあるMIMEヘッダのContent-Typeフィールドの値は，java.awt.Image型を使用したときの初期値（"image/png"）です。

注※3

MIMEタイプに"text/xml"を指定した場合，送信するSOAPメッセージの添付ファイルパートにあるMIMEヘッダのContent-Typeフィールドの値は，javax.xml.transform.Source型を使用したときの初期値（"application/xml"）です。

注※4

MIMEタイプに"application/*"や未知のMIMEタイプを指定した場合，送信するSOAPメッセージの添付ファイルパートにあるMIMEヘッダのContent-Typeフィールドの値は，javax.activation.DataHandler型を使用したときの初期値（javax.activation.DataHandlerオブジェクトのMIMEタイプ）です。

16.2.12　javax.xml.bind.annotation.XmlTypeアノテーション

javax.xml.bind.annotation.XmlTypeアノテーションは例外クラスに指定します。指定すると，生成されるフォルトbeanのjavax.xml.bind.annotation.XmlTypeアノテーションにマッピングされます。

javax.xml.bind.annotation.XmlTypeアノテーションを例外クラス以外で指定した場合の動作の保証はされません。

javax.xml.bind.annotation.XmlTypeアノテーションを使用したマッピング例を次の図に示します。

図16‒21　javax.xml.bind.annotation.XmlTypeアノテーションを使用したマッピング例

(1)　name要素（javax.xml.bind.annotation.XmlType）

name要素は，生成されるフォルトbeanのjavax.xml.bind.annotation.XmlTypeアノテーションのname要素にマッピングされます。

(2)　namespace要素（javax.xml.bind.annotation.XmlType）

namespace要素は，生成されるフォルトbeanのjavax.xml.bind.annotation.XmlTypeアノテーションのnamespace要素にマッピングされます。

(3)　propOrder要素（javax.xml.bind.annotation.XmlType）

propOrder要素は，生成されるフォルトbeanのプロパティ順序，およびフォルトbeanのjavax.xml.bind.annotation.XmlTypeアノテーションのpropOrder要素にマッピングされます。

propOrder要素には，例外クラスに存在するプロパティのプロパティ名のString型配列だけで指定できます。

propOrder要素を使用する場合の注意事項を次に示します。

プロパティの数が2個未満のとき，生成されるフォルトbeanのjavax.xml.bind.annotation. XmlTypeアノテーションのpropOrder要素はマッピングされません。

空文字（""）をプロパティ名として設定したとき，動作は保証されません。

16.2.13　javax.xml.ws.Actionアノテーション

javax.xml.ws.Actionアノテーションでは，オペレーションのinput，output，およびfaultの各メッセージでWebサービスが使用するアドレッシング・ヘッダのwsa:Action要素の値を指定できます。

javax.xml.ws.Actionアノテーションは，SEIでだけ指定できます。

javax.xml.ws.Actionアノテーションを使用したカスタマイズ例を次の図に示します。

図16‒22　javax.xml.ws.Actionアノテーションを使用したカスタマイズ例

(1)　fault要素（javax.xml.ws.Action）

fault要素には，Webサービスがフォルトメッセージを送信する場合に使用する，アドレッシング・ヘッダのwsa:Action要素の値（javax.xml.ws.FaultAction アノテーション）を指定します。nullや{null}を指定した場合の動作は保証されません。

fault要素はWebサービス開始時に参照されるだけです。hwsgenコマンドの実行時には解釈されません。

(2)　input要素（javax.xml.ws.Action）

input要素には，Webサービスがリクエストメッセージを受信する場合に使用するアドレッシング・ヘッダの，wsa:Action要素の値を指定します。input要素には，RFC 2396で規定されたxsd:anyURIを満たす文字を指定してください。それ以外の文字を指定した場合の動作は保証されません。

input要素に空白を指定した場合，空白がそのままアドレッシング・ヘッダのwsa:Action要素の値となります。空文字を指定した場合は，その指定は無視され，input要素を記述していないものと見なされます。

input要素はWebサービス開始時に参照されるだけです。hwsgenコマンドの実行時には解釈されません。

(3)　output要素（javax.xml.ws.Action）

output要素には，Webサービスがレスポンスメッセージを送信する場合に使用する，アドレッシング・ヘッダのwsa:Action要素の値を指定します。output要素には，RFC 2396で規定されたxsd:anyURIを満たす文字を指定してください。それ以外の文字を指定した場合の動作は保証されません。

output要素に空白を指定した場合，空白がそのままアドレッシング・ヘッダのwsa:Action要素の値となります。空文字を指定した場合は，その指定は無視され，output要素を記述していないものと見なされます。

output要素はWebサービス開始時に参照されるだけです。hwsgenコマンドの実行時には解釈されません。

16.2.14　javax.xml.ws.BindingTypeアノテーション

javax.xml.ws.BindingTypeアノテーションは，Webサービス実装クラスで指定するアノテーションです。SEIに指定した場合は無視されます。

(1)　value要素（javax.xml.ws.BindingType）

value要素には，javax.xml.ws.soap.SOAPBindingインタフェースの次に示すフィールド値が指定できます。

"SOAP11HTTP_BINDING"（SOAP1.1 over HTTP）

"SOAP12HTTP_BINDING"（SOAP1.2 over HTTP）

"SOAP11HTTP_MTOM_BINDING"（デフォルトでMTOM/XOP仕様形式の添付ファイルが有効であるSOAP1.1 over HTTP）

"SOAP12HTTP_MTOM_BINDING"（デフォルトでMTOM/XOP仕様形式の添付ファイルが有効であるSOAP1.2 over HTTP）

javax.xml.ws.BindingTypeアノテーションから，WSDLのwsdl:binding要素の子要素であるsoap:binding要素またはsoap12:binding要素のtransport属性値へのマッピングを次の表に示します。

表16‒19　BindingTypeアノテーションからtransport属性値へのマッピング

項番

SOAPバージョン

BindingTypeアノテーションの値

transport属性値

1

SOAP 1.1

http://schemas.xmlsoap.org/soap/http

または

@SOAPBinding.SOAP11HTTP_BINDING

http://schemas.xmlsoap.org/soap/http

2

http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true

または

@SOAPBinding.SOAP11HTTP_MTOM_BINDING

3

SOAP 1.2

http://www.w3.org/2003/05/soap/bindings/HTTP/

または

@SOAPBinding.SOAP12HTTP_BINDING

com.cosminexus.jaxws.publish_wsdl.soap12bindingプロパティの指定値によって，WSDLのtransport属性値が異なります。

4

http://www.w3.org/2003/05/soap/bindings/HTTP/?mtom=true

または

@SOAPBinding.SOAP12HTTP_MTOM_BINDING

com.cosminexus.jaxws.publish_wsdl.soap12bindingプロパティの指定値とWSDLのtransport属性値の関係を次の表に示します。

表16‒20　プロパティの指定値とWSDLのtransport属性値の関係

項番

プロパティ指定有無

プロパティ指定値

transport属性値

1

指定なし

なし

http://www.w3.org/2003/05/soap/bindings/HTTP/

2

指定あり

DEFAULT

3

WSI_BP20_TRANSPORT

http://schemas.xmlsoap.org/soap/http※

注※

transport属性値については標準仕様であいまいなため，JAX-WSではこのURLを使用できます。

16.2.15　javax.xml.ws.FaultActionアノテーション

javax.xml.ws.FaultActionアノテーションでは，Webサービスがフォルトメッセージを送信する場合に使用するアドレッシング・ヘッダのwsa:Action要素の値を指定します。

javax.xml.ws.FaultActionアノテーションが指定できるのは，javax.xml.ws.Actionアノテーションのfault要素内だけです。SEIやサービス実装クラスのメソッドに指定しても，無効となります。

(1)　className要素（javax.xml.ws.FaultAction）

className要素は，javax.xml.ws.FaultActionアノテーションの必須要素です。Webサービスが送信する例外クラスのクラス名を指定してください。className要素を指定しないと，Webサービス側のJAX-WSエンジンで例外が発生し，Webサービスを開始できません（KDJW40013-E）。

なお，className要素にWebサービスが送信する例外クラス以外を指定した場合は，動作は保証されません。

className要素はWebサービス開始時に参照されるだけです。hwsgenコマンドの実行時には解釈されません。

(2)　value要素（javax.xml.ws.FaultAction）

value要素には，className要素で指定した例外クラスのフォルトメッセージをWebサービスが送信する場合に使用するアドレッシング・ヘッダのwsa:Action要素の値を指定します。value要素には，RFC 2396で規定されたxsd:anyURIを満たす文字を指定してください。それ以外の文字を指定した場合の動作は保証されません。

value要素に空白を指定した場合，空白がそのままアドレッシング・ヘッダのwsa:Action要素の値となります。空文字を指定した場合は，その指定は無視され，value要素を記述していないものと見なされます。

value要素はWebサービス開始時に参照されるだけです。hwsgenコマンドの実行時には解釈されません。

16.2.16　javax.xml.ws.RequestWrapperアノテーション

javax.xml.ws.RequestWrapperアノテーションは，wrapperスタイルで指定できます。

javax.xml.ws.RequestWrapperアノテーションはSEIで指定するアノテーションです。

javax.xml.ws.RequestWrapperアノテーションを使用したカスタマイズ例を次の図に示します。

図16‒23　javax.xml.ws.RequestWrapperアノテーションを使用したカスタマイズ例

(1)　localName要素（javax.xml.ws.RequestWrapper）

localName要素は，リクエストwrapper要素のローカル名のマッピングをカスタマイズするときに指定します。localName要素に要素値を指定した場合，wrapper要素の型名もカスタマイズできます。

localName要素を指定するときの注意事項について説明します。

localName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

localName要素とオペレーション名は同じ名前にしてください。ただし，javax.xml.ws.RequestWrapperアノテーションが存在しない場合，またはjavax.xml.ws.RequestWrapperアノテーションのlocalName要素に空文字（""）が指定されている場合，同一かどうかの比較処理は行われません。

(2)　targetNamespace要素（javax.xml.ws.RequestWrapper）

targetNamespace要素は，リクエストwrapper要素の名前空間のマッピングをカスタマイズするときに指定します。

targetNamespace要素には，http://またはurn:のプロトコルを名前空間として指定します。指定できる名前空間の形式および文字列を示します。

プロトコル

名前空間のプロトコルは，http://またはurn:のプロトコルで記述してください。

名前空間の記述形式

名前空間には次に示す形式は記述できません。

クエリストリング（例）http://example.com/?a=b

アンカー（例）http://example.com/index.html#anchor

ポート番号（例）http://example.com:8080/

ユーザ名／パスワード（例）http://user:password@example.com

記述できる文字列

区切り文字のスラッシュ（/）またはピリオド（.）で区切られたセグメントには，次の表に示すすべての条件を満たす文字列を記述できます。ただし，バインディング宣言でカスタマイズする場合は，XML Schema仕様のxsd:NCName型として使用できる文字列を記述できます。

表16‒21　名前空間に記述できる文字列の条件（javax.xml.ws.RequestWrapper）

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z）だけを使用した文字列

http://鈴木.com

http://133.145.224.19/

http://[1080:2C14;D30:BA04:275:806:270C:418A]/

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列

http://xxx.com/abstract

動作は保証されません。

3

先頭が数字でない文字列

http://1xxx.com

(3)　className要素（javax.xml.ws.RequestWrapper）

className要素は，生成するリクエストbeanのクラス名を完全修飾名で指定します。

className要素を指定するときの注意事項について説明します。

className要素は半角英数字，アンダースコア（_），およびドルマーク（$）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

Java言語仕様で規定されるJava識別子の命名規則に従った値を指定してください。

(4)　partName要素（javax.xml.ws.RequestWrapper）

partName要素は，リクエストwrapper要素を参照するinputメッセージのパート名のマッピングをカスタマイズするときに指定します。

partName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

16.2.17　javax.xml.ws.ResponseWrapperアノテーション

javax.xml.ws.ResponseWrapperアノテーションは，wrapperスタイルで指定できます。

javax.xml.ws.ResponseWrapperアノテーションはSEIで指定するアノテーションです。Webサービス実装クラスに指定した場合は無視されます。

javax.xml.ws.ResponseWrapperアノテーションを使用したカスタマイズ例を次の図に示します。

図16‒24　javax.xml.ws.ResponseWrapperアノテーションを使用したカスタマイズ例

(1)　localName要素（javax.xml.ws.ResponseWrapper）

localName要素は，レスポンスwrapper要素のローカル名のマッピングをカスタマイズするときに指定します。localName要素に要素値を指定した場合，wrapper要素の型名もカスタマイズできます。

localName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

(2)　targetNamespace要素（javax.xml.ws.ResponseWrapper）

targetNamespace要素は，レスポンスwrapper要素の名前空間のマッピングをカスタマイズするときに指定します。

targetNamespace要素には，http://またはurn:のプロトコルを名前空間として指定します。指定できる名前空間の形式および文字列を示します。

プロトコル

名前空間のプロトコルは，http://またはurn:のプロトコルで記述してください。

名前空間の記述形式

名前空間には次に示す形式は記述できません。

クエリストリング（例）http://example.com/?a=b

アンカー（例）http://example.com/index.html#anchor

ポート番号（例）http://example.com:8080/

ユーザ名／パスワード（例）http://user:password@example.com

記述できる文字列

区切り文字のスラッシュ（/）またはピリオド（.）で区切られたセグメントには，次の表に示すすべての条件を満たす文字列を記述できます。

表16‒22　名前空間に記述できる文字列の条件（javax.xml.ws.ResponseWrapper）

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z）だけを使用した文字列

http://鈴木.com

http://133.145.224.19/

http://[1080:2C14;D30:BA04:275:806:270C:418A]/

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列

http://xxx.com/abstract

動作は保証されません。

3

先頭が数字でない文字列

http://1xxx.com

(3)　className要素（javax.xml.ws.ResponseWrapper）

className要素は，生成するレスポンスbeanのクラス名を完全修飾名で指定します。

className要素を指定するときの注意事項について説明します。

className要素はパッケージの区切り文字であるピリオド（.），半角英数字，アンダースコア（_），およびドルマーク（$）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

Java言語仕様で規定されるJava識別子の命名規則に従った値を指定してください。

(4)　partName要素（javax.xml.ws.ResponseWrapper）

partName要素は，レスポンスwrapper要素を参照するoutputメッセージのパート名をカスタマイズするときに指定します。

partName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

16.2.18　javax.xml.ws.ServiceModeアノテーション

javax.xml.ws.ServiceModeアノテーションでは，プロバイダがアクセスする対象がプロトコルメッセージのペイロード（SOAPボディ）だけなのか，プロトコルメッセージ全体（SOAPエンベロープ）なのかを指定します。

javax.xml.ws.ServiceModeアノテーションは，Webサービス開始時に参照されるだけです。hwsgenコマンドの実行時には解釈されません。

(1)　value要素（javax.xml.ws.ServiceMode）

value要素には，javax.xml.ws.Service.Mode.MESSAGEまたはjavax.xml.ws.Service.Mode.PAYLOADを指定します。デフォルト値はjavax.xml.ws.Service.Mode.PAYLOADです。

javax.xml.ws.Service.Mode.MESSAGEを指定するとプロトコルメッセージのすべてが，javax.xml.ws.Service.Mode.PAYLOADを指定するとプロトコルメッセージのペイロードだけが，プロバイダのインスタンスに渡されます。

16.2.19　javax.xml.ws.soap.Addressingアノテーション

javax.xml.ws.soap.Addressingアノテーションは，アドレッシング機能を使用する場合に必要です。

javax.xml.ws.soap.Addressingアノテーションについて，次に説明します。

Webサービス側

サービス実装クラスでだけ指定できます。

Webサービスクライアント側

ポートをインジェクトするフィールドまたはsetterメソッドに指定できます。詳細については，「10.21.1(4)　フィーチャの有効化」を参照してください。それ以外のフィールドやメソッドに指定した場合は無視されます。

javax.xml.ws.soap.Addressingアノテーションを使用したカスタマイズ例を次の図に示します。

図16‒25　javax.xml.ws.soap.Addressingアノテーションを使用したカスタマイズ例（Webサービス側）

(1)　enabled要素（javax.xml.ws.soap.Addressing）

enabled要素では，Webサービスでアドレッシング機能を有効にするかどうかを指定します。"true"を指定した場合はアドレッシング機能が有効に，"false"を指定した場合はアドレッシング機能は無効となります。デフォルト値は"true"です。

enabled要素はWebサービス開始時に参照されるだけです。hwsgenコマンドの実行時には解釈されません。

(2)　required要素（javax.xml.ws.soap.Addressing）

required要素では，Webサービスを呼び出す場合のリクエストメッセージに，アドレッシング・ヘッダを必須とするかどうかを指定します。"true"を指定した場合はアドレッシング・ヘッダが必須に，"false"を指定した場合はアドレッシング・ヘッダは任意となります。デフォルト値は"false"です。

required要素はWebサービス開始時に参照されるだけです。hwsgenコマンドの実行時には解釈されません。

(3)　responses要素（javax.xml.ws.soap.Addressing）

responses要素は，WS-Addressingが有効の場合に，エンドポイントが要求する応答エンドポイントの種別を指定します。responses要素に指定できる値を次の表に示します。

表16‒23　responses要素に指定できる値

項番

responses要素の値

説明

1

javax.xml.ws.soap.AddressingFeature.Responses.ALL

デフォルト値です。

すべてのURIを指定できます。

2

javax.xml.ws.soap.AddressingFeature.Responses.ANONYMOUS

匿名のURIだけを指定できます。

3

javax.xml.ws.soap.AddressingFeature.Responses.NON_ANONYMOUS

非匿名のURIだけを指定できます。

responses要素の要素値にjavax.xml.ws.soap.AddressingFeatures.Responses.ANONYMOUSを指定した場合，エンドポイントに送信するメッセージのアドレッシング・ヘッダのwsa:ReplyTo要素およびwsa:FaultTo要素に匿名URIを指定する必要があります。非匿名URIを指定すると，javax.xml.ws.WebServiceExceptionを返します。

responses要素の要素値にjavax.xml.ws.soap.AddressingFeatures.Responses.NON_ANONYMOUSを指定した場合，非匿名URIを指定する必要があります。匿名URIを指定すると，javax.xml.ws.WebServiceExceptionを返します。

デフォルトではjavax.xml.ws.soap.AddressingFeatures.Responses.ALLを指定した場合と同様で，すべてのURIを指定できます。

responses要素は，Webサービス開始時に参照されるだけです。hwsgenコマンドの実行時には解釈されません。

16.2.20　javax.xml.ws.soap.MTOMアノテーション

javax.xml.ws.soap.MTOMアノテーションは，MTOM/XOP仕様形式の添付ファイルを使用するWebサービスに指定します。

javax.xml.ws.soap.MTOMアノテーションについて，次に説明します。

Webサービス側

Webサービス実装クラスだけで指定できます。SEIに指定すると無視されます。また，プロバイダ実装クラス（javax.xml.ws.providerインタフェースを実装するクラス）に指定した場合は動作が保証されません。

Webサービスクライアント側

ポートをインジェクトするフィールドまたはsetterメソッドに指定できます。詳細については，「10.21.1(4)　フィーチャの有効化」を参照してください。それ以外のフィールドやメソッドに指定した場合は無視されます。

cjwsimportコマンドが生成するWebサービス実装クラスのスケルトンクラスを使用してMTOM/XOP仕様形式の添付ファイルを使用するWebサービスを作成する場合，Webサービス実装クラスのスケルトンクラスにはjavax.xml.ws.soap.MTOMアノテーションをマッピングしないので，javax.xml.ws.soap.MTOMアノテーションを指定する必要があります。なお，Webサービス実装クラスにjavax.xml.ws.soap.MTOMアノテーションを指定しても，Webサービス側のJAX-WSエンジンが発行するWSDLファイルやhwsgenコマンドが生成するWSDLファイルには，MTOM/XOP仕様形式の添付ファイルが使用されていることを示す要素や属性は出現しません。

javax.xml.ws.soap.MTOMアノテーションは，Webサービス開始時に参照されるだけです。hwsgenコマンドの実行時には解釈されません。

Webサービス側でjavax.xml.ws.soap.MTOMアノテーションを使用した例を次に示します。

・・・・・
@MTOM
@WebService(endpointInterface = "jaxwstp.example.service.ExamplePortType", targetNamespace = "http://service.example.jaxwstp/", serviceName = "ExampleService", portName = "ExamplePort")
public class ExampleBinding implements ExamplePortType {

(1)　enabled要素（javax.xml.ws.soap.MTOM）

enabled要素は，WebサービスでMTOM/XOP仕様形式の添付ファイルを使用するかどうかを指定します。"true"を指定した場合はMTOM/XOP仕様形式の添付ファイルが使用でき，"false"を指定した場合はMTOM/XOP仕様形式の添付ファイルが使用できません。デフォルト値は"true"です。

(2)　threshold要素（javax.xml.ws.soap.MTOM）

threshold要素は，WebサービスでMTOM/XOP仕様形式の添付ファイルが使用できるときに，バイナリデータをMTOM/XOP仕様形式の添付ファイルとして送信するためのしきい値です。javax.activation.DataHandlerクラス以外で，さらに指定された値を超えるバイナリデータ（threshold要素値≦送信するデータのサイズ）の場合，MTOM/XOP仕様形式の添付ファイルとして送信されます。デフォルト値は"0"です。

16.2.21　javax.xml.ws.WebFaultアノテーション

javax.xml.ws.WebFaultアノテーションは，戻り値のマッピングをカスタマイズするときに使用できます。

javax.xml.ws.WebFaultアノテーションを使用したカスタマイズ例を次の図に示します。

図16‒26　javax.xml.ws.WebFaultアノテーションを使用したカスタマイズ例

(1)　name要素（javax.xml.ws.WebFault）

name要素は，フォルトbeanからマッピングするグローバル要素のローカル名をカスタマイズするときに使用します。

name要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

(2)　targetNamespace要素（javax.xml.ws.WebFault）

targetNamespace要素は，フォルトbeanからマッピングするグローバル要素の名前空間をカスタマイズするときに指定します。

targetNamespace要素には，http://またはurn:のプロトコルを名前空間として指定します。指定できる名前空間の形式および文字列を示します。

プロトコル

名前空間のプロトコルは，http://またはurn:のプロトコルで記述してください。

名前空間の記述形式

名前空間には次に示す形式は記述できません。

クエリストリング（例）http://example.com/?a=b

アンカー（例）http://example.com/index.html#anchor

ポート番号（例）http://example.com:8080/

ユーザ名／パスワード（例）http://user:password@example.com

記述できる文字列

区切り文字のスラッシュ（/）またはピリオド（.）で区切られたセグメントには，次の表に示すすべての条件を満たす文字列を記述できます。ただし，バインディング宣言でカスタマイズする場合は，XML Schema仕様のxsd:NCName型として使用できる文字列を記述できます。

表16‒24　名前空間に記述できる文字列の条件（javax.xml.ws.WebFault）

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z）だけを使用した文字列

http://鈴木.com

http://133.145.224.19/

http://[1080:2C14;D30:BA04:275:806:270C:418A]/

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語以外の文字列

http://xxx.com/abstract

動作は保証されません。

3

先頭が数字でない文字列

http://1xxx.com

(3)　faultBean要素（javax.xml.ws.WebFault）

faultBean要素は，生成するフォルトbeanのクラス名を完全修飾名で指定します。ラッパ例外クラスが，javax.xml.ws.WebFaultアノテーションおよびフォルトbeanを返すgetFaultInfoメソッドを持つ場合，faultBean要素を指定しても，フォルトbeanは生成されません。

faultBean要素を指定するときの注意事項について説明します。

faultBean要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

Java言語仕様で規定されるJava識別子の命名規則に従った値を指定してください。

(4)　messageName要素（javax.xml.ws.WebFault）

messageName要素は，ラッパ例外クラスに対応するフォルトメッセージ名（wsdl:fault要素から参照されるwsdl:message要素のname属性）をカスタマイズするときに指定します。

messageName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

16.2.22　javax.xml.ws.WebServiceProviderアノテーション

javax.xml.ws.WebServiceProviderアノテーションは，javax.xml.ws.providerインタフェースを実装するクラスに指定し，プロバイダの要件を満たすクラスがWebサービスのエンドポイントを定義していることを宣言します。

javax.xml.ws.WebServiceProviderアノテーションとjavax.jws.WebServiceアノテーションは，どちらか一方しか指定できません。

javax.xml.ws.WebServiceProviderアノテーションは，Webサービス開始時に参照されるだけです。hwsgenコマンドの実行時には解釈されません。

(1)　targetNamespace要素（javax.xml.ws.WebServiceProvider）

targetNamespace要素には，http://またはurn:のプロトコルを名前空間として指定します。指定できる名前空間の形式および文字列を示します。

プロトコル

名前空間のプロトコルは，http://またはurn:のプロトコルで記述してください。

名前空間の記述形式

名前空間には次に示す形式は記述できません。

クエリストリング（例）http://example.com/?a=b

アンカー（例）http://example.com/index.html#anchor

ポート番号（例）http://example.com:8080/

ユーザ名／パスワード（例）http://user:password@example.com

記述できる文字列

区切り文字のスラッシュ（/）またはピリオド（.）で区切られたセグメントには，次の表に示すすべての条件を満たす文字列を記述できます。

表16‒25　名前空間に記述できる文字列の条件（javax.xml.ws.WebServiceProvider）

項番

条件

不正な文字列の例

不正な文字列を指定した場合の動作

1

半角英数字（0〜9，A〜Z，a〜z）だけを使用した文字列

http://鈴木.com/

http://133.145.224.19/

http://[1080:2C14;D30:BA04:275:806:270C:418A]/

動作は保証されません（エラーメッセージは出力されません）。

2

Javaの予約語でない文字列

http://xxx.com/abstract

動作は保証されません。

3

先頭が数字でない文字列

http://1xxx.com/

(2)　serviceName要素（javax.xml.ws.WebServiceProvider）

serviceName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合の動作は保証されません（エラーメッセージは出力されません）。

(3)　portName要素（javax.xml.ws.WebServiceProvider）

portName要素は半角英数字とアンダースコア（_）で指定します。それ以外の文字を指定した場合，動作は保証されません（エラーメッセージは出力されません）。

(4)　wsdlLocation要素（javax.xml.ws.WebServiceProvider）

wsdlLocation要素については，「10.6　メタデータの発行」を参照してください。

17　Webリソースとプロバイダ

この章では，RESTful Webサービス（Webリソース）のリソースクラスとプロバイダのサポート範囲について説明します。

17.1　リソースクラス

リソースクラスのリソースメソッド，サブリソースメソッド，およびサブリソースロケータの違い，ならびにルートリソースクラスとサブリソースクラスの違いについて説明します。

リソースクラスのリソースメソッド，サブリソースメソッド，およびサブリソースロケータは，Pathアノテーション，および要求メソッド識別子の有無によって定義されます。それぞれの定義を次に示します。

表17‒1　リソースメソッド，サブリソースメソッド，およびサブリソースロケータの定義

項番

メソッドまたはロケータ

Pathアノテーション

要求メソッド識別子

1

リソースメソッド

×

○

2

サブリソースメソッド

○

○

3

サブリソースロケータ

○

×

（凡例）

○：使用できることを示します。

×：使用できないことを示します。

ルートリソースクラスのインスタンスは，JAX-RSエンジンによって生成されます。このとき，コンストラクタのパラメタ，フィールド，およびbeanプロパティにはJAX-RS仕様に従ってインジェクトされます。

一方，サブリソースクラスのインスタンスは，JAX-RSエンジンによって生成されません。サブリソースクラスは，対応するサブリソースロケータでインスタンス化する必要があります。このため，コンストラクタのパラメタ，フィールド，およびbeanプロパティの初期化は，サブリソースロケータ，またはサブリソースクラスで行う必要があります。

17.1.1　ルートリソースクラス

ルートリソースクラスは，リソースメソッド，サブリソースメソッド，またはサブリソースロケータのどれかを一つ以上持ち，クラスレベルでPathアノテーションでアノテートされたJavaのpublicのクラスです。

リソースメソッドとサブリソースロケータを持つルートリソースクラスの例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

//ルートリソースクラス
@Path("/root")
public class Resource2 {

  //コンテキストルート+ "/root/sub1"への要求に対応するサブリソースロケータ
  @Path("/sub1")
  public SubResource1 subResourceLocator1() {
    //処理するサブリソースクラスのインスタンスを戻す
    return new SubResource1();
  }

  //コンテキストルート+ "/root/sub2"への要求に対応するサブリソースロケータ
  @Path("/sub2")
  public SubResource2 subResourceLocator2() {
    //処理するサブリソースクラスのインスタンスを戻す
    return new SubResource2();
}
  //リソースメソッド
  @GET
  public String getValue() {
    String returnValue = "";
    //戻り値を構築する
    return returnValue;
  }

}

com.sample.resources.Resource2はルートリソースクラスです。クラスレベルでPathアノテーションでアノテートされていることに注意してください。このルートリソースクラスは，二つのサブリソースロケータsubResourceLocator1()とsubResourceLocator2()およびHTTP GETリクエストを処理するリソースメソッドgetValue()を持ちます。サブリソースロケータがPathアノテーションでアノテートされ，リソースメソッドが要求メソッド識別子でアノテートされていることに注意してください。二つのクラスSubResource1とSubResource2はサブリソースクラスです。詳細は，次の項目を参照してください。

「17.1.1(4)　リソースメソッド」

「17.1.1(5)　サブリソースメソッド」

「17.1.1(6)　サブリソースロケータ」

「17.1.7　サブリソースクラス」

サブリソースメソッドを持つルートリソースクラスの例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

// ルートリソースクラス
@Path("/root")
public class Resource3 {

  // コンテキストルート+ "root/sub1"への要求に対応するサブリソースメソッド
  @Path("/sub1")
  @GET
  public String subResourceMethod1() {
    String value = "";
    // 処理を実行して，実行結果を返す
    return value;
  }

  // コンテキストルート+ "root/sub2"への要求に対応するサブリソースメソッド
  @Path("/sub2")
  @GET
  public String subResourceMethod2() {
    String value = "";
    // 処理を実行して，実行結果を返す
    return value;
  }
}

com.sample.resources.Resource3はルートリソースクラスです。このルートリソースクラスは，二つのサブリソースメソッドsubResourceMethod1()とsubResourceMethod2()を持ちます。サブリソースメソッドは，Pathアノテーションと要求メソッドの両方でアノテートされます。

PathアノテーションのURLにアスタリスク（*）を指定されている場合は，リソースメソッドだけを呼び出すことができます。サブリソースメソッド，およびサブリソースロケータを呼び出した場合は，例外マッピングプロバイダで処理できるjava.lang.StringIndexOutOfBoundsExceptionがスローされます。

(1)　ライフサイクル

JAX-RSエンジンは，Webリソースに対する要求ごとにルートリソースクラスをインスタンス化します。ルートリソースクラスのライフサイクルは次のとおりです。

コンストラクタが呼び出される

必要なインジェクションが行われる

適切なメソッドが呼び出される

GC（ガーベージコレクション）の対象になる

(2)　コンストラクタ

ルートリソースクラスは，publicデフォルトコンストラクタ（明示的に宣言されないコンストラクタ）も含めて，少なくとも一つ以上のpublicコンストラクタを持つ必要があります。

パラメタを持つpublicコンストラクタの例を次に示します。

package com.sample.resources;

import javax.ws.rs.DefaultValue;
import javax.ws.rs.Encoded;
import javax.ws.rs.QueryParam;
import javax.ws.rs.Path;
import javax.ws.rs.GET;

//ルートリソースクラス
@Path("/root")
public class Resource1 {
  private String query1;

  //パラメタを持つpublicコンストラクタ
  public Resource1(@Encoded @DefaultValue("abc") @QueryParam("query") String query){
    this.query1 = query;
  }

  //リソースメソッド
  @GET
  public String getValue() {
    return "Your requested query parameter ¥"query¥" is: " + this.query1;
  }
}

この例では，ルートリソースクラスcom.sample.resources.Resource1は，QueryParamアノテーションでアノテートされたパラメタqueryを持つpublicコンストラクタResource1()によってインスタンス化されます。

パラメタqueryを自動でURLデコードされるのを無効化するためにEncodedアノテーションが使用されています。また，クライアントから送信された要求にパラメタqueryにインジェクトする値がない場合のデフォルト値を指定するためにDefaultValueアノテーションが組み合わされて使用されています。

パラメタを持たないpublicコンストラクタの例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

//ルートリソースクラス
@Path("/root")
public class Resource2 {
  //パラメタを持たないpublicコンストラクタ
  public Resource2() {
    // 処理を実行する
  }

 //リソースメソッド
  @GET
  public String getValue(){
    return "Your request was accepted.";
  }
}

この例では，ルートリソースクラスcom.sample.resources.Resource2は，パラメタを持たないpublicコンストラクタResource2()によってインスタンス化されます。

パラメタを持つpublicコンストラクタが一つ以上宣言されている例を次に示します。

package com.sample.resources;

import javax.ws.rs.Encoded;
import javax.ws.rs.MatrixParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.QueryParam;

//ルートリソースクラス
@Path("/root/")
public class Resource3 {
  private String matrix1;
  private String query1;

  //パラメタを持たないpublicコンストラクタ
  public Resource3() {
    // 処理を実行する
  }

  //パラメタを持つpublicコンストラクタ（1番目）
  @Encoded
  public Resource3(@MatrixParam("matrix1") String matrix1) {
    this.matrix1 = matrix1;
  }

  //パラメタを持つpublicコンストラクタ（2番目）
  @Encoded
  public Resource3(@FormParam("form1") String form1,
      @QueryParam("query1") String query1) {
    this.form1 = form1;
    this.query1 = query1;
  }

  //リソースメソッド
  @GET
  public String getValue() {
    return "Your requested matrix parameter ¥"matrix1¥" is: " + this.matrix1 +  "¥n" +
      "Your requested query parameter ¥"query1¥" is: " + this.query1;
  }
}

この例では，ルートリソースクラスcom.sample.resources.Resource3は，それぞれMatrixParamアノテーションおよびQueryParamアノテーションでアノテートされたパラメタmatrix1およびパラメタquery1を持つ，2番目のpublicコンストラクタによってインスタンス化されます。

パラメタmatrix1とパラメタquery1を自動でURLデコードされるのを無効化するために，Encodedアノテーションがコンストラクタのレベルで使用されています。

デフォルトコンストラクタの例を次に示します。

package com.sample.resources;

import javax.ws.rs.FormParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;

//ルートリソースクラス
@Path("/root")
public class Resource4 {

  //リソースメソッド
  @POST
  public String getValue(@FormParam("form1") String form1) {
    return "Your requested form parameter ¥"form1¥" is: " + form1;
  }
}

この例では，ルートリソースクラスcom.sample.resources.Resource4は，暗黙的に宣言されているデフォルトコンストラクタResource4()によってインスタンス化されます。

デフォルトコンストラクタでjava.io.IOExceptionが発生した場合，エラーとなり（KDJJ10039-E），ルートリソースクラスはインスタンス化されません。HTTPステータスコードには500が返されます。

publicコンストラクタが一つも宣言されていない場合，エラーとなり（KDJJ10006-E），ルートリソースクラスはインスタンス化されません。HTTPステータスコードには500が返されます。

なお，次に示すコンストラクタはpublicコンストラクタではありません。

privateコンストラクタ

protectedコンストラクタ

アクセス識別子を持たないコンストラクタ

コンストラクタのパラメタで使用できるインジェクション用アノテーションと，オプションのアノテーションの組み合わせを次の表に示します。

表17‒2　コンストラクタのパラメタで使用できるアノテーション

項番

インジェクション用アノテーション

オプションのアノテーション

Encoded

DefaultValue

1

MatrixParam

○

○

2

QueryParam

○

○

3

PathParam

○

×

4

CookieParam

×

○

5

HeaderParam

×

○

6

FormParam

×

○

7

Context

×

×

（凡例）

○：インジェクション用アノテーションと組み合わせて使用できることを示します。

×：インジェクション用アノテーションが使用できないことを示します。

オプションのEncodedアノテーションを使用すると，インジェクション対象のコンストラクタのパラメタが自動でURLデコードされるのを無効化できます。

オプションのDefaultValueアノテーションを使用すると，インジェクション対象のコンストラクタのパラメタにインジェクトする値がない場合に仮定されるデフォルト値を指定できます。

ルートリソースクラスがパラメタを持つpublicコンストラクタを一つ以上持つ場合，JAX-RSエンジンは，最もパラメタ数が多いコンストラクタを使用してルートリソースクラスをインスタンス化します。最もパラメタ数が多いコンストラクタを二つ以上持つ場合，最初に定義されているコンストラクタを使用してルートリソースクラスをインスタンス化します。このとき，警告メッセージがログに出力されます（KDJJ20010-W）。

次のどちらかの場合，HTTPリクエストは処理されません。HTTPステータスコードには500が返されます。なお，ログを確認するときは，JAX-RS機能のログファイルではなくJ2EEサーバのログファイルを確認してください。

ルートリソースクラスのコンストラクタのパラメタのうち，インジェクション用アノテーションとDefaultValueアノテーションが使用されているパラメタで，JAX-RSエンジンがインジェクトするときにランタイム例外が発生した場合

ルートリソースクラスのデフォルトコンストラクタでjava.lang.InstantiationException，java.lang.IllegalAccessException，java.lang.reflect.InvocationTargetException，またはjava.io.IOExceptionのどれでもないチェック済み例外（ランタイム例外でない例外）が発生した場合

(3)　フィールドおよびbeanプロパティ

ルートリソースクラスのフィールドおよびbeanプロパティで使用できるインジェクション用アノテーションと，オプションのアノテーションの組み合わせを次の表に示します。JAX-RSエンジンは，ルートリソースクラスをインスタンス化する際に，アノテーションに基づいてアノテートされたフィールドおよびbeanプロパティに値をインジェクトします。なお，Beanプロパティは，読み取り専用プロパティでなくても構いません。

表17‒3　フィールドおよびbeanプロパティで使用できるアノテーション

項番

インジェクション用アノテーション

オプションのアノテーション

Encoded

DefaultValue

1

MatrixParam

○

○

2

QueryParam

○

○

3

PathParam

○

×

4

CookieParam

×

○

5

HeaderParam

×

○

6

FormParam

×

○

7

Context

×

×

（凡例）

○：インジェクション用のアノテーションと組み合わせて使用できることを示します。

×：インジェクション用のアノテーションが使用できないことを示します。

オプションのEncodedアノテーションを使用すると，インジェクション対象のフィールドまたはbeanプロパティが自動でURLデコードされるのを無効化できます。

オプションのDefaultValueアノテーションを使用すると，インジェクション対象のフィールドまたはbeanプロパティにインジェクトする値がない場合に仮定されるデフォルト値を指定できます。

ルートリソースクラスのフィールドでDefaultValueアノテーションを使用する例を次に示します。

private @DefaultValue("value1") @QueryParam("id") String id;

この例では，クエリパラメタidがURLに指定されていない場合，フィールドidは"value1"になります。

ルートリソースクラスのbeanプロパティでDefaultValueアノテーションを使用する例を次に示します。

private String property1;

@DefaultValue("10") @QueryParam("prop1")
public void setProperty1(String property1) {
  this.property1 = property1;
}

この例では，クエリパラメタprop1がURIに指定されていない場合，beanプロパティproperty1の値は"10"になります。

ルートリソースクラスのフィールドでEncodedアノテーションを使用する例を次に示します。

private @Encoded @QueryParam("id") String id;

この例では，フィールドidの値は，自動でURLデコードされません。

ルートリソースクラスのbeanプロパティでEncodedアノテーションを使用する例を次に示します。

private String property1;

@Encoded @QueryParam("prop1")
public void setProperty1(String property1) {
  this.property1 = property1;
}

この例では，beanプロパティproperty1の値は，自動でURLデコードされません。

ルートリソースクラスのフィールド，またはbeanプロパティのうち，インジェクション用アノテーションとDefaultValueアノテーションが使用されているパラメタで，JAX-RSエンジンがインジェクトするときにランタイム例外が発生した場合，HTTPリクエストは処理されません。HTTPステータスコードには500が返されます。なお，ログを確認するときは，JAX-RS機能のログファイルではなくJ2EEサーバのログファイルを確認してください。

(4)　リソースメソッド

リソースメソッドは，JAX-RS仕様で定義された要求メソッド識別子のどれかでアノテートされた，ルートリソースクラスのメソッドです。ルートリソースクラスは，一つ以上のリソースメソッドを持つことができます。

JAX-RS仕様で定義された要求メソッド識別子を次に示します。

GETアノテーション

POSTアノテーション

PUTアノテーション

DELETEアノテーション

HEADアノテーション

OPTIONSアノテーション

一つのリソースメソッドに対し，二つ以上の要求メソッド識別子を使用している場合，エラーとなり（KDJJ10006-E），ルートリソースクラスはインスタンス化されません。HTTPステータスコードには500が返されます。

二つ以上のリソースメソッドに対し，同じ要求メソッド識別子を使用している場合，エラーとなり（KDJJ10006-E），ルートリソースクラスはインスタンス化されません。HTTPステータスコードには500が返されます。

HTTPリクエストに対し，ディスパッチするリソースメソッドが一つもない場合，HTTPステータスコードに405が設定された，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。

リソースメソッドで要求メソッド識別子を使用している例を次に示します。

@GET
@Encoded
@Produces("text/plain")
public String echo(@QueryParam("id") String id){
  return "ID is: " + id;
}

この例では，echo()メソッドがGET要求メソッド識別子でアノテートされています。また，echo()メソッドは，Content-Typeが"text/plain"であるHTTPレスポンスを返すために，"text/plain"を値に持つProducesアノテーションでアノテートされています。なお，パラメタidは，クエリパラメタidを受け取るQueryParamアノテーションでアノテートされ，さらにクエリパラメタが自動でURLデコードされるのを無効化するためにEncodedアノテーションでアノテートされています。

(a)　可視性

リソースメソッドは，要求メソッド識別子が適用されたpublicメソッドである必要があります。次に示すメソッドは，要求メソッド識別子でアノテートされていてもリソースメソッドではありません。

Privateメソッド

Protectedメソッド

アクセス識別子を持たないメソッド

要求メソッド識別子を上記のメソッドのどれかに適用した場合，警告メッセージまたはエラーメッセージがログに出力されます（KDJJ20003-WまたはKDJJ10006-E）。KDJJ20003-WおよびKDJJ10006-Eについては，「13.7.1　Webリソース初期化時の構文チェック（KDJJ20003-WとKDJJ10006-E）」を参照してください。

(b)　パラメタのアノテーション

リソースメソッドのパラメタで使用できるインジェクション用アノテーションと，オプションのアノテーションの組み合わせを次の表に示します。

表17‒4　リソースメソッドのパラメタで使用できるアノテーション

項番

インジェクション用アノテーション

オプションのアノテーション

Encoded

DefaultValue

1

MatrixParam

○

○

2

QueryParam

○

○

3

PathParam

○

×

4

CookieParam

×

○

5

HeaderParam

×

○

6

FormParam

×

○

7

Context

×

×

（凡例）

○：インジェクション用のアノテーションと組み合わせて使用できることを示します。

×：インジェクション用のアノテーションが使用できないことを示します。

オプションのEncodedアノテーションを使用すると，インジェクション対象のリソースメソッドのパラメタが自動でURLデコードされるのを無効化できます。

オプションのDefaultValueアノテーションを使用すると，インジェクション対象のリソースメソッドのパラメタにアノテートされるアノテーションのデフォルト値を指定できます。

リソースメソッドのパラメタでアノテーションを使用する例を次に示します。

@GET
@Produces("text/plain")
public String echo(@Encoded @DefaultValue("10") @QueryParam("id") String id, @Encoded @MatrixParam("matrix1") String matrix1){
  return "ID is: " + id + "¥nMatrix1 is: " + matrix1;
}

この例では，リソースメソッドecho()は，QueryParamアノテーションでアノテートされたパラメタidおよびMatrixParamアノテーションでアノテートされたパラメタmatrix1を含みます。パラメタidは，自動でURLデコードされるのを無効化し，デフォルト値を指定するために，さらにEncodedアノテーションおよびDefaultValueアノテーションでアノテートされています。matrixパラメタは，さらに自動でURLデコードされるのを無効化するためにEncodedアノテーションでアノテートされています。

ルートリソースクラスのリソースメソッド，またはサブリソースメソッドのパラメタのうち，インジェクション用アノテーションとDefaultValueアノテーションが使用されているパラメタで，JAX-RSエンジンがインジェクトするときにランタイム例外が発生した場合，エラーとなり（KDJJ10009-E，KDJJ10006-E），HTTPリクエストは処理されません。HTTPステータスコードには500が返されます。

(c)　エンティティパラメタ

エンティティパラメタの説明については，「17.1.2　エンティティパラメタ」を参照してください。

(d)　戻り値

戻り値の説明については，「17.1.3　戻り値」を参照してください。

(5)　サブリソースメソッド

Pathアノテーションでアノテートされたリソースメソッドを，特に，サブリソースメソッドと呼びます。サブリソースメソッドとリソースメソッドの違いは，Pathアノテーションを使用しているかどうかだけです。

サブリソースメソッドの例を次に示します。

package com.sample.resources;

import javax.ws.rs.POST;
import javax.ws.rs.Path;

//ルートリソースクラス
@Path("/root/")
public class Resource1 {

  //サブリソースメソッド
  @Path("sub1")
  @POST
  public String doSomething(String entityBody) {
    return "By Sub-Resource Method.";
  }

  //リソースメソッド
  @POST
  public String doOthers(String entityBody){
    return "By Resource Method.";
  }
}

この例では，doSomething()メソッドがサブリソースメソッドです。ルートリソースクラスcom.sample.resources.Resource1を含むWebアプリケーション（WARファイル）のコンテキストルートが，"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。その場合，URL"http://sample.com/example/root/sub1"に対するHTTP POST要求は，サブリソースメソッドdoSomething()にディスパッチされます。

一方，URL"http://sample.com/example/root"に対するHTTP POST要求は，リソースメソッドdoOthers()にディスパッチされます。

(6)　サブリソースロケータ

要求メソッド識別子が適用されていない，Pathアノテーションだけでアノテートされたルートリソースクラスのメソッドをサブリソースロケータと呼びます。

サブリソースロケータは，HTTPリクエストに対する残りの処理を行うサブリソースクラスを返します。サブリソースクラスについては，「17.1.7　サブリソースクラス」を参照してください。

ルートリソースクラスのサブリソースロケータの例を次に示します。

package com.sample.resources;

import javax.ws.rs.Encoded;
import javax.ws.rs.QueryParam;
import javax.ws.rs.PathParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

//ルートリソースクラス
@Path("/root/")
public class Resource {

  //コンテキストルート+ "/root/sub1"への要求に対応するサブリソースロケータ
  @Path("sub1")
  public SubResource getRequestHandler(@PathParam("id") String id,
      @Encoded @QueryParam("query1") String query1) {
    return new SubResource(id, query1);
  }
}

対応するサブリソースクラスの例を次に示します。

//サブリソースクラス
public class SubResource {
  private String id;
  private String query;

  public SubResource(String id, String query){
    this.id = id;
    this.query = query;
  }
  @GET
  public String getRequestParameter(){
    return "ID is: " + this.id + "¥nQuery is: " + this.query;
  }
}

この例では，ルートリソースクラスcom.sample.resources.Resourceは，HTTPリクエストを直接処理しません。サブリソースロケータgetRequestHandlerが返すサブリソースクラスは，com.sample.resources.SubResourceが処理します。

リソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。その場合，URL"http://sample.com/example/root/sub1?query1=10"に対するHTTP GETリクエストは，ルートリソースクラスcom.sample.resources.ResourceのメソッドgetRequestHandler()にディスパッチされます。

HTTP GETリクエストに対する残りの処理は，サブリソースクラスcom.sample.resources.SubResourceのリソースメソッドgetRequestParameter()によって処理されます。

サブリソースロケータのパラメタとしてエンティティパラメタを使用した場合，エラーとなり（KDJJ10006-E），クライアントからのHTTPリクエストは処理されません。HTTPステータスコードには500が返されます。

サブリソースロケータがpublicでない場合の動作は，リソースメソッドと同じです。

サブリソースロケータの戻り値の型がvoidの場合，エラーとなり（KDJJ10006-E），クライアントからのHTTPリクエストは処理されません。HTTPステータスコードには500が返されます。

サブリソースロケータのパラメタのうち，インジェクション用アノテーションとDefaultValueアノテーションが使用されているパラメタで，JAX-RSエンジンがインジェクトするときにランタイム例外が発生した場合，HTTPリクエストは処理されません。HTTPステータスコードには500が返されます。なお，ログを確認するときは，JAX-RS機能のログファイルではなくJ2EEサーバのログファイルを確認してください。

17.1.2　エンティティパラメタ

リソースメソッドのパラメタのうち，アノテーションでアノテートされていないパラメタをエンティティパラメタと呼びます。エンティティパラメタの値は，HTTPエンティティボディです。

リソースメソッドでエンティティパラメタを使用する例を次に示します。

@POST
public String getRequestParameters(@MatrixParam("matrix") String matrix,
    String entity) {
  return "Matrix is:" + matrix + "¥mEntity Body is: " + entity;
}

この例では，リソースメソッドgetRequestParameters()は，MatrixParamアノテーションでアノテートされたパラメタmatrixと，アノテートされていないパラメタ（エンティティパラメタ）entityを持っています。エンティティボディの内容が"Entity Content"であるHTTPリクエストを受信した場合，エンティティパラメタentityの値は"Entity Content"になります。

(1)　エンティティパラメタに使用できるJavaの型とMIMEメディアタイプの組み合わせ

エンティティパラメタに使用できるJavaの型とMIMEメディアタイプの組み合わせを次の表に示します。なお，POJOにJAXB仕様のアノテーションは使用しないでください。使用した場合，説明とは異なる動作になるおそれがあります。

表17‒5　エンティティパラメタに使用できるJavaの型とMIMEメディアタイプの組み合わせ

項番

Javaの型

charset※1

MIMEメディアタイプ

1

byte[]

×

任意(*/*)

2

java.lang.String

○

任意(*/*)

3

java.io.InputStream

×

任意(*/*)

4

java.io.Reader

○

任意(*/*)

5

java.io.File※2

○

任意(*/*)

6

javax.activation.DataSource

○

任意(*/*)

7

javax.xml.transform.Source※3

×

text/xml，

application/xml，

application/*+xml

8

javax.xml.bind.JAXBElement<String>※4

×

text/xml，

application/xml，

application/*+xml

9

XmlRootElementアノテーションおよび/またはXmlTypeアノテーションでアノテートされたJAXBクラス※4

×

text/xml，

application/xml，

application/*+xml

10

javax.ws.rs.core.MultivaluedMap<String,String>

○

application/x-www-form-urlencoded

11

org.w3c.dom.Document

×

text/xml，

application/xml，

application/*+xml

12

java.util.List<T>※5

×

text/xml，

application/xml，

application/*+xml

13

java.awt.image.RenderedImage

×

application/octet-stream，

image/jpeg

14

com.cosminexus.jersey.core.provider.EntityHolder<T>※6

△

Tに指定した型と同じMIMEメディアタイプです。

15

POJO※7

○

application/json

（凡例）

任意(*/*)：すべてのMIMEメディアタイプをサポートしていることを示します。

注※1

Content-Type HTTPヘッダにcharsetパラメタが含まれる場合，エンティティパラメタにインジェクトされるときにその情報が考慮されるかどうかを示します。

○：考慮されます。Content-Type HTTPヘッダにcharsetパラメタが含まれない場合は，UTF-8が仮定されます。

△：Tに指定した型に依存します。

×：考慮されません。

なお，Consumesアノテーションの値にcharsetパラメタが含まれていても無視されます。

注※2

JAX-RSエンジンは，J2EEサーバの環境にtempディレクトリを作成し，一時ファイルを保存します。J2EEサーバの環境はcjsetupコマンドを使用して構築します。cjsetupコマンドについては，マニュアル「アプリケーションサーバ リファレンスコマンド編」の「cjsetup（J2EEサーバのセットアップとアンセットアップ）」を参照してください。

注※3

次に示す実装クラスを使用できます。

・javax.xml.transform.stream.StreamSource

・javax.xml.transform.sax.SAXSource

・javax.xml.transform.dom.DOMSource

注※4

MIMEメディアタイプがapplication/fastinfosetまたはapplication/jsonの場合，エラーにならないで正常終了します。

注※5

TにはXmlRootElementアノテーションおよび/またはXmlTypeアノテーションでアノテートされたJAXBクラスを指定できます。

注※6

Tにはこの表の項番2から項番13，および項番15の型を指定できます。

注※7

JSON POJOマッピングを有効にしてください。JSON POJOマッピングが有効でない場合の動作は，サポートされないJava型がエンティティパラメタに指定された場合の動作と同じです。JSON POJOマッピングを有効にする方法については「18.　JSON POJOマッピング」を参照してください。

(2)　エンティティパラメタに関する注意事項

エンティティパラメタに関するそのほかの注意事項は次のとおりです。

エンティティパラメタへの変換で例外が発生した場合の動作について

エンティティパラメタへの変換で例外が発生した場合，エラーとなります。例外の処理については「17.1.8　例外ハンドリング」を参照してください。

エンティティパラメタの型がサポートされないJavaの型の場合，またはHTTPリクエストのエンティティボディが使用できないMIMEメディアタイプの場合の動作について

次に示すJavaの型のエンティティパラメタでは，HTTPリクエストのエンティティボディが使用できないMIMEメディアタイプの場合，エラーとなり（KDJJ10024-E），HTTPステータスコードに415が設定された，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。

javax.xml.bind.JAXBElement<String>

XmlRootElementアノテーションおよび/またはXmlTypeアノテーションでアノテートされたJAXBクラス

javax.ws.rs.core.MultivaluedMap<String,String>

java.util.List<T>

POJO

ただし，1.または2.でHTTPリクエストのエンティティボディのMIMEメディアタイプがapplication/fastinfosetまたはapplication/jsonのときは，エラーにならないで正常終了します。

java.awt.image.RenderedImageのエンティティパラメタでは，HTTPリクエストのエンティティボディのMIMEメディアタイプがimage/*の場合，例外マッピングプロバイダで処理できるjava.io.IOExceptionがスローされます。

com.cosminexus.jersey.core.provider.EntityHolder<T>のエンティティパラメタでは，HTTPリクエストにエンティティボディがある場合，次に示すどちらかのときにエラーとなり（KDJJ10003-E），HTTPステータスコードに500が設定された，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。

・Tがサポートされない型（表の項番1および項番14）のとき

・Tがサポートされる型（表の項番2から項番13まで）だが，HTTPリクエストのエンティティボディが使用できないMIMEメディアタイプのとき

エンティティパラメタの型がサポートされないJavaの型を使用した場合，エラーとなり（KDJJ10024-E），HTTPステータスコードに次の値が設定された，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。

400：エンティティパラメタの型がjava.lang.Objectで，HTTPリクエストのエンティティボディのMIMEメディアタイプがapplication/xml，text/xml，またはapplication/*+xmlのとき

415：エンティティパラメタの型がjava.lang.Object以外の場合，またはエンティティパラメタの型がjava.lang.Objectで，HTTPリクエストのエンティティボディのMIMEメディアタイプがapplication/xml，text/xml，application/*+xmlのどれでもない場合

ただし，エンティティパラメタの型がjavax.mail.internet.MimeMultipartで，HTTPリクエストのエンティティボディのMIMEメディアタイプがmultipart/*のときは，エラーにならないで正常終了します。

リソースメソッドで使用できるエンティティパラメタの数について

リソースメソッドで使用できるエンティティパラメタは一つだけです。リソースメソッドが複数のエンティティパラメタを持つ場合，警告メッセージがログに出力されます（KDJJ20012-W）。HTTPリクエストのエンティティボディは最初のエンティティパラメタだけにインジェクトされ，二つ目以降のエンティティパラメタの状態は保証されません。

GET要求メソッド識別子を持つリソースメソッドについて

GET要求メソッド識別子を持つリソースメソッドがエンティティパラメタを持つ場合，警告メッセージまたはエラーメッセージがログに出力されます（KDJJ20003-WまたはKDJJ10006-E）。KDJJ20003-WおよびKDJJ10006-Eについては，「13.7.1　Webリソース初期化時の構文チェック（KDJJ20003-WとKDJJ10006-E）」を参照してください。

注意

EncodedアノテーションおよびDefaultValueアノテーションがエンティティパラメタにアノテートされている場合，無視されます。

エンティティパラメタの型パラメタが解決できない場合のメッセージの出力について

エンティティパラメタの型パラメタが解決できない場合は，警告メッセージまたはエラーメッセージがログに出力されます（KDJJ10006-EまたはKDJJ20003-W）。KDJJ20003-WとKDJJ10006-Eについては，「13.7.1　Webリソース初期化時の構文チェック（KDJJ20003-WとKDJJ10006-E）」を参照してください。

エンティティパラメタに特定の型が指定された場合の注意

エンティティパラメタの型がjavax.ws.rs.core.MultivaluedMap<String,String>，またはcom.cosminexus.jersey.core.provider.EntityHolder<javax.ws.rs.core.MultivaluedMap<String,String>>の場合，次の注意事項があります。

エンティティボディがJAX-RS機能のサーブレットやサーブレットフィルタ以外からすでにアクセスされている場合，警告メッセージがログに出力されます（KDJJ20007-W）。

このとき，エンティティパラメタの状態は不定です。エンティティボディに含まれるフォームパラメタは，FormParamアノテーションでアノテートされたパラメタから参照してください。

エンティティボディに含まれるフォームパラメタ数の上限値は，デフォルトでは10,000です。

リクエストのパラメタ数が指定した値を超えた場合，エラーとなり（KDJJ10042-E），HTTPステータスコードに413を設定した，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。必要に応じてJ2EEサーバ用ユーザプロパティファイル（usrconf.properties）のwebserver.connector.limit.max_parameter_countプロパティで変更してください。

J2EEサーバ用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「2.2.3　usrconf.properties（J2EEサーバ用ユーザプロパティファイル）」を参照してください。

エンティティパラメタの型がPOJOの場合は，次の注意事項があります。

JSON POJOマッピングが有効になっていない場合，エラーとなり（KDJJ10024-E），HTTPステータスコードに415を設定した，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。JSON POJOマッピングを有効にする方法については「18.　JSON POJOマッピング」を参照してください。

17.1.3　戻り値

リソースメソッドの戻り値に使用できるJava型とMIMEメディアタイプの組み合わせを次の表に示します。戻り値はHTTPレスポンスのエンティティボディに変換されます。なお，POJOにJAXB仕様のアノテーションは使用しないでください。使用した場合，説明とは異なる動作になるおそれがあります。

表17‒6　リソースメソッドの戻り値に使用できるJavaの型とMIMEメディアタイプの組み合わせ

項番

Javaの型

charset※1

MIMEメディアタイプ

1

byte[]

×

任意(*/*)

2

java.lang.String

○

任意(*/*)

3

java.io.InputStream

×

任意(*/*)

4

java.io.Reader

○

任意(*/*)

5

java.io.File

×

任意(*/*)

6

javax.activation.DataSource

×

任意(*/*)

7

javax.xml.transform.Source※2

×

text/xml，

application/xml，

application/*+xml

8

javax.xml.bind.JAXBElement<String>※3

○

text/xml，

application/xml，

application/*+xml

9

XmlRootElementアノテーションでアノテートされたJAXBクラス※3

○

text/xml，

application/xml，

application/*+xml

10

javax.ws.rs.core.MultivaluedMap<String, String>

○

application/x-www-form-urlencoded

11

javax.ws.rs.core.StreamingOutput

×

任意(*/*)

12

org.w3c.dom.Document

×

text/xml，

application/xml，

application/*+xml

13

java.util.List<T>※4

○

text/xml，

application/xml，

application/*+xml

14

java.awt.image.RenderedImage

×

image/jpeg

15

void

−

任意(*/*)

16

javax.ws.rs.core.Response

○

任意(*/*)

17

javax.ws.rs.core.GenericEntity<T>※5

△

Tに指定した型と同じMIMEメディアタイプです。

18

POJO※6

×※7

application/json

（凡例）

−：該当しないことを示します。

任意(*/*)：すべてのMIMEメディアタイプをサポートしていることを示します。

注※1

Producesアノテーションまたは戻り値にcharsetパラメタが含まれる場合，HTTPレスポンスに変換するときに，その情報がContent-Type HTTPヘッダのcharsetパラメタに反映されるかどうかを示します。

○：反映されます。Producesアノテーションおよび戻り値にcharsetパラメタが含まれない場合はUTF-8が仮定されます。

△：Tに指定した型に依存します。

×：反映されません。

注※2

次に示す実装クラスを使用できます。

・javax.xml.transform.stream.StreamSource

・javax.xml.transform.sax.SAXSource

・javax.xml.transform.dom.DOMSource

注※3

MIMEメディアタイプがapplication/fastinfosetまたはapplication/jsonの場合，エラーにならないで正常終了します。

注※4

TにはXmlRootElementアノテーションでアノテートされたJAXBクラスを指定できます。

注※5

Tにはこの表の項番17以外の型を指定できます。

注※6

JSON POJOマッピングを有効にしてください。JSON POJOマッピングが有効でない場合の動作は，サポートされないJava型がエンティティパラメタに指定された場合の動作と同じです。JSON POJOマッピングを有効にする方法については「18.　JSON POJOマッピング」を参照してください。

注※7

Content-Type HTTPヘッダにcharsetパラメタを追加しないでください。

戻り値とHTTPレスポンスの対応を次の表に示します。

表17‒7　戻り値とHTTPレスポンスの対応

項番

戻り値

HTTPレスポンス

型

値

HTTPステータスコード

エンティティボディ

1

void

−

204

空のエンティティボディ

2

Response

nullではないインスタンス

200

Responseのエンティティプロパティ

3

null

204

空のエンティティボディ

4

String

nullではないインスタンス

200

Stringの値

5

null

204

空のエンティティボディ

6

void，Response，String以外のサポートしているJavaの型

nullではないインスタンス

200

戻り値のクラスに応じて変換されたエンティティボディ

7

null

204

空のエンティティボディ

（凡例）

−：戻り値の値がないことを示します。

戻り値の型がサポートされないJavaの型の場合，エラーとなり（KDJJ10026-E），HTTPステータスコードに500が設定された，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。ただし，戻り値の型がjavax.mail.internet.MimeMultipartで，MIMEメディアタイプがmultipart/*のときは，エラーにならないで正常終了します。

HTTPレスポンスのエンティティボディへの変換で例外が発生した場合，エラーとなります。例外の処理については「17.1.8　例外ハンドリング」を参照してください。

戻り値の型が次に示すJavaの型で，HTTPレスポンスのエンティティボディが使用できないMIMEメディアタイプの場合，エラーとなり（KDJJ10026-E），HTTPステータスコードに500が設定された，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。

javax.xml.bind.JAXBElement<String>

XmlRootElementアノテーションでアノテートされたJAXBクラス

javax.ws.rs.core.MultivaluedMap<String, String>

java.util.List<T>

java.awt.image.RenderedImage

ただし，1.または2.でHTTPリクエストのエンティティボディのMIMEメディアタイプがapplication/fastinfosetまたはapplication/jsonのときは，エラーにならないで正常終了します。

次に示す戻り値の場合，警告メッセージまたはエラーメッセージがログに出力されます（KDJJ20003-WまたはKDJJ10006-E）。KDJJ20003-WとKDJJ10006-Eについては，「13.7.1　Webリソース初期化時の構文チェック（KDJJ20003-WとKDJJ10006-E）」を参照してください。

GET要求メソッド識別子を持つリソースメソッドの戻り値の型がvoidの場合

戻り値の型パラメタが解決できない場合

17.1.4　パラメタ型

インジェクション用アノテーションを指定できるパラメタ型の一覧，およびDefaultValueアノテーションを組み合わせて使用できるかどうかを次の表に示します。

表17‒8　各アノテーションをサポートしているパラメタの型

項番

データ型

アノテーション

PathParam

QueryParam

MatrixParam

CookieParam

HeaderParam

FormParam

Context

1

プリミティブ

int

△

○※1

○※1

○※2

○※1

○※1

×

2

short

△

○※1

○※1

○※2

○※1

○※1

×

3

long

△

○※1

○※1

○※2

○※1

○※1

×

4

float

△

○※1

○※1

○※2

○※1

○※1

×

5

double

△

○※1

○※1

○※2

○※1

○※1

×

6

char

△

○※1

○※1

○※2

○※1

○※1

×

7

byte

△

○※1

○※1

○※2

○※1

○※1

×

8

boolean

△

○※1

○※1

○※2

○※1

○※1

×

9

ラッパクラス

Integer

△

○※1

○※1

○※2

○※1

○※1

×

10

Short

△

○※1

○※1

○※2

○※1

○※1

×

11

Long

△

○※1

○※1

○※2

○※1

○※1

×

12

Float

△

○※1

○※1

○※2

○※1

○※1

×

13

Double

△

○※1

○※1

○※2

○※1

○※1

×

14

Character

×

×

×

×

×

×

×

15

Byte

△

○※1

○※1

○※2

○※1

○※1

×

16

Boolean

△

○※1

○※1

○※2

○※1

○※1

×

17

String型の引数を一つ持つコンストラクタを持つ型

△※7

○※1，※7

○※1，※7

○※2，※7

○※1，※7

○※1，※7

×

18

String型の引数を一つ持ち，その型のインスタンスを返すstaticなvalueOfメソッドを持つ型

△※7

○※1，※7

○※1，※7

○※2，※7

○※1，※7

○※1，※7

×

19

String型の引数を一つ持ち，その型のインスタンスを返すstaticなfromStringメソッドを持つ型

△※7

○※1，※7

○※1，※7

○※2，※7

○※1，※7

○※1，※7

×

20

String型の引数を一つ持ち，その型のインスタンスを返すstaticなfromStringメソッドを持つenum型

△※3，※7

○※1，※3，※7

○※1，※3，※7

○※2，※3，※7

○※1，※3，※7

○※1，※3，※7

×

21

String型の引数を一つ持ち，その型のインスタンスを返すstaticなvalueOfとfromStringメソッドの両方を持つenum以外の型

△※4，※7

○※1，※4，※7

○※1，※4，※7

○※2，※4，※7

○※1，※4，※7

○※1，※4，※7

×

22

上記以外

×

×

×

×

×

×

×

23

List<T>

TがIntegerの場合

△

○

○

×

○

○

×

24

T がShortの場合

△

○

○

×

○

○

×

25

TがLongの場合

△

○

○

×

○

○

×

26

T がFloatの場合

△

○

○

×

○

○

×

27

TがDoubleの場合

△

○

○

×

○

○

×

28

Tが Characterの場合

×

×

×

×

×

×

×

29

TがByteの場合

△

○

○

×

○

○

×

30

TがBooleanの場合

△

○

○

×

○

○

×

31

TがString型の引数を一つ持つコンストラクタを持つ型の場合

△※7

○※7

○※7

×

○※7

○※7

×

32

TがString型の引数を一つ持ち，その型のインスタンスを返すstaticなvalueOfメソッドを持つ場合

△※7

○※7

○※7

×

○※7

○※7

×

33

TがString型の引数を一つ持ち，その型のインスタンスを返すstaticなfromStringメソッドを持つ場合

△※7

○※7

○※7

×

○※7

○※7

×

34

TがString型の引数を一つ持ち，その型のインスタンスを返すstaticなfromStringメソッドを持つenum型の場合

△※3，※7

○※3，※7

○※3，※7

×

○※3，※7

○※3，※7

×

35

TがString型の引数を一つ持ち，その型のインスタンスを返すstaticなvalueOfメソッドとfromStringメソッドの両方を持つenum以外の型の場合

△※4，※7

○※4，※7

○※4，※7

×

○※4，※7

○※4，※7

×

36

Tが上記以外の場合

×

×

×

×

×

×

×

37

Set<T>※5

TがIntegerの場合

△

○

○

×

○

○

×

38

T がShortの場合

△

○

○

×

○

○

×

39

TがLongの場合

△

○

○

×

○

○

×

40

T がFloatの場合

△

○

○

×

○

○

×

41

TがDoubleの場合

△

○

○

×

○

○

×

42

Tが Characterの場合

×

×

×

×

×

×

×

43

TがByteの場合

△

○

○

×

○

○

×

44

TがBooleanの場合

△

○

○

×

○

○

×

45

TがString型の引数を一つ持つコンストラクタを持つ型の場合

△※7

○※7

○※7

×

○※7

○※7

×

46

TがString型の引数を一つ持ち，その型のインスタンスを返すstaticなvalueOfメソッドを持つ場合

△※7

○※7

○※7

×

○※7

○※7

×

47

TがString型の引数を一つ持ち，その型のインスタンスを返すstaticなfromStringメソッドを持つ場合

△※7

○※7

○※7

×

○※7

○※7

×

48

TがString型の引数を一つ持ち，その型のインスタンスを返すstaticなvalueOfメソッドとfromStringメソッドの両方を持つenum型の場合

△※3，※7

○※3，※7

○※3，※7

×

○※3，※7

○※3，※7

×

49

TがString型の引数を一つ持ち，その型のインスタンスを返すvalueOfメソッドとfromStringメソッドの両方を持つenum以外の型の場合

△※4，※7

○※4，※7

○※4，※7

×

○※4，※7

○※4，※7

×

50

Tが上記以外の場合

×

×

×

×

×

×

×

51

Sorted

Set<T>※5，※6

TがIntegerの場合

×

×

×

×

×

×

×

52

T がShortの場合

×

×

×

×

×

×

×

53

TがLongの場合

×

×

×

×

×

×

×

54

T がFloatの場合

×

×

×

×

×

×

×

55

TがDoubleの場合

×

×

×

×

×

×

×

56

Tが Characterの場合

×

×

×

×

×

×

×

57

TがByteの場合

×

×

×

×

×

×

×

58

TがBooleanの場合

×

×

×

×

×

×

×

59

TがString型の引数を一つ持つコンストラクタを持つ型の場合

×※7，※8

×※7，※9

×※7，※9

×

×※7，※9

×※7，※9

×

60

TがString型の引数を一つ持ち，その型のインスタンスを返すstaticなvalueOfメソッドを持つ場合

×※7，※8

×※7，※9

×※7，※9

×

×※7，※9

×※7，※9

×

61

TがString型の引数を一つ持ち，その型のインスタンスを返すstaticなfromStringメソッドを持つ場合

×

×

×

×

×

×

×

62

TがString型の引数を一つ持ち，その型のインスタンスを返すstaticなvalueOfメソッドとfromStringメソッドの両方を持つenum型の場合

×

×

×

×

×

×

×

63

TがString型の引数を一つ持ち，その型のインスタンスを返すstaticなvalueOfメソッドとfromStringメソッドの両方を持つenum以外の型の場合

×

×

×

×

×

×

×

64

Tが上記以外の場合

×

×

×

×

×

×

×

65

PathSegment

△

×

×

×

×

×

×

66

コンテキスト型

UriInfo

×

×

×

×

×

×

△

67

HttpHeaders

×

×

×

×

×

×

△

68

Request

×

×

×

×

×

×

△

69

SecurityContext

×

×

×

×

×

×

△

70

Providers

×

×

×

×

×

×

△

71

ServletConfig

×

×

×

×

×

×

△

72

ServletContext

×

×

×

×

×

×

△

73

HttpServletRequest

×

×

×

×

×

×

△

74

HttpServletResponse

×

×

×

×

×

×

△

（凡例）

○：インジェクション用アノテーションを使用できることを示します。

×：インジェクション用アノテーションを使用できないことを示します。

△：インジェクション用アノテーションを使用できることを示します。ただし，DefaultValueアノテーションを組み合わせて使用しないでください。

注※1

同じ名称のパラメタを複数受け取った場合，JAX-RSエンジンは最初のパラメタの値だけを使用します。

注※2

同じ名称のパラメタを複数受け取った場合，JAX-RSエンジンは最後のパラメタの値をインジェクトします。

注※3

String型の引数を一つ持ち，その型のインスタンスを返すstaticなvalueOfメソッドとstaticなfromStringメソッドの両方を持つ型の場合，JAX-RSエンジンはstaticなfromStringメソッドを使用します。

注※4

String型の引数を一つ持ち，その型のインスタンスを返すstaticなvalueOfメソッドとstaticなfromStringメソッドの両方を持つ型の場合，JAX-RSエンジンはstaticなvalueOfメソッドを使用します。

注※5

enum型以外の場合，Tに指定するクラス，またはその親以上のクラスでは，Java言語の規約に従ってjava.lang.Objectのequals()メソッドとhashCode()メソッドを適切に実装している必要があります。

注※6

enum型以外の場合，Tに指定するクラス，またはその親以上のクラスでは，java.lang.Comparableインタフェースを実装している必要があります。

注※7

valueOfメソッド，fromStringメソッド，およびコンストラクタは，インジェクションの検証のため，初期化時に複数回呼び出されることがあります。

注※8

TがString型の場合は使用できます。ただし，DefaultValueアノテーションを組み合わせて使用しないでください。

注※9

TがString型の場合は使用できます。

上記の表の項番22，項番36，項番50，項番64，および項番65の型に各アノテーションが使用された場合，エラーが発生します（KDJJ10006-E）。ルートリソースクラスではHTTPステータスコード500のHTTPレスポンスが返されます。サブリソースクラスでは，例外マッピングプロバイダで処理できるjava.lang.RuntimeExceptionがスローされます。

また，上記の表の項番14，項番28，項番42，および項番56の型に各アノテーションが使用された場合，例外マッピングプロバイダで処理できるjava.lang.RuntimeExceptionがスローされます。

17.1.5　例外のマッピング

ルートリソースクラスのリソースメソッドのパラメタ，コンストラクタのパラメタ，フィールド，beanプロパティ，およびサブリソースクラスのリソースメソッドのパラメタへのインジェクションで例外がスローされた場合，JAX-RSエンジンは次の表に示すように処理します。サポートされるJava型とアノテーションについては，「17.1.4　パラメタ型」を参照してください。

表17‒9　インジェクションで発生した例外に対するJAX-RSエンジンの対応

項番

アノテーション

インジェクションで発生した例外

WebApplicationException

その他

1

MatrixParam

「17.1.8　例外ハンドリング」で説明するようにWebApplicationExceptionを処理します。

スローされた例外を，エンティティがなく，HTTPステータスコード404であるWebApplicationExceptionでラップします。さらに，「17.1.8　例外ハンドリング」で説明するように処理します。

2

QueryParam

3

PathParam

4

CookieParam

スローされた例外を，エンティティがなく，HTTPステータスコード400であるWebApplicationExceptionでラップします。さらに，「17.1.8　例外ハンドリング」で説明するように処理します。

5

FormParam

6

HeaderParam

注意事項

WebApplicationExceptionは，「17.1.4　パラメタ型」の「各アノテーションをサポートしているパラメタの型」を説明している表の各パラメタ型のうち，項番17〜21，項番31〜36，項番45〜50，項番59〜64だけで発生します。

17.1.6　URIテンプレート

Pathアノテーションは，ルートリソースクラス，サブリソースメソッド，またはサブリソースロケータがどのURLに対するHTTPリクエストを処理するのかを指定するために使用します。Pathアノテーションの値はURIテンプレートと呼ばれます。

ルートリソースにクラスレベルで指定される場合は，Webリソースを含むWebアプリケーション（WARファイル）のコンテキストルートに対して相対的なURIを示します。また，サブリソースメソッドまたはサブリソースロケータの場合は，ルートリソースクラスのURIテンプレートに対して相対的なURIを示します。

アノテーションの値は，自動的にエンコードされます。例えば，次に示すアノテーションの意味は同じです。

@Path ("widget list/{id}")

@Path ("widget%20list/{id}")

二つ以上のルートリソースクラスのPathアノテーションが同じURIテンプレートを持つ場合，または同じ正規表現に解決されるURIテンプレートを持つ場合，エラーとなり（KDJJ10006-E），ルートリソースクラスはインスタンス化されません。HTTPステータスコードには500が返されます。

二つ以上のサブリソースメソッドのPathアノテーションが同じURIテンプレートを持つ場合，または同じ正規表現に解決されるURIテンプレートを持つ場合，メディアタイプ宣言や要求メソッド識別子などのほかの情報も一致するようなとき，エラーとなります（KDJJ10006-E）。ルートリソースクラスでは，HTTPステータスコード500のHTTPレスポンスが返されます。サブリソースクラスでは，例外マッピングプロバイダで処理できるjava.lang.RuntimeExceptionがスローされます。

二つ以上のサブリソースロケータのPathアノテーションが同じURIテンプレートを持つ場合，または同じ正規表現に解決されるURIテンプレートを持つ場合，エラーとなります（KDJJ10006-E）。ルートリソースクラスではHTTPステータスコード500のHTTPレスポンスが返されます。サブリソースクラスでは，例外マッピングプロバイダで処理できるjava.lang.RuntimeExceptionがスローされます。

Pathアノテーションがインタフェースや抽象クラスにアノテートされている場合，エラーとなり（KDJJ10006-E），クライアントからの要求は処理されません。HTTPステータスコードには500が返されます。

(1)　テンプレートパラメタ

URIテンプレートは，テンプレートパラメタと呼ばれる埋め込みのパラメタを0個以上含めることができます。テンプレートパラメタは，開始括弧（{）で記述し始め，スラッシュ（/）ではない一文字以上の英数字および記号を続けて記述し，最後に閉じ括弧（}）を記述します。テンプレートパラメタの実際の値は，PathParamアノテーションでアノテートされたパラメタ，フィールド，またはbeanプロパティにインジェクトすると，取得できます。テンプレートパラメタの記述方法については，標準仕様を確認してください。

テンプレートパラメタの例を次に示します。

package com.someshop;

import javax.ws.rs.PathParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

//ルートリソースクラス
@Path("/customers")
public class CustomerResource {
  //サブリソースメソッド
  @GET
  @Path("{id}")
  public String getCustomer(@PathParam("id") int id) {
    //割り当てた値を返すために実行する
  }
}

この例では，Pathアノテーションに含まれる表現{id}はテンプレートパラメタです。ルートリソースクラスcom.someshop.CustomerResourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"resource"で，Webアプリケーションが"someshop.com"というホストで公開されているとします。その場合，URL"http://someshop.com/resource/customers/333"に対するHTTP GETリクエストは，サブリソースメソッドgetCustomer()にディスパッチされ，テンプレートパラメタidの実際の値はPathParamアノテーションでアノテートされたパラメタidにインジェクトされます。

一方，URL"http://someshop.com/resource/customers/333/444"に対するHTTP GETリクエストは，どのメソッドにもディスパッチされません。HTTPステータスコードには404が返されます。

テンプレートパラメタは，Pathアノテーションの値（URIテンプレート）のどこにでも埋め込むことができます。テンプレートパラメタを複数使用している例を次に示します。

package com.someshop;

import javax.ws.rs.PathParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

//ルートリソースクラス
@Path("/")
public class CustomerResource {
  //サブリソースクラス
  @GET
  @Path("customers/{firstname}-{lastname}")
  public String getCustomer(@PathParam("firstname") String firstname,
      @PathParam("lastname") String lastname) {
    //割り当てた値を返すために実行する
  }
}

この例では，Pathアノテーションに含まれる表現{firstname}および{lastname}は，ハイフンによって区切られた二つのテンプレートパラメタです。

URL"http://someshop.com/resource/customers/John-Smith"に対するHTTP GETリクエストは，サブリソースメソッドgetCustomer()にディスパッチされ，テンプレートパラメタfirstnameおよびテンプレートパラメタlastnameの実際の値は，それぞれPathParamアノテーションでアノテートされたパラメタfirstnameおよびパラメタlastnameにインジェクトされます。

(a)　正規表現

Pathアノテーションでは，ワイルドカード以外の正規表現を使用できます。テンプレートパラメタでの正規表現の使用例を次に示します。

package com.someshop;

import javax.ws.rs.PathParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

//ルートリソースクラス
@Path("/customers")
public class CustomerResource {
  //サブリソースメソッド1
  @GET
  @Path("{id : ¥¥d+}")
  public String getCustomer(@PathParam("id") int id) {
    // Implementation to return appropriate value
  }
//サブリソースメソッド2
@GET
  @Path("{path : .+}")
  public String getCustomerIdAndName(@PathParam("path") String path) {
    //割り当てた値を返すために実行する
  }
}

この例では，Pathアノテーションに含まれる表現{id : ¥¥d+}は，正規表現を使用しているテンプレートパラメタです。ここでは，識別子idと正規表現"¥¥d+"を組み合わせて使用しています。識別子と正規表現は，コロン（:）で区切ります。

正規表現"¥¥d+"は，一桁以上の数字と一致します。URL"http://someshop.com/resource/customers/333"に対するHTTP GETリクエストは，サブリソースメソッドgetCustomer()にディスパッチされます。

正規表現".+"は，どんな文字とでも一致します。URL"http://someshop.com/resource/customers/33/John/Smith"に対するHTTP GETリクエストは，サブリソースメソッドgetCustomerIdAndName()にディスパッチされます。

(b)　テンプレートパラメタを使用する場合の注意事項

次に示す場合，エラーが発生します（KDJJ10006-E）。

テンプレートパラメタに不正な文字が使用されている。

テンプレートパラメタに不正な構文の正規表現が記述されている。

ルートリソースクラスではHTTPステータスコード500のHTTPレスポンスが返されます。サブリソースクラスでは例外マッピングプロバイダで処理できるjava.lang.RuntimeExceptionがスローされます（KDJJ10006-E）。

17.1.7　サブリソースクラス

サブリソースクラスは，リソースメソッド，サブリソースメソッド，またはサブリソースロケータのどれかを一つ以上持ち，クラスレベルでPath アノテーションでアノテートされていないJava のクラスです。

サブリソースクラスの例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

public class Resource {
  @Path("/subresourcemethod1")
  @GET
  public String subResourceMethod1() {
    return "from sub resource method1";
  }
  @GET
  public String resourceMethod() {
    return "from resource method";
  }
}

サブリソースクラスのインスタンスは，JAX-RSエンジンによって生成されません。サブリソースクラスは，対応するサブリソースロケータでインスタンス化する必要があります。

(1)　メカニズム

サブリソースクラスは，次のように生成され，HTTPリクエストを処理します。

HTTPリクエストがサブリソースロケータにディスパッチされます。

サブリソースロケータはサブリソースクラスを生成し，HTTPリクエストの処理を生成したサブリソースクラスに委譲します。

HTTPリクエストはサブリソースクラスによって直接処理されるか，同じ仕組みによって，さらにサブリソースクラスに委譲されます。

サブリソースロケータについては，「17.1.1(6)　サブリソースロケータ」を参照してください。

JAX-RSエンジンは，サブリソースロケータのメソッドシグネチャで宣言された戻り値型ではなく，実行時にサブリソースロケータが返すインスタンスをサブリソースクラスとして扱い，処理を委譲します。

例えば，M，N，およびOの三つのサブリソースクラスがあるとします。NはMを継承し，OはNを継承しています。同様に，戻り型Mを持つRというサブリソースロケータがあるとします。サブリソースロケータがMのインスタンスを返した場合，サブリソースクラスMがHTTPリクエストを実行します。同様に，サブリソースロケータがNのインスタンスを返す場合は，サブリソースクラスNがHTTPリクエストを実行します。Oのインスタンスを返す場合は，サブリソースクラスOがHTTPリクエストを実行します。

(2)　ライフサイクル

サブリソースクラスのインスタンスは，JAX-RSエンジンによって生成されません。サブリソースクラスは，対応するサブリソースロケータでインスタンス化する必要があります。このため，サブリソースロケータまたはサブリソースクラスで，コンストラクタのパラメタ，フィールド，およびbeanプロパティを初期化する必要があります。

(3)　コンストラクタ

サブリソースクラスのコンストラクタのパラメタでは，JAX-RS仕様のアノテーションを使用しないでください。使用されている場合は無視されます。

(4)　フィールドおよびbeanプロパティ

JAX-RS仕様のアノテーションをサブリソースクラスのフィールドおよびbeanプロパティで使用しないでください。使用されている場合は，無視されます。

(5)　リソースメソッド，サブリソースメソッド，およびサブリソースロケータ

サブリソースクラスのリソースメソッド，サブリソースメソッド，およびサブリソースメソッドは，次に説明する相違点を除いてルートリソースクラスの場合と同じです。ルートリソースクラスについては，次の個所を参照してください。

「17.1.1(4)　リソースメソッド」

「17.1.1(5)　サブリソースメソッド」

「17.1.1(6)　サブリソースロケータ」

サブリソースロケータの戻り値の型がvoidの場合，エラーとなり，クライアントからのHTTPリクエストは処理されません。HTTPステータスコードには500が返されます。なお，ログはJAX-RS機能のログファイルではなく，J2EEサーバのログファイルを確認してください。

次に示す条件に当てはまる場合は，エラーとなり（KDJJ10006-E），例外マッピングプロバイダで処理できるjava.lang.RuntimeExceptionがスローされます。

一つのリソースメソッドに対し，二つ以上の要求メソッド識別子を使用している場合

二つ以上のリソースメソッドに対し，同じ要求メソッド識別子を使用している場合

サブリソースロケータがエンティティパラメタを持っている場合

17.1.8　例外ハンドリング

JAX-RSエンジンは，次に示す個所からスローされる例外をここで説明するようにハンドリングします。

リソースメソッド

サブリソースメソッド

サブリソースロケータ

ルートリソースクラスのコンストラクタおよびサブリソースクラス

(1)　WebApplicationException（例外マッピングプロバイダがない場合）

WebApplicationExceptionがスローされる場合で，WebApplicationExceptionまたはその親以上の例外に対応する例外マッピングプロバイダがないとき，JAX-RSエンジンは次の表に示すようにWebApplicationExceptionをハンドリングします。

表17‒10　WebApplicationExceptionのハンドリング（例外マッピングプロバイダがない場合）

項番

条件

ハンドリング結果

responseプロパティ

responseプロパティのHTTPステータスコード

HTTPレスポンスのHTTPステータスコード

メッセージID

1

設定されている

499以下

列挙型Response.Statusにある値

WebApplicationExceptionのresponseプロパティが持つ値が使用されます。

KDJJ30021-I

2

設定されている

499以下

列挙型Response.Statusにない値

WebApplicationExceptionのresponseプロパティが持つ値が使用されます。

KDJJ30022-I

3

設定されている

500以上

列挙型Response.Statusにある値

WebApplicationExceptionのresponseプロパティが持つ値が使用されます。

KDJJ10018-E

4

設定されている

500以上

列挙型Response.Statusにない値

WebApplicationExceptionのresponseプロパティが持つ値が使用されます。

KDJJ10019-E

5

設定されていない

−

500

KDJJ10018-E

（凡例）

−：該当しないことを示します。

WebApplicationExceptionを生成し，responseプロパティを設定する例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.WebApplicationException;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.ResponseBuilder;

//ルートリソースクラス
@Path("/root")
public class Resource {

  //サブリソースメソッド
  @Path("/subresourcemethod")
  @GET
  public String subResourceMethod() {
    //ResponseBuilderを使用してResponseインスタンスを生成
    ResponseBuilder rb = Response.status(208).
    entity("entity for WebApplicationException");

    //WebApplicationExceptionへResponseインスタンスを設定
    throw new WebApplicationException(rb.build());
}
}

この例では，ルートリソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"resource"で，Webアプリケーションが"example.com"というホストで公開されているとします。その場合，URL"http://example.com/resource/root/subresourcemethod"に対するHTTP GETリクエストは，メソッドsubResourceMethod()にディスパッチされます。また，HTTPレスポンスは，WebApplicationExceptionのresponseプロパティから変換されます。

(2)　その他の例外（例外マッピングプロバイダがない場合）

WebApplicationException以外の例外がスローされる場合で，その例外またはその親以上の例外に対応する例外マッピングプロバイダがないとき，JAX-RSエンジンは次の表に示すようにその例外をハンドリングします。

表17‒11　その他の例外（例外マッピングプロバイダがない場合）

項番

条件

ハンドリングの結果

例外の種類

JAX-RSエンジンの動作

HTTPレスポンスのHTTPステータスコード

メッセージID

1

ランタイム例外

そのランタイム例外をスローし直します。

500

KDJJ10010-E，

KDJJ10039-E

2

上記以外

RuntimeExceptionでその例外をラップしてスローします

500

KDJJ10017-E，

KDJJ10039-E

(3)　例外マッピングプロバイダがある場合

スローされる例外，またはその親以上の例外に対応する例外マッピングプロバイダがある場合は，例外マッピングプロバイダの動作に依存します。なお，スローされる例外とその親以上の例外に対応する例外マッピングプロバイダが複数存在する場合は，その例外に最も近い例外（スローされた例外を含む）を処理できる例外マッピングプロバイダが動作します。

17.1.9　メディアタイプ宣言

ConsumesアノテーションとProducesアノテーションをそれぞれ使用することで，WebリソースでサポートするMIMEメディアタイプを指定できます。ConsumesアノテーションとProducesアノテーションを使用していない場合は，すべてのメディアタイプがサポートされていると見されます。

ConsumesアノテーションとProducesアノテーションは，次に示す場所で使用できます。

ルートリソースクラス（クラスレベル）

サブリソースクラス（クラスレベル）

リソースメソッド（メソッドレベル）

サブリソースメソッド（メソッドレベル）

メソッドレベルで使用されているアノテーションは，クラスレベルで使用されているアノテーションより優先されます。

二つ以上のリソースメソッドまたはサブリソースメソッドが同じMIMEメディアタイプを処理できる場合で，要求メソッド識別子やパスなどほかの情報も一致するようなとき，エラーが発生します（KDJJ10006-E）。ルートリソースクラスでは，HTTPステータスコード500のHTTPレスポンスが返されます。サブリソースクラスでは，例外マッピングプロバイダで処理できるjava.lang.RuntimeExceptionがスローされます。

HTTPリクエストのContent-Typeヘッダが，どのConsumesアノテーションにも一致しない場合，エラーとなり（KDJJ10040-E），HTTPステータスコードに415が設定された，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationException がスローされます。

HTTPレスポンスのAccept HTTPヘッダが，どのProducesアノテーションにも一致しない場合，エラーとなり（KDJJ10041-E），HTTPステータスコードに406が設定された，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationException がスローされます。

メディアタイプ宣言の例を次に示します。

package com.sample.resources;

java.awt.image.RenderedImage
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.Consumes;

@Path("sample")
@Produces("image/jpeg")
public class ImageBasedResource {

@GET
  public RenderedImage getAsImage() {
  //実装
  }

  @GET
  @Produces("text/html")
  public String getAsHtml() {
    //実装
  }

  @POST
  @Consumes("image/jpeg")
  public void addWidget(RenderedImage image) {
    //実装
  }
}

この例では，MIMEメディアタイプimage/jpegのHTTPレスポンスを要求するHTTP GETリクエストを処理するためにリソースメソッドgetAsImage()が呼び出されます。

また，MIMEメディアタイプtext/htmlのHTTPレスポンスを要求するHTTP GETリクエストを処理するためにリソースメソッドgetAsHtmlが呼び出されます。

さらに，MIMEメディアタイプimage/jpegのエンティティボディを持つHTTP POST要求を処理するためにリソースメソッドaddImageが呼び出されます。

17.1.10　URLデコードの無効化

デフォルトでは，JAX-RSエンジンは次に示すアノテーションでアノテートされたパラメタ，フィールド，またはbeanプロパティにインジェクトするとき，インジェクトされる値がURLエンコードされている場合は自動でデコードします。デコードされていない元の値を利用した場合は，Encodedアノテーションを各アノテーションと組み合わせて使用してください。

MatrixParamアノテーション

QueryParamアノテーション

PathParamアノテーション

17.1.11　アノテーションの継承

親クラスやインタフェースのメソッドで使用されているJAX-RS仕様のアノテーションは，子クラスや実装クラスに継承されます。

アノテーションが継承される条件を次に示します。

子クラスのメソッドおよびそのパラメタでJAX-RS仕様のアノテーションが使用されていない場合

実装クラスのメソッドおよびそのパラメタでJAX-RS仕様のアノテーションが使用されていない場合

親クラスを継承し，かつインタフェースを実装している場合で，アノテーションを継承する条件に両方合致する場合は親クラスのアノテーションを優先します。

複数の親クラスを継承している場合，または複数のインタフェースを実装している場合，それぞれ最初に継承または実装している親クラスまたはインタフェースのアノテーションを優先します。

アノテーションが継承される例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.QueryParam;

//インタフェース
public interface A {

  //JAX-RS仕様のアノテーションを使用しているメソッド
  @GET
  public String getValue(@QueryParam("query") String query);

}

package com.sample.resources;

import javax.ws.rs.Path;

//インタフェースを実装するルートリソースクラス
@Path("/root/")
public class Resource implements A {

  //メソッドの実装
  public String getValue(String query) {
    //実装

  }
}

package com.sample.resources;

import javax.ws.rs.Path;
import javax.ws.rs.Produces;

//インタフェースを実装するルートリソースクラス
@Path("/root1/")
public class Resource1 implements A {

  //メソッドの実装
  @Produces("text/xml")
  public String getValue(String query) {
    //実装
  }
}

この例では，インタフェースcom.sample.resources.A，ルートリソースクラスcom.sample.resources.Resource，およびルートリソースクラスcom.sample.resources.Resource1を含むWebアプリケーション（WARファイル）のコンテキストルートが"resource"で，"example.com"というホストで公開されているとします。

URL"http://example.com/resource/root?query=10"に対するHTTP GETリクエストは，リソースメソッドgetValue()にディスパッチされます。リソースメソッドgetValue()はインタフェースのGETアノテーションを継承しているためです。

一方で，URL"http://example.com/resource/root1?query=10"に対するHTTP GETリクエストは，リソースメソッドgetValue()にディスパッチされないで，HTTPステータスコード405が返ります。リソースメソッドgetValue()はインタフェースのGETアノテーションを継承していないためです。

17.2　プロバイダ

プロバイダは，Providerアノテーションでアノテートされ，標準仕様によって定義されるインタフェースを実装するクラスです。

プロバイダは，Webアプリケーション（WARファイル）ごとにインスタンス化されます。プロバイダのライフサイクルは次のとおりです。

コンストラクタが呼び出される

必要なインジェクションが行われる

適切なメソッドが呼び出される

GC（ガーベージコレクション）の対象になる

17.2.1　エンティティプロバイダ

JAX-RS機能ではビルトインのエンティティプロバイダを提供しています。

17.2.2　例外マッピングプロバイダ

例外マッピングプロバイダで処理できる例外からHTTPレスポンスへのマッピングをカスタマイズする場合は，例外マッピングプロバイダを実装してください。

例外マッピングプロバイダは，ExceptionMapper<T>インタフェースを実装し，Providerアノテーションでアノテートします。

例外マッピングプロバイダの例を次に示します。

package com.sample.providers;

import javax.ws.rs.core.Response;
import javax.ws.rs.ext.ExceptionMapper;
import javax.ws.rs.ext.Provider;

//RuntimeExceptionからHTTPレスポンスへのマッピングをカスタマイズする例外マッピングプロバイダ
@Provider
public class RuntimeExceptionMapper implements
    ExceptionMapper<RuntimeException> {

  public Response toResponse(RuntimeException runtimeException) {
    int httpStatus = 0;
    String entity = "";

    //ResponseBuilderクラスを使用してHTTPレスポンスを作成する
    return Response.status(httpStatus).entity(entity).build();
  }
}

この例では，プロバイダcom.sample.providers.RuntimeExceptionMapperが，例外マッピングプロバイダで，型パラメタにRuntimeExceptionを指定したExceptionMapperインタフェースを実装しています。ここでは，ResponseBuilderクラスのtoResponseメソッドを呼び出してHTTPレスポンスを作成しています。

なお，例外マッピングプロバイダは，一つの例外に対して一つだけ作成できます。一つの例外に対して二つ以上の例外マッピングプロバイダを作成すると，エラーになり（KDJJ10028-E，KDJJ10039-E），例外マッピングプロバイダはインスタンス化されません。HTTPステータスコードには500が返されます。

(1)　コンストラクタ

例外マッピングプロバイダは，publicデフォルトコンストラクタ（明示的に宣言されないコンストラクタ）も含めて，少なくとも一つ以上のpublicコンストラクタを持つ必要があります。

publicコンストラクタが一つも宣言されていない場合，エラーとなり（KDJJ10002-E，KDJJ10006-E），例外マッピングプロバイダはインスタンス化されません。HTTPステータスコードには500が返されます。

次に示すコンストラクタはpublicコンストラクタではありません。

privateコンストラクタ

protectedコンストラクタ

アクセス識別子を持たないコンストラクタ

コンストラクタのパラメタでは，インジェクション用アノテーションとしてContextアノテーションを使用できます。Contextアノテーション以外のインジェクション用アノテーションが使用されている場合，エラーとなり（KDJJ10006-E），例外マッピングプロバイダはインスタンス化されません。HTTPステータスコードには500が返されます。使用できないインジェクション用アノテーションを次に示します。

MatrixParam

QueryParam

PathParam

CookieParam

HeaderParam

FormParam

これらのパラメタにインジェクション用アノテーション以外を指定した場合，エラーメッセージが出力されます（KDJJ10006-E）。HTTPステータスコードには500が返されます。

例外マッピングプロバイダがパラメタを持つpublicコンストラクタを一つ以上持つ場合，JAX-RSエンジンは，最もパラメタ数が多いコンストラクタを使用して例外マッピングプロバイダをインスタンス化します。最もパラメタ数が多いコンストラクタを二つ以上持つ場合，最初に定義されているコンストラクタを使用して例外マッピングプロバイダをインスタンス化します。このとき，警告メッセージがログに出力されます（KDJJ20011-W）。

例外マッピングプロバイダがインスタンス化されるときにランタイム例外が発生した場合，エラーとなります（KDJJ10028-E，KDJJ10039-E）。HTTPステータスコードには500が返されます。

(2)　フィールドおよびbeanプロパティ

例外マッピングプロバイダのフィールドおよびbeanプロパティ上では，インジェクション用アノテーションとしてContextアノテーションを使用できます。

Contextアノテーション以外のインジェクション用アノテーションが使用されている場合，無視されます。使用できないアノテーションを次に示します。

MatrixParam

QueryParam

PathParam

CookieParam

HeaderParam

FormParam

18　JSON POJOマッピング

この章では，JAX-RS機能が提供している，JSONとPOJOのマッピングを行うビルトインのエンティティプロバイダのマッピングについて説明します。

なお，POJOにJAXB仕様のアノテーションは使用しないでください。使用した場合，説明とは異なる動作になるおそれがあります。

18.1　JSON POJOマッピングの設定

JSON POJOマッピングでは，POJOからJSON，またはJSONからPOJOへのデータ変換ができます。

ここでは，サーバ側およびクライアント側でJSON POJOマッピングをする方法について説明します。

18.1.1　サーバ側

JSON POJOマッピングは，次の方法で有効または無効を指定できます。

共通定義ファイル（cjrconf.properties）

com.sun.jersey.api.json.POJOMappingFeatureの値に「true（有効）」または「false（無効）」を指定します。値の大文字と小文字は区別されません。

web.xmlのサーブレット初期化パラメタ

サーブレット初期化パラメタ（com.sun.jersey.api.json.POJOMappingFeature）で次の表に示す値を設定します。値の大文字と小文字は区別されません。

表18‒1　サーブレット初期化パラメタ（com.sun.jersey.api.json.POJOMappingFeature）で指定できる値

値

説明

true

JSON POJOマッピングが有効になります。

false

JSON POJOマッピングが無効になります。

true，false以外の値

web.xmlのサーブレット初期化パラメタで指定した値は無視され，共通定義ファイルで指定した値が採用されます。

なお，共通定義ファイルとサーブレット初期化パラメタの両方が指定された場合は，サーブレット初期化パラメタで指定した値が優先されます。

18.1.2　クライアント側

クライアントでは，共通定義ファイル（cjrconf.properties）のcom.sun.jersey.api.json.POJOMappingFeatureの値に「true（有効）」または「false（無効）」を指定するか，Clientオブジェクトのプロパティマップにcom.sun.jersey.api.json.POJOMappingFeatureフィーチャを追加してください。com.sun.jersey.api.json.POJOMappingFeatureフィーチャを追加する実装例を次に示します。

// ClientConfigオブジェクトを生成する
ClientConfig cc = new DefaultClientConfig();
// ClientConfigオブジェクトにJSON POJOマッピングを有効にするための
// フィーチャを追加する
cc.getFeatures().put(JSONConfiguration.FEATURE_POJO_MAPPING, true);
// 上記で生成したClientConfigオブジェクトを指定して
// Clientオブジェクトを生成する
Client client = Client.create(cc);

この例では，JSONConfiguration.FEATURE_POJO_MAPPINGフィーチャをあらかじめ追加したClientConfigを指定して，Clientオブジェクトを生成しています。

なお，共通定義ファイルとClientオブジェクトの両方が指定された場合は，Clientオブジェクトに指定した値が優先されます。

18.2　POJOからJSONへのマッピング

JSONフォーマットの詳細についてはRFC 4627を参照してください。ここでは，POJOからJSONへのマッピング要件と，指定できるデータ型について説明します。

18.2.1　マッピング要件

POJOからJSONへのマッピング要件について次に説明します。

(1)　POJO

POJOクラスは，publicスコープまたはパッケージスコープで定義してください。final修飾子を指定しても問題ありません。

任意のコンストラクタを含めることができます。

JSONの同じ要素にマッピングできるフィールドまたはプロパティが複数ある場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

フィールドおよびBeanプロパティの名称が同じ場合，Beanプロパティが優先されます。

(2)　フィールド

フィールドはpublicスコープで定義してください。publicスコープ以外で定義された場合はマッピングされません。

static修飾子またはtransient修飾子をフィールドに指定しないでください。指定されている場合はマッピングされません。

final修飾子は指定しても問題ありません。

(3)　Beanプロパティ

Beanプロパティのgetterメソッドはpublicスコープで定義してください。publicスコープ以外で定義された場合はマッピングされません。

同じプロパティに対して大文字・小文字の違いだけがあるgetterメソッドが複数ある場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

staticをBeanプロパティに指定しないでください。指定されている場合はマッピングされません。

final修飾子は指定しても問題ありません。

Beanプロパティは書き込み可能なプロパティである必要はありません。Beanプロパティの詳細についてはJavaBeans仕様を参照してください。

18.2.2　指定できるデータ型

POJOのフィールドおよびBeanプロパティに指定できるデータ型を次に示します。

表18‒2　POJOのフィールドおよびBeanプロパティに指定できるデータ型（POJOからJSONへのマッピング）

項番

データ

1

プリミティブ

int

2

short

3

long

4

float

5

double

6

char

7

byte

8

boolean

9

ラッパクラス

Integer

10

Short

11

Long

12

Float

13

Double

14

Character

15

Byte

16

Boolean

17

java.lang.String

18

java.math.BigInteger

19

java.math.BigDecimal

20

java.util.Date

21

java.util.Calendar

22

java.lang.Enum

23

POJO※1

24

java.util.List<T>※2

25

java.util.Set<T>※2

26

java.util.Map<T,T>※2

27

項番1〜26のどれかの配列

注※1

フィールドまたはBeanプロパティとして再帰的にPOJOを持つことができます。サポートされるPOJOの条件については，「18.2　POJOからJSONへのマッピング」を参照してください。

注※2

Tの型は表の項番1〜26のどれかになります。

注意事項を次に示します。

フィールドまたはBeanプロパティが初期化されていない場合，生成されたJSONにマッピングされる値は，それぞれのデータ型のデフォルト値（プリミティブ型ではそれぞれのデフォルト値，オブジェクト型ではnull）になります。

表の項番9〜27の型の値がnullの場合，生成されるJSONの対応する値にはnullがマッピングされます。

表の項番24〜27の型の値にnullが含まれている場合，生成されるJSONの対応する値にはnullがマッピングされます。

表の項番20または21の型の値がnull以外の場合，生成されるJSONの対応する値はミリ秒で表現される等しい値がマッピングされます。例えば，データ型としてDateが使用されている場合，DateクラスのgetTime()メソッドを呼び出して得られる値がマッピングされます。Calendar型では，CalendarクラスのgetTime()で取得されるDateオブジェクトに対してDateクラスのgetTime()メソッドを呼び出して得られる値がマッピングされます。

表の項番26の型の値がnullの場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

表の項番27がchar配列またはbyte配列のとき，生成されるJSONの対応する値は，配列ではなくそれぞれ次の値がマッピングされます。

char配列：配列から生成される文字列

byte配列：配列から生成されるBase64エンコードされた文字列

例を次に示します。

値が{'a','b'}で名称が"bean"であるchar[]型のBeanプロパティは，{"bean":["a","b"]}ではなく{"bean":["ab"]}にマッピングされます。

値が{1,2}で名称が"bean"であるbyte[]型のBeanプロパティは{"bean":[1,2]}ではなく{"bean":["AQ=="]}にマッピングされます。

18.2.3　例外ハンドリング

POJOからJSONへのマッピングは，JAX-RS仕様のエンティティプロバイダの仕組みで実装されています。このため，マッピングで発生する例外はほかのマッピングで例外が発生する場合と同じように処理されます。マッピングで例外がどのように処理されるかについては，サーバ側については「17.1.3　戻り値」を，クライアント側については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

18.3　JSONからPOJOへのマッピング

JSONフォーマットの詳細についてはRFC 4627を参照してください。ここでは，JSONからPOJOへのマッピング要件と，指定できるデータ型について説明します。

18.3.1　マッピング要件

(1)　POJO

POJOクラスは，publicスコープまたはパッケージスコープで定義してください。final修飾子を指定しても問題ありません。

POJOクラスはデフォルトコンストラクタを持つ必要があります。デフォルトコンストラクタは明示的に宣言してもしなくてもどちらでも問題ありません。また，publicスコープ，privateスコープ，protectedスコープ，またはパッケージスコープのどれでも問題ありません。POJOクラスがデフォルトコンストラクタを持たない場合，JsonMappingExceptionがスローされます。Java言語仕様にあるとおり，パラメタを持つコンストラクタを宣言した場合は明示的にデフォルトコンストラクタを宣言する必要があることに注意してください。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

POJOクラスはインナークラスとして宣言された型のフィールドまたはBeanプロパティを持つことができます。この場合，インナークラスはインタフェースまたは非staticなクラスにしないでください。インタフェースまたは非staticなクラスであるインナークラスとして宣言された型のフィールドまたはBeanプロパティがある場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

POJOにマッピングできない値がJSONフォーマットにある場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

フィールドおよびBeanプロパティの名称が同じ場合，Beanプロパティが優先されます。

POJOがマッピングの対象となるフィールドもBeanプロパティも持たなくてもエラーにならないのは，JSONフォーマットが空の場合だけです。

(2)　フィールド

フィールドはpublicスコープで定義してください。publicスコープではない場合は，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

static修飾子，またはtransient修飾子およびfinal修飾子をフィールドに指定しないでください。指定されている場合はマッピングの対象になりません。

JSONフォーマットに対応する値がないフィールドは初期化されません（例外はスローされません）。

(3)　Beanプロパティ

Beanプロパティのsetterメソッドにはpublicスコープを推奨します。なお，privateスコープ，protectedスコープ，パッケージスコープも使用できます。

大文字・小文字の違いだけがある複数のsetterメソッドを宣言しないでください。複数宣言されている場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

staticをBeanプロパティに指定しないでください。指定されている場合はマッピングの対象になりません。

final修飾子を指定しても問題ありません。

Beanプロパティは読み取り可能なプロパティである必要はありません。Beanプロパティの詳細についてはJavaBeans仕様を参照してください。

JSONフォーマットに対応する値がないBeanプロパティのsetterメソッドは呼び出されません（例外はスローされません）。

18.3.2　指定できるデータ型

POJOのフィールドおよびBeanプロパティに指定できるデータ型を次に示します。

表18‒3　POJOのフィールドおよびBeanプロパティに指定できるデータ型（JSONからPOJOへのマッピング）

項番

データ

1

プリミティブ

int

2

short

3

long

4

float

5

double

6

char

7

byte

8

boolean

9

ラッパクラス

Integer

10

Short

11

Long

12

Float

13

Double

14

Character

15

Byte

16

Boolean

17

java.lang.String

18

java.math.BigInteger

19

java.math.BigDecimal

20

java.util.Date

21

java.util.Calendar

22

java.lang.Enum

23

POJO※1

24

java.util.List<T>※2

25

java.util.Set<T>※2

26

java.util.Map<K,V>※2

27

項番1〜26のどれかの配列※2，※3

注※1

フィールドまたはBeanプロパティとして再帰的にPOJOを持つことができます。サポートされるPOJOの条件については，「18.3　JSONからPOJOへのマッピング」を参照してください。

注※2

T，K，およびVの型は表の項番1〜26のどれかになります。

注※3

対応するJSONフォーマットの値は，配列の構造に準拠している必要があります。

要素を設定するときの注意事項を次に示します。

JSONフォーマットに次の誤りがある場合，JsonParseExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

数値，文字列，配列，オブジェクト，true，falseまたはnullではない値が含まれている場合

二つのオブジェクトがコンマで区切られていない場合

トークンの間に許可されていない文字が使用されている場合（許可されている文字はスペース，ラインフィード，キャリッジリターン，水平タブ）

数値の形式が不正な場合（12，1.2eE8，0X3F7Aなど）

データ型が数値（表の項番1〜5，7，9〜13，15）のフィールドまたはBeanプロパティに対応するJSONフォーマットの値が数値でない場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

(1)　int型（プリミティブ型）

対応するJSONフォーマットの値が空の文字列の場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

対応するJSONフォーマットの値がnullの場合，int型のデフォルト値で初期化されます。

対応するJSONフォーマットの値はint型の範囲内の数値である必要があります。値がint型の範囲外の場合，動作は保証されません。

(2)　short型（プリミティブ型）

対応するJSONフォーマットの値がnullまたは空の文字列の場合，short型のデフォルト値で初期化されます。

対応するJSONフォーマットの値はshort型の範囲内の数値である必要があります。値がshort型の範囲外の場合，動作は保証されません。

(3)　long型（プリミティブ型）

対応するJSONフォーマットの値が空の文字列の場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

対応するJSONフォーマットの値がnullの場合，long型のデフォルト値で初期化されます。

対応するJSONフォーマットの値はlong型の範囲内の数値である必要があります。値がlong型の範囲外の場合，動作は保証されません。

(4)　float型（プリミティブ型）

対応するJSONフォーマットの値が空の文字列の場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

対応するJSONフォーマットの値がnullの場合，float型のデフォルト値で初期化されます。

対応するJSONフォーマットの値はfloat型の範囲内の数値である必要があります。値がfloat型の範囲外の場合，動作は保証されません。

(5)　double型（プリミティブ型）

対応するJSONフォーマットの値が空の文字列の場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

対応するJSONフォーマットの値がnullの場合，double型のデフォルト値で初期化されます。

対応するJSONフォーマットの値はdouble型の範囲内の数値である必要があります。値がdouble型の範囲外の場合，動作は保証されません。

(6)　char型（プリミティブ型）

対応するJSONフォーマットの値が空の文字列の場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

対応するJSONフォーマットの値がnullの場合，char型のデフォルト値で初期化されます。

対応するJSONフォーマットの値はchar型の範囲内の数値である必要があります。値がchar型の範囲外の場合，動作は保証されません。

(7)　byte型（プリミティブ型）

対応するJSONフォーマットの値がnullまたは空の文字列の場合，byte型のデフォルト値で初期化されます。

対応するJSONフォーマットの値はbyte型の範囲内の数値である必要があります。値がbyte型の範囲外の場合，動作は保証されません。

(8)　boolean型（プリミティブ型）

対応するJSONフォーマットの値がnullまたは空の文字列の場合，boolean型のデフォルト値で初期化されます。

対応するJSONフォーマットの値にtrue，false（大文字と小文字を区別します）以外が設定された場合，JAX-RSエンジンの動作は定義されません。

(9)　Integer型（ラッパクラス型）

対応するJSONフォーマットの値がnullまたは空の文字列の場合，nullがマッピングされます。

対応するJSONフォーマットの値はInteger型の範囲内の数値である必要があります。値がInteger型の範囲外の場合，動作は保証されません。

(10)　Short型（ラッパクラス型）

対応するJSONフォーマットの値が空の文字列の場合，Short型のデフォルト値で初期化されます。

対応するJSONフォーマットの値がnullの場合，nullがマッピングされます。

対応するJSONフォーマットの値はShort型の範囲内の数値である必要があります。値がShort型の範囲外の場合，動作は保証されません。

(11)　Long型（ラッパクラス型）

対応するJSONフォーマットの値がnullまたは空の文字列の場合，nullがマッピングされます。

対応するJSONフォーマットの値はLong型の範囲内の数値である必要があります。値がLong型の範囲外の場合，動作は保証されません。

(12)　Float型（ラッパクラス型）

対応するJSONフォーマットの値がnullまたは空の文字列の場合，nullがマッピングされます。

対応するJSONフォーマットの値はFloat型の範囲内の数値である必要があります。値がFloat型の範囲外の場合，動作は保証されません。

(13)　Double型（ラッパクラス型）

対応するJSONフォーマットの値がnullまたは空の文字列の場合，nullがマッピングされます。

対応するJSONフォーマットの値はDouble型の範囲内の数値である必要があります。値がDouble型の範囲外の場合，動作は保証されません。

(14)　Character型（ラッパクラス型）

対応するJSONフォーマットの値が空の文字列の場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

対応するJSONフォーマットの値がnullの場合，Char型のデフォルト値で初期化されます。

対応するJSONフォーマットの値はChar型の範囲内の数値である必要があります。値がchar型の範囲外の場合，動作は保証されません。

(15)　Byte型（ラッパクラス型）

対応するJSONフォーマットの値が空の文字列の場合，Short型のデフォルト値で初期化されます。

対応するJSONフォーマットの値がnullの場合，nullがマッピングされます。

対応するJSONフォーマットの値はShort型の範囲内の数値である必要があります。値がShort型の範囲外の場合，動作は保証されません。

(16)　Boolean型（ラッパクラス型）

対応するJSONフォーマットの値が空の文字列の場合，Boolean型のデフォルト値で初期化されます。

対応するJSONフォーマットの値がnullの場合，nullがマッピングされます。

対応するJSONフォーマットの値にtrue，false（大文字と小文字を区別します）以外が設定された場合，JAX-RSエンジンの動作は定義されません。

(17)　java.lang.String型

対応するJSONフォーマットの値が空の文字列の場合，空の文字列がマッピングされます。

対応するJSONフォーマットの値がnullの場合，nullがマッピングされます。

対応するJSONフォーマットの値に引用符（"）が含まれている場合，エスケープされている必要があります。エスケープされていない場合はJsonParseExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

対応するJSONフォーマットの値に¥n，¥r，¥t，¥bなどの制御文字が含まれている場合，エスケープされている必要があります。エスケープされていない場合はJsonParseExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

対応するJSONフォーマットの値に制御文字の¥uが含まれている場合，エスケープされている必要があります。また，¥uに続く文字列は16進数の数値である必要があります。これらの条件に反する場合はJsonParseExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

(18)　java.math.BigInteger型，java.math.BigDecimal型

対応するJSONフォーマットの値がnullまたは空の文字列の場合，nullがマッピングされます。

対応するJSONフォーマットの値が数値以外の場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

(19)　java.util.Date型，java.util.Calendar型

対応するJSONフォーマットの値がnullまたは空の文字列の場合，nullがマッピングされます。

サポートされている標準のフォーマットは次のとおりです。

yyyy-MM-dd'T'HH:mm:ss.SSSZ

yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

EEE, dd MMM yyyy HH:mm:ss zzz

yyyy-MM-dd

それぞれのパターン文字の意味と例を次の表に示します。

要素

意味

例

yyyy

年を4桁の数値で表します。

2013

MM

月を2桁の数値で表します。

04

MMM

月を3文字の文字列で表します。

Apr

dd

月における日を2桁の数値で表します。

30

EEE

曜日を3文字の文字列で表します。

Sun

'T'

固定文字です。

−

HH

1日における時を2桁の数値で表します。

23

mm

分を2桁の数値で表します。

30

ss

秒を2桁の数値で表します。

10

SSS

ミリ秒を3桁の数値で表します。

978

'Z'

固定文字です。

−

Z

RFC 822で定義されているタイムゾーンを表します。

-0530

zzz

標準時間を表します。

IST

（凡例）

−：固定文字のため例はありません。

DateまたはCalendarのフォーマットにおける各パターン文字，特にロケールに依存する「E」および「M」については，Java SE仕様のSimpleDateFormatクラスに関する情報を参照してください。

対応するJSONフォーマットの値がサポートされないフォーマットの場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

対応するJSONフォーマットの値がlong型の範囲の数値の場合，つまりDate型，またはCalendar型に対応する値がミリ秒で表現されている場合，それぞれそのミリ秒で初期化されたDate型，またはCalendar型のオブジェクトがマッピングされます。値がlong型の範囲外の場合，動作は保証されません。

例えば，対応するJSONフォーマットの値が1346850421185の場合，Date型のフィールドまたはBeanプロパティには，dateパラメタに1346850421185を指定してDateクラスのDate(long date)コンストラクタを呼び出した結果（Dateオブジェクト）がマッピングされます。Calendar型のフィールドまたはBeanプロパティには，同じようにDateオブジェクトを生成し，さらにdateパラメタにそのDateオブジェクトを指定してCalendarクラスのsetTime(Date date)メソッドの呼び出した結果（Calendarオブジェクト）がマッピングされます。

(20)　java.lang.Enum型

対応するJSONフォーマットの値が空の文字列の場合，JsonMappingExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

対応するJSONフォーマットの値がnullの場合，nullがマッピングされます。

対応するJSONフォーマットの値がEnum型に含まれない場合，JsonMappingExceptionがスローされます。例外ハンドリングついては「18.3.3　例外ハンドリング」を参照してください。

(21)　java.util.List<T>型

対応するJSONフォーマットの値が空のリスト（[]）の場合，空のリストがマッピングされます。

対応するJSONフォーマットの値がnullの場合，nullがマッピングされます。

対応するJSONフォーマットのリストにnullが含まれている場合，マッピングされるList<T>型のフィールド，またはBeanプロパティの対応する要素にはnullが設定されます。

対応するJSONフォーマットのリストに含まれる値は，Tに設定する型の条件に準拠している必要があります。条件については，「18.3.2　指定できるデータ型」のそれぞれの型の注意事項を参照してください。条件に反する場合の動作はそれぞれの注意事項に記載されているとおりです。

(22)　java.util.Set<T>型

対応するJSONフォーマットの値が空のリスト（[]）の場合，空のセットがマッピングされます。

対応するJSONフォーマットの値がnullの場合，nullがマッピングされます。

対応するJSONフォーマットのリストにnullが含まれている場合，マッピングされるSet<T>型のフィールド，またはBeanプロパティの対応する要素にはnullが設定されます。

対応するJSONフォーマットのセットに含まれる値は，Tに設定する型の条件に準拠している必要があります。条件については，「18.3.2　指定できるデータ型」のそれぞれの型の注意事項を参照してください。条件に反する場合の動作はそれぞれの注意事項に記載されているとおりです。

(23)　java.util.Map<K,V>型

対応するJSONフォーマットの値が空のマップ（{}）の場合，空のマップがマッピングされます。

対応するJSONフォーマットの値がnullの場合，nullがマッピングされます。

対応するJSONフォーマットのマップにキーとしてnullが含まれている場合，JsonParseExceptionがスローされます。例外ハンドリングについては「18.3.3　例外ハンドリング」を参照してください。

対応するJSONフォーマットのマップに値としてnullが含まれている場合，マッピングされるMap<K,V>型のフィールド，またはBeanプロパティの対応する値にはnullが設定されます。

対応するJSONフォーマットのマップに含まれるキーおよび値は，それぞれK，Vに設定する型の条件に準拠している必要があります。条件については，「18.3.2　指定できるデータ型」のそれぞれの型の注意事項を参照してください。条件に反する場合の動作はそれぞれの注意事項に記載されているとおりです。

18.3.3　例外ハンドリング

JSONからPOJOへのマッピングは，JAX-RS仕様のエンティティプロバイダの仕組みで実装されています。このため，マッピングで発生する例外はほかのマッピングで例外が発生する場合と同じように処理されます。マッピングで例外がどのように処理されるかについては，サーバ側については「17.1.2　エンティティパラメタ」を，クライアント側については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

18.4　マッピング中に発生する例外

JSON POJOマッピング中に発生する例外を次の表に示します。

表18‒4　JSON POJOマッピング中に発生する例外

項番

インタフェースまたはクラス

com.cosminexus.org.codehaus.jackson.mapパッケージ

1

JsonMappingException

com.cosminexus.org.codehaus.jacksonパッケージ

2

JsonParseException

3

JsonGenerationException

19　JAX-WS仕様のサポート範囲

この章では，Webサービスを開発するときに留意が必要な，JAX-WS仕様のサポート範囲について説明します。

19.1　JAX-WS 2.2仕様のサポート範囲

JAX-WS 2.2仕様の機能のサポート範囲，およびConformanceへの対応について説明します。

19.1.1　JAX-WS 2.2仕様の機能のサポート範囲

JAX-WS 2.2仕様の機能のサポート範囲を次の表に示します。

なお，前提条件については，「1.4.2　機能および仕様に関する前提条件」を参照してください。

表19‒1　JAX-WS 2.2仕様の機能のサポート範囲

分類

サポート

備考

大分類※1

小分類※2

2

WSDL 1.1からJavaへのマッピング

○

2

埋め込みによるバインディング宣言，または外部バインディングファイルによるマッピングのカスタマイズ

○

バンディング宣言のサポート範囲については，「15.2　WSDLからJavaへのマッピングのカスタマイズ」を参照してください。

2

生成されるJavaコードへのアノテーションの付与

○

アノテーションのサポート範囲については，「16.2.1　アノテーション一覧」を参照してください。

2.1

名前空間からパッケージへのマッピング

○

マッピングについては，「15.1.1　名前空間からパッケージ名へのマッピング」を参照してください。

2.2

ポートタイプからSEIへのマッピング

○

マッピングについては，「15.1.2　ポートタイプからSEI名へのマッピング」を参照してください。

2.3

オペレーションからSEIのメソッドへのマッピング

○

マッピングについては，「15.1.3　オペレーションからメソッド名へのマッピング」を参照してください。

2.3

メソッドのオーバーロード

○

メソッドのオーバーロードについては，「15.1.11(1)　Javaメソッドのオーバーロード」を参照してください。

2.3

MEP:request-responseオペレーションのサポート

○

2.3

MEP:one-wayオペレーションのサポート

○

2.3.1.1

Non-wrapperスタイルのオペレーションのサポート

○

2.3.1.2

Wrapperスタイルのオペレーションのサポート

○

2.3.2

パラメタの順序と戻り値の型

parameterOrder属性

×

parameterOrder属性以外

○

2.3.3

javax.xml.ws.Holder<T>クラス

○

javax.xml.ws.Holder<T>クラスのサポート範囲については，「19.2.4(12)　javax.xml.ws.Holder<T>クラス」を参照してください。

2.3.4

非同期マッピング

×

2.4.1

W3CEndpointReferenceクラス

○

2.5

フォルトからサービス固有例外へのマッピング

○

マッピングについては，「15.1.7　フォルトから例外クラスへのマッピング」を参照してください。

2.6

SOAPバインディング

SOAP 1.1/HTTP

○

SOAP 1.2/HTTP

○

2.6

MIMEバインディング

×

2.6.2.1

soap:header要素

○

soap:header要素のサポート範囲（記述できる構文）については，「20.1.22　soap:header要素」を参照してください。

2.7

サービスとポートからサービスクラスへのマッピング

○

マッピングについては，「15.1.9　サービスおよびポートからサービスクラスへのマッピング」を参照してください。

2.8

XMLの名前からJavaの識別子へのマッピング

○

2.8.1

名前が衝突した場合の処理

○

名前衝突時の処理については，「15.1.11(2)　名前衝突時のマッピング」を参照してください。

3

JavaからWSDL 1.1へのマッピング

○

3

アノテーションによるマッピングのカスタマイズ

○

アノテーションのサポート範囲については，「16.2.1　アノテーション一覧」を参照してください。

3.1

Javaの識別子からXMLの名前へのマッピング

○

3.2

パッケージから名前空間へのマッピング

○

3.3

暗黙のSEIからポートタイプへのマッピング

○

3.4

SEIからポートタイプへのマッピング

○

マッピングについては，「16.1.3　SEI名からポートタイプへのマッピング」を参照してください。

3.5

SEIのメソッドからオペレーションへのマッピング

○

マッピングについては，「16.1.4　SEIのメソッド名からオペレーションへのマッピング」を参照してください。

3.5.1

one-wayのオペレーション

○

3.6

パラメタと戻り値のマッピング

○

マッピングについては，「16.1.5　パラメタおよび戻り値からメッセージのパートへのマッピング（wrapperスタイルの場合）」および「16.1.6　パラメタおよび戻り値からメッセージのパートへのマッピング（non-wrapperスタイルの場合）」を参照してください。

3.6

soap:header要素

○

3.6.2.1

Document Wrappedスタイルのマッピング

○

3.6.2.2

Document Bareスタイルのマッピング

○

3.6.2.3

RPCスタイルのマッピング

×

3.7

サービス固有例外からフォルトへのマッピング

○

マッピングについては，「16.1.7　Javaのラッパ例外クラスからフォルトへのマッピング」を参照してください。

3.8

サービスクラスからバインディングへのマッピング

○

マッピングについては，「16.1.8　SEIからバインディングへのマッピング」を参照してください。

3.9

ジェネリクスの処理

○

ジェネリクスの処理については，「16.1.10(1)　ジェネリクスの型削除」および「16.1.10(3)　ジェネリクス型の制限」を参照してください。

3.10

SOAP/HTTPバインディング

SOAP 1.1/HTTP

○

SOAP 1.2/HTTP

○

3.11

サービスクラスからサービスとポートへのマッピング

○

マッピングについては，「16.1.9　Webサービス実装クラスからサービスおよびポートへのマッピング」を参照してください。

4

クライアントAPI

○

APIのサポート範囲については，「19.2　APIのサポート範囲」を参照してください。

5

サービスAPI

○

APIのサポート範囲については，「19.2　APIのサポート範囲」を参照してください。

6

コアAPI

○

APIのサポート範囲については，「19.2　APIのサポート範囲」を参照してください。

7

アノテーション

○

アノテーションのサポート範囲については，「16.2.1　アノテーション一覧」を参照してください。

8

バインディング宣言

○

バンディング宣言のサポート範囲については，「15.2　WSDLからJavaへのマッピングのカスタマイズ」を参照してください。

9.1.1

論理ハンドラ

○

論理ハンドラについては，「36.4　ハンドラの型」を参照してください。

9.1.1

プロトコルハンドラ

○

プロトコルハンドラについては，「36.4　ハンドラの型」を参照してください。

9.2.1.1

Webサービスクライアント側でのハンドラの設定

APIによる動的な設定

○

ハンドラの設定については，「36.9　ハンドラチェインの設定」を参照してください。

上記以外

×

9.2.1.2

ハンドラの順番づけ

○

ハンドラの実行順序については，「36.5　ハンドラチェインの編成と実行順序」を参照してください。

9.2.1.3

Webサービス側でのハンドラの設定

javax.jws.HandlerChainアノテーションによる設定

○

ハンドラの設定については，「36.9　ハンドラチェインの設定」を参照してください。

上記以外

×

9.2.2

WSEE仕様（JSR-109）に基づくハンドラのデプロイ

×

9.3

ハンドラの処理モデル

○

ハンドラの処理については，「36.5　ハンドラチェインの編成と実行順序」を参照してください。

9.4

メッセージコンテキスト

○

メッセージコンテキストのプロパティのサポート範囲については，「19.2.5(1)　メッセージコンテキストのプロパティのサポート範囲」を参照してください。

10.1.1

SOAPバインディングの動的な（プログラム的な）設定

○

10.1.2

SOAPバインディングの静的な（デプロイメントによる）設定

×

10.2

SOAPバインディングの処理モデル

○

10.3

SOAPメッセージコンテキスト

○

メッセージコンテキストのサポート範囲については，「19.2.5　メッセージコンテキストの使用」を参照してください。

10.4.1

SOAP 1.1/HTTPバインディング

○

10.4.1

SOAP 1.2/HTTPバインディング

○

10.4.1.1

MTOM仕様

○

10.4.1.2

one-wayのオペレーション

○

10.4.1.3

HTTPベーシック認証

○

10.4.1.4

セッション管理

○

10.4.1.5

WS-Addressing仕様

○

11

XML/HTTPバインディング

×

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

空欄：特に補足する内容がないことを示します。

注※1

JAX-WS 2.2仕様の該当個所（章節項）を示します。

注※2

JAX-WS 2.2仕様の該当個所に記載されている内容を示します。

19.1.2　Conformanceへの対応

Conformanceへ対応しているかどうかを次の表に示します。なお，Conformanceの番号は，JAX-WS 2.2仕様の"Appendix A Conformance Requirements"に準じます。

表19‒2　Conformanceへの対応

分類

対応

備考

番号※1

タイトル※2

2.1

WSDL 1.1 support

○

2.2

Customization required

○

バンディング宣言のサポート範囲については，「15.2　WSDLからJavaへのマッピングのカスタマイズ」を参照してください。

2.3

Annotations on generated classes

○

アノテーションのサポート範囲については，「16.2.1　アノテーション一覧」を参照してください。

2.4

Definitions mapping

○

wsdl:definitions要素のtargetNamespace属性に指定できる値については，「15.1.1(2)　名前空間の条件」を参照してください。

2.5

WSDL and XML Schema import directives

○

wsdl:import要素については，「26.3　wsdl:import要素の書式」を参照してください。

2.6

Optional WSDL extensions

○

Conformance自体には対応していますが，JAX-WS 2.2仕様で規定されていないWSDLの拡張要素や属性はサポートしていません。

2.7

SEI naming

○

wsdl:portType要素のname属性に指定できる値については，「15.1.2(2)　ポートタイプ名の条件」を参照してください。

2.8

javax.jws.WebService required

○

2.9

javax.xml.bind.XmlSeeAlso required

○

2.10

Method naming

○

wsdl:operation要素のname属性に指定できる値については，「15.1.3(2)　オペレーション名の条件」を参照してください。

2.11

javax.jws.WebMethod required

○

2.12

Transmission primitive support

one-way

○

request-response

○

2.13

Using javax.jws.OneWay

○

2.14

Using javax.jws.SOAPBinding

○

2.15

Using javax.jws.WebParam

○

wsdl:part要素のname属性に指定できる値については，「15.1.5(2)　パート名の条件」を参照してください。

2.16

Using javax.jws.WebResult

○

2.17

Generating @Action

○

2.18

Generating @Action input

○

2.19

Generating @Action output

○

2.20

Generating @Action fault

○

2.21

use of JAXB annotations

○

アノテーションのサポート範囲については，「16.2.1　アノテーション一覧」を参照してください。

2.22

Non-wrapped parameter naming

○

wsdl:part要素のname属性に指定できる値については，「15.1.5(2)　パート名の条件」を参照してください。

2.23

Default mapping mode

○

2.24

Disabling wrapper style

○

2.25

Wrapped parameter naming

○

wrapper子要素のname属性に指定できる値については，「15.1.4(2)　wrapper子要素名の条件」を参照してください。

2.26

Parameter name clash

○

2.27

Using javax.xml.ws.RequestWrapper

○

2.28

Using javax.xml.ws.ResponseWrapper

○

2.29

Use of Holder

○

2.30

Asynchronous mapping required

×

2.31

Asynchronous mapping option

×

2.32

Asynchronous method naming

−

非同期関連の機能はサポートしていません。

2.33

Asynchronous parameter naming

−

非同期関連の機能はサポートしていません。

2.34

Failed method invocation

−

非同期関連の機能はサポートしていません。

2.35

Response bean naming

−

非同期関連の機能はサポートしていません。

2.36

Asynchronous fault reporting

−

非同期関連の機能はサポートしていません。

2.37

Asynchronous fault cause

−

非同期関連の機能はサポートしていません。

2.38

JAXB class mapping

○

2.39

JAXB customization use

○

2.40

JAXB customization clash

○

2.41

javax.xml.ws.wsaddressing.W3CEndpointReference

○

2.42

javax.xml.ws.WebFault required

○

2.43

Exception naming

○

wsdl:fault要素およびwsdl:message要素のname属性に指定できる値については，「15.1.7(2)　フォルト名の条件」を参照してください。

2.44

Fault equivalence

○

2.45

Fault equivalence

○

2.46

Required WSDL extensions

SOAP

○

MIME

×

2.47

Unbound message parts

○

2.48

Duplicate headers in binding

○

2.49

Duplicate headers in message

○

2.50

Use of MIME type information

−

MIMEバインディングはサポートしていません。

2.51

MIME type mismatch

−

MIMEバインディングはサポートしていません。

2.52

MIME part identification

−

MIMEバインディングはサポートしていません。

2.53

Service superclass required

○

2.54

Service class naming

○

wsdl:service要素のname属性に指定できる値については，「15.1.9(2)　サービス名およびポート名の条件」を参照してください。

2.55

javax.xml.ws.WebServiceClient required

○

2.56

Generated service default constructor

○

2.57

Generated service(WebServiceFeature ...) constructor

○

2.58

Generated service(URL) constructor

○

2.59

Generated service(URL,WebServiceFeature...) constructor

○

2.60

Generated service(URL,QName) constructor

○

2.61

Generated service(URL,QName,WebServiceFeature...) constructor

○

2.62

Failed getPort Method

○

2.63

javax.xml.ws.WebEndpoint required

○

3.1

WSDL 1.1 support

○

WSDL 1.1仕様のサポート範囲については，「20.1　WSDL 1.1仕様のサポート範囲」を参照してください。

3.2

Standard annotations

○

アノテーションのサポート範囲については，「16.2.1　アノテーション一覧」を参照してください。

3.3

Java identifier mapping

○

3.4

Method name disambiguation

○

3.5

Package name mapping

○

Javaの識別子やアノテーションで指定できる値については，「16.　JavaからWSDLへのマッピング」を参照してください。

3.6

WSDL and XML Schema import directives

○

3.7

Class mapping

○

3.8

portType naming

○

Javaの識別子やアノテーションで指定できる値については，「16.　JavaからWSDLへのマッピング」を参照してください。

3.9

Inheritance flattening

○

3.10

Inherited interface mapping

○

Conformance自体には対応していますが，Application ServerのJAX-WS機能ではこのConformanceで説明されているようなマッピングはされません。

3.11

Operation naming

○

Javaの識別子やアノテーションで指定できる値については，「16.　JavaからWSDLへのマッピング」を参照してください。

3.12

Generating wsam:Action

○

3.13

One-way mapping

○

3.14

One-way mapping errors

○

3.15

use of JAXB annotations

○

3.16

Overriding JAXB types empty namespace

○

3.17

Parameter classification

○

3.18

Parameter naming

○

Javaの識別子やアノテーションで指定できる値については，「16.　JavaからWSDLへのマッピング」を参照してください。

3.19

Result naming

○

Javaの識別子やアノテーションで指定できる値については，「16.　JavaからWSDLへのマッピング」を参照してください。

3.20

Header mapping of parameters and results

○

3.21

Dynamically generating wrapper beans

○

3.22

Default wrapper bean names

○

Javaの識別子やアノテーションで指定できる値については，「16.　JavaからWSDLへのマッピング」を参照してください。

3.23

Default wrapper bean package

○

Javaの識別子やアノテーションで指定できる値については，「16.　JavaからWSDLへのマッピング」を参照してください。

3.24

Wrapper element names

○

Javaの識別子やアノテーションで指定できる値については，「16.　JavaからWSDLへのマッピング」を参照してください。

3.25

Wrapper bean name clash

○

3.26

Default Wrapper wsdl:part names

○

3.27

Customizing Wrapper wsdl:part names

○

3.28

Wrapper property

○

3.29

Null Values in rpc/literal

−

rpc/literalスタイルはサポートしていません。

3.30

Exception naming

○

Javaの識別子やアノテーションで指定できる値については，「16.　JavaからWSDLへのマッピング」を参照してください。

3.31

wsdl:message naming

○

3.32

wsdl:message naming using WebFault

○

3.33

java.lang.RuntimeExceptions and java.rmi.RemoteExceptions

○

3.34

Fault bean’s @XmlType

○

3.35

Fault bean name clash

○

3.36

Dynamically generating exception beans

○

3.37

Binding selection

○

3.38

SOAP binding support

○

3.39

SOAP binding style required

○

3.40

Service creation

○

3.41

Port selection

○

Javaの識別子やアノテーションで指定できる値については，「16.　JavaからWSDLへのマッピング」を参照してください。

3.42

Port binding

○

3.43

Use of Addressing

○

4.1

Service completeness

×

未サポートのAPIがあります。

4.2

Service Creation Failure

○

4.3

Service creation using features

○

4.4

Use of Executor

−

非同期関連の機能はサポートしていません。

4.5

Default Executor

−

非同期関連の機能はサポートしていません。

4.6

javax.xml.ws.BindingProvider.getEndpointReference

○

4.7

BindingProvider’s W3CEndpointReference

○

4.8

Message context decoupling

○

4.9

Required BindingProvider properties

○

4.10

Optional BindingProvider properties

○

4.11

Additional context properties

○

4.12

Asynchronous response context

−

非同期関連の機能はサポートしていません。

4.13

Proxy support

○

4.14

Implementing BindingProvider

○

4.15

Service.getPort failure

○

4.16

Proxy's Addressing use

○

4.17

Remote Exceptions

○

4.18

Exceptions During Handler Processing

○

4.19

Other Exceptions

○

4.20

Dispatch support

○

4.21

Failed Dispatch.invoke

○

4.22

Failed Dispatch.invokeAsync

−

非同期関連の機能はサポートしていません。

4.23

Failed Dispatch.invokeOneWay

○

4.24

Reporting asynchronous errors

−

javax.xml.ws.Responseインタフェースはサポートしていません。

4.25

Marshalling failure

○

4.26

Use of the Catalog

○

5.1

Provider support required

○

5.2

Provider default constructor

○

5.3

Provider implementation

○

5.4

WebServiceProvider annotation

○

5.5

Endpoint publish(String address, Object implementor) Method

−

javax.xml.ws.Endpointクラスはサポートしていません。

5.6

Default Endpoint Binding

−

javax.xml.ws.Endpointクラスはサポートしていません。

5.7

Other Bindings

−

javax.xml.ws.Endpointクラスはサポートしていません。

5.8

Publishing over HTTP

−

javax.xml.ws.Endpointクラスはサポートしていません。

5.9

WSDL Publishing

−

javax.xml.ws.Endpointクラスはサポートしていません。

5.10

Checking publishEndpoint Permission

−

javax.xml.ws.Endpointクラスはサポートしていません。

5.11

Required Metadata Types

−

javax.xml.ws.Endpointクラスはサポートしていません。

5.12

Unknown Metadata

−

javax.xml.ws.Endpointクラスはサポートしていません。

5.13

Use of Executor

−

javax.xml.ws.Endpointクラスはサポートしていません。

5.14

Default Executor

−

javax.xml.ws.Endpointクラスはサポートしていません。

5.15

Endpoint's W3CEndpointReference

○

5.16

Building W3CEndpointReference

○

6.1

Read-only handler chains

○

6.2

Concrete javax.xml.ws.spi.Provider required

○

6.3

Provider createAndPublishEndpoint Method

−

javax.xml.ws.Providerインタフェースはサポートしていません。

6.4

Concrete javax.xml.ws.spi.ServiceDelegate required

○

6.5

Protocol specific fault generation

○

6.6

Protocol specific fault consumption

○

6.7

One-way operations

○

6.8

javax.xml.ws.WebServiceFeatures

−

javax.xml.ws.WebServiceFeatureクラスはサポートしていません。

6.9

enabled property

−

javax.xml.ws.WebServiceFeatureクラスはサポートしていません。

6.10

javax.xml.ws.soap.MTOMFeature

○

6.11

javax.xml.ws.RespectBindingFeature

−

javax.xml.ws.RespectBindingFeatureクラスはサポートしていません。

6.12

HTTP SPI in SE platform

×

JAX-WSでは，Java SE単体での開発および運用をサポートしていません。

7.1

Correctness of annotations

○

アノテーションのサポート範囲については，「16.2.1　アノテーション一覧」を参照してください。

7.2

Handling incorrect annotations

○

アノテーションのサポート範囲については，「16.2.1　アノテーション一覧」を参照してください。

7.3

Unsupported WebServiceFeatureAnnotation

○

7.4

WebServiceProvider and WebService

○

7.5

JSR-181 conformance

○

アノテーションのサポート範囲については，「16.2.1　アノテーション一覧」を参照してください。

8.1

Standard binding declarations

○

8.2

Binding language extensibility

○

8.3

Multiple binding files

○

9.1

Handler framework support

○

9.2

Logical handler support

○

9.3

Other handler support

○

APIのサポート範囲については，「19.2　APIのサポート範囲」を参照してください。

9.4

Incompatible handlers

○

9.5

Incompatible handlers

○

9.6

Handler chain snapshot

○

9.7

HandlerChain annotation

○

9.8

Handler resolver for a HandlerChain annotation

○

9.9

Binding handler manipulation

○

9.10

Handler initialization

○

9.11

Handler destruction

○

9.12

Invoking close

○

9.13

Order of close invocations

○

9.14

Message context property scope

○

10.1

SOAP required roles

○

10.2

SOAP required roles

○

10.3

Default role visibility

○

10.4

Default role persistence

○

10.5

None role error

○

10.6

Incompatible handlers

○

10.7

Incompatible handlers

○

10.8

Logical handler access

○

10.9

SOAP 1.1 HTTP Binding Support

○

10.10

SOAP 1.2 HTTP Binding Support

○

10.11

SOAP MTOM Support

○

10.12

Semantics of MTOM enabled

○

10.13

MTOM support

○

10.14

SOAP bindings with MTOM disabled

○

10.15

SOAP bindings with MTOM enabled

○

10.16

MTOM on Other SOAP Bindings

−

ほかのjavax.xml.ws.soap.SOAPBindingインタフェースの実装をサポートしていないので，このConformanceには該当しません。

10.17

One-way operations

○

10.18

HTTP basic authentication support

○

10.19

Authentication properties

○

10.21

URL rewriting support

×

10.22

Cookie support

○

10.22

SSL session support

○

Conformance自体には対応していますが，Application ServerのJAX-WS機能ではSSLセッションをベースとする状態管理をサポートしていません。

10.23

SOAP Addressing Support

○

11.1

XML/HTTP Binding Support

×

11.2

Incompatible handlers

×

11.3

Incompatible handlers

×

11.4

Logical handler access

×

11.5

One-way operations

×

11.6

HTTP basic authentication support

×

11.7

Authentication properties

×

11.8

URL rewriting support

×

11.9

Cookie support

×

11.10

SSL session support

×

（凡例）

○：対応しています。

×：対応していません。

−：該当しません。

空欄：特に補足する内容がないことを示します。

注※1

JAX-WS 2.2仕様の"Appendix A Conformance Requirements"の番号を示します。

注※2

Conformanceに記載されたタイトルです。

19.2　APIのサポート範囲

19.2.1　インタフェースおよびクラスの一覧（JAX-WS）

ここでは，JAX-WS APIのインタフェースおよびクラスの種類について説明します。また，インタフェースおよびクラスのサポート範囲についても示します。

(1)　インタフェースおよびクラスの種類

JAX-WS APIのインタフェースおよびクラスは，次に示すAPI群に分類されます。

クライアントAPI

ディスパッチベースまたはAPIベースのWebサービスクライアントで使用するAPIです。スタブベースのWebサービスクライアントでは，コマンドで生成されたサービスクラスやスタブを使用してWebサービスにアクセスするため，クライアントAPIは使用しません。

サービスAPI

Webサービスに高度な実装を記述する場合に使用するAPIです。プロバイダ実装クラスを使用したWebサービスやハンドラなど，複雑な機能を利用する場合に使用します。

コアAPI

WebサービスとWebサービスクライアントのどちらでも使用できるAPIです。inoutおよびoutパラメタを保持するためのHolderクラス，または例外などが含まれます。

(2)　インタフェースおよびクラスの一覧表

JAX-WS APIのインタフェースおよびクラスの一覧を次の表に示します。Application ServerのJAX-WS機能でサポートしていないインタフェースおよびクラスを使用してWebサービスを開発した場合の動作は保証されません。

表19‒3　JAX-WS APIのインタフェースおよびクラス一覧

項番

インタフェースまたはクラス名

説明

サポート

javax.xml.wsパッケージ

1

AsyncHandler<T>

−

×

2

Binding

−

×

3

BindingProvider

プロトコルバインディングと関連づけられたコンテキストオブジェクトへのアクセスを提供するインタフェースです。

○

4

Dispatch<T>

XMLメッセージを送信するためのインタフェースです。

○

5

LogicalMessage

プロトコルに捕らわれないXMLメッセージを表現し，メッセージのペイロードへアクセスする方法を提供するメソッドを含むインタフェースです。

○

6

Provider<T>

XMLメッセージを受信するためのインタフェースです。

○

7

Response<T>

−

×

8

WebServiceContext

Webサービス実装クラスまたはプロバイダ実装クラスに対して現在処理中のリクエストに関連する情報へのアクセスを提供するインタフェースです。

javax.annotation.Resourceアノテーションを指定し，現在処理中のリクエストに関連する情報をインジェクトして使用します。

○

9

Endpoint

−

×

10

EndpointReference

Webサービスエンドポイントのリモート参照のWS-Addressing EndpointReferenceを表す抽象クラスです。

○

11

Holder<T>

型Tの値を保持するクラスです。

○

12

RespectBindingFeature

−

×

13

Service

Webサービスクライアントが使用するためのWebサービスを表すクラスです。

○

14

WebServiceFeature

ユーザが直接使用することはありません。

○

15

WebServicePermission

−

×

16

ProtocolException

プロトコルレベルでのフォルト情報を，クライアントに通知するためのクラスです。

○

17

WebServiceException

JAX-WS APIの実行時例外を表す例外クラスです。

○

javax.xml.ws.handlerパッケージ

18

Handler<C extends MessageContext>

ハンドラの基底インタフェースです。

○

19

HandlerResolver

プロキシに設定されたハンドラチェインを制御するために，Webサービスクライアントの実装者が実装するインタフェースです。

○

20

LogicalHandler<C extends LogicalMessageContext>

論理ハンドラです。論理ハンドラを実装する場合はこのインタフェースを実装してください。

このインタフェースには，メソッドはありません。

○

21

LogicalMessageContext

論理ハンドラ用のメッセージコンテキストです。

○

22

MessageContext

プロパティセットを管理するメソッドを提供するインタフェースです。

○

23

PortInfo

ハンドラリゾルバがハンドラチェインの生成を求められたときに，どのポートのために求められているのかクエリするために使用する情報です。

○

javax.xml.handler.soapパッケージ

24

SOAPHandler<T extends SOAPMessageContext>

SOAPハンドラです。SOAPハンドラを実装する場合はこのインタフェースを実装してください。

○

25

SOAPMessageContext

SOAPハンドラ用のメッセージコンテキストです。

○

javax.xml.ws.httpパッケージ

26

HTTPBinding

−

×

27

HTTPException

−

×

javax.xml.ws.soapパッケージ

28

SOAPBinding

SOAPバインディング用の抽象クラスです。

○

29

AddressingFeature

WS-Addressingを使用することを表すフィーチャクラスです。

○

30

MTOMFeature

MTOM/XOP仕様形式の添付ファイルを使用することを表すフィーチャクラスです。

○

31

SOAPFaultException

SOAPフォルトの例外を表すクラスです。

○

javax.xml.ws.spiパッケージ

32

Provider

ServiceDelegateおよびEndpointオブジェクトを作成する抽象クラスです。

ユーザが直接使用することはありません。

○

33

ServiceDelegate

Serviceオブジェクトによって内部的に使用される抽象クラスです。

ユーザが直接使用することはありません。

○

javax.xml.ws.wsaddressingパッケージ

34

W3CEndpointReference

EndpointReference抽象クラスの実装クラスです。

○

35

W3CEndpointReferenceBuilder

W3CEndpointReferenceクラスを作成するために使用されるビルダクラスです。

○

com.sun.xml.ws.developerパッケージ

36

StreamingAttachmentFeature

ストリーミングを使用することを表すフィーチャクラスです。

○

37

StreamingDataHandler

ストリーミングを使用した添付ファイルを表す抽象クラスです。

○

org.jvnet.mimepullパッケージ

38

MIMEConfig

MIMEメッセージの構文解析と出力に関する設定をするためのクラスです。

○

（凡例）

−：説明がないことを示します（非サポートのため）。

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

19.2.2　クライアントAPI

ここでは，クライアントAPIのサポート範囲について説明します。

(1)　javax.xml.ws.BindingProviderインタフェース

javax.xml.ws.BindingProviderインタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒4　javax.xml.ws.BindingProviderインタフェースのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

Binding

getBinding()

○

説明

このバインディングプロバイダのバインディングを取得します。

2

EndpointReference

getEndpointReference()

×

3

<T extends EndpointReference> T

getEndpointReference (java.lang.Class<T> clazz)

×

4

java.util.Map <java.lang.String, java.lang.Object>

getRequestContext()

○

説明

要求メッセージのメッセージコンテキストを初期化するために使用されるコンテキストを取得します。

5

java.util.Map <java.lang.String, java.lang.Object>

getResponseContext()

○

説明

応答メッセージの処理によって得られたコンテキストを取得します。応答メッセージが処理される前に呼び出した場合はnullを返します。one-wayオペレーションの場合は，レスポンスメッセージが存在しないため，このメソッドを呼び出さないでください。one-wayオペレーションで使用したときの動作は保証されません。

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

(2)　javax.xml.ws.Dispatchインタフェース

javax.xml.ws.Dispatchインタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒5　javax.xml.ws.Dispatchインタフェースのサポート範囲

項番

戻り値の型

メソッド名

サポート

1

T

invoke(T msg)

○

2

Response<T>

invokeAsync(T msg)

×

3

java.util.concurrent.Future<?>

invokeAsync(T msg, AsyncHandler<T> handler)

×

4

void

invokeOneWay(T msg)

○

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

(3)　javax.xml.ws.EndpointReferenceクラス

javax.xml.ws.EndpointReferenceクラスのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒6　javax.xml.ws.EndpointReferenceクラスのサポート範囲

項番

戻り値の型

メソッド名

サポート

1

−

EndpointReference()

○

2

<T> T

getPort (java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)

×

3

static EndpointReference

readFrom (javax.xml.transform.Source eprInfoset)

○

4

java.lang.String

toString()

×

5

abstract void

writeTo(javax.xml.transform.Result result)

×

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

(4)　javax.xml.ws.Serviceクラス

javax.xml.ws.Serviceクラスのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒7　javax.xml.ws.Serviceクラスのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

−

Service(java.net.URL wsdlDocumentLocation, javax.xml.namespace.QName serviceName)

○

説明

Serviceインスタンスを生成するコンストラクタです。

引数

wsdlDocumentLocation：

WSDL文書の位置です。nullを指定した場合，Serviceコンストラクタを呼び出しているクラスに設定されているjavax.xml.ws.WebServiceClientアノテーションのwsdlLocation属性の値が設定されます。指定するURLの形式については，java.net.URLクラスの仕様に従ってください。なお，カタログ機能が有効な場合，この引数に指定した値を，カタログファイルで指定した別のWSDLロケーションを示すURIにマッピングします。

serviceName：

サービスの名前です。

例外

javax.xml.ws.WebServiceException：

次の場合に発生します。

wsdlDocumentLocationに，存在しないローカルパス名を指定した場合

wsdlDocumentLocationに，「?wsdl」付きの存在しないHTTPのURLを指定した場合

wsdlDocumentLocationに，「?wsdl」付きではない存在しないHTTPのURLを指定した場合

serviceNameにnullを指定した場合

serviceNameに，WSDLのサービス名（wsdl:service要素のname属性の値）以外のQNameを指定した場合

wsdlDocumentLocationにnullを指定し，かつServiceコンストラクタを呼び出しているクラスでjavax.xml.ws.WebServiceClientアノテーションを使用していない場合

wsdlDocumentLocationにnullを指定し，かつServiceコンストラクタを呼び出しているクラスのjavax.jws.WebServiceアノテーションで，wsdlLocation属性が設定されていない場合

2

void

addPort(javax.xml.namespace.QName portName, java.lang.String bindingId, java.lang.String endpointAddress)

○

例外

javax.xml.ws.WebServiceException：

生成済みのポート名を指定した場合に発生します。

注意

portNameは，createDispatch()を呼び出すときに同じQNameを指定する必要があります。nullは指定できません。

bindingIdにnullを指定した場合は，SOAP1.1/HTTPのバインディングIDが設定されます。

3

static Service

create(javax.xml.namespace.QName serviceName)

○

4

static Service

create(javax.xml.namespace.QName serviceName, javax.xml.ws.WebServiceFeature ... features)

×

5

static Service

create(java.net.URL wsdlDocumentLocation, javax.xml.namespace.QName serviceName)

○

説明

Serviceインスタンスを生成します。

引数

wsdlDocumentLocation：

WSDL文書の位置です。指定するURLの形式についてはjava.net.URLクラスの仕様に従ってください。

serviceName：

WSDLのサービス名（wsdl:service要素のname属性値）です。

例外

javax.xml.ws.WebServiceException：

次の場合に発生します。

wsdlDocumentLocationに存在しないローカルパス名を指定した場合

wsdlDocumentLocationに，「?wsdl」付きの存在しないHTTPのURLを指定した場合

wsdlDocumentLocationに，「?wsdl」付きではない存在しないHTTPのURLを指定した場合

serviceNameに，WSDLのサービス名（wsdl:service要素のname属性の値）以外を指定した場合（ただし，wsdlDocumentLocationにnullを指定した場合を除く）

6

static Service

create(java.net.URL wsdlDocumentLocation, javax.xml.namespace.QName serviceName, javax.xml.ws.WebServiceFeature ... features)

×

7

<T> Dispatch<T>

createDispatch (EndpointReference endpointReference, java.lang.Class<T> type, Service.Mode mode, WebServiceFeature... features)

×

8

Dispatch <java.lang.Object>

createDispatch (EndpointReference endpointReference, javax.xml.bind.JAXBContext context, Service.Mode mode, WebServiceFeature... features)

×

9

<T> Dispatch<T>

createDispatch (javax.xml.namespace.QName portName, java.lang.Class<T> type, Service.Mode mode)

○

注意

portNameは，addPort()の引数に指定するポート名と同じものを指定する必要があります。nullは指定できません。

10

<T> Dispatch<T>

createDispatch (javax.xml.namespace.QName portName, java.lang.Class<T> type, Service.Mode mode, WebServiceFeature... features)

×

11

Dispatch <java.lang.Object>

createDispatch (javax.xml.namespace.QName portName, javax.xml.bind.JAXBContext context, Service.Mode mode)

○

注意

portNameは，addPort()の引数に指定するポート名と同じものを指定する必要があります。nullは指定できません。

12

Dispatch <java.lang.Object>

createDispatch (javax.xml.namespace.QName portName, javax.xml.bind.JAXBContext context, Service.Mode mode, WebServiceFeature... features)

×

13

java.util.concurrent.Executor

getExecutor()

×

14

HandlerResolver

getHandlerResolver()

○

説明

このServiceインスタンスによって使用されているHandlerResolverインスタンスを返します。存在しない場合はnullを返します。

15

<T> T

getPort (java.lang.Class<T> serviceEndpointInterface)

○

説明

ポート（サービスにアクセスするためのプロキシ）を返します。

引数

serviceEndpointInterface：

SEIのClassクラスです。

例外

javax.xml.ws.WebServiceException：

次の場合に発生します。

serviceEndpointInterfaceがnullの場合

wsdlDocumentLocationにnullを指定したService.create()で生成したServiceインスタンスから呼び出した場合

javax.jws.WebServiceアノテーションを使用していないSEIを引数に指定した場合

このメソッドを呼び出す前に，nullを返すgetHandlerChain()を実装したHandlerResolverオブジェクトをsetHandlerResolver()で設定している場合

このメソッドを呼び出す前に，論理ハンドラでもSOAPハンドラでもない，ハンドラを含むハンドラチェインを返すgetHandlerChain()を実装したHandlerResolverオブジェクトをsetHandlerResolver()で設定している場合

16

<T> T

getPort (java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)

×

17

<T> T

getPort(EndpointReference endpointReference, java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)

○※

説明

ポート（サービスにアクセスするためのプロキシ）を返します。

引数

endpointReference：

ポートによって呼び出されるサービスエンドポイントです。

serviceEndpointInterface：

SEIのClassクラスです。

features：

ポート上で構成するWebServiceFeatureのリストです。

例外

javax.xml.ws.WebServiceException：

次の場合に発生します。

ポートの生成中に例外が発生した場合

このメソッドの処理に必要なWSDLが存在しない場合

endpointReferenceメタデータがServiceインスタンスのserviceNameに合っていない場合

WSDLまたはendpointReferenceメタデータからportNameを抽出できない場合

無効なendpointReferenceが指定された場合

無効なserviceEndpointInterfaceが指定された場合

ポートと互換性がない，またはサポートされていないWebServiceFeatureが指定された場合

18

<T> T

getPort(javax.xml.namespace.QName portName, java.lang.Class<T> serviceEndpointInterface)

○

説明

ポート（サービスにアクセスするためのプロキシ）を返します。

引数

portName：

WSDLのポート名（wsdl:port要素のname属性の値）です。

serviceEndpointInterface：

SEIのClassクラスです。

例外

javax.xml.ws.WebServiceException：

次の場合に発生します。

portNameにWSDLのポート名（wsdl:port要素のname属性の値）以外のQNameを指定した場合

portNameがnullの場合

serviceEndpointInterfaceがnullの場合

19

<T> T

getPort(javax.xml.namespace.QName portName, java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)

×

20

java.util.Iterator <javax.xml.namespace.QName>

getPorts()

○

説明

サービスエンドポイント（WSDLに含まれるポート（wsdl:port要素））を表すQNameのリストのIteratorを返します。

例外

javax.xml.ws.WebServiceException：

wsdlDocumentLocationにnullを指定して生成したServiceインスタンスに対して，Service.create()メソッドを呼び出した場合に発生します。

21

javax.xml.namespace.QName

getServiceName()

○

説明

このサービスの名前（WSDLのサービス名（wsdl:service要素のname属性の値））を返します。

22

java.net.URL

getWSDLDocumentLocation()

○

説明

このサービスのWSDLファイルの位置を返します。引数wsdlDocumentLocationにnullを指定して生成したServiceインスタンスに対して，Service.create()メソッドを呼び出した場合にはnullを返します。

23

void

setExecutor (java.util.concurrent.Executor executor)

×

24

void

setHandlerResolver (HandlerResolver handlerResolver)

○

説明

このServiceインスタンスのHandlerResolverインスタンスを設定してください。

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

注※

getPortメソッドで可変長引数を指定した場合の動作を次の表に示します。

表19‒8　可変長引数の指定方法と動作

項番

指定方法

指定例

動作

1

引数を省略

getPort(epr, sei)

可変長引数が指定されなかったと見なします。

2

引数を一つ指定

getPort(epr, sei, new FooFeatures())

可変長引数が一つ指定されたと見なします。

3

引数を二つ指定

getPort(epr, sei,

new FooFeatures(),

new BarFeatures())

可変長引数が二つ指定されたと見なします。

4

引数にnullを指定

getPort(epr, sei, null)

可変長引数が指定されなかったと見なします。

5

引数にnullを指定してWebServiceFeature 型にキャスト

getPort(epr, sei,

(WebServiceFeature) null)

内容がnullの可変長引数が指定されたと見なし，例外NullPointerExceptionが発生します。

6

引数にnullを指定してWebServiceFeature 型の配列にキャスト

getPort(epr, sei,

(WebServiceFeature[]) null)

可変長引数が指定されなかったと見なします。

(5)　javax.xml.ws.wsaddressing.W3CEndpointReferenceクラス

javax.xml.ws.wsaddressing.W3CEndpointReferenceクラスのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒9　javax.xml.ws.wsaddressing.W3CEndpointReferenceクラスのサポート範囲

項番

戻り値の型

メソッド名

サポート

1

−

W3CEndpointReference()

○

2

−

W3CEndpointReference (javax.xml.transform.Source source)

○

3

void

writeTo(javax.xml.transform.Result result)

×

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

19.2.3　サービスAPI

ここでは，サービスAPIのサポート範囲について説明します。

(1)　javax.xml.ws.Providerインタフェース

javax.xml.ws.Providerインタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒10　javax.xml.ws.Providerインタフェースのサポート範囲

項番

戻り値の型

メソッド名

サポート

1

T

invoke(T request)

○

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

(2)　javax.xml.ws.WebServiceContextインタフェース

javax.xml.ws.WebServiceContextインタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒11　javax.xml.ws.WebServiceContextインタフェースのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

<T extends EndpointReference>

T

getEndpointReference (java.lang.Class<T> clazz, org.w3c.dom.Element... referenceParameters)

×

2

EndpointReference

getEndpointReference (org.w3c.dom.Element... referenceParameters)

×

3

MessageContext

getMessageContext()

○

説明

このメソッドが呼び出されたときに処理されているリクエストのメッセージコンテキストを取得します。

例外

java.lang.IllegalStateException：

リクエストが処理されていないときにこのメソッドが呼び出された場合に発生します。

4

java.security.Principal

getUserPrincipal()

×

5

boolean

isUserInRole(java.lang.String role)

×

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

(3)　javax.xml.ws.wsaddressing.W3CEndpointReferenceBuilderクラス

javax.xml.ws.wsaddressing.W3CEndpointReferenceBuilderクラスのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒12　javax.xml.ws.wsaddressing.W3CEndpointReferenceBuilderクラスのサポート範囲

項番

戻り値の型

メソッド名

サポート

1

−

W3CEndpointReferenceBuilder()

○

2

W3CEndpointReferenceBuilder

address(java.lang.String address)

○

3

W3CEndpointReferenceBuilder

attribute(javax.xml.namespace.QName name, java.lang.String value)

○

4

W3CEndpointReference

build()

○※1

5

W3CEndpointReferenceBuilder

element(org.w3c.dom.Element element)

○

6

W3CEndpointReferenceBuilder

endpointName (javax.xml.namespace.QName endpointName)

○

7

W3CEndpointReferenceBuilder

interfaceName(javax.xml.namespace.QName interfaceName)

○

8

W3CEndpointReferenceBuilder

metadata (org.w3c.dom.Element metadataElement)

○

9

W3CEndpointReferenceBuilder

referenceParameter (org.w3c.dom.Element referenceParameter)

○

10

W3CEndpointReferenceBuilder

serviceName (javax.xml.namespace.QName serviceName)

○

11

W3CEndpointReferenceBuilder

wsdlDocumentLocation (java.lang.String wsdlDocumentLocation)

○※2

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

注※1

buildメソッドは，スレッドセーフではありません。W3CEndpointReferenceBuilderのオブジェクトを複数スレッドで共有しないでください。共有した場合の動作は保証されません。

注※2

カタログ機能による引数wsdlDocumentLocationのマッピングは，サポートしていません。

19.2.4　コアAPI

ここでは，コアAPIのサポート範囲について説明します。

(1)　com.sun.xml.ws.developer.StreamingAttachmentFeatureクラス

com.sun.xml.ws.developer.StreamingAttachmentFeatureクラスのサポート範囲を次の表に示します。

表19‒13　com.sun.xml.ws.developer.StreamingAttachmentFeatureクラスのサポート範囲

項番

戻り値の型

メソッド名

サポート

1

−

StreamingAttachmentFeature()

×

2

−

StreamingAttachmentFeature(String dir,boolean parseEagerly,long memoryThreshold)

○

説明

StreamingAttachmentFeatureを作成します。

引数

dir：

一時ファイルの出力先ディレクトリパスです。存在しないディレクトリ，アクセス権のないディレクトリ，または存在するファイル名を指定した場合，メッセージを出力し，受信した添付ファイルを含むSOAPメッセージに含まれるMIMEボディをメモリ上に展開します（KDJW10026-W）。

parseEagerly：

受信した添付ファイルを含むSOAPメッセージを詳細に解析するかどうかを設定します。trueの場合，添付ファイルを含むSOAPメッセージを詳細に解析します。

memoryThreshold：

添付ファイルを含むSOAPメッセージを受信する際に，SOAPメッセージに含まれるMIMEボディをメモリ上に展開するかどうかを判定するためのしきい値(単位：バイト)です。16KB（16384L）より大きい値または-1を指定します。これら以外の値を指定した場合，動作は保証されません。-1を指定した場合，常にMIMEボディをメモリ上に展開します。

3

java.lang.String

getID()

○

説明

StreamingAttachmentFeatureの一意の識別子を取得します。

4

org.jvnet.mimepull.MIMEConfig

getConfig()

○

説明

ストリーミングの設定情報を表すMIMEConfigインスタンスを取得します。一度このメソッドを呼び出した場合，次のsetterメソッドを用いてストリーミングの設定情報を変更することはできません。

setDir(String dir)

setParseEagerly(boolean parseEagerly)

setMemoryThreshold(int memoryThreshold)

5

void

setDir(String dir)

○

説明

ストリーミングが有効の場合に，受信した添付ファイルを含むSOAPメッセージに含まれるMIMEボディを一時ファイルとして出力するときに使用するディレクトリを設定します。このメソッドを複数回呼び出した場合，最後に指定した値が有効になります。getConfig()メソッドを呼び出した場合，このメソッドによる再設定はできません。

引数

dir：

一時ファイルの出力先ディレクトリパスです。存在しないディレクトリ，アクセス権のないディレクトリ，または存在するファイル名を指定した場合，メッセージを出力し，受信した添付ファイルを含むSOAPメッセージに含まれるMIMEボディをメモリ上に展開します（KDJW10026-W）。

6

void

setParseEagerly(boolean parseEagerly)

○

説明

ストリーミングが有効の場合に，受信した添付ファイルを含むSOAPメッセージを詳細に解析するかどうかを設定します。このメソッドを複数回呼び出した場合，最後に指定した値が有効になります。getConfig()メソッドを呼び出した場合，このメソッドによる再設定はできません。

引数

parseEagerly：

受信した添付ファイルを含むSOAPメッセージを詳細に解析するかどうかを設定します。trueの場合，添付ファイルを含むSOAPメッセージを詳細に解析します。

7

void

setMemoryThreshold(int memoryThreshold)

○

説明

ストリーミングが有効の場合に，添付ファイルを含むSOAPメッセージを受信するときにSOAPメッセージに含まれるMIMEボディをメモリ上に展開するかどうかを判定するためのしきい値を設定します。このメソッドを複数回呼び出した場合，最後に指定した値が有効になります。getConfig()メソッドを呼び出した場合，このメソッドによる再設定はできません。

引数

memoryThreshold：

添付ファイルを含むSOAPメッセージを受信する際に，SOAPメッセージに含まれるMIMEボディをメモリ上に展開するかどうかを判定するためのしきい値(単位：バイト)です。16KB（16384L）より大きい値または-1を指定します。これら以外の値を指定した場合，動作は保証されません。-1を指定した場合，常にMIMEボディをメモリ上に展開します。

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

(2)　com.sun.xml.ws.developer.StreamingDataHandlerクラス

com.sun.xml.ws.developer.StreamingDataHandlerクラスのサポート範囲を次の表に示します。

表19‒14　com.sun.xml.ws.developer.StreamingDataHandlerクラスのサポート範囲

項番

戻り値の型

メソッド名

サポート

1

−

StreamingDataHandler(Object o, String s)

×

2

−

StreamingDataHandler(URL url)

×

3

−

StreamingDataHandler(DataSource dataSource)

×

4

java.io.InputStream

readOnce()

○

説明

このオブジェクトのjava.io.InputStreamを取得します。

例外

IOException：

このオブジェクトに対応するInputStreamが取得できなかった場合に発生します。

5

void

moveTo(File file)

○

説明

このオブジェクトが示す添付ファイルを指定されたファイルに移動します。

引数fileにnullを指定した場合，java.io.IOExceptionが発生します（KDJW10023-E）。

引数fileに存在するファイルまたはディレクトリのパス，存在しない親ディレクトリを含むファイルパスを指定した場合，IOExceptionが発生します（KDJW10027-E）。

引数

file：

出力先ファイルパスです。

例外

IOException：

次の場合に発生します。

nullをfileに指定。

存在するファイルまたはディレクトリのパス，または存在しない親ディレクトリを含むファイルパスをfileに指定。

入出力エラーが発生。

6

void

close()

○

説明

このオブジェクトが示す添付ファイルのリソースを解放します。

例外

IOException：

入出力エラーが発生した場合に発生します。

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

(3)　org.jvnet.mimepull.MIMEConfigクラス

org.jvnet.mimepull.MIMEConfigクラスのサポート範囲を次の表に示します。

表19‒15　org.jvnet.mimepull.MIMEConfigクラスのサポート範囲

項番

戻り値の型

メソッド名

サポート

1

−

MIMEConfig()

×

2

void

setParseEagerly(boolean parseEagerly)

○

説明

ストリーミングが有効の場合に，受信した添付ファイルを含むSOAPメッセージを詳細に解析するかどうかを設定します。このメソッドを複数回呼び出した場合，最後に指定した値が有効になります。

引数

parseEagerly：

受信した添付ファイルを含むSOAPメッセージを詳細に解析するかどうかを設定します。trueの場合，添付ファイルを含むSOAPメッセージを詳細に解析します。

3

void

setMemoryThreshold(long memoryThreshold)

○

説明

ストリーミングが有効の場合に，添付ファイルを含むSOAPメッセージを受信するときに，SOAPメッセージに含まれるMIMEボディをメモリ上に展開するかどうかを判定するためのしきい値を設定します。このメソッドを複数回呼び出した場合，最後に指定した値が有効になります。

引数

memoryThreshold：

添付ファイルを含むSOAPメッセージを受信する際に，SOAPメッセージに含まれるMIMEボディをメモリ上に展開するかどうかを判定するためのしきい値(単位：バイト)です。16KB（16384L）より大きい値または-1を指定します。これら以外の値を指定した場合，動作は保証されません。-1を指定した場合，常にMIMEボディをメモリ上に展開します。

4

void

setDir(String dir)

○

説明

ストリーミングが有効の場合に，受信した添付ファイルを含むSOAPメッセージに含まれるMIMEボディを一時ファイルとして出力するときに使用するディレクトリを設定します。このメソッドを複数回呼び出した場合，nullまたは空文字（""）以外の値で最初に指定したものが有効になります。

引数

dir：

一時ファイルの出力先ディレクトリパスです。

5

void

validate()

○

説明

一時ファイルを作成できるかを検証します。作成できない場合，添付ファイルをメモリ上に展開するように設定します。

存在しないディレクトリ，アクセス権のないディレクトリ，存在するファイル名をsetDir(String dir)メソッドで設定し，このメソッドで検証しない場合，ストリーミングが一時ファイルを出力するときにorg.jvnet.mimepull.MIMEParsingExceptionが発生します。

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

(4)　javax.xml.ws.Bindingインタフェース

javax.xml.ws.Bindingインタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒16　javax.xml.ws.Bindingインタフェースのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

java.lang.String

getBindingID()

×

2

java.util.List<Handler>

getHandlerChain()

○

説明

プロトコルバインディングインスタンスのハンドラチェインのコピーを取得します。

3

void

setHandlerChain (java.util.List<Handler> chain)

○

説明

プロトコルバインディングインスタンスのハンドラチェインを設定します。

引数

chain：

ハンドラチェインを構成するハンドラのリストです。

例外

javax.xml.ws.WebServiceException：

ハンドラチェインの設定でエラーが起きた場合，またはchainにnullを指定した場合に発生します。

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

(5)　javax.xml.ws.handler.Handler<C extends MessageContext>インタフェース

javax.xml.ws.handler.Handler<C extends MessageContext>インタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒17　javax.xml.ws.handler.Handler<C extends MessageContext>インタフェースのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

MessageContext.Scope

close(MessageContext context)

○

説明

メッセージ交換を完了するとき，JAX-WSのランタイムがメッセージ，フォルト，または例外をディスパッチする直前に呼び出されます。

2

boolean

handleFault(C context)

○

説明

フォルトメッセージを処理するために呼び出されます。

3

boolean

handleMessage(C context)

○

説明

インバウンドおよびアウトバウンドのメッセージで通常の処理をするために呼び出されます。

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

(6)　javax.xml.ws.handler.HandlerResolverインタフェース

javax.xml.ws.handler.HandlerResolverインタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒18　javax.xml.ws.handler.HandlerResolverインタフェースのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

java.util.List<Handler>

getHandlerChain(PortInfo portInfo)

○

説明

指定されたポートのハンドラチェインを取得します。このメソッドではnullを返さないでください。

引数

portInfo：

アクセス対象のポートの情報です。

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

(7)　javax.xml.ws.handler.LogicalMessageContextインタフェース

javax.xml.ws.handler.LogicalMessageContextインタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒19　javax.xml.ws.handler.LogicalMessageContextインタフェースのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

LogicalMessage

getMessage()

○

説明

このメッセージコンテキストからメッセージを取得します。

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

(8)　javax.xml.ws.handler.MessageContextインタフェース

javax.xml.ws.handler.MessageContextインタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒20　javax.xml.ws.handler.MessageContextインタフェースのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

MessageContext.Scope

getScope(java.lang.String name)

○※1

説明

プロパティのスコープを取得します。

例外

java.lang.IllegalArgumentException：

nameにnull，空の文字列，およびこのメッセージコンテキストに関連づけられていないプロパティ名を指定した場合に発生します。

標準のメッセージコンテキストのプロパティと，ユーザ定義メッセージコンテキストプロパティは，メッセージコンテキストに関連づけられているものと見なされます。

メッセージコンテキストのプロパティについては，「19.2.5(1)　メッセージコンテキストのプロパティのサポート範囲」を参照してください。

2

void

setScope(java.lang.String name, MessageContext.Scope scope)

○※2

説明

プロパティのスコープを設定します。

例外

java.lang.IllegalArgumentException

nameにnull，空の文字列，およびこのメッセージコンテキストに関連づけられていないプロパティ名を指定した場合に発生します。標準のメッセージコンテキストのプロパティと，ユーザ定義メッセージコンテキストプロパティは，メッセージコンテキストに関連づけられているものと見なされます。

メッセージコンテキストのプロパティについては，「19.2.5(1)　メッセージコンテキストのプロパティのサポート範囲」を参照してください。

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

注※1

ハンドラで使用する場合だけサポートしています。

注※2

インバウンド時のサービス側ハンドラで，ユーザ定義メッセージコンテキストプロパティを追加する場合だけサポートします。ユーザ定義メッセージコンテキストプロパティ追加時の注意事項についての詳細は，「10.21.2(2)　ユーザ定義メッセージコンテキストプロパティ追加時の注意事項」を参照してください。

(9)　javax.xml.ws.handler.PortInfoインタフェース

javax.xml.ws.handler.PortInfoインタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒21　javax.xml.ws.handler.PortInfoインタフェースのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

java.lang.String

getBindingID()

○

説明

アクセス対象のポートが使用する，バインディングを識別するURIを取得します。

2

javax.xml.namespace.QName

getPortName()

○

説明

アクセス対象のWSDLのポートからQNameを取得します。

3

javax.xml.namespace.QName

getServiceName()

○

説明

アクセス対象のポートを含む，WSDLのサービスのQNameを取得します。

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

(10)　javax.xml.ws.handler.soap.SOAPHandler<T extends SOAPMessageContext>インタフェース

javax.xml.ws.handler.soap.SOAPHandler<T extends SOAPMessageContext>インタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒22　javax.xml.ws.handler.soap.SOAPHandler<T extends SOAPMessageContext>インタフェースのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

java.util.Set<javax.xml.namespace.QName>

getHeaders()

○

説明

このハンドラインスタンスで処理できるヘッダを取得します。

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

(11)　javax.xml.ws.handler.soap.SOAPMessageContextインタフェース

javax.xml.ws.handler.soap.SOAPMessageContextインタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒23　javax.xml.ws.handler.soap.SOAPMessageContextインタフェースのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

java.lang.Object[]

getHeaders(javax.xml.namespace.QName header, javax.xml.bind.JAXBContext context, boolean allRoles)

○

説明

このメッセージコンテキストが持つメッセージから特定のQNameを持つヘッダを取得します。このメッセージコンテキストがメッセージを持っていない場合，またはheaderで指定したQNameに一致するヘッダが存在しない場合は，空の配列を返します。

例外

javax.xml.ws.WebServiceException：

次の場合に発生します。

headerにnullを指定した場合

contextにnullを指定した場合

2

javax.xml.soap.SOAPMessage

getMessage()

○

説明

このメッセージコンテキストからSOAPメッセージを取得します。

3

java.util.Set<java.lang.String>

getRoles()

○

説明

ハンドラチェインの実行に関連づけられたSOAPアクタおよびロールを取得します。

4

void

setMessage(javax.xml.soap.SOAPMessage message)

×

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

(12)　javax.xml.ws.Holder<T>クラス

javax.xml.ws.Holder<T>クラスのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒24　javax.xml.ws.Holder<T>クラスのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

−

Holder()

○

説明

null値を含む新しいホルダを作成します。

2

−

Holder(T value)

○

説明

指定した値を含む新しいホルダを作成します。

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

(13)　javax.xml.ws.LogicalMessageインタフェース

javax.xml.ws.LogicalMessageインタフェースのサポート範囲を次の表に示します。

表19‒25　javax.xml.ws.LogicalMessageインタフェースのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

javax.xml.transform.Source

getPayload()

○

説明

XMLソースとしてメッセージのペイロードを取得します。

2

java.lang.Object

getPayload(javax.xml.bind.JAXBContext context)

○

説明

JAXBオブジェクトとしてメッセージのペイロードを取得します

3

void

setPayload(java.lang.Object payload, javax.xml.bind.JAXBContext context)

×

4

void

setPayload(javax.xml.transform.Source payload)

×

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

(14)　javax.xml.ws.ProtocolExceptionクラス

javax.xml.ws.ProtocolExceptionクラスのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒26　javax.xml.ws.ProtocolExceptionクラスのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

−

ProtocolException()

○

説明

詳細メッセージがnullである新規例外を構築します。

2

−

ProtocolException(java.lang.String message)

○

説明

指定された詳細メッセージを持つ新規例外を構築します。

3

−

ProtocolException(java.lang.String message, java.lang.Throwable cause)

○

説明

指定された詳細メッセージおよび原因を使用して新規例外を構築します。

4

−

ProtocolException(java.lang.Throwable cause)

○

説明

指定された原因と詳細メッセージを持つ新規例外を構築します。

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

(15)　javax.xml.ws.soap.AddressingFeatureクラス

javax.xml.ws.soap.AddressingFeatureクラスのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒27　javax.xml.ws.soap.AddressingFeatureクラスのサポート範囲

項番

戻り値の型

メソッド名

サポート

1

−

AddressingFeature()

○

説明

AddressingFeatureを作成します。

2

−

AddressingFeature(boolean enabled)

○

説明

AddressingFeatureを作成します。

引数

enabled：

WS-Addressingを有効にするか無効にするかを指定します。

3

−

AddressingFeature(boolean enabled, boolean required)

○

説明

AddressingFeatureを作成します。

引数

enabled：

WS-Addressingを有効にするか無効にするかを指定します。

required：

WS-Addressingの使用を要求する場合に指定します。

4

−

AddressingFeature(boolean enabled, boolean required,

AddressingFeature.Responses responses)

○

説明

AddressingFeatureを作成します。

引数

enabled：

WS-Addressingを有効にするか無効にするかを指定します。

required：

WS-Addressingの使用を要求する場合に指定します。

responses：

要求する応答エンドポイントの種別を指定します。応答エンドポイントの種別は，次のどれかを指定できます。※

すべてのURI

javax.xml.ws.soap.AddressingFeature.Responses.ALL

匿名URIだけ

javax.xml.ws.soap.AddressingFeature.Responses.ANONYMOUS

非匿名URIだけ

javax.xml.ws.soap.AddressingFeature.Responses.NON_ANONYMOUS

5

java.lang.String

getID()

○

説明

AdderssingFeatureの一意の識別子を取得します。

6

AddressingFeature.Responses

getResponses()

○

説明

要求する応答エンドポイントの種別を取得します。

7

Boolean

isRequired()

○

説明

AdderssingFeatureの使用を要求するかどうかの情報を取得します。

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

注※

responsesの指定は，クライアント側JAX-WSエンジンの動作には影響しません。

(16)　javax.xml.ws.soap.MTOMFeatureクラス

javax.xml.ws.soap.MTOMFeatureクラスのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒28　javax.xml.ws.soap.MTOMFeatureクラスのサポート範囲

項番

戻り値の型

メソッド名

サポート

1

−

MTOMFeature()

○

説明

MTOMFeatureを作成します。

2

−

MTOMFeature(boolean enabled)

○

説明

MTOMFeatureを作成します。

引数

enabled：

MTOM/XOP仕様形式の添付ファイルを使用するかどうかを指定します。

3

−

MTOMFeature(boolean enabled, int threshold)

○

説明

MTOMFeatureを作成します。

引数

enabled：

MTOM/XOP仕様形式の添付ファイルを使用するかどうかを指定します。

threshold：

MTOM/XOP仕様形式の添付ファイルとして送信するバイナリデータのサイズ（単位：バイト）です。thresholdの指定値≦バイナリデータのサイズのとき，バイナリデータをMTOM/XOP仕様形式の添付ファイルとして送信します。

4

−

MTOMFeature(int threshold)

○

説明

MTOMFeatureを作成します。

引数

threshold：

MTOM/XOP仕様形式の添付ファイルとして送信するバイナリデータのサイズ（単位：バイト）です。thresholdの指定値≦バイナリデータのサイズのとき，バイナリデータをMTOM/XOP仕様形式の添付ファイルとして送信します。

5

java.lang.String

getID()

○

説明

MTOMFeatureの一意の識別子を取得します。

6

int

getThreshold()

○

説明

バイナリデータをMTOM/XOP仕様形式の添付ファイルとして送信するかどうかを判定するためのしきい値を取得します。

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

(17)　javax.xml.ws.soap.SOAPBindingインタフェース

javax.xml.ws.soap.SOAPBindingインタフェースのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒29　javax.xml.ws.soap.SOAPBindingインタフェースのサポート範囲

項番

戻り値の型

メソッド名

サポート

1

javax.xml.soap.MessageFactory

getMessageFactory()

×

2

java.util.Set<java.lang.String>

getRoles()

×

3

javax.xml.soap.SOAPFactory

getSOAPFactory()

×

4

boolean

isMTOMEnabled()

○

説明

MTOM/XOP仕様形式の添付ファイルが有効化されている場合，trueを返します。

5

void

setMTOMEnabled(boolean flag)

○

説明

MTOM/XOP仕様形式の添付ファイルを有効または無効にします。

MTOMFeatureやこのメソッドを使用してMTOM/XOP仕様形式の添付ファイルの有効または無効が設定されていない場合に，このメソッドで設定できます。すでにMTOM/XOP仕様形式の添付ファイルの有効または無効が設定されている場合，このメソッドによる再設定はできません。

引数

flag：

MTOM/XOP仕様形式の添付ファイルを有効にするか無効にするかを指定します。

6

void

setRoles(java.util.Set<java.lang.String> roles)

×

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

(18)　javax.xml.ws.soap.SOAPFaultExceptionクラス

javax.xml.ws.soap.SOAPFaultExceptionクラスのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒30　javax.xml.ws.soap.SOAPFaultExceptionクラスのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

−

SOAPFaultException (javax.xml.soap.SOAPFault fault)

○

説明

SOAPFaultExceptionの新規例外を構築します。

2

javax.xml.soap.SOAPFault

getFault()

○

説明

埋め込まれたSOAPFaultインスタンスを取得します。

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

(19)　javax.xml.ws.WebServiceExceptionクラス

javax.xml.ws.WebServiceExceptionクラスのサポート範囲を次の表に示します。詳細はJAX-WS 2.2仕様を参照してください。

表19‒31　javax.xml.ws.WebServiceExceptionクラスのサポート範囲

項番

戻り値の型

メソッド名／説明

サポート

1

−

WebServiceException()

○

説明

詳細メッセージがnullである新規例外を構築します。

2

−

WebServiceException (java.lang.String message)

○

説明

指定された詳細メッセージを持つ新規例外を構築します。

3

−

WebServiceException(java.lang.String message, java.lang.Throwable cause)

○

説明

指定された詳細メッセージおよび原因を持つ新規例外を構築します。

4

−

WebServiceException (java.lang.Throwable cause)

○

説明

指定された原因および詳細メッセージを持つ新規例外を構築します。

（凡例）

−：戻り値の型がないことを示します。

○：Application ServerのJAX-WS機能でサポートしています。

19.2.5　メッセージコンテキストの使用

JAX-WS APIのサポート範囲内で，ハンドラ，Webサービスクライアント，およびWebサービスからメッセージコンテキストにアクセスできます。詳細を次に示します。

ハンドラの場合

コールバックされるメソッド（handleMessageメソッドなど）のパラメタでメッセージコンテキストが渡されます。

Webサービスクライアントの場合

javax.xml.ws.BindingProviderインタフェースのgetRequestContextメソッド，およびgetResponseContextメソッドでメッセージコンテキストのコピーにアクセスできます。

Webサービスの場合

javax.xml.ws.WebServiceContextインタフェースのgetMessageContextメソッドでメッセージコンテキストにアクセスできます。

JAX-WS APIについては，JAX-WS 2.2仕様を参照してください。また，Application ServerのJAX-WS機能でのJAX-WS APIのサポート範囲については，「19.2.1　インタフェースおよびクラスの一覧（JAX-WS）」を参照してください。Application ServerのJAX-WS機能では，JAX-WS 2.2仕様で定義された標準のプロパティ，およびベンダ固有のプロパティをサポートしています。

JAX-WS 2.2仕様の9章に記載されている標準のプロパティについては，参照だけサポートしています。変更した場合の動作はサポートしていません。

(1)　メッセージコンテキストのプロパティのサポート範囲

メッセージコンテキストのプロパティのサポート範囲を次の表に示します。

表19‒32　メッセージコンテキストのプロパティの一覧

項番

プロパティ名

記載個所※1

必須※2

サポート

Webサービスクライアント

Webサービス※5

ハンドラ

Webサービスクライアント側

Webサービス側

out※3

in※4

out※6

in※7

in※8

out※9

javax.xml.ws.handler.message

1

.outbound※10

9.4.1.1

○

×※10

×※10

×

△

△

△

△

javax.xml.ws.binding.attachments

2

.inbound※10

9.4.1.1

○

×※10

×※10

△

△

△

△

△

3

.outbound※10

9.4.1.1

○

×※10

×※10

×

△

△

△

△

javax.xml.ws.reference

4

.parameters※10

9.4.1.1

○

×※10

×※10

△

△

△

△

△

javax.xml.ws.wsdl

5

.description※10，※12

9.4.1.1

−

×※10

×※10

×※11

×※11

×※11

×※11

×※11

6

.service※10，※12

9.4.1.1

−

×※10

×※10

△

△

△

△

△

7

.port※10，※12

9.4.1.1

−

×※10

×※10

△

△

△

△

△

8

.interface※10，※12

9.4.1.1

−

×※10

×※10

△

△

△

△

△

9

.operation※10，※12，※13

9.4.1.1

−

×※10

△※13

△

△

△

△

△

javax.xml.ws.http.request

10

.headers

9.4.1.1

○

◎※14

×※10

△

◎※14

△※15

△

△

11

.method※10，※11

9.4.1.1

○

×※10

×※10

△

△※15

△※15

△

△

12

.querystring※10，※11

9.4.1.1

○

×※10

×※10

△

△※15

△※15

△

△

13

.headers

9.4.1.1

○

×※10

×※10

△※16

△※15

△※15

△※16

△※16

javax.xml.ws.http.response

14

.headers※10

9.4.1.1

○

×※10

×※10

×

△※17

△

△※17

△※17

15

.code※10

9.4.1.1

○

×※10

×※10

×

△※18

△

△

△

javax.xml.ws.servlet

16

.context※10，※11

9.4.1.1

○

×※10

×※10

△

△※15

△※15

△

△

17

.request※10

9.4.1.1

○

×※10

×※10

△

△※15

△※15

△

△

18

.response※10

9.4.1.1

○

×※10

×※10

△

△※15

△※15

△

△

javax.xml.ws.service.endpoint

19

.address※19

4.2.1.1

○

◎

△

×

◎

△

△

△

javax.xml.ws.security.auth

20

.username

4.2.1.1

○

◎

△

×

◎

△

△

△

21

.password

4.2.1.1

○

◎

△

×

◎

△

△

△

javax.xml.ws.session

22

.maintain

4.2.1.1

○

◎

△

×

◎

△

△

△

javax.xml.ws.soap.http.soapaction

23

.use

4.2.1.1

−

×※20

×※20

×※20

×※20

×※20

×※20

×※20

24

.uri

4.2.1.1

−

×※20

×※20

×※20

×※20

×※20

×※20

×※20

com.cosminexus.jaxws

25

.connect.timeout

◎

△

×

◎

△

△

△

26

.request.timeout

◎

△

×

◎

△

△

△

com.cosminexus.xml.ws.client.http

27

.HostnameVerificationProperty

◎※21

×

×

×

×

×

×

（凡例）

○：必須であることを示します。

−：必須でないことを示します。

◎：参照および変更できます。

△：参照だけできます。変更した場合の動作は保証されません。

×：参照および変更できません。

空欄：Application ServerのJAX-WS機能が提供するプロパティであるため，該当しないことを示します。

注※1

JAX-WS 2.2仕様で定義されている個所を示します。

注※2

JAX-WS 2.2仕様で必須かどうかを示します。

注※3

javax.xml.ws.BindingProvider#getRequestContextで取得できる要求コンテキストで，参照または変更できるかどうかを示します。

注※4

javax.xml.ws.BindingProvider#getResponseContextで取得できる要求コンテキストで，参照または変更できるかどうかを示します。

注※5

Webサービスコンテキストのインジェクションについては，「10.21.2　Webサービスコンテキストのインジェクション」を，Webサービスにおけるメッセージコンテキストプロパティについては，「19.2.5(2)(l)　Webサービスでのメッセージコンテキストプロパティ」を参照してください。

注※6

Webサービスクライアントに関連づけられたハンドラで，アウトバウンド時（要求メッセージを送信するとき）に，参照または変更できるかどうかを示します。

注※7

Webサービスクライアントに関連づけられたハンドラで，インバウンド時（応答メッセージを受信するとき）に，参照または変更できるかどうかを示します。

注※8

Webサービス実装クラスまたはプロバイダ実装クラスに関連づけられたハンドラで，インバウンド時（要求メッセージを受信する時）に，参照または変更できるかどうかを示します。メッセージコンテキストプロパティ追加時の注意事項については，「10.21.2(2)　ユーザ定義メッセージコンテキストプロパティ追加時の注意事項」を参照してください。

注※9

Webサービス実装クラスまたはプロバイダ実装クラスに関連づけられたハンドラで，アウトバウンド時（応答メッセージを送信するとき）に，参照または変更できるかどうかを示します。メッセージコンテキストプロパティ追加時の注意事項については，「10.21.2(2)　ユーザ定義メッセージコンテキストプロパティ追加時の注意事項」を参照してください。

注※10

「19.2.5(2)(e)　WebサービスクライアントでのHANDLERスコープのメッセージコンテキストプロパティ」を参照してください。

注※11

常にnullが返されます。

注※12

「19.2.5(2)(h)　WSDLに関連するメッセージコンテキストプロパティ」を参照してください。

注※13

「19.2.5(2)(i)　WSDLオペレーションの名前に関連するメッセージコンテキストプロパティ」を参照してください。

注※14

HTTPレスポンス圧縮機能との連携時に使用するHTTPヘッダ「Accept-Encoding」，およびHTTPリクエストボディのgzip圧縮時に使用するHTTPヘッダ「Content-Encoding」の追加と参照だけできます。「Accept-Encoding」については，「10.18　HTTPレスポンス圧縮機能との連携」を参照してください。「Content-Encoding」については「10.17　HTTPリクエストボディのgzip圧縮」を参照してください。

注※15

「19.2.5(2)(a)　Webサービスクライアント側のハンドラで操作しても意味のないメッセージコンテキストプロパティ」を参照してください。

注※16

「19.2.5(2)(b)　パス情報」を参照してください。

注※17

「19.2.5(2)(c)　HTTPヘッダ」を参照してください。

注※18

「19.2.5(2)(d)　HTTPステータスコード」を参照してください。

注※19

「19.2.5(2)(g)　サービスエンドポイントのアドレスに指定するメッセージコンテキストのプロパティ」を参照してください。

注※20

「19.2.5(2)(f)　SOAPActionヘッダに関連するメッセージコンテキストプロパティ」を参照してください。

注※21

「19.2.5(2)(k)　com.cosminexus.xml.ws.client.http.HostnameVerificationPropertyプロパティの設定方法」を参照してください。

(2)　メッセージコンテキスト使用時の注意事項

メッセージコンテキスト使用時の注意事項について説明します。

(a)　Webサービスクライアント側のハンドラで操作しても意味のないメッセージコンテキストプロパティ

要求メッセージのHTTPメソッドのマップを保持するプロパティ（javax.xml.ws.http.request.methodプロパティなど）は，Webサービス側のハンドラで取得して意味のあるプロパティです。したがって，Webサービスクライアント側のハンドラでこのプロパティを参照した場合は常にnullが返されます。

(b)　パス情報

javax.xml.ws.http.request.pathinfoプロパティは常にnullが保持されます。

(c)　HTTPヘッダ

応答メッセージのHTTPヘッダのマップを保持するjavax.xml.ws.http.response.headersプロパティは，インバウンド時にWebサービスクライアント側のハンドラで取得して意味のあるプロパティです。したがって，Webサービス側のハンドラ，またはWebサービスクライアント側のアウトバウンド処理のハンドラで参照した場合は，常にnullが返されます。

メッセージコンテキストのjavax.xml.ws.http.request.headersプロパティ，およびjavax.xml.ws.http.response.headersプロパティをハンドラで参照した場合，取得されるマップ（Map<String,List<String>>オブジェクト）のキー値であるHTTPヘッダ名は，実際に送受信されるHTTPメッセージ（SOAPメッセージを含むHTTPメッセージ）に関係なく，常に先頭文字だけが大文字になります。

例）Content-type

(d)　HTTPステータスコード

Webサービスクライアント側のアウトバウンドのハンドラは，HTTP通信が行われる前に処理されます。したがって，ハンドラからHTTPステータスコードを保持するjavax.xml.ws.http.response.codeプロパティを参照した場合は，常にnullが返されます。

(e)　WebサービスクライアントでのHANDLERスコープのメッセージコンテキストプロパティ

標準のメッセージコンテキストプロパティとしてAPPLICATIONスコープおよびHANDLERスコープがありますが，Webサービスクライアントからは，APPLICATIONスコープのメッセージコンテキストプロパティだけ参照できます。したがって，Application ServerのJAX-WS機能では，「19.2.5(1)　メッセージコンテキストのプロパティのサポート範囲」の表で注※9が付けられたプロパティは，Webサービスクライアントでは使用できません。これらのプロパティを参照した場合の動作は保証されません。

(f)　SOAPActionヘッダに関連するメッセージコンテキストプロパティ

Application ServerのJAX-WS機能ではSOAPActionヘッダをサポートしていないため，javax.xml.ws.soap.http.soapaction.useプロパティとjavax.xml.ws.soap.http.soapaction.uriプロパティは使用できません。これらのプロパティを参照した場合の動作は保証されません。

(g)　サービスエンドポイントのアドレスに指定するメッセージコンテキストのプロパティ

サービスエンドポイントのアドレスを指定するjavax.xml.ws.service.endpoint.addressプロパティには，空白および空文字は設定できません。空白または空文字を設定した場合の動作は保証されません。javax.xml.ws.service.endpoint.addressプロパティのその他の指定値については，「20.2.3　soap:address要素またはsoap12:address要素のlocation属性に指定できる値」を参照してください。

(h)　WSDLに関連するメッセージコンテキストプロパティ

ディスパッチベースのWebサービスクライアントおよびプロバイダベースのWebサービスではWSDLファイルがないので，WSDLに関連するメッセージコンテキストプロパティを参照した場合は常にnullが返ります。

(i)　WSDLオペレーションの名前に関連するメッセージコンテキストプロパティ

スタブベースのWebサービスクライアントでのjavax.xml.ws.wsdl.operationプロパティの参照は，javax.xml.ws.BindingProvider#getResponseContextで取得できる要求コンテキストだけでできます。javax.xml.ws.BindingProvider#getRequestContextで取得できる要求コンテキストで参照した場合は常にnullが返ります。また，javax.xml.ws.wsdl.operationプロパティに値を設定しても，送信するSOAPメッセージには影響を与えません。

(j)　WS-RM 1.2機能を使用する場合のサービスエンドポイントのアドレスの指定

WS-RM 1.2機能を使用するWebサービスクライアントでは，最初のWebサービスの呼び出し前にサービスエンドポイントのアドレスを指定してください。最初の通信以降にサービスエンドポイントを変更すると，WS-RMの通信に失敗します。

(k)　com.cosminexus.xml.ws.client.http.HostnameVerificationPropertyプロパティの設定方法

com.cosminexus.xml.ws.client.http.HostnameVerificationPropertyプロパティにメッセージコンテキストでtrueまたはfalseを設定する場合は，次の例のようにjava.lang.String型の文字列で設定してください。java.lang.String型の文字列以外で設定した場合の動作は保証されません。

context.put("com.cosminexus.xml.ws.client.http.HostnameVerificationProperty", "true");

(l)　Webサービスでのメッセージコンテキストプロパティ

Webサービスでのメッセージコンテキストプロパティの，参照および変更について次に説明します。

HANDLERスコープであるJAX-WS 2.2仕様の9.4.1.1項で定義されている標準のメッセージコンテキストプロパティのうち，一部のメッセージコンテキストプロパティを参照できます。参照できるメッセージコンテキストプロパティについては，「19.2.5(1)　メッセージコンテキストのプロパティのサポート範囲」の「表19-32　メッセージコンテキストのプロパティの一覧」を参照してください。

APPLICATIONスコープであるJAX-WS 2.2仕様の4.2.1.1項で定義されている標準のメッセージコンテキストプロパティやCJW固有のメッセージコンテキストプロパティについては，参照および変更できません。

APPLICATIONスコープのユーザ定義メッセージコンテキストプロパティの参照および変更ができます。

19.3　アノテーションのサポート範囲

javax.xml.ws.WebServiceRefアノテーションは，サービスクラスおよびポートをインジェクトする場合に指定します。これら以外に指定したときの動作は保証されません。なお，フィールドと対応するsetterメソッドには，同時に指定できません。

javax.xml.ws.WebServiceRefアノテーションは，J2EEサーバ上で実行されるWebサービスクライアントの，フィールドおよびsetterメソッドに指定できます。これら以外に指定した場合は無視されます。

19.3.1　javax.xml.ws.WebServiceRefアノテーション

javax.xml.ws.WebServiceRefアノテーション要素とサポート範囲を次の表に示します。

表19‒33　JAX-WSのアノテーションの要素の一覧

項番

アノテーション

サポート

アノテーション名

要素名

1

javax.xml.ws.WebServiceRef

lookup

×

2

mappedName

×

3

name

×

4

type

×

5

value

○

6

wsdlLocation

○

（凡例）

○：アノテーションおよび要素が指定できることを示します。

×：アノテーションおよび要素が指定できないことを示します（非サポート）。

要素ごとのサポート範囲について説明します。

(1)　value要素（javax.xml.ws.WebServiceRef）

value要素は，javax.xml.ws.Serviceを継承するサービスクラスを指定します。

サービスクラス型のフィールドまたはメソッドに対してjavax.xml.ws.WebServiceRefアノテーションを指定した場合は，value要素を指定できません。指定した場合の動作は保証されません。

ポート型のフィールドまたはメソッドに対してjavax.xml.ws.WebServiceRefアノテーションを指定した場合は，必ず指定します。指定しない場合の動作は保証されません。

(2)　wsdlLocation要素（javax.xml.ws.WebServiceRef）

wsdlLocation要素は，WebサービスのWSDL文書の位置を指定します。

指定できる方法を次に示します。

URL

WSDL文書のURLを指定します。指定形式はjava.net.URLクラスの仕様に従います。プロトコルはhttpとhttpsだけ指定できます。そのほかのプロトコルは指定できません。

相対パス

WARファイルまたはEJB JARファイル内のWSDL文書を，次のように相対パスで指定します。なお，RFC 2396仕様の規則に従った文字列を指定できます。

javax.xml.ws.WebServiceRefアノテーションを指定したWebサービスクライアントをWARファイルに格納する場合は，WEB-INFで始まる相対パスを指定します。WSDL文書はそのWARファイル内の指定したパスに格納します。

javax.xml.ws.WebServiceRefアノテーションを指定したWebサービスクライアントをEJB JARファイルに格納する場合は，META-INFで始まる相対パスを指定します。WSDL文書はそのEJB JARファイル内の指定したパスに格納します。

絶対パス

WSDL文書の絶対パスを指定します。システムに依存する絶対パスで指定してください。指定形式はjava.io.Fileクラスの仕様に従います。

wsdlLocation要素を指定するときの注意事項について説明します。

Webサービスクライアントのインスタンス生成時に，wsdlLocation要素に指定された値を使用してサービスクラスを生成し，サービスクラスやポートのインジェクトを行います。このため，wsdlLocation要素にはインスタンス生成時に有効なWSDL文書の位置を指定する必要があります。存在しないWSDLや不正な内容のWSDLロケーションを指定した場合は，サービスクラスやポートのインジェクションを行わないため，フィールドの値やsetterメソッドの戻り値はnullのままとなります。

wsdlLocation要素を指定しない場合は，サービスクラスのデフォルトコンストラクタと同様に，サービスクラスに指定されたjavax.xml.ws.WebServiceClientアノテーションのwsdlLocation要素の値を使用して，サービスクラスまたはポートのインスタンスを生成します。

19.4　ハンドラチェイン設定ファイルのサポート範囲

ハンドラチェイン設定ファイルの構文のサポート範囲を，次に示す要素ごとに説明します。

javaee:handler-chains要素

javaee:handler-chain要素

javaee:handler要素

javaee:handler-name要素

javaee:handler-class要素

javaee:soap-header要素

javaee:soap-role要素

ここで説明する内容を除いたサポート範囲については，Java EE 5仕様の"Java EE Web Services Metadata Handler Chain Schema"（標準のスキーマ）に従います。

19.4.1　javaee:handler-chains要素

javaee:handler-chains要素のサポート範囲を説明します。

ハンドラチェイン設定ファイルのルート要素として，1個だけ記述できます。省略できません。

子要素としてjavaee:handler-chain要素を指定できます。javaee:handler-chain要素以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

XML仕様およびXML Schema仕様の標準の属性（xmlns属性など）を除いて，属性を指定できません。XML仕様およびXML Schema仕様の標準の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

19.4.2　javaee:handler-chain要素

javaee:handler-chain要素のサポート範囲を説明します。

javaee:handler-chains要素の子要素として，1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

子要素としてjavaee:handler要素を指定できます。javaee:handler要素以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

XML仕様やXML Schema仕様の標準の属性（xmlns属性など）を除いて，属性を指定できません。XML仕様およびXML Schema仕様の標準の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

19.4.3　javaee:handler要素

javaee:handler要素のサポート範囲を説明します。

javaee:handler-chain要素の子要素として，1個から64個まで記述できます。省略または65個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

子要素として下記の要素を指定できます。次に示す要素以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

javaee:handler-name要素

javaee:handler-class要素

javaee:soap-header要素

javaee:soap-role要素

javaee:handler-name要素，javaee:handler-class要素，javaee:soap-header要素，およびjavaee:soap-role要素は上記の順序で指定してください。

XML仕様およびXML Schema仕様の標準の属性（xmlns属性など）を除いて，属性を指定できません。XML仕様およびXML Schema仕様の標準の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

19.4.4　javaee:handler-name要素

javaee:handler-name要素のサポート範囲を説明します。

javaee:handler要素の子要素として，0個または1個記述できます。2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）※。

値には，ハンドラの名称を記述します。ただし，JAX-WSエンジンではこの値は無視されるので，XML Schema仕様のxsd:token型の制限に違反しない範囲で値を記述できます※。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

XML仕様やXML Schema仕様の標準の属性（xmlns属性など）を除いて，属性を指定できません。XML仕様およびXML Schema仕様の標準の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

注※

標準のスキーマでは，javaee:handler-name要素は必須です。動作定義ファイルでcom.cosminexus.jaxws.validation.handlerchain.strictプロパティにtrueを設定すると，この要素の指定有無がJAX-WSエンジンでチェックされます。com.cosminexus.jaxws.validation.handlerchain.strictプロパティでtrueを設定した場合に，javaee:handler要素が省略されているときは，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

19.4.5　javaee:handler-class要素

javaee:handler-class要素のサポート範囲を説明します。

javaee:handler要素の子要素として，1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

値には，ハンドラを実装したクラスの完全修飾名を記述してください。存在しないクラス名を記述した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW00011-E）。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

XML仕様およびXML Schema仕様の標準の属性（xmlns属性など）を除いて，属性を指定できません。XML仕様およびXML Schema仕様の標準の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

19.4.6　javaee:soap-header要素

javaee:soap-header要素のサポート範囲を説明します。

javaee:handler要素の子要素として記述できます。省略することもできます。

値には，このハンドラが処理するSOAPヘッダの名称を記述します。ただし，JAX-WSエンジンではこの値は無視されるので，XML Schema仕様のxsd:QName型の制限に違反しない範囲で値を記述できます。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

XML仕様およびXML Schema仕様の標準の属性（xmlns属性など）を除いて，属性を指定できません。XML仕様およびXML Schema仕様の標準の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

19.4.7　javaee:soap-role要素

javaee:soap-role要素のサポート範囲を説明します。

javaee:handler要素の子要素として記述できます。省略することもできます。

値には，このハンドラが振る舞うSOAPアクタまたはロールを記述してください。ただし，"http://www.w3.org/2003/05/soap-envelope/role/none"は記述できません。記述した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW10007-E）。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

XML仕様およびXML Schema仕様の標準の属性（xmlns属性など）を除いて，属性を指定できません。XML仕様およびXML Schema仕様の標準の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力されます（KDJW30019-E）。

20　WSDL仕様のサポート範囲

この章では，Webサービスを開発するときに注意が必要な，WSDL仕様のサポート範囲について説明します。

20.1　WSDL 1.1仕様のサポート範囲

WSDLの要素ごとに，WSDL 1.1仕様のサポート範囲を説明します。

注意事項

この節に記載していない要素や属性を指定している場合など，Application ServerのJAX-WS機能でサポートしているWSDL仕様として文法的に不正な場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

この節では，WSDL構文の制約について説明しています。WSDL構文の問題がない場合でも，Javaへのマッピングで問題があれば，別のエラーとなることがあります。WSDL上で参照されない要素や属性についても不正がある場合は，エラーとなることがあります。

また，WSDL拡張要素および拡張属性については次の注意事項があります。

MIMEバインディングのための拡張要素（mime:content，mime:mimeXmlなど）はサポートしていません。したがって，MIME関連のWSDL要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51188-E）。

次の仕様はサポートしています。

・SOAP 1.1仕様のSOAPバインディングのための拡張要素（soap:header，soap:bodyなど）

・SOAP 1.2仕様のSOAPバインディングのための拡張要素

・WS-Addressing 1.0仕様の拡張要素（wsaw:UsingAddressingなど）および拡張属性（wsaw:Actionなど）

・JAX-WS 2.2仕様のバインディング宣言（jaxws:bindingsなど）

サポートしていない拡張要素または拡張属性を指定した場合は，無視されます。

20.1.1　wsdl:definitions要素

wsdl:definitions要素のサポート範囲を説明します。

WSDLファイルのルート要素として1個だけ記述できます。省略できません。省略または2個以上記述した場合は，XML Processorのエラーになります。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素のうち，次に示す要素以外の拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51053-E）。

wsdl:documentation要素

jaxws:bindings要素（JAX-WS 2.2仕様のバインディング宣言）

wsdl:import要素

wsdl:types要素

wsdl:message要素

wsdl:portType要素

wsdl:binding要素

wsdl:service要素

wsdl:documentation要素とjaxws:bindings要素は，上記の順序で指定する必要があります。ただし，それ以外の要素は，指定する順序を問いません。

wsdl:documentation要素とjaxws:bindings要素の指定順序を誤った場合，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性

targetNamespace属性

(1)　name属性（wsdl:definitions要素）

wsdl:definitions要素に含まれるname属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。

(2)　targetNamespace属性（wsdl:definitions要素）

wsdl:definitions要素に含まれるtargetNamespace属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「15.1.1(2)　名前空間の条件」を参照してください。

20.1.2　wsdl:import要素

wsdl:import要素のサポート範囲を説明します。

wsdl:definitions要素の子要素として，0個から255個まで記述できます。256個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51052-E）。

子要素としてwsdl:documentation要素を指定できます。wsdl:documentation要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51054-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

namespace属性

location属性

(1)　namespace属性（wsdl:import要素）

wsdl:import要素に含まれるnamespace属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「26.3.1(1)　namespace属性（wsdl:import要素）」を参照してください。

(2)　location属性（wsdl:import要素）

wsdl:import要素に含まれるlocation属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

xsd:anyURIを満たす任意の文字列を指定できます。

指定できる値については，「26.3.1(2)　location属性（wsdl:import要素）」を参照してください。

20.1.3　wsdl:types要素

wsdl:types要素のサポート範囲を説明します。

wsdl:definitions要素の子要素として，1個だけ記述できます。省略できません※。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51049-E）。

注※

WSDLのインポート機能を使用する場合は，インポート関係にあるすべてのWSDL内で1個あれば足りるので，この場合は省略できます。また，インポート関係にあるWSDLの合計が上限になります。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51059-E）。

wsdl:documentation要素

xsd:schema要素

wsdl:documentation要素とxsd:schema要素は上記の順序で指定する必要があります。指定順序を誤った場合，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

属性は指定できません。属性を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.4　wsdl:message要素

wsdl:message要素のサポート範囲を説明します。

wsdl:definitions要素の子要素として，1個以上記述できます。省略できません※。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51050-E）。

注※

WSDLのインポート機能を使用する場合は，インポート関係にあるすべてのWSDL内で1個あれば足りるので，この場合は省略できます。また，インポート関係にあるWSDLの合計が上限になります。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51055-E）。

wsdl:documentation要素

wsdl:part要素

wsdl:documentation要素とwsdl:part要素は上記の順序で指定する必要があります。指定順序を誤った場合，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性を指定できます。name属性以外の属性は指定できません。name属性以外の属性を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(1)　name属性（wsdl:message要素）

wsdl:message要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。ただし，同じwsdl:definitions要素以下にあるほかのwsdl:message要素のname属性と同じ値は指定できません。同じ値を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.5　wsdl:part要素

wsdl:part要素のサポート範囲を説明します。

wsdl:message要素の子要素として，0個から255個まで記述できます。256個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

指定できる値については，「20.2　WSDL作成時の注意事項」を参照してください。

子要素としてwsdl:documentation要素を指定できます。wsdl:documentation要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51056-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性

element属性

(1)　name属性（wsdl:part要素）

wsdl:part要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「15.1.5(2)　パート名の条件」を参照してください。

(2)　element属性（wsdl:part要素）

wsdl:part要素に含まれるelement属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

参照できるwsdl:types要素以下に宣言されている要素宣言をQNameで指定してください。

20.1.6　wsdl:portType要素

wsdl:portType要素のサポート範囲を説明します。

要素の子要素として，1個から255個まで記述できます。省略できません※。省略または256個以上記述した場合については，「15.1.2(3)　ポートタイプの記述個数」を参照してください。

注※

WSDLのインポート機能を使用する場合は，インポート関係にあるすべてのWSDL内で1個あれば足りるので，この場合は省略できます。また，インポート関係にあるすべてのWSDL内での合計が上限になります。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素のうち，次に示す要素以外の拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51074-E）。

wsdl:documentation要素

jaxws:bindings要素（JAX-WS 2.2仕様のバインディング宣言）

wsdl:operation要素

wsdl:documentation要素，jaxws:bindings要素，およびwsdl:operation要素は上記の順序で指定する必要があります。指定順序を誤った場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性を指定できます。name属性以外の属性は指定できません。name属性以外の属性を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(1)　name属性（portType要素）

wsdl:portType要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「15.1.2(2)　ポートタイプ名の条件」を参照してください。ただし，同じwsdl:definitions要素以下にある，ほかのwsdl:portType要素のname属性と同じ値は指定できません。同じ値を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.7　wsdl:operation要素（wsdl:portType要素の子要素の場合）

wsdl:operation要素のサポート範囲を説明します。

wsdl:portType要素の子要素として，1個から255個まで記述できます。省略できません。省略または256個以上記述した場合については，「15.1.3(3)　オペレーションとその子要素の記述個数」を参照してください。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素のうち，次に示す要素以外の拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51080-E）。

wsdl:documentation要素

jaxws:bindings要素（JAX-WS 2.2仕様のバインディング宣言）

wsdl:input要素

wsdl:output要素

wsdl:fault要素

wsdl:documentation要素，jaxws:bindings要素，wsdl:input要素，wsdl:output要素およびwsdl:fault要素は上記の順序で指定する必要があります。指定順序を誤った場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性を指定できます。name属性以外の属性は指定できません。name属性以外の属性を指定した場合の動作は保証されません。

(1)　name属性（wsdl:operation要素）

wsdl:operation要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「15.1.3(2)　オペレーション名の条件」を参照してください。ただし，同じwsdl:operation要素以下にある，ほかのwsdl:portType要素のname属性と同じ値は指定できません。同じ値を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51083-E）。

20.1.8　wsdl:input要素（wsdl:portType要素の孫要素の場合）

wsdl:input要素のサポート範囲を説明します。

wsdl:operation要素の子要素として，1個だけ記述できます。省略できません。省略または2個以上記述した場合については，「15.1.3(3)　オペレーションとその子要素の記述個数」を参照してください。

子要素としてwsdl:documentation要素を指定できます。wsdl:documentation要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51057-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性

message属性

wsaw:Action属性

wsaw:Action属性については，「37.5.6　wsa:Action要素指定時の動作」を参照してください。

(1)　name属性（wsdl:input要素）

wsdl:input要素に含まれるname属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。

(2)　message属性（wsdl:input要素）

wsdl:input要素に含まれるmessage属性のサポート範囲を説明します。

wsdl:input要素の子要素として，1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

参照できるwsdl:definitions要素以下に宣言されているwsdl:messageをQNameで指定してください。

20.1.9　wsdl:output要素（wsdl:portType要素の孫要素の場合）

wsdl:output要素のサポート範囲を説明します。

wsdl:operation要素の子要素として，1個だけ記述できます。0個または2個以上記述した場合については，「15.1.3(3)　オペレーションとその子要素の記述個数」を参照してください。

子要素としてwsdl:documentation要素を指定できます。wsdl:documentation要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51058-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性

message属性

wsaw:Action属性

wsaw:Action属性については，「37.5.6　wsa:Action要素指定時の動作」を参照してください。

(1)　name属性（wsdl:output要素）

wsdl:output要素に含まれるname属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。

(2)　message属性（wsdl:output要素）

wsdl:output要素に含まれるmessage属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

参照できるwsdl:definitions要素以下に宣言されているwsdl:messageをQNameで指定してください。

20.1.10　wsdl:fault要素（wsdl:portType要素の孫要素の場合）

wsdl:fault要素のサポート範囲を説明します。

wsdl:operation要素の子要素として，0個から255個まで記述できます。省略または256個以上記述した場合については，「15.1.3(3)　オペレーションとその子要素の記述個数」を参照してください。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素のうち，次に示す拡張要素以外の拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51096-E）。

wsdl:documentation要素

jaxws:bindings要素（JAX-WS 2.2仕様のバインディング宣言）

wsdl:documentation要素とjaxws:bindings要素は上記の順序で指定する必要があります。指定順序を誤った場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性

message属性

wsaw:Action属性

wsaw:Action属性については，「37.5.6　wsa:Action要素指定時の動作」を参照してください。

(1)　name属性（wsdl:fault要素）

wsdl:fault要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。

(2)　message属性（wsdl:fault要素）

wsdl:fault要素に含まれるmessage属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

参照できるwsdl:definitions要素以下に宣言されているwsdl:messageをQNameで指定します。

20.1.11　wsdl:binding要素

wsdl:binding要素のサポート範囲を説明します。

wsdl:definitions要素の子要素として，1個から255個まで記述できます。省略できません※。省略または256個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51100-E）。

注※

WSDLのインポート機能を使用する場合は，インポート関係にあるすべてのWSDL内で1個あれば足りるので，この場合は省略できます。また，インポート関係にあるすべてのWSDL内での合計が上限になります。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素のうち，次に示す要素以外の拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51102-E）。

wsdl:documentation要素

soap:binding要素（SOAP 1.1仕様のSOAPバインディングのための拡張要素）※

soap12:binding要素（SOAP 1.2仕様のSOAPバインディングのための拡張要素）※

jaxws:bindings要素（JAX-WS 2.2仕様のバインディング宣言）

wsaw:UsingAddressing要素（WS-Addressing 1.0仕様の拡張要素）

wsdl:operation要素

注※

soap:binding要素とsoap12:binding要素は，どちらかを選択して指定してください。両方の要素を指定することはできません。

wsdl:binding要素の子要素は，上記の順序で指定してください。指定順序を誤った場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。ただし，次に示す要素の順序は入れ替わってもかまいません。

soap:binding要素またはsoap12:binding要素

jaxws:bindings要素

wsaw:UsingAddressing要素

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性

type属性

(1)　name属性（wsdl:binding要素）

wsdl:binding要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。

(2)　type属性（wsdl:binding要素）

wsdl:binding要素に含まれるtype属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

参照できるwsdl:definitions要素以下に宣言されているwsdl:messageをQNameで指定します。

20.1.12　wsdl:operation要素（wsdl:binding要素の子要素の場合）

wsdl:operation要素のサポート範囲を説明します。

wsdl:binding要素の子要素として，1個から255個まで記述できます。省略できません。省略または256個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素のうち，次に示す要素以外の拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51108-E）。

wsdl:documentation要素

soap:operation要素（SOAP 1.1仕様のSOAPバインディングのための拡張要素）※

soap12: operation要素（SOAP 1.2仕様のSOAPバインディングのための拡張要素）※

jaxws:bindings要素（JAX-WS 2.2仕様のバインディング宣言）

wsaw:Anonymous要素（WS-Addressing 1.0仕様の拡張要素）

wsdl:input要素

wsdl:output要素

wsdl:fault要素

注※

soap: operation要素とsoap12: operation要素は，どちらかを選択して指定してください。両方の要素を指定することはできません。

wsdl:operation要素（wsdl:binding要素の子要素の場合）の子要素は，上記の順序で指定してください。指定順序を誤った場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。ただし，次に示す要素の順序は入れ替わってもかまいません。

soap:operation要素またはsoap12: operation要素

jaxws:bindings要素

wsaw:Anonymous要素

name属性を指定できます。name属性以外の属性は指定できません。name属性以外の属性を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

wsdl:binding要素のwsdl:operation要素は，wsdl:portType要素で定義されているwsdl:operation要素に対応するように定義してください。対応するように定義していない場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51112-E）。

子要素としてwsdl:output要素を指定する場合は，wsdl:portType要素のwsdl:operation要素で定義されているwsdl:output要素に対応するように定義してください。

wsdl:portType要素のwsdl:operation要素にwsdl:output要素を1個記述し，wsdl:binding要素のwsdl:operation要素からwsdl:output要素を省略したときは，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51222-E）。

wsdl:portType要素のwsdl:operation要素からwsdl:output要素を省略し，wsdl:binding要素のwsdl:operation要素にwsdl:output要素を1個記述したときは，wsdl:output要素が無視され，cjwsimportコマンドの処理が続行されます。

(1)　name属性（wsdl:operation要素）

wsdl:operation要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。

20.1.13　wsdl:input要素（wsdl:binding要素の孫要素の場合）

wsdl:input要素のサポート範囲を説明します。

wsdl:operation要素の子要素として1個だけ記述できます。省略できません。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素のうち，次に示す要素以外の拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51114-E）。

wsdl:documentation要素

soap:header要素（SOAP 1.1仕様のSOAPバインディングのための拡張要素）※

soap:body要素（SOAP 1.1仕様のSOAPバインディングのための拡張要素）※

soap12:header要素（SOAP 1.2仕様のSOAPバインディングのための拡張要素）※

soap12:body要素（SOAP 1.2仕様のSOAPバインディングのための拡張要素）※

注※

soap:header要素とsoap12:header要素，およびsoap:body要素とsoap12:header要素は，それぞれどちらかを選択して指定してください。SOAP 1.1仕様とSOAP 1.2仕様の要素を両方または混在して指定することはできません。

wsdl:input要素（wsdl:binding要素の孫要素の場合）の子要素は，上記の順序で指定してください。指定順序を誤った場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。ただし，次に示す要素の順序は入れ替わってもかまいません。

soap:header要素またはsoap12:header要素

soap:body要素またはsoap12:body要素

name属性を指定できます。name属性以外の属性は指定できません。name属性以外の属性を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(1)　name属性（wsdl:input要素）

wsdl:input要素に含まれるname属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。

20.1.14　wsdl:output要素（wsdl:binding要素の孫要素の場合）

wsdl:output要素のサポート範囲を説明します。

wsdl:operation要素の子要素として1個だけ記述できます。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素のうち，次に示す拡張要素以外の拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51119-E）。

wsdl:documentation要素

soap:header要素（SOAP 1.1仕様のSOAPバインディングのための拡張要素）※

soap:body要素（SOAP 1.1仕様のSOAPバインディングのための拡張要素）※

soap12:header要素（SOAP 1.2仕様のSOAPバインディングのための拡張要素）※

soap12:body要素（SOAP 1.2仕様のSOAPバインディングのための拡張要素）※

注※

soap:header要素とsoap12:header要素，およびsoap:body要素とsoap12:header要素は，それぞれどちらかを選択して指定してください。SOAP 1.1仕様とSOAP 1.2仕様の要素を両方または混在して指定することはできません。

wsdl:output要素（wsdl:binding要素の孫要素の場合）の子要素は，上記の順序で指定してください。指定順序を誤った場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。ただし，次に示す要素の順序は入れ替わってもかまいません。

soap:header要素またはsoap12:header要素

soap:body要素またはsoap12:body要素

name属性を指定できます。name属性以外の属性は指定できません。name属性以外の属性を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(1)　name属性（wsdl:output要素）

wsdl:output要素に含まれるname属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。

20.1.15　wsdl:fault要素（wsdl:binding要素の孫要素の場合）

wsdl:fault要素のサポート範囲を説明します。

wsdl:operation要素の子要素として，0個から255個まで記述できます。256個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素のうち，次に示す拡張要素以外の拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51123-E）。

wsdl:documentation要素

soap:fault要素（SOAP 1.1仕様のSOAPバインディングのための拡張要素）※

soap12:fault要素（SOAP 1.2仕様のSOAPバインディングのための拡張要素）※

注※

soap:fault要素とsoap12:fault要素は，どちらかを選択して指定してください。両方の要素を指定することはできません。

wsdl:fault要素（wsdl:binding要素の孫要素の場合）の子要素は，上記の順序で指定してください。指定順序を誤った場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性を指定できます。name属性以外の属性は指定できません。name属性以外の属性を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(1)　name属性（wsdl:fault要素）

wsdl:fault要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。ただし，同じwsdl:operation要素以下にある，ほかのwsdl:fault要素のname属性と同じ値を指定できません。同じ値を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.16　wsdl:service要素

wsdl:service要素のサポート範囲を説明します。

wsdl:definitions要素の子要素として，1個から255個まで記述できます。省略できません※。省略または256個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51127-E）。

注※

WSDLのインポート機能を使用する場合は，インポート関係にあるすべてのWSDL内で1個あれば足りるので，この場合は省略できます。また，インポート関係にあるすべてのWSDL内での合計が上限になります。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素のうち，次に示す拡張要素以外の拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51129-E）。

wsdl:documentation要素

jaxws:bindings要素（JAX-WS 2.2仕様のバインディング宣言）

wsdl:port要素

wsdl:service要素の子要素は，上記の順序で指定する必要があります。指定順序を誤った場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性を指定できます。name属性以外の属性は指定できません。name属性以外の属性を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(1)　name属性（wsdl:service要素）

wsdl:service要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「15.1.9(2)　サービス名およびポート名の条件」を参照してください。ただし，同じwsdl:definitions要素以下にある，ほかのwsdl:service要素のname属性と同じ値は指定できません。同じ値を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.17　wsdl:port要素

wsdl:port要素のサポート範囲を説明します。

wsdl:service要素の子要素として，1個から255個まで記述できます。省略できません。省略または256個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

子要素として次に示す要素を指定できます。次に示すWSDL要素以外の要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。cjwsimportコマンドで無視しない拡張要素のうち，次に示す要素以外の拡張要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51135-E）。

wsdl:documentation要素

soap:address要素（SOAP 1.1仕様のSOAPバインディングのための拡張要素）※

soap12:address要素（SOAP 1.2仕様のSOAPバインディングのための拡張要素）※

jaxws:bindings要素（JAX-WS 2.2仕様のバインディング宣言）

wsaw:UsingAddressing要素（WS-Addressing 1.0仕様の拡張要素）

注※

soap:address要素とsoap12:address要素は，どちらかを選択して指定してください。両方の要素を指定することはできません。

wsdl:port要素の子要素は，上記の順序で指定してください。指定順序を誤った場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。ただし，次に示す要素の順序は入れ替わってもかまいません。

soap:address要素またはsoap12:address要素

jaxws:bindings要素

wsaw:UsingAddressing要素

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性

binding属性

(1)　name属性（wsdl:port要素）

wsdl:port要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「15.1.9(2)　サービス名およびポート名の条件」を参照してください。ただし，同じwsdl:service要素以下にある，ほかのwsdl:port要素のname属性と同じ値は指定できません。同じ値を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(2)　binding属性（wsdl:port要素）

wsdl:port要素に含まれるbinding属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

参照できるwsdl:definitions要素以下に宣言されているwsdl:bindingをQNameで指定してください。

20.1.18　wsdl:documentation要素

wsdl:documentation要素のサポート範囲を説明します。

次に示す要素の子要素として，0個または1個記述できます。2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。WSDL要素とcjwsimportコマンドで無視しない拡張要素のうち，次の要素の子要素として記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

wsdl:definitions要素

wsdl:import要素

wsdl:types要素

wsdl:message要素

wsdl:part要素

wsdl:portType要素

wsdl:operation要素

wsdl:input要素

wsdl:output要素

wsdl:fault要素

wsdl:binding要素

wsdl:service要素

wsdl:port要素

子要素として任意の要素を指定できます。

属性は指定できません。属性を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.19　soap:binding要素

soap:binding要素のサポート範囲を説明します。

wsdl:binding要素として1個だけ記述できます。省略できません。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51143-E）。

子要素は記述できません。記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次に示す属性以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

transport属性

style属性

(1)　transport属性（soap:binding要素）

soap:binding要素に含まれるtransport属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

値には"http://schemas.xmlsoap.org/soap/http"を記述してください。"http://schemas.xmlsoap.org/soap/http"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51147-E）。

(2)　style属性（soap:binding要素）

soap:binding要素に含まれるstyle属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

値には"document"を記述してください。"document"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.20　soap:operation要素

soap:operation要素のサポート範囲を説明します。

wsdl:operation要素の子要素として1個だけ記述できます。省略できません。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51150-E）。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次に示す属性以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

soapAction属性

style属性

(1)　soapAction属性（soap:operation要素）

soap:operation要素に含まれるsoapAction属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

xsd:anyURIを満たす任意の文字列を指定できます。

この属性に指定した値は無視されます。

(2)　style属性（soap:operation要素）

soap:operation要素に含まれるstyle属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

値には"document"を記述してください。"document"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.21　soap:body要素

soap:body要素のサポート範囲を説明します。

wsdl:binding要素の孫要素となるwsdl:input要素およびwsdl:outputの子要素として1個だけ記述できます。省略できません。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51156-E）。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。ただし，namespace属性を指定した場合は，標準エラー出力とログに異なるエラーメッセージが出力されます（KDJW51208-E）。

use属性

parts属性

(1)　use属性（soap:body要素）

soap:body要素に含まれるuse属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

値には"literal"を記述してください。"literal"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(2)　parts属性（soap:body要素）

soap:body要素に含まれるparts属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

soap:body要素に参照されるwsdl:message要素以下に宣言されているwsdl:part要素を0個または1個指定してください。2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

parts属性を指定するときの注意事項については，「20.2.2　SOAPボディおよびSOAPヘッダと参照先のwsdl:part要素の記述について」を参照してください。

20.1.22　soap:header要素

soap:header要素のサポート範囲を説明します。

wsdl:binding要素の孫要素となるwsdl:input要素およびwsdl:output要素の子要素として記述できます。省略することもできます。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。ただし，namespace属性を指定した場合は，標準エラー出力とログに警告メッセージが出力され，cjwsimportコマンドの処理が続行されます（KDJW51009-W）。

message属性

part属性

use属性

soap:header要素を指定するときの注意事項については，「20.2.2　SOAPボディおよびSOAPヘッダと参照先のwsdl:part要素の記述について」を参照してください。

(1)　message属性（soap:header要素）

soap:header要素に含まれるmessage属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

参照できるwsdl:definitions要素以下に宣言されているwsdl:messageをQNameで指定してください。

message属性を指定するときの注意事項については，「20.2.2　SOAPボディおよびSOAPヘッダと参照先のwsdl:part要素の記述について」を参照してください。

(2)　part属性（soap:header要素）

soap:header要素に含まれるpart属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

message属性に指定されたwsdl:message要素以下に宣言されているwsdl:part要素を指定してください。

part属性を指定するときの注意事項については，「20.2.2　SOAPボディおよびSOAPヘッダと参照先のwsdl:part要素の記述について」を参照してください。

(3)　use属性（soap:header要素）

soap:header要素に含まれるuse属性のサポート範囲を説明します。

1個だけ記述できます。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

値には"literal"を記述してください。"literal"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.23　soap:fault要素

soap:fault要素のサポート範囲を説明します。

wsdl:binding要素の孫要素となるwsdl:fault要素の子要素として1個だけ記述できます。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51051-E）。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。ただし，namespace属性を指定した場合は，標準エラー出力とログに異なるエラーメッセージが出力されます（KDJW51210-E）。

name属性

use属性

(1)　name属性（soap:fault要素）

soap:fault要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

親要素であるwsdl:fault要素のname属性と同じ値を記述してください。異なる値を記述した場合は，標準エラー出力とログに警告メッセージが出力され，cjwsimportコマンドの処理は続行されます（KDJW51027-W）。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。

(2)　use属性（soap:fault要素）

soap:fault要素に含まれるuse属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

値には"literal"を記述してください。"literal"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.24　soap:address要素

soap:address要素のサポート範囲を説明します。

wsdl:port要素の子要素として1個だけ記述できます。省略できません。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51175-E）。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

location属性を指定できます。location属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(1)　location属性（soap:address要素）

soap:address要素に含まれるlocation属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.3　soap:address要素またはsoap12:address要素のlocation属性に指定できる値」を参照してください。

20.1.25　soap12:operation要素

soap12:operation要素のサポート範囲を説明します。

wsdl:operation要素の子要素として1個だけ記述できます。省略できません。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51150-E）。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。ただし，soapActionRequired属性を指定した場合は，cjwsimportコマンドの処理は続行されます。

soapAction属性

style属性

(1)　soapAction属性（soap12:operation要素）

soap12:operation要素に含まれるsoapAction属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

xsd:anyURIを満たす任意の文字列を指定できます。

JAX-WSエンジンではsoapAction属性の指定は無視されます。

(2)　style属性（soap12:operation要素）

soap12:operation要素に含まれるstyle属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

値には"document"を記述してください。"document"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）

20.1.26　soap12:binding要素

soap12:binding要素のサポート範囲を説明します。

wsdl:binding要素の子要素として1個だけ記述できます。省略できません。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51143-E）。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

transport属性

style属性

(1)　transport属性（soap12:binding要素）

soap12:binding要素に含まれるtransport属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーとなります。

値には"http://schemas.xmlsoap.org/soap/http"または"http://www.w3.org/2003/05/soap/bindings/HTTP/"を記述してください。"http://schemas.xmlsoap.org/soap/http"または"http://www.w3.org/2003/05/soap/bindings/HTTP/"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51147-E）。

(2)　style属性（soap12:binding要素）

soap12:binding要素に含まれるstyle属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

値には"document"を記述してください。"document"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.27　soap12:body要素

soap12:body要素のサポート範囲を説明します。

wsdl:binding要素の孫要素であるwsdl:input要素，およびwsdl:output要素の子要素として，1個だけ記述できます。省略できません。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51156-E）。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。ただし，namespace属性を指定した場合は，標準エラー出力とログに異なるエラーメッセージが出力されます（KDJW51208-E）。

use属性

parts属性

(1)　use属性（soap12:body要素）

soap12:body要素に含まれるuse属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

値には"literal"を記述してください。"literal"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(2)　parts属性（soap12:body要素）

soap12:body要素に含まれるparts属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

soap12:body要素が参照するwsdl:message要素以下に宣言されているwsdl:part要素を，0個または1個記述できます。2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

parts属性を指定するときの注意事項については，「20.2.2　SOAPボディおよびSOAPヘッダと参照先のwsdl:part要素の記述について」を参照してください。

20.1.28　soap12:header要素

soap12:header要素のサポート範囲を説明します。

wsdl:binding要素の孫要素であるwsdl:input要素およびwsdl:output要素の子要素として記述できます。省略することもできます。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。ただし，namespace属性を指定した場合は，標準エラー出力とログに警告メッセージが出力され，cjwsimportコマンドの処理は続行されます（KDJW51009-W）。

message属性

part属性

use属性

soap12:header要素を指定するときの注意事項については，「20.2.2　SOAPボディおよびSOAPヘッダと参照先のwsdl:part要素の記述について」を参照してください。

(1)　message属性（soap12:header要素）

soap12:header要素に含まれるmessage属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

参照できるwsdl:definitions要素以下に宣言されているwsdl:messageをQNameで指定してください。

message属性を指定するときの注意事項については，「20.2.2　SOAPボディおよびSOAPヘッダと参照先のwsdl:part要素の記述について」を参照してください。

(2)　part属性（soap12:header要素）

soap12:header要素に含まれるpart属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

message属性に指定されたwsdl:message要素以下に宣言されているwsdl:part要素を指定してください。

part属性を指定するときの注意事項については，「20.2.2　SOAPボディおよびSOAPヘッダと参照先のwsdl:part要素の記述について」を参照してください。

(3)　use属性（soap12:header要素）

soap12:header要素に含まれるuse属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

値には"literal"を記述してください。"literal"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.29　soap12:fault要素

soap12:fault要素のサポート範囲を説明します。

wsdl:binding要素の孫要素となるwsdl:fault要素の子要素として1個だけ記述できます。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51051-E）。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

次の属性を指定できます。次の属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

name属性

use属性

(1)　name属性（soap12:fault要素）

soap12:fault要素に含まれるname属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

親要素であるwsdl:fault要素のname属性と同じ値を記述してください。異なる値を記述した場合は，標準エラー出力とログに警告メッセージが出力され，cjwsimportコマンドの処理は続行されます（KDJW51027-W）。

指定できる値については，「20.2.1　NCName型に指定できる値」を参照してください。

(2)　use属性（soap12:fault要素）

soap12:fault要素に含まれるuse属性のサポート範囲を説明します。

0個または1個記述できます。2個以上記述した場合は，XML Processorのエラーになります。

値には"literal"を記述してください。"literal"以外を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

20.1.30　soap12:address要素

soap12:address要素のサポート範囲を説明します。

wsdl:port要素の子要素として1個だけ記述できます。省略できません。省略または2個以上記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51175-E）。

子要素は記述できません。子要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

location属性を指定できます。location属性以外を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(1)　location属性（soap12:address要素）

soap12:address要素に含まれるlocation属性のサポート範囲を説明します。

1個だけ記述できます。省略できません。省略した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。2個以上記述した場合は，XML Processorのエラーになります。

指定できる値については，「20.2.3　soap:address要素またはsoap12:address要素のlocation属性に指定できる値」を参照してください。

20.1.31　xsd:schema要素

xsd:schema要素のサポート範囲を説明します。

JAXB 2.2仕様に従いJava型にマッピングしますが，マッピングはXML Processorにすべて委譲しています。

(1)　xmime:expectedContentTypes属性（xsd:schema要素）

WSDLのスキーマ宣言であるxsd:element要素のtype属性に"xsd:base64Binary"を指定している場合，xmime:expectedContentTypes属性を用いてMIMEタイプを明示的に指定することで，Base64形式のデータをMIMEタイプに対応したJava型に関連づけることができます。WSDLのスキーマ宣言であるxsd:element要素に対するxmime:expectedContentTypes属性の記述可否を次の表に示します。

表20‒1　xmime:expectedContentTypes属性の記述可否

項番

xsd:element要素を参照するwsdl:messageのパラメタ

xsd:element要素に対するxmime:expectedContentTypes属性の記述可否

1

wsdl:input

○※1

2

wsdl:output

○※1

3

wsdl:fault

×※2

（凡例）

○：記述できます。

×：記述できません。

注※1

WSDLパートの種類がinoutの場合，wsdl:input要素から参照するxsd:element要素のxmime:expectedContentTypes属性の値とwsdl:output要素から参照するxsd:element要素のxmime:expectedContentTypes属性の値には，同じMIMEタイプを指定してください。異なるMIMEタイプを指定した場合，動作は保証されません。

注※2

フォルトメッセージにxmime:expectedContentTypes属性が記述されたxsd:element要素を指定した場合，動作は保証されません。

xsd:element要素にxmime:expectedContentTypes属性を指定した場合のWSDLからJava型へのマッピング方法は，WSDLのxmime:expectedContentTypes属性があるxsd:base64Binary型をJava型へマッピングします。WSDLからJava型へのマッピング例を次の図に示します。

図20‒1　WSDLからJava型へのマッピング例

xmime:expectedContentTypes属性に指定するMIMEタイプには，"text/xml"および"application/xml"のcharsetパラメタを除いて，パラメタを記述しないでください。"text/xml"および"application/xml"のcharsetパラメタ以外のパラメタを記述した場合，動作は保証されません。

WSDLからマッピングするJava型は，xmime:expectedContentTypes属性に指定されているMIMEタイプによって変化します。xmime:expectedContentTypes属性に記述されているMIMEタイプと関連づけるJava型の関係を次の表に示します。

表20‒2　xmime:expectedContentTypes属性の値と関連づけるJava型

項番

xmime:expectedContentTypes属性の値（MIMEタイプ）

関連づけるJava型

1

application/xml

javax.xml.transform.Source

2

image/png※1

java.awt.Image※2

3

image/jpeg※1

4

上記のMIMEタイプをコンマ区切りで記述（例：image/png, image/jpeg）※3

5

image/*※3

6

text/plain

java.lang.String

7

text/*※4

javax.activation.DataHandler

8

text/xml※5

javax.xml.transform.Source

9

上記以外※4，※6

javax.activation.DataHandler

注※1

表中にないimageタイプをJava型に関連づける場合は，xmime:expectedContentTypes属性に"application/octet-stream"を指定し，javax.activation.DataHandlerクラスに関連づけます。

注※2

JAXB仕様に従います。java.awt.ImageクラスはJava SE仕様でのグラフィカルイメージを表現する抽象クラスで，データ形式の規定はありません。この関連づけを使用して画像データをインスタンス化した場合，具象クラスのインスタンスには復号化した情報だけが保持されることがあります。そのため，JPEG形式のように符号化するときに情報が削減される可能性のある画像を添付ファイルとして送信する場合，受信側のインスタンスが送信側のインスタンスや元のデータと異なることがあります。

画像を元の形式のまま扱いたい場合は，javax.activation.DataHandlerにマッピングされるMIMEタイプ（application/octet-streamなど）を使用してください。

注※3

MIMEタイプに"image/png，image/jpeg"など同一タイプを指定した場合や"image/*"を指定した場合，送信するSOAPメッセージの添付ファイルパートにあるMIMEヘッダのContent-Typeフィールドの値は，java.awt.Image型を使用したときの初期値（"image/png"）です。

注※4

MIMEタイプに"text/*"や表中にないMIMEタイプを指定した場合，送信するSOAPメッセージの添付ファイルパートにあるMIMEヘッダのContent-Typeフィールドの値は，javax.activation.DataHandler型を使用したときの初期値（javax.activation.DataHandlerオブジェクトのMIMEタイプ）です。

注※5

MIMEタイプに"text/xml"を指定した場合，送信するSOAPメッセージの添付ファイルパートにあるMIMEヘッダのContent-Typeフィールドの値は，javax.xml.transform.Source型を使用したときの初期値（"application/xml"）です。

注※6

異なるタイプ名のMIMEタイプをコンマ区切りで記述した場合も含まれます（例：image/png, text/plain）。

xmime:expectedContentTypes属性に指定されているMIMEタイプは，cjwsimportコマンドで自動生成されるJavaBeanクラスのうち，xmime:expectedContentTypes属性を記述した要素に対応するJavaBeanクラスにアノテートされたjavax.xml.bind.annotation.XmlMimeTypeアノテーションの値へマッピングされます。WSDLから自動生成されたJavaBeanクラスへのマッピングの例を次の図に示します。

図20‒2　WSDLから自動生成されたJavaBeanクラスへのマッピング

(a)　名前空間"xmime"のインポート

WSDLからJava型へのマッピングでは，名前空間"xmime"に存在する属性"xmime:expectedContentTypes"を使用しますが，JAX-WSではxsd:import要素による名前空間"xmime"のインポートは不要です。

hwsgenコマンドで作成したWSDLを使用する場合，必要に応じて名前空間"xmime"をインポートする必要があります。名前空間"xmime"のインポート例を次に示します。

<wsdl:definitions targetNamespace="http://localhost"
  xmlns:intf="http://localhost"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xmime="http://www.w3.org/2005/05/xmlmime" ・・・・・・>
  <wsdl:types>
    <xsd:schema targetNamespace="http://localhost">
      <xsd:import namespace="http://www.w3.org/2005/05/xmlmime"/>
      <xsd:element name="setPhotoData" type="intf:setPhotoData"/>
      <xsd:complexType name="setPhotoData">
        <xsd:sequence>
          <xsd:element name="in0" type="xsd:base64Binary" xmime:expectedContentTypes="image/jpeg"/>
        </xsd:sequence>
      </xsd:complexType>
      ・・・・・・
    </xsd:schema>
  </wsdl:types>
   ・・・・・・

20.2　WSDL作成時の注意事項

WSDL作成時の注意事項について説明します。

20.2.1　NCName型に指定できる値

Application ServerのJAX-WS機能では，XML Schema仕様のxsd:NCName型の制限に違反しないかぎり，半角英数字（0〜9，A〜Z，a〜z）およびアンダースコア（_）を使用できます。半角英数字およびアンダースコア以外の文字を使用した場合，動作は保証されません。

20.2.2　SOAPボディおよびSOAPヘッダと参照先のwsdl:part要素の記述について

wsdl:input要素とwsdl:output要素の子要素として記述するSOAPボディおよびSOAPヘッダの記述と，SOAPボディおよびSOAPヘッダから参照されるwsdl:part要素の記述について説明します。

以降では，SOAP 1.1仕様の場合を例に説明します。SOAP 1.2仕様の場合は，名前空間や要素名，属性値などを読み替えてください。

(1)　SOAPヘッダを定義しない場合

soap:body要素にparts属性を記述する場合でも，記述しない場合でも，親要素となるwsdl:input要素またはwsdl:output要素から参照されるwsdl:message要素の子要素には，wsdl:part要素を1個だけ記述してください。

soap:header要素を記述しない場合の記述例を次の図に示します。

図20‒3　soap:header要素を記述しない場合の記述例

(2)　SOAPヘッダを定義する場合

soap:header要素を記述する場合，次に示す内容に従って定義してください。

soap:header要素のmessage属性には，親要素であるwsdl:input要素，またはwsdl:output要素から参照されるwsdl:message要素を指定してください。

soap:header要素のpart属性には，message属性に指定したwsdl:message要素以下に宣言されているwsdl:part要素を指定してください。宣言されていないwsdl:part要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51022-E）。

soap:body要素のparts属性は省略できません。親要素となるwsdl:input要素，またはwsdl:output要素から参照されるwsdl:message要素の複数のwsdl:part子要素のうち，どの要素をsoap:body要素にバインドするのかを指定してください。バインドしない場合は，空の文字列を指定してください。

soap:body要素のparts属性に参照されていないwsdl:message要素のwsdl:part要素，または存在しないwsdl:part要素を指定した場合は，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51021-E）。また，soap:body要素のparts属性を指定していない場合も，標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51179-E）。

soap:header要素を記述する場合の記述例を次の図に示します。

図20‒4　soap:header要素を記述する場合の記述例

20.2.3　soap:address要素またはsoap12:address要素のlocation属性に指定できる値

soap:address要素またはsoap12:address要素のlocation属性には，次に示す形式のURLを指定できます。

<プロトコル※1>://<ホスト名※2>/<パス部分※4>

（例）http://xxx.com/jaxws/service/UserInfoPort

<プロトコル※1>://<ホスト名※2>:<ポート番号※3>/<パス部分※4>

（例）http://xxx.com:80/jaxws/service/UserInfoPort

注※1

名前空間としては，http://またはhttps://だけ指定できます。そのほかのプロトコルは指定できません。http://およびhttps://以外のプロトコルを指定した場合，動作は保証されません。

注※2

RFC 2396仕様の規則に従った文字列を指定できます。また，RFC 2732（IPv6アドレス）仕様の規則に従った文字列も指定できます。

ただし，次の形式は指定できません。次の形式で指定した場合，動作は保証されません。

クエリストリング　（例）http://example.com/?a=b

アンカー　（例）http://example.com/index.html#anchor

ポート番号　（例）http://example.com:8080/

ユーザ名／パスワード　（例）http://user:password@example.com

パーセントエンコードされた文字　（例）http://%E4%BD%BF%E7%94%A8

注※3

半角数字0〜9だけを使用した文字列を指定できます。そのほかの文字を指定した場合，動作は保証されません。

注※4

RFC 2396仕様の規則に従った文字列を指定できます。また，パーセントエンコードされた文字（（例）http://%E4%BD%BF%E7%94%A8）も指定できます。

21　XML Catalogs 1.1のサポート範囲

この章では，XML Catalogs 1.1仕様のサポート範囲について説明します。

21.1　XML Catalogs 1.1仕様のサポート範囲の一覧

XML Catalogs 1.1仕様で定義されている，カタログファイルの構文のサポート範囲を次の表に示します。Application ServerのJAX-WS機能でサポートしていない構文で記述した場合の動作は保証されません。

表21‒1　カタログファイルの構文のサポート範囲の一覧（要素）

項番

要素名

サポート

1

er:catalog

○

2

er:group

×

3

er:public

○

4

er:system

○

5

er:rewriteSystem

×

6

er:systemSuffix

×

7

er:delegatePublic

×

8

er:delegateSystem

×

9

er:uri

×

10

er:rewriteURI

×

11

er:uriSuffix

×

12

er:delegateURI

×

13

er:nextCatalog

×

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

表21‒2　カタログファイルの構文のサポート範囲の一覧（属性）

項番

要素名

属性名

サポート

1

er:catalog

prefer

○

id

×

xml:base

×

2

er:public

publicId

○

uri

○

id

×

xml:base

×

3

er:system

systemId

○

uri

○

id

×

xml:base

×

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

21.2　XML Catalogs 1.1仕様のサポート範囲の詳細

XML Catalogs 1.1仕様で定義されている，カタログファイルの構文のサポート範囲を要素ごとに説明します。

21.2.1　er:catalog要素

カタログファイルのルート要素として，1個だけ記述できます。省略できません。省略した場合または2個以上記述した場合は警告メッセージ※が出力され，カタログ機能が無効な状態で処理が続行されます。

次の要素を子要素として指定できます。次の要素以外を記述した場合は警告メッセージ※が出力されます。

er:public要素

er:system要素

注※

カタログ機能を使用する場所によって，出力先と警告メッセージは次のように異なります。

Webサービスクライアントの実行時：ログファイル（KDJW30023-W）

Webサービスクライアントの開発時：標準エラー出力（KDJW51221-W）

(1)　prefer属性

er:catalog要素の属性として0個または1個記述できます。省略した場合の動作は，publicを指定したときと同じになります。

次の値を属性値として指定できます。次の属性以外を記述した場合は警告メッセージ※が出力されます。

public

system

WSDLまたはXMLスキーマのxsd:import要素にnamespace属性とschemalocation属性が含まれる場合，prefer属性にpublicを指定しても，er:public要素によってxsd:import要素のnamespace属性をマッピングすることはできません。

注※

カタログ機能を使用する場所によって，出力先と警告メッセージは次のように異なります。

Webサービスクライアントの実行時：ログファイル（KDJW30023-W）

Webサービスクライアントの開発時：標準エラー出力（KDJW51221-W）

21.2.2　er:public要素

publicId属性に指定したXMLスキーマの名前空間URIを，uri属性に指定したXMLスキーマのロケーションを示すURIにマッピングします。

er:catalog要素の子要素として，0個から255個まで記述できます。256個以上記述した場合の動作は保証されません。

(1)　publicId属性

er:public要素の属性として，1個だけ記述できます。省略できません。省略した場合は警告メッセージ※が出力され，カタログ機能が無効な状態で処理が続行されます。

属性値は，xsd:import要素のnamespace属性と同じ名前空間URIを指定してください。

注※

カタログ機能を使用する場所によって，出力先と警告メッセージは次のように異なります。

Webサービスクライアントの実行時：ログファイル（KDJW30023-W）

Webサービスクライアントの開発時：標準エラー出力（KDJW51221-W）

(2)　uri属性

er:public要素の属性として，1個だけ記述できます。省略できません。省略した場合は警告メッセージ※1が出力され，カタログ機能が無効な状態で処理が続行されます。

指定できる属性値の条件を次に示します。

マッピングするXMLスキーマの相対パス※2またはURLを指定してください。指定する際は，マッピングするXMLスキーマの対象の名前空間と，xsd:import要素のnamespace属性の名前空間を一致させてください。名前空間が一致しない場合の動作は保証されません。

RFC 2396で規定されたxsd:anyURIを満たす文字で指定してください。また，RFC 2732（IPv6アドレス）の規則に従った文字列も使用できます。

大文字と小文字は区別されません。

指定できる文字列の最大長の制限はありません。ただし，OSの制限を超えた場合は，エラーとなります。

注意

存在しない，またはアクセス権限のないWSDLまたはXMLスキーマを指定した場合は警告メッセージ（KDJW30024-W）が出力され，カタログ機能が無効な状態で処理が続行されます。

注※1

カタログ機能を使用する場所によって，出力先と警告メッセージは次のように異なります。

Webサービスクライアントの実行時：ログファイル（KDJW30023-W）

Webサービスクライアントの開発時：標準エラー出力（KDJW51221-W）

注※2

カタログファイルを配置したディレクトリからの相対パスを示します。

21.2.3　er:system要素

systemId属性に指定したWSDLまたはXMLスキーマのロケーションを示すURIを，uri属性に指定した別のWSDLまたはXMLスキーマのロケーションを示すURIにマッピングします。

er:catalog要素の子要素として，0個から255個まで記述できます。256個以上記述した場合の動作は保証されません。

(1)　systemId属性

er:system要素の属性として，1個だけ記述できます。省略できません。省略した場合は警告メッセージ※が出力され，カタログ機能が無効な状態で処理が続行されます。

指定できる属性値の条件を次に示します。

マッピングされるWSDLまたはXMLスキーマのURLを，絶対URLで指定してください。相対URLおよび相対パスは指定できません。相対URLおよび相対パスは，絶対URLに変換して指定してください。

RFC 2396で規定されたxsd:anyURIを満たす文字で指定してください。また，RFC 2732（IPv6アドレス）の規則に従った文字列も使用できます。

大文字と小文字は区別されません。

指定できる文字列の最大長の制限はありません。ただし，OSの制限を超えた場合は，エラーとなります。

注※

カタログ機能を使用する場所によって，出力先と警告メッセージは次のように異なります。

Webサービスクライアントの実行時：ログファイル（KDJW30023-W）

Webサービスクライアントの開発時：標準エラー出力（KDJW51221-W）

(2)　uri属性

er:system要素の属性として，1個だけ記述できます。省略できません。省略した場合は警告メッセージ※1が出力され，カタログ機能が無効な状態で処理が続行されます。

指定できる値の条件を次に示します。

マッピングするWSDLまたはXMLスキーマの相対パス※2またはURLを指定してください。

RFC 2396で規定されたxsd:anyURIを満たす文字で指定してください。また，RFC 2732（IPv6アドレス）の規則に従った文字列も使用できます。

大文字と小文字は区別されません。

指定できる文字列の最大長の制限はありません。ただし，OSの制限を超えた場合は，エラーとなります。

注意

存在しない，またはアクセス権限のないWSDLまたはXMLスキーマを指定した場合は警告メッセージ（KDJW30024-W）が出力され，カタログ機能が無効な状態で処理が続行されます。

注※1

カタログ機能を使用する場所によって，出力先と警告メッセージは次のように異なります。

Webサービスクライアントの実行時：ログファイル（KDJW30023-W）

Webサービスクライアントの開発時：標準エラー出力（KDJW51221-W）

注※2

カタログファイルを配置したディレクトリからの相対パスを示します。

22　SAAJ仕様のサポート範囲

この章では，Webサービスを開発するときに注意が必要な，SAAJ仕様のサポート範囲について説明します。

22.1　SAAJ 1.3仕様のサポート範囲

ここでは，SAAJ 1.3仕様のインタフェースおよびクラスのサポート範囲について説明します。また，ディスパッチベースのWebサービスクライアントで利用する場合の注意事項についても説明します。なお，SAAJの各メソッドはスレッドセーフではありません。SAAJのオブジェクトを複数スレッドで共有しないでください。共有した場合の動作は保証されません。

SAAJ 1.3仕様のインタフェースのサポート範囲を次の表に示します。インタフェースについては，JDKのドキュメントを参照してください。

表22‒1　SAAJ 1.3仕様のインタフェースのサポート範囲

項番

インタフェース名

メソッド名／フィールド名

サポート

1

Detail

addDetailEntry(Name name)

○

2

addDetailEntry(QName qname)

○

3

上記以外のメソッド

○

4

DetailEntry

メソッドなし

○

5

Name

すべてのメソッド

○

6

Node

getValue()

○

7

recycleNode()

○

8

setParentElement(SOAPElement parent)

○

9

setValue(String value)

○

10

上記以外のメソッド

○

11

SOAPBody

addBodyElement(Name name)

○

12

addBodyElement(QName qname)

○

13

addDocument(Document document)

○

14

addFault(Name faultCode, String faultString, Locale locale)

○

15

addFault(Name faultCode, String faultString)

○

16

addFault(QName faultCode, String faultString, Locale locale)

○

17

addFault(QName faultCode, String faultString)

○

18

上記以外のメソッド

○

19

SOAPBodyElement

メソッドなし

○

20

SOAPConstants

すべてのフィールド

○

21

SOAPElement

addAttribute(Name name, String value)

○

22

addAttribute(QName qname, String value)

○

23

addChildElement(Name name)

○

24

addChildElement(SOAPElement element)

○

25

addChildElement(String localName)

○

26

addChildElement(String localName, String prefix)

○

27

addChildElement(String localName, String prefix, String uri)

○

28

addChildElement(QName qname)

○

29

addNamespaceDeclaration(String prefix, String uri)

○

30

addTextNode(String text)

○

31

createQName(String localName, String prefix)

○

32

getAttributeValue(Name name)

○

33

getAttributeValue(QName qname)

○

34

getChildElements(Name name)

○

35

getChildElements(QName qname)

○

36

getEncodingStyle()

○

37

getNamespacePrefixes()

○

38

getNamespaceURI(String prefix)

○

39

removeAttribute(Name name)

○

40

removeAttribute(QName qname)

○

41

setElementQName(QName newName)

○

42

上記以外のメソッド

○

43

SOAPEnvelope

createName(String localName)

○

44

createName(String localName, String prefix, String uri)

○

45

上記以外のメソッド

○

46

SOAPFault

getFaultCode()

○

47

getFaultCodeAsName()

○

48

getFaultCodeAsQName()

○

49

getFaultString()

○

50

setFaultCode(Name faultCodeQName)

○

51

setFaultCode(QName faultCodeQName)

○

52

setFaultCode(String faultCode)

○

53

setFaultString(String faultString)

○

54

setFaultString(String faultString, Locale locale)

○

55

addFaultReasonText(String text, Locale locale)

○

56

getFaultReasonLocales()

○

57

getFaultReasonText(Locale locale)

○

58

getFaultReasonTexts()

○

59

getFaultStringLocale()

○

60

setFaultRole(String uri)

○

61

上記以外のメソッド

○

62

SOAPFaultElement

メソッドなし

○

63

SOAPHeader

addHeaderElement(Name name)

○

64

addHeaderElement(QName qname)

○

65

addUpgradeHeaderElement(String supportedSoapUri)

○

66

examineHeaderElements(String actor)

○

67

examineMustUnderstandHeaderElements(String actor)

○

68

extractHeaderElements(String actor)

○

69

上記以外のメソッド

○

70

SOAPHeaderElement

setActor(String actorURI)

○

71

setRole(String uri)

○

72

上記以外のメソッド

○

73

Text

すべてのメソッド

○

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

SAAJ 1.3仕様のクラスのサポート範囲を次の表に示します。クラスについては，JDKのドキュメントを参照してください。

表22‒2　SAAJ 1.3仕様のクラスのサポート範囲

項番

クラス名

メソッド名／フィールド名

サポート

1

AttachmentPart

addMimeHeader(String name, String value)

○

2

getAllMimeHeaders()

○

3

getContentLocation()

×

4

setContentLocation(String contentLocation)

×

5

setBase64Content(InputStream content, String contentType)

○

6

setContent(Object object, String contentType)

○

7

setContentId(String contentId)

○

8

setContentType(String contentType)

○

9

setMimeHeader(String name, String value)

○

10

setRawContent(InputStream content, String contentType)

○

11

setRawContentBytes(byte[] content, int offset, int len, String contentType)

○

12

上記以外のメソッド

○

13

MessageFactory

newInstance(String protocol)

○

14

上記以外のメソッド

○

15

MimeHeader

MimeHeader(String name, String value)コンストラクタ

○

16

上記以外のメソッド

○

17

MimeHeaders

addHeader(String name, String value)

○

18

setHeader(String name, String value)

○

19

上記以外のメソッド

○

20

SAAJMetaFactory

すべてのメソッド

○

21

SAAJResult

SAAJResult(SOAPMessage message)コンストラクタ

○

22

SAAJResult(SOAPElement rootNode)コンストラクタ

○

23

上記以外のメソッド

○

24

SOAPConnection

すべてのメソッド

○

25

SOAPConnectionFactory

すべてのメソッド

○

26

SOAPElementFactory※

すべてのメソッド

×

27

SOAPFactory

newInstance(String protocol)

○

28

createElement(Element domElement)

○

29

createElement(String localName, String prefix, String uri)

○

30

createFault(String reasonText, QName faultCode)

○

31

createName(String localName)

○

32

createName(String localName, String prefix, String uri)

○

33

上記以外のメソッド

○

34

SOAPMessage

addAttachmentPart(AttachmentPart AttachmentPart)

○

35

createAttachmentPart(Object content, String contentType)

○

36

getAttachment(SOAPElement element)

○

37

getAttachments(MimeHeaders headers)

×

38

getProperty(String property)

○

39

removeAttachments(MimeHeaders headers)

○

40

setContentDescription(String description)

○

41

setProperty(String property, Object value)

○

42

writeTo(OutputStream out)

○

43

上記以外のメソッド

○

44

SOAPPart

addMimeHeader(String name, String value)

○

45

getContentId()

×

46

getContentLocation()

×

47

getMimeHeader(String name)

○

48

setContent(Source source)

○

49

setContentId(String contentId)

×

50

setContentLocation(String contentLocation)

×

51

setMimeHeader(String name, String value)

○

52

上記以外のメソッド

○

（凡例）

○：Application ServerのJAX-WS機能でサポートしています。

×：Application ServerのJAX-WS機能でサポートしていません。

注※

非推奨クラスのため，使用した場合の動作は保証されません。

22.1.1　Detailインタフェース

Detailインタフェースのメソッドを使用する場合の注意事項を示します。

addDetailEntry(Name name)メソッドおよびaddDetailEntry(QName qname)メソッドの引数にnullを指定しないでください。nullを指定した場合の動作は保証されません。

22.1.2　Nodeインタフェース

Nodeインタフェースのメソッドを使用する場合の注意事項を示します。

getValue()メソッドの対象ノードの子ノードの値は取得できません。対象ノードの子ノードの値を取得したい場合は，子ノードに対してメソッドを発行してください。

対象ノードに対してdetachNode()を呼び出したことがなくても，recycleNode()メソッドを呼び出せます。メソッドを呼び出すと，detachNode()と同じ動作が実行されます。

setParentElement(SOAPElement parent)メソッドでは，異なるDOM Documentに属するノード同士を親子関係にできません。

setValue(String value)メソッドの引数にnullを指定すると，対象ノードの値にnullが設定されます。

22.1.3　SOAPBodyインタフェース

SOAPBodyインタフェースのメソッドを使用する場合の注意事項を示します。

次に示すメソッドの引数にはnullを指定しないでください。nullを指定した場合の動作は保証されません。

addBodyElement(Name name)

addBodyElement(QName qname)

addDocument(Document document)

addFault(Name faultCode, String faultString, Locale locale)

addFault(Name faultCode, String faultString)

addFault(QName faultCode, String faultString, Locale locale)

addFault(QName faultCode, String faultString)

addFault(Name faultCode, String faultString, Locale locale)メソッドおよびaddFault(QName faultCode, String faultString, Locale locale)メソッドのlocale引数には，nullを指定しないでください。指定した場合の動作は保証されません。

addFault(QName faultCode, String faultString, Locale locale)メソッドおよびaddFault(QName faultCode, String faultString)メソッドの引数には，標準仕様で定義されているフォルトコードを指定してください。標準仕様で定義されていないフォルトコードを指定した場合の動作は保証されません。

addFault(QName faultCode, String faultString, Locale locale)メソッドまたはaddFault(QName faultCode, String faultString)メソッドのfaultString引数に空文字を設定してSOAPフォルトを送信した場合，受信したSOAPフォルトに対してgetFaultString()メソッドおよびgetFaultReasonTexts().next()を発行すると，nullが取得されます。

22.1.4　SOAPElementインタフェース

SOAPElementインタフェースのメソッドを使用する場合の注意事項を示します。

addAttribute(Name name, String value)メソッドのname引数にnullを指定しないでください。指定した場合の動作は保証されません。

addAttribute(QName qname, String value)メソッドのqname引数にnullを指定しないでください。指定した場合の動作は保証されません。

次に示すメソッドの引数にはnullを指定しないでください。nullを指定した場合の動作は保証されません。

addChildElement(Name name)

addChildElement(SOAPElement element)

addChildElement(QName qname)

addTextNode(String text)

getAttributeValue(Name name)

getAttributeValue(QName qname)

getChildElements(Name name)

getChildElements(QName qname)

removeAttribute(Name name)

removeAttribute(QName qname)

setElementQName(QName newName)

次に示すメソッドのlocalName引数にnullまたは空文字を指定しないでください。nullまたは空文字を指定した場合の動作は保証されません。

addChildElement(String localName)

addChildElement(String localName, String prefix)

addChildElement(String localName, String prefix, String uri)

addChildElement(String localName, String prefix, String uri)メソッドのuri引数にnullまたは空文字を指定しないでください。指定した場合の動作は保証されません。

addNamespaceDeclaration(String prefix, String uri)メソッドのprefix引数にnullを指定しないでください。指定した場合の動作は保証されません。

addNamespaceDeclaration(String prefix, String uri)メソッドのuri引数にnullまたは空文字を指定した場合，名前空間URIが空文字の名前空間宣言が追加されます。

createQName(String localName, String prefix)メソッドのlocalName引数にnullを指定しないでください。指定した場合の動作は保証されません。

エンコードスタイルが設定されていない状態でgetEncodingStyle()メソッドを発行した場合，nullが返されます。

デフォルト名前空間(xmlns="")に属する対象SOAPElementに対してgetNamespacePrefixes()メソッドを発行した場合，戻り値にデフォルト名前空間のプレフィクスは含まれません。

getNamespaceURI(String prefix)メソッドで引数に指定したプレフィクスが対象のSOAPElementに宣言されていない場合，または引数にnullまたは空文字を指定した場合，nullが返されます。

22.1.5　SOAPEnvelopeインタフェース

SOAPEnvelopeインタフェースのメソッドを使用する場合の注意事項を示します。

createName(String localName)メソッドおよびcreateName(String localName, String prefix, String uri)メソッドのlocalName引数にnullまたは空文字を指定しないでください。指定した場合の動作は保証されません。

createName(String localName, String prefix, String uri)メソッドのuri引数にnullまたは空文字を指定した場合，名前空間URIが空文字のNameオブジェクトが生成されます。

22.1.6　SOAPFaultインタフェース

SOAPFaultインタフェースのメソッドを使用する場合の注意事項を示します。

フォルトコードが明示的に設定されていないSOAPFaultオブジェクトに対して次のメソッドを発行した場合，Application ServerのJAX-WS機能が自動的に設定した値が返されます。

getFaultCode()

getFaultCodeAsName()

getFaultCodeAsQName()

フォルトコードが明示的に設定されていないSOAPFaultオブジェクトに対して次のメソッドを発行した場合，Application ServerのJAX-WS機能が自動的に設定したフォルト文字列"Fault string, and possibly fault code, not set"が返されます。

getFaultString()

getFaultReasonTexts()

SOAP 1.1形式の場合に，フォルトコードが明示的に設定されていないSOAPFaultオブジェクトに対してgetFaultStringLocale()メソッドを発行した場合，nullが返されます。

SOAP 1.2形式の場合に，フォルトコードが明示的に設定されていないSOAPFaultオブジェクトに対してgetFaultReasonLocales()メソッドまたはgetFaultStringLocale()メソッドを発行した場合，Application ServerのJAX-WS機能が自動的に設定した値が返されます。

次に示すメソッドの引数にはnullを指定しないでください。nullを指定した場合の動作は保証されません。

setFaultCode(Name faultCodeQName)

setFaultCode(QName faultCodeQName)

setFaultCode(String faultCode)

setFaultString(String faultString)

setFaultString(String faultString, Locale locale)

setFaultRole(String uri)

次に示すメソッドの引数には，名前空間で修飾されたフォルトコードを指定してください。名前空間で修飾されていない，ローカル名だけのフォルトコードを指定した場合の動作は保証されません。

setFaultCode(Name faultCodeQName)

setFaultCode(QName faultCodeQName)

setFaultCode(String faultCode)

setFaultString(String faultString, Locale locale)メソッドのlocale引数にnullを指定しないでください。指定した場合の動作は保証されません。

addFaultReasonText(String text, Locale locale)メソッドのtext引数にnullを指定しないでください。指定した場合の動作は保証されません。

getFaultReasonText(Locale locale)メソッドの引数にnullを指定した場合，nullが返されます。

getFaultReasonLocales()メソッドまたはgetFaultStringLocale()メソッドが取得したロケールは，受信したSOAPフォルトのxml:lang属性に設定されているロケールと異なる場合があります。

setFaultRole(String uri)メソッドのuri引数には，URI形式の文字列を指定してください。URI形式以外の文字列を指定した場合の動作は保証されません。

22.1.7　SOAPHeaderインタフェース

SOAPHeaderインタフェースのメソッドを使用する場合の注意事項を示します。

addHeaderElement(Name name)メソッドおよびaddHeaderElement(QName qname)メソッドの引数にnullは指定しないでください。nullを指定した場合の動作は保証されません。

addUpgradeHeaderElement(String supportedSoapUri)メソッドのsupportedSoapUri引数にnullを指定しないでください。指定した場合の動作は保証されません。

examineHeaderElements(String actor)メソッドおよびextractHeaderElements(String actor)メソッドのactor引数にnullを指定しないでください。指定した場合の動作は保証されません。

examineMustUnderstandHeaderElements(String actor)メソッドのactor引数にnullを指定した場合，設定されているすべてのSOAPHeaderElementを含むIteratorが返されます。

22.1.8　SOAPHeaderElementインタフェース

SOAPHeaderElementインタフェースのメソッドを使用する場合の注意事項を示します。

setActor(String actorURI)メソッドのactorURI引数にnullを指定した場合，SOAP 1.1形式の場合は値が空文字のactor属性が，SOAP 1.2形式の場合は値が空文字のrole属性が設定されます。

SOAP 1.2形式の場合，setRole(String uri)メソッドのuri引数にnullを指定すると，値が空文字のrole属性が設定されます。

22.1.9　AttachmentPartクラス

AttachmentPartクラスのメソッドを使用する場合の注意事項を示します。

addMimeHeader(String name, String value)メソッドまたはsetMimeHeader(String name, String value)メソッドでMIMEヘッダを設定しても，送受信時のSOAPメッセージ上にMIMEヘッダは現れません。

addMimeHeader(String name, String value)メソッドまたはsetMimeHeader(String name, String value)メソッドのvalue引数に指定した値は，MIMEヘッダの値に設定されます。

getAllMimeHeaders()メソッドではContent-Transfer-Encodingヘッダを取得できません。Application ServerのJAX-WS機能では，添付ファイルは常にバイナリ形式で送信されるため，AttachmentPartのContent-Transfer-Encodingヘッダの値はbinaryになります。

getContentLocation()メソッドを使用した場合の動作は保証されません。

setContentLocation(String contentLocation)メソッドを使用した場合の動作は保証されません。Content-Locationヘッダの代わりにAttachmentPart#setContentIdメソッドで設定したContent-Idヘッダを使用する必要があります。

次に示すメソッドのcontentType引数に指定した値がContent-Typeヘッダの値に設定されます。そのため，添付ファイルの型に適合するMIMEタイプを指定する必要があります。不正なMIMEタイプを指定した場合の動作は保証されません。

setBase64Content(InputStream content, String contentType)

setContentType(String contentType)

setRawContent(InputStream content, String contentType)

setRawContentBytes(byte[] content, int offset, int len, String contentType)

setContent(Object object, String contentType)メソッドのcontentType引数にnullまたは標準仕様で定義されていないMIMEタイプを指定しないでください。指定した場合の動作は保証されません。

setContent(Object object, String contentType)メソッドの第1引数には，第2引数に指定したMIMEタイプに適合するオブジェクトを指定してください。適合しないオブジェクトを指定した場合の動作は保証されません。また，nullを指定した場合の動作も保証されません。

setContentId(String contentId)メソッドのcontentId引数にnullまたは空文字を指定した場合は，その値がContent-Idヘッダの値に設定されます。

setRawContentBytes(byte[] content, int offset, int len, String contentType)メソッドのoffset引数には正しいオフセットを，len引数には正しいサイズを指定してください。不正な値を指定した場合の動作は保証されません。

22.1.10　MessageFactoryクラス

MessageFactoryクラスのメソッドを使用する場合の注意事項を示します。

newInstance(String protocol)メソッドでDYNAMIC_SOAP_PROTOCOLは指定しないでください。指定した場合の動作は保証されません。

22.1.11　MimeHeaderクラス

MimeHeaderクラスのメソッドを使用する場合の注意事項を示します。

RFC 822やRFC 2045などで，MIMEヘッダでは使用できないと定義されている文字は，MimeHeader(String name, String value)コンストラクタの引数に指定しないでください。指定した場合の動作は保証されません。

22.1.12　MimeHeadersクラス

MimeHeadersクラスのメソッドを使用する場合の注意事項を示します。

addHeader(String name, String value)メソッドおよびsetHeader(String name, String value)メソッドのvalue引数にnullを指定しないでください。指定した場合の動作は保証されません。

addHeader(String name, String value)メソッドまたはsetHeader(String name, String value)メソッドでContent-LengthヘッダまたはContent-Typeヘッダの値を設定しても，送受信時に値が上書きされます。

SOAPハンドラ内でSOAPMessage#getMimeHeaders()メソッドから取得したMimeHeadersオブジェクトは，HTTPヘッダの取得および更新ができません。メッセージコンテキストを使用することによりHTTPヘッダを取得することはできます。メッセージコンテキストについては，「19.2.5　メッセージコンテキストの使用」を参照してください。

22.1.13　SAAJResultクラス

SAAJResultクラスのメソッドを使用する場合の注意事項を示します。

SAAJResult(SOAPMessage message)コンストラクタの引数にnullは指定しないでください。nullを指定した場合の動作は保証されません。

SAAJResult(SOAPElement rootNode)コンストラクタのrootNode引数にnullを指定しないでください。指定した場合の動作は保証されません。

22.1.14　SOAPFactoryクラス

SOAPFactoryクラスのメソッドを使用する場合の注意事項を示します。

newInstance(String protocol)メソッドでDYNAMIC_SOAP_PROTOCOLは指定しないでください。指定した場合の動作は保証されません。

createElement(Element domElement)メソッドの引数にnullを指定した場合，nullが返されます。

createElement(String localName, String prefix, String uri)メソッドのlocalName引数に空文字を指定しないでください。指定した場合の動作は保証されません。

createElement(String localName, String prefix, String uri)メソッドのprefix引数にnullまたは空文字を指定した場合，プレフィクスがnullのSOAPElementオブジェクトが生成されます。

createElement(String localName, String prefix, String uri)メソッドのuri引数にnullを指定しないでください。指定した場合の動作は保証されません。また，uri引数に空文字を指定した場合は，名前空間URIがnullのSOAPElementオブジェクトが生成されます。

createFault(String reasonText, QName faultCode)メソッドの引数にnullは指定しないでください。nullを指定した場合の動作は保証されません。

createFault(String reasonText, QName faultCode)メソッドのfaultCode引数に標準仕様で定義されていないフォルトコードを指定しないでください。指定した場合の動作は保証されません。

createName(String localName)メソッドまたはcreateName(String localName, String prefix, String uri)メソッドのlocalName引数に空文字を指定しないでください。指定した場合の動作は保証されません。

createName(String localName, String prefix, String uri)メソッドのuri引数にnullまたは空文字を指定した場合，名前空間URIが空文字のNameオブジェクトが生成されます。

22.1.15　SOAPMessageクラス

SOAPMessageクラスのメソッドを使用する場合の注意事項を示します。

次に示すメソッドの引数にnullは指定しないでください。nullを指定した場合の動作は保証されません。

addAttachmentPart(AttachmentPart AttachmentPart)

getAttachment(SOAPElement element)

writeTo(OutputStream out)

addAttachmentPart(AttachmentPart AttachmentPart)メソッドのAttachmentPart引数に空のAttachmentPartオブジェクトを指定しないでください。指定した場合の動作は保証されません。

createAttachmentPart(Object content, String contentType)メソッドの第1引数には，第2引数に指定したMIMEタイプに適合するオブジェクトを指定してください。適合しないオブジェクトを指定した場合の動作は保証されません。また，nullを指定した場合の動作も保証されません。

getAttachment(SOAPElement element)メソッドの引数に指定した要素の値やhref属性からAttachmentPartを参照する場合は，存在するAttachmentPartを示すCID URLスキーム（RFC 2392規定）を記述してください。存在しないAttachmentPartを示すCID URLスキームを記述した場合の動作は保証されません。

getAttachments(MimeHeaders headers)メソッドを使用した場合の動作は保証されません。SOAPMessage#getAttachments()メソッドまたはgetAttachment(SOAPElement)メソッドでAttachmentPartを取得する必要があります。

getProperty(String property)メソッドの引数にnullを指定した場合，nullが返されます。

Application ServerのJAX-WS機能が対応しているSOAPメッセージの文字エンコードは，utf-8だけです。ただし，getProperty(String property)メソッドの引数にSOAPMessage.CHARACTER_SET_ENCODINGを指定してプロパティ値を取得する場合，nullが返される場合があります。

SOAPMessage#setPropertyメソッドで対象プロパティを設定していない場合，getProperty(String property)メソッドにはnullが返されます。

removeAttachments(MimeHeaders headers)メソッドの引数にnullを指定した場合，AttachmentPartはすべて削除されます。

setContentDescription(String description)メソッドの引数にnullを指定した場合，Content-Descriptionヘッダには値が設定されません。空文字を指定した場合は，Content-Descriptionヘッダに空文字が設定されます。

setProperty(String property, Object value)メソッドのproperty引数にはSOAPMessage.CHARACTER_SET_ENCODINGまたはSOAPMessage.WRITE_XML_DECLARATIONを指定してください。SOAPMessage.CHARACTER_SET_ENCODINGまたはSOAPMessage.WRITE_XML_DECLARATION以外のプロパティを指定しても，無視されます。

setProperty(String property, Object value)メソッドのproperty引数にSOAPMessage.CHARACTER_SET_ENCODINGを指定する場合は，value引数にutf-8を指定してください。utf-8以外の値を指定した場合の動作は保証されません。

setProperty(String property, Object value)メソッドのproperty引数にSOAPMessage.WRITE_XML_DECLARATIONを指定する場合は，"true"または"false"を指定してください。"true"または"false"以外を指定した場合の動作は保証されません。

setProperty(String property, Object value)メソッドのproperty引数にnullを指定しないでください。指定した場合の動作は保証されません。

Dispatch／ProviderでSOAPメッセージを送受信する場合，setProperty(String property, Object value)メソッドではプロパティを設定できません。プロパティを設定したい場合は，SOAPConnectionでSOAPメッセージを送受信してください。

22.1.16　SOAPPartクラス

SOAPPartクラスのメソッドを使用する場合の注意事項を示します。

addMimeHeader(String name, String value)メソッドまたはsetMimeHeader(String name, String value)メソッドのvalue引数に指定した値がMIMEヘッダの値に設定されます。

addMimeHeader(String name, String value)メソッドまたはsetMimeHeader(String name, String value)メソッドでSOAPPartにMIMEヘッダを設定しても，送受信時のSOAPメッセージ上にMIMEヘッダは現れません。

getMimeHeader(String name)メソッドの引数にSOAPPartオブジェクトに設定されていないMIMEヘッダ名やnullを指定した場合，nullが返されます。

setContent(Source source)メソッドの引数にはXMLとしてもSOAPとしても正しい内容のSourceオブジェクトを指定してください。不正な内容のSourceオブジェクトを指定した場合の動作は保証されません。また，nullを指定した場合の動作も保証されません。

次のメソッドを使用した場合の動作は保証されません。

getContentId()

getContentLocation()

setContentId(String contentId)

setContentLocation(String contentLocation)

22.1.17　添付ファイルを使用する場合のサポート範囲

プロバイダ実装クラスを使用して開発したWebサービス，またはディスパッチベースのWebサービスクライアントでは，SAAJ仕様に従って添付ファイル付きのSOAPメッセージを生成，送受信できます。一度に送受信できる添付ファイルのサイズおよび個数は，実行環境のメモリ量によって変わりますが，制限はありません。メモリ量を増やせば，容量の大きい添付ファイルや多量の添付ファイルを一度に送受信することもできます。

添付ファイルを送受信するときのメモリの使用量については，「付録C.3　添付ファイル使用時の1リクエスト当たりのメモリ使用量」を参照してください。

(1)　MIMEタイプ

添付ファイルに対応するMIMEタイプは，添付ファイルの拡張子によって決まります。添付ファイルのMIMEタイプを明示しない場合，添付ファイルの拡張子によって自動的に適切なMIMEタイプが設定されます。AttachmentPart#setContentType()メソッドなどによってMIMEタイプを明示する場合は，添付ファイルの拡張子に対応した適切なMIMEタイプを指定する必要があります。不正なMIMEタイプを指定した場合の動作は保証されません。

添付ファイルの拡張子とMIMEタイプの適切な組み合わせを次の表に示します。次の表に示した拡張子以外の場合，MIMEタイプはapplication/octet-streamとなります。

表22‒3　添付ファイルの拡張子とMIMEタイプ

項番

添付ファイルの拡張子

対応するMIMEタイプ

1

html，htm

text/html

2

txt，text

text/plain

3

gif，GIF

image/gif

4

ief

image/ief

5

jpeg，jpg，jpe，JPG

image/jpeg

6

tiff，tif

image/tiff

7

xwd

image/x-xwindowdump

8

ai，eps，ps

application/postscript

9

rtf

application/rtf

10

tex

application/x-tex

11

texinfo，texi

application/x-texinfo

12

t，tr，roff

application/x-troff

13

au

audio/basic

14

midi，mid

audio/midi

15

aifc

audio/x-aifc

16

aif，aiff

audio/x-aiff

17

wav

audio/x-wav

18

mpeg，mpg，mpe

video/mpeg

19

qt，mov

video/quicktime

20

avi

video/x-msvideo

(2)　添付ファイルを読み込む場合の注意事項

ファイルを読み込んで添付ファイルとして送受信する場合は，java.io.FileInputStreamで読み込んだオブジェクトではなく，javax.activation.FileDataSourceで読み込んだオブジェクトを添付ファイルに設定する必要があります。例を次に示します。

AttachmentPart apPart = request.createAttachmentPart();
FileDataSource source = new FileDataSource("D:¥¥attachment.txt");
apPart.setDataHandler(new DataHandler(source));
request.addAttachmentPart(apPart);

java.io.FileInputStreamで読み込んだオブジェクトを設定した場合の動作は保証されません。

(3)　DOM APIを使用する場合の注意事項

DOM APIを使用してSOAPメッセージを作成する場合は，次に示すメソッドは使用しないでください。使用した場合の動作は保証されません。

org.w3c.dom.createEntityReference(String name)

org.w3c.dom.createProcessingInstruction(String target, String data)

(4)　複数のファイルを添付する場合の注意事項

複数の添付ファイルを一度に送信する場合は，それぞれのAttachmentPartオブジェクトにユニークなContent-IDを設定する必要があります。Content-IDを設定しない，または重複するContent-IDを設定して複数の添付ファイルを送信しようとした場合，最後に設定した添付ファイルだけが送信されます。

複数のAttachmentPartオブジェクトにユニークなContent-IDを設定する例を次に示します。

AttachmentPart apPart1 = request.createAttachmentPart();
FileDataSource source1 = new FileDataSource("D:¥¥attachment1.txt");
apPart1.setDataHandler(new DataHandler(source1));
apPart1.setContentId("001");
request.addAttachmentPart(apPart1);

AttachmentPart apPart2 = request.createAttachmentPart();
FileDataSource source2 = new FileDataSource("D:¥¥attachment2.txt");
apPart2.setDataHandler(new DataHandler(source2));
apPart2.setContentId("002");
request.addAttachmentPart(apPart2);

AttachmentPart apPart3 = request.createAttachmentPart();
FileDataSource source3 = new FileDataSource("D:¥¥attachment3.txt");
apPart3.setDataHandler(new DataHandler(source3));
apPart3.setContentId("003");
request.addAttachmentPart(apPart3);

23　WS-RM仕様のサポート範囲

この章では，WS-RM仕様のサポート範囲について説明します。WS-RM 1.2機能については，「34.　WS-RM 1.2機能」を参照してください。

23.1　WS-RM 1.2仕様のサポート範囲

WS-RM 1.2仕様のサポート範囲を次の表に示します。なお，表中の大分類はWS-RM 1.2仕様の該当個所（章節項）を，小分類はWS-RM 1.2仕様の該当個所に記載されている内容を示します。

表23‒1　WS-RM 1.2仕様のサポート範囲

分類

サポート

大分類

小分類

2.4

送達保証

AtLeastOnce

×

AtMostOnce

×

ExactlyOnce

○

InOrder

×

3

RM要素

○

3.1

拡張要素／拡張属性の考慮※1

○

3.2

Piggy-Backing

○

3.3

WS-Addressingの利用

○

3.4

シーケンス生成

○

3.4

シーケンス生成リクエスト

wsrm:CreateSequence

○

wsrm:AcksTo※2

△

wsrm:Expires※3

×

wsrm:Offer

○

拡張要素／拡張属性※1

○

3.4

シーケンス生成レスポンス

wsrm:CreateSequenceResponse

○

wsrm:Identifier

○

wsrm:Expires※3

×

wsrm:IncompleteSequenceBehavior

DiscardEntireSequence

×

DiscardFollowingFirstGap

×

NoDiscard

○

wsrm:Accept

○

拡張要素／拡張属性※1

○

3.5

シーケンスクローズ

○

3.5

シーケンスクローズリクエスト

wsrm:CloseSequence

○

wsrm:Identifier

○

wsrm:LastMsgNumber

○

拡張要素／拡張属性※1

○

3.5

シーケンスクローズレスポンス

wsrm:CloseSequenceResponse

○

wsrm:Identifier

○

拡張要素／拡張属性※1

○

3.6

シーケンス終了

○

3.6

シーケンス終了リクエスト

wsrm:TerminateSequence

○

wsrm:Identifier

○

wsrm:LastMsgNumber

○

拡張要素／拡張属性※1

○

3.6

シーケンス終了レスポンス

wsrm:TerminateSequenceResponse

○

wsrm:Identifier

○

拡張要素／拡張属性※1

○

3.7

シーケンス

○

シーケンス要素

wsrm:Sequence

○

wsrm:Identifier

○

wsrm:MessageNumber

○

3.8

Ackリクエスト

○

3.8

Ackリクエスト要素

wsrm:AckRequested

○

wsrm:Identifier

○

拡張要素／拡張属性※1

○

3.9

Ack

○

3.9

Ack要素

wsrm:SequenceAcknowledgement

○

wsrm:Identifier

○

wsrm:AcknowledgementRange

○

wsrm:None※4

△

wsrm:Final

○

wsrm:Nack

×

拡張要素／拡張属性※1

○

4

フォルト

○

4

SOAP 1.1対応

○

4

SOAP 1.2対応

○

4.1

wsrm:SequenceFaultフォルト

○

4.2

wsrm:SequenceTerminatedフォルト

○

4.3

wsrm:UnknownSequenceフォルト

○

4.4

wsrm:InvalidAcknowledgementフォルト

○

4.5

wsrm:MessageNumberRolloverフォルト

○

4.6

wsrm:CreateSequenceRefusedフォルト

○

4.7

wsrm:SequenceClosedフォルト

○

4.8

wsrm:WSRMRequiredフォルト

×

5

セキュリティの脅威と対策

×

6

セキュアなシーケンス

×

（凡例）

○：Application ServerのWS-RM 1.2機能でサポートしています。

×：Application ServerのWS-RM 1.2機能でサポートしていません。

△：Application ServerのWS-RM 1.2機能でサポートしていますが，一部制限があります。

注※1

Application ServerのWS-RM 1.2機能では，拡張要素および拡張属性を付加しません。受信メッセージに含まれる拡張要素および拡張属性は無視されます。

注※2

使用できる要素値は，匿名URIだけです。

注※3

wsrm:Expires要素によるシーケンス有効期限の設定はサポートしていません。シーケンスの有効期限は，WSDLにnet35rmpInactivityTimeoutを指定して設定します。

注※4

Application ServerのWS-RM 1.2機能では，wsrm:None要素を送信しません。返すAckがない場合，HTTPステータスコード202を返します。受信メッセージに含まれる場合は正常に処理されます。

23.2　WS-RM Policy 1.2仕様のサポート範囲

WS-RM Policy 1.2仕様のサポート範囲を次の表に示します。なお，表中の大分類はWS-RM Policy 1.2仕様の該当個所（章節項）を，小分類はWS-RM Policy 1.2仕様の該当個所に記載されている内容を示します。

表23‒2　WS-RM Policy 1.2仕様のサポート範囲

分類

サポート

大分類

小分類

2.2

アサーション要素

/wsrmp:RMAssertion

○

/wsrmp:RMAssertion/@wsp:Optional

×

/wsrmp:RMAssertion/wsp:Policy

○

/wsrmp:RMAssertion/wsp:Policy/wsrmp:SequenceSTR

×

/wsrmp:RMAssertion/wsp:Policy/wsrmp:SequenceTransportSecurity

×

/wsrmp:RMAssertion/wsp:Policy/wsrmp:DeliveryAssurance

○

/wsrmp:RMAssertion/wsp:Policy/wsrmp:DeliveryAssurance/wsp:Policy

○

/wsrmp:RMAssertion/wsp:Policy/wsrmp:DeliveryAssurance/wsp:Policy/wsrmp:ExactlyOnce

○

/wsrmp:RMAssertion/wsp:Policy/wsrmp:DeliveryAssurance/wsp:Policy/wsrmp:AtLeastOnce

×

/wsrmp:RMAssertion/wsp:Policy/wsrmp:DeliveryAssurance/wsp:Policy/wsrmp:AtMostOnce

×

/wsrmp:RMAssertion/wsp:Policy/wsrmp:DeliveryAssurance/wsp:Policy/wsrmp:InOrder

×

拡張要素/拡張属性※

○

2.3

アサーション添付

/wsdl:definitions/wsdl:service/wsdl:port

×

/wsdl:definitions/wsdl:binding

○

/wsdl:definitions/wsdl:binding/wsdl:operation/wsdl:input

×

/wsdl:definitions/wsdl:binding/wsdl:operation/wsdl:output

×

/wsdl:definitions/wsdl:binding/wsdl:operation/wsdl:fault

×

2.5

シーケンスセキュリティポリシー

×

（凡例）

○：Application ServerのWS-RM Policy 1.2機能でサポートしています。

×：Application ServerのWS-RM Policy 1.2機能でサポートしていません。

注※

Application ServerのWS-RM Policy 1.2機能では，拡張要素および拡張属性を付加しません。受信メッセージに含まれる拡張要素および拡張属性は無視されます。

23.3　com.sun.xml.ws.Closeableクラス

com.sun.xml.ws.Closeableクラスのサポート範囲を次の表に示します。

表23‒3　com.sun.xml.ws.Closeableクラスのメソッドの一覧

項番

戻り値の型

メソッド名／説明

1

void

close()

説明

シーケンスをクローズし，終了させるために，クライアント側でポートのオブジェクトをcom.sun.xml.ws.Closeable型にキャストして，close()メソッドを呼び出す必要があります。close()メソッドを呼び出したあとは，Webサービスメソッドを呼び出すことはできません。再度，通信したい場合は，ポートのオブジェクトを取得し直す必要があります。

例外

javax.xml.ws.WebServiceException：

close()メソッドを呼び出したあとにWebサービスメソッドを使用した場合に発生します。

23.4　WS-Policyによる設定

WS-RM 1.2機能には，WS-RM Policyでの設定のほかに，WS-PolicyとしてWSDLに記述する独自の設定があります。ここではWSDLに追加するプロパティについて説明します。

WS-RM Policyの追加方法については，「34.4　WS-RM Policyの追加方法」を参照してください。

表23‒4　WSDLに追加するプロパティ

項番

プロパティ

説明

単位

範囲

デフォルト値

1

<net35rmp:InactivityTimeout Milliseconds = "設定値"/>

シーケンスの有効期限を設定します。アプリケーションメッセージの再送間隔を設定する場合，アプリケーションメッセージの再送間隔以上の値を設定してください。

設定した期間，通信されない場合

シーケンスの有効期限が切れ，シーケンスは自動的に終了します。

有効期限が切れたあとにメッセージを送信した場合

WebServiceExceptionの子クラスであるSequenceTerminatedException例外またはUnknownSequenceException例外が発生します。

有効期限が切れたあとにメッセージを受信した場合

SequenceTerminatedフォルトまたはUnknownSequenceフォルトを返信します。

通信を続ける場合

再度ポートのオブジェクトを取得し，シーケンスを生成し直す必要があります。

範囲外の値を指定した場合

警告メッセージを出力し，デフォルト値で動作します（KDJR16017-W）。

ミリ秒

1〜9,223,372,036,854,775,807

600,000

2

<cwsrm:MaxMessageNumber value="設定値"/>

一つのシーケンスで扱える最大のメッセージ数を設定します。

設定したメッセージ数を超えてメッセージを送信した場合

WebServiceExceptionの子クラスであるMessageNumberRolloverException例外が発生します。

設定したメッセージ数を超えてメッセージを受信した場合

MessageNumberRolloverフォルトを返信します。

通信を続ける場合

既存のシーケンスを終了するため，ポートのオブジェクトをcom.sun.xml.ws.Closeableにキャストし，closeメソッドを呼び出します。その後，再度ポートのオブジェクトを取得し，シーケンスを生成し直す必要があります。

範囲外の値を指定した場合

警告メッセージを出力し，デフォルト値で動作します（KDJR16017-W）。

−

1〜100,000

10,000

3

<metro:AckRequestInterval Milliseconds="設定値"/>

WS-RM 1.2機能が自動的にバックグラウンドで送信するAckメッセージの送信間隔を設定します。タイミングによっては，設定値の2倍程度の間隔が開く場合があります。

範囲外の値を指定した場合，警告メッセージを出力し，デフォルト値で動作します（KDJR16017-W）。

ミリ秒

1〜9,223,372,036,854,775,807

2,000

4

<metro:RetransmissionConfig>

<metro:Interval Milliseconds="設定値"/>

</metro:RetransmissionConfig>

アプリケーションメッセージの再送間隔を設定します。

範囲外の値を設定した場合，警告メッセージを出力し，デフォルト値で動作します（KDJR16017-W）。

ミリ秒

1〜9,223,372,036,854,775,807

2,000

5

<metro:RetransmissionConfig>

<metro:MaxRetries>設定値</metro:MaxRetries>

</metro:RetransmissionConfig>

アプリケーションメッセージの再送回数を設定します。設定した再送回数を超えると，再送を停止し，アプリケーションに発生したエラーを返します。

0を指定した場合

再送回数は無限になります。

範囲外の値を設定した場合

警告メッセージを出力し，デフォルト値で動作します（KDJR16017-W）。

−

0〜9,223,372,036,854,775,807

3

（凡例）

−：なし

シーケンスの有効期限を300,000ミリ秒（5分）に，シーケンスの最大メッセージ数を1,000に設定するWS-RM Policyの例を次に示します。

  <wsp:Policy wsu:Id="WSRM_policy">
    <wsp:ExactlyOne>
      <wsp:All>
        <wsrmp:RMAssertion>
          <wsp:Policy>
            <wsrmp:DeliveryAssurance>
              <wsp:Policy>
                <wsrmp:ExactlyOnce/>
              </wsp:Policy>
            </wsrmp:DeliveryAssurance>
          </wsp:Policy>
        </wsrmp:RMAssertion>
        <wsaw:UsingAddressing/>
        <net35rmp:InactivityTimeout Milliseconds="300000"/>
        <cwsrm:MaxMessageNumber value="1000"/>
      </wsp:All>
    </wsp:ExactlyOne>
  </wsp:Policy>

24　JAX-RS仕様のサポート範囲

この章では，RESTful Webサービス（Webリソース）を開発するときに留意が必要な，JAX-RS仕様のサポート範囲について説明します。

24.1　JAX-RS 1.1仕様のサポート範囲

ここでは，JAX-RS 1.1仕様のサポート範囲について説明します。JAX-RS 1.1仕様のサポート範囲を次の表に示します。

表24‒1　JAX-RS 1.1仕様のサポート範囲

分類

対応

備考

大分類※

小分類

2

Application

ビルトイン実装

○

Application ServerのJAX-RS機能は，サーブレットベースのメカニズム（JAX-RS 1.1仕様の2.3.2項の最終段落に記述されています）をサポートしています。また，JAX-RS機能はデフォルトのビルトインApplication実装を提供しているので，RESTful Webサービスを実装する際にApplicationの実装は不要です（Applicationのカスタム実装はサポートしていません）。ビルトインApplication実装やデプロイについては，「3.5.1　WARファイルの構成」を参照してください。

カスタム実装

×

3.1，3.3

要求メソッド識別子

ビルトイン実装

○

Application ServerのJAX-RS機能は，JAX-RS 1.1仕様で定義されている次の標準の要求メソッド識別子をサポートしています。

GETアノテーション

POSTアノテーション

PUTアノテーション

DELETEアノテーション

HEADアノテーション

JAX-RS 1.1仕様でオプションとなっている要求メソッド識別子のカスタム実装はサポートしていません。

カスタム実装

×

3.1

ルートリソースクラス

○

ルートリソースクラスについては，「17.1.1　ルートリソースクラス」を参照してください。

3.1

ルートリソースクラスのライフサイクル

○

ルートリソースクラスのライフサイクルについては，「17.1.1(1)　ライフサイクル」を参照してください。

3.1.2

ルートリソースクラスのコンストラクタパラメタへのインジェクション

○

ルートリソースクラスのコンストラクタパラメタへのインジェクションについては，「17.1.1(2)　コンストラクタ」を参照してください。

インジェクトできる型や，DefaultValueアノテーションとの組み合わせについては，「17.1.4　パラメタ型」を参照してください。

3.2

フィールドとbeanプロパティへのインジェクション

○

フィールドとbeanプロパティへのインジェクションについては，「17.1.1(3)　フィールドおよびbeanプロパティ」を参照してください。

インジェクトできる型や，DefaultValueアノテーションとの組み合わせについては，「17.1.4　パラメタ型」を参照してください。

3.3

リソースメソッド

○

リソースメソッドについては，「17.1.1(4)　リソースメソッド」を参照してください。

3.3.2

リソースメソッドのパラメタへのインジェクション

○

リソースメソッドのパラメタへのインジェクションについては，「17.1.1(4)(b)　パラメタのアノテーション」を参照してください。

インジェクトできる型や，DefaultValueアノテーションとの組み合わせについては，「17.1.4　パラメタ型」を参照してください。

3.3.2(1)

HTTPリクエストのエンティティボディからエンティティパラメタへのマッピング

○

エンティティパラメタについては，「17.1.1(4)(c)　エンティティパラメタ」を参照してください。

3.3.3

戻り値からHTTPレスポンスのエンティティボディへのマッピング

○

戻り値については，「17.1.1(4)(d)　戻り値」を参照してください。

3.2，3.3.4

例外のハンドリング

○

例外については，「17.1.5　例外のマッピング」を参照してください。

3.3.5

HEAD HTTPリクエストおよびOPTIONS HTTPリクエストの処理

○

HEAD HTTPリクエストの処理については，「24.3.2(3)　javax.ws.rs.HEADアノテーション」を参照してください。OPTIONS HTTPリクエストの処理については，「24.3.2(4)　javax.ws.rs.OPTIONSアノテーション」を参照してください。

3.4，3.7.3

URIテンプレートと正規表現

○

URIテンプレートについては，「17.1.6　URIテンプレート」を参照してください。

3.4.1

サブリソースメソッド

○

サブリソースメソッドについては，「17.1.1(5)　サブリソースメソッド」を参照してください。

3.4.1

サブリソースロケータとサブリソース

○

サブリソースロケータについては，「17.1.1(6)　サブリソースロケータ」を参照してください。サブリソースクラスについては，「17.1.7　サブリソースクラス」を参照してください。

3.5

メディアタイプの宣言

○

メディアタイプの宣言については，「17.1.9　メディアタイプ宣言」を参照してください。

3.6

アノテーションの継承

○

アノテーションの継承については，「17.1.11　アノテーションの継承」を参照してください。

3.7

HTTPリクエストからリソースメソッドへのマッチング

○

−

3.8

HTTPレスポンスのメディアタイプの決定

○

−

4.2

エンティティプロバイダ（メッセージボディリーダおよびライタ）

ビルトイン実装

○

Application ServerのJAX-RS機能は，ビルトインのエンティティプロバイダを提供しているので，RESTful Webサービスを実装する際にエンティティプロバイダの実装は不要です（エンティティプロバイダのカスタム実装はサポートしていません）。

ビルトインのエンティティプロバイダには，JAX-RS 1.1仕様でサポートが必須とされているエンティティプロバイダのほか，JAX-RS機能で追加にサポートするエンティティプロバイダが含まれます。ビルトインのエンティティプロバイダとサポートされる型については，「17.1.1(4)(c)　エンティティパラメタ」を参照してください。

カスタム実装

×

4.3

コンテキストプロバイダ

×

コンテキストプロバイダを実装しなくても，Application ServerのJAX-RS機能はJAX-RS 1.1仕様の標準のコンテキストを適切に処理します。

4.4

例外マッピングプロバイダ

○

例外マッピングプロバイダについては，「17.2.2　例外マッピングプロバイダ」を参照してください。

5

コンテキスト

○

Application ServerのJAX-RS機能は標準のコンテキスト型をサポートしています。コンテキストについては，「24.4　コンテキスト」を参照してください。

5.2.1

javax.ws.rs.core.Application

×

−

5.2.2

javax.ws.rs.core.UriInfo

○

javax.ws.rs.core.UriInfoについては，「24.4.1　javax.ws.rs.core.UriInfo」を参照してください。

5.2.3

javax.ws.rs.core.HttpHeaders

○

javax.ws.rs.core.HttpHeadersについては，「24.4.2　javax.ws.rs.core.HttpHeaders」を参照してください。

5.2.4

javax.ws.rs.core.Request

○

javax.ws.rs.core.Requestについては，「24.4.3　javax.ws.rs.core.Request」を参照してください。

5.2.5

javax.ws.rs.core.SecurityContext

○

javax.ws.rs.core.SecurityContextについては，「24.4.4　javax.ws.rs.core.SecurityContext」を参照してください。

5.2.6

javax.ws.rs.ext.Providers

○

javax.ws.rs.ext.Providersについては，「24.4.5　javax.ws.rs.core.ext.Providers」を参照してください。

6.1

javax.servlet.ServletConfig

○

javax.servlet.ServletConfigについては，「24.4.6　javax.servlet.ServletConfig」を参照してください。

6.1

javax.servlet.ServletContext

○

javax.servlet.ServletContextについては，「24.4.7　javax.servlet.ServletContext」を参照してください。

6.1

javax.servlet.http.HttpServletRequest

○

javax.servlet.http.HttpServletRequestについては，「24.4.8　javax.servlet.http.HttpServletRequest」を参照してください。

6.1

javax.servlet.http.HttpServletResponse

○

javax.servlet.http.HttpServletResponseについては，「24.4.9　javax.servlet.http.HttpServletResponse」を参照してください。

6.1

サーブレットコンテナ（Webコンテナ）による実行環境

○

JAX-RS機能は，サーブレットコンテナによるRESTful Webサービスの実行環境を提供しています。

「1.4.2(2)(c)　Application」も参照してください。

6.1

サーブレット仕様で定義されている型のインジェクション

○

次の項目も参照してください。

javax.servlet.ServletConfig

javax.servlet.ServletContext

javax.servlet.http.HttpServletRequest

javax.servlet.http.HttpServletResponse

6.1

要求エンティティのストリーミング処理とメソッド内での応答のコミット

×

Application ServerのJAX-RS機能は，JAX-RS 1.1仕様の6.1節の後半で説明されている動作をサポートしていません。

6.2

Java EEコンテナ（EJBコンテナ）による実行環境

×

−

7

ランタイムデリゲート

○

Application ServerのJAX-RS実装は，JAX-RS 1.1仕様のランタイムデリゲートのメカニズムに従って実装されています。

Apx.A

アノテーション

○

APIについては，「24.2　APIのサポート範囲」を参照してください。

Apx.B

HTTPヘッダ

○

−

JavaDoc

API

○

APIについては，「24.2　APIのサポート範囲」を参照してください。

（凡例）

○：対応しています。

×：対応していません。

−：該当しません。

注※

JAX-RS 1.1仕様の該当個所（章節項）を示します。

24.2　APIのサポート範囲

ここでは，JAX-RS APIのインタフェースおよびクラスのサポート範囲について説明します。また，JAX-RS 1.1仕様のインタフェースおよびクラスを利用する場合の注意事項についても説明します。

JAX-RS APIのインタフェースおよびクラスのサポート範囲を次の表に示します。インタフェースおよびクラスについては，JAX-RS APIのドキュメントを参照してください。

表24‒2　JAX-RS 1.1仕様のインタフェースおよびクラスのサポート範囲

項番

インタフェースまたはクラス

コンストラクタ／メソッド／フィールド

サポート

javax.ws.rsパッケージ

1

WebApplicationException

すべてのメソッド

○

2

ApplicationPath

−

×

3

Consumes

−

○

4

CookieParam

−

○

5

DefaultValue

−

○

6

DELETE

−

○

7

Encoded

−

○

8

FormParam

−

○

9

GET

−

○

10

HEAD

−

○

11

HeaderParam

−

○

12

HttpMethod

−

×

13

MatrixParam

−

○

14

OPTIONS

−

○

15

Path

−

○

16

PathParam

−

○

17

POST

−

○

18

Produces

−

○

19

PUT

−

○

20

QueryParam

−

○

javax.ws.rs.coreパッケージ

21

HttpHeaders

getAcceptableMediaTypes()

○

22

getCookies()

○

23

getLanguages()

○

24

getRequestHeader(String name)

○

25

上記以外のメソッド

○

26

MultivaluedMap<K,V>

すべてのメソッド

○

27

PathSegment

getPath()

○

28

上記以外のメソッド

○

29

Request

evaluatePreconditions(java.util.Date lastModified)

○

30

evaluatePreconditions(EntityTag eTag)

○

31

evaluatePreconditions(java.util.Date lastModified, EntityTag eTag)

○

32

getMethod()

○

33

selectVariant(java.util.List<Variant> variants)

○

34

上記以外のメソッド

○

35

Response.StatusType

すべてのメソッド

○

36

SecurityContext

isUserInRole(String role)

○

37

上記以外のメソッド

○

38

StreamingOutput

すべてのメソッド

○

39

UriInfo

getMatchedResources()

×

40

getMatchedURIs()

×

41

getMatchedURIs(boolean decode)

×

42

getPath()

○

43

getPath(boolean decode)

○

44

getPathParameters()

○

45

getPathParameters(boolean decode)

○

46

getPathSegments()

○

47

getPathSegments(boolean decode)

○

48

getQueryParameters()

○

49

getQueryParameters(boolean decode)

○

50

getRequestUri()

○

51

getRequestUriBuilder()

○

52

上記以外のメソッド

○

53

Application

すべてのメソッド

×

54

CacheControl

すべてのメソッド

○

55

Cookie

valueOf(String value)

○

56

上記以外のメソッド

○

57

EntityTag

Entity(String value)

○

58

valueOf(String value)

○

59

上記以外のメソッド

○

60

GenericEntity<T>

すべてのメソッド

○

61

MediaType

MediaType(String type, String subtype, java.util.Map<String,String> parameters)

○

62

equals(Object obj)

○

63

getParameters()

○

64

isCompatible(MediaType other)

○

65

valueOf(String type)

○

66

上記以外のメソッド

○

67

NewCookie

valueOf(String value)

○

68

上記以外のメソッド

○

69

Response

created(URI location)

○

70

fromResponse(Response response)

○

71

notModified(EntityTag tag)

○

72

notModified(String tag)

○

73

ok(Object entity, String type)

○

74

seeOther(URI location)

○

75

status(int status)

○

76

temporaryRedirect(URI location)

○

77

上記以外のメソッド

○

78

Response.ResponseBuilder

build()

○

79

status(int status)

○

80

上記以外のメソッド

○

81

UriBuilder

build(Object... values)

○

82

clone()

○

83

fragment(String fragment)

○

84

fromPath(String path)

○

85

fromUri(String uri)

○

86

fromUri(java.net.URI uri)

○

87

host(String host)

○

88

newInstance()

○

89

path(String path)

○

90

port(int port)

○

91

queryParam(String name, Object... values)

○

92

replacePath(String path)

○

93

replaceQuery(String query)

○

94

replaceQueryParam(String name, Object... values)

○

95

scheme(String scheme)

○

96

schemeSpecificPart(String ssp)

○

97

segment(String... segments)

○

98

uri(java.net.URI uri)

○

99

userInfo(String ui)

○

100

上記以外のメソッド

×

101

Variant

すべてのメソッド

○

102

Variant.VariantListBuilder

すべてのメソッド

×

103

Response.Status

すべてのメソッド

○

104

Response.Status.Family

すべてのメソッド

○

105

UriBuilderException

すべてのメソッド

○

106

Context

−

○

javax.ws.rs.ext パッケージ

107

ContextResolver<T>

すべてのメソッド

×

108

ExceptionMapper<E extends Throwable>

すべてのメソッド

○

109

MessageBodyReader<T>

すべてのメソッド

×

110

MessageBodyWriter<T>

すべてのメソッド

×

111

Providers

すべてのメソッド

○

112

RuntimeDelegate.HeaderDelegate<T>

すべてのメソッド

○※

113

RuntimeDelegate

すべてのメソッド

○※

114

Provider

−

○

（凡例）

○：Application ServerのJAX-RS機能でサポートしています。

×：Application ServerのJAX-RS機能でサポートしていません。

−：該当するメソッドおよびフィールドはありません。

注※

ユーザが直接使用することはありません。

24.2.1　HttpHeadersインタフェース

HttpHeadersインタフェースのメソッドを使用する場合の注意事項を次に示します。

getCookies()メソッドの戻り値に，Cookieのバージョン情報（例："cookieName=$Version=0;cookieName=cookieValue"）も含まれます。

受信したHTTPメッセージの"Content-Language"ヘッダに，ISO 639で規定された言語コード以外を指定すると，getLanguages()メソッドの動作は保証されません。

getRequestHeader(String name)メソッドを使用する場合，Httpリクエストに存在しないヘッダの値を取得しようとすると，nullが返却されます。

24.2.2　PathSegmentインタフェース

PathSegmentインタフェースのメソッドを使用する場合の注意事項を次に示します。

getPath()メソッドを使用するとき，対象パスにある文字コード（例："%20"など）は，デコードされて返されます。

24.2.3　Requestインタフェース

Requestインタフェースのメソッドを使用する場合の注意事項を次に示します。

次に示すメソッドの引数にはnullを指定しないでください。nullを指定したときの動作は保証されません。

evaluatePreconditions(java.util.Date lastModified)

evaluatePreconditions(EntityTag eTag)

evaluatePreconditions(java.util.Date lastModified, EntityTag eTag)

次に示すメソッドの引数EntityTag eTagにweakのEntityTagを指定しないでください。weakのEntityTagを指定すると，戻り値のResponseBuilderインスタンスのHTTP Statusは"412"（Precondition Failed）になります。

evaluatePreconditions(EntityTag eTag)

evaluatePreconditions(java.util.Date lastModified, EntityTag eTag)

If-None-Matchヘッダが設定されて，かつマッチするリソースがないときは，If-Modified-Sinceヘッダが設定されても無視されます。

リクエストのスコープ外からgetMethod()メソッドを呼び出さないでください。getMethod()メソッドが呼び出された場合の動作は保証されません。

引数が異なる四つのevaluatePreconditions()メソッドのどれかを呼び出す前にselectVariant(java.util.List<Variant> variants)メソッドを呼び出していても，JAX-RS 1.1標準仕様のAPIドキュメントの記載と異なり，Response.ResponseBuilderオブジェクトにはvary HTTPヘッダは含まれません。

24.2.4　SecurityContextインタフェース

SecurityContextインタフェースのメソッドを使用する場合の注意事項を次に示します。

isUserInRole(String role)メソッドの引数にはnullを指定しないでください。nullを指定したときの動作は保証されません。

24.2.5　UriInfoインタフェース

UriInfoインタフェースのメソッドを使用する場合の注意事項を次に示します。

getAbsolutePath()メソッドは，JAX-RS 1.1標準仕様のAPIドキュメントの記載と異なり，UriInfo#getBase().resolve(uriInfo.getPath())のショートカットではなく，UriInfo#getBaseUri().resolve(uriInfo.getPath())のショートカットです。getBase()というメソッドは存在しません。

次に示すメソッドを使用したときの動作は保証されません。

getMatchedResources()

getMatchedURIs()

getMatchedURIs(boolean decode)

getPath()メソッドおよびgetPath(boolean decode)メソッドの戻り値に，マトリクスパラメタ情報は含まれますが，クエリパラメタ情報は含まれません。

getPathParameters()メソッドおよびgetPathParameters(boolean decode)メソッドで取得したMultivaluedMap<String,String>は，JAX-RS 1.1標準仕様のAPIドキュメントの記載と異なり，変更できます。

getPathSegments()メソッドおよびgetPathSegments(boolean decode)メソッドで取得したjava.util.List<PathSegment>は，JAX-RS 1.1標準仕様のAPIドキュメントの記載と異なり，変更できます。

getQueryParameters()メソッドおよびgetQueryParameters(boolean decode)メソッドで取得したMultivaluedMap<String,String>は，JAX-RS 1.1標準仕様のAPIドキュメントの記載と異なり，変更できます。

24.2.6　Cookieクラス

Cookieクラスのメソッドを使用する場合の注意事項を次に示します。

次に示すようにvalueOf(String value)メソッドの引数を指定してください。次に示す以外の記述形式で引数を指定したとき，動作は保証されません。

Cookie.valueOf("$Version=xxxx;name=xxxx;$Path=xxxx;$Domain=xxxx;");※

Cookie.valueOf("name=xxxx;$Domain=xxxx;$Path=xxxx");※

Cookie.valueOf("$Version=xxxx;name=xxxx;");※

Cookie.valueOf("name=xxxx");※

注※

"xxxx"の部分に，プロパティの値を入れます。

24.2.7　EntityTagクラス

EntityTagクラスのメソッドを使用する場合の注意事項を次に示します。

EntityTag(String value)コンストラクタでは，weakのEntityTagインスタンスを生成できません。EntityTag(String value)コンストラクタの引数に，"W/"tagValue""のような文字列を指定しないでください。

valueOf(String value)メソッドを使用するときは，指定したいタグを引用符で囲んで，メソッド引数に指定してください。引用符がないときの動作は保証されません。指定例を次に示します。

String value = "¥"entityTag¥"";

EntityTag entityTag = EntityTag.valueOf(value);

valueOf(String value)メソッドを使用してweakのEntityTagインスタンスを生成するときは，指定したいタグの前に大文字の"W"を追加して引数に指定してください。指定例を次に示します。

String value = "W/¥"weakEntityTag¥"";

EntityTag entityTag = EntityTag.valueOf(value);

24.2.8　MediaTypeクラス

MediaTypeクラスのメソッドを使用する場合の注意事項を次に示します。

標準仕様に従った値を使用してください。それ以外の値を指定したときの動作は保証されません。

MediaType(String type,String subtype, java.util.Map<String,String> parameters)コンストラクタのparameters引数に指定するマップには，同一のキー（大文字と小文字が異なるだけの文字列も含む）を複数登録しないでください。同一のキーを複数登録したときの動作は保証されません。

equals(Object obj)メソッドを使用するとき，比較対象となるMediaTypeオブジェクトの属性である"type"，"subtype"および"parameters"のキーは，大文字と小文字を区別しません。"parameters"の値については大文字と小文字を区別します。

isCompatible(MediaType other)メソッドを使用するとき，引数のMediaTypeオブジェクトの属性である"type"および"subtype"は，大文字と小文字を区別しません。

valueOf(String type)メソッドの引数には，次の文字は使用しないでください。使用した場合の動作は保証されません。

:　(　)　<　>　@　,　;　:　/　"　[　]　?　=　{　}

スペース，ラインフィード，キャリッジリターン，水平タブ

24.2.9　NewCookieクラス

NewCookieクラスのメソッドを使用する場合の注意事項を次に示します。

次に示すようにvalueOf(String value)メソッドの引数を指定してください。次に示す以外の記述形式で引数を指定したとき，動作は保証されません。

NewCookie.valueOf("name=xxxx;Version=xxxx;Comment=xxxx;Domain=xxxx;Path=xxxx;Max-Age=xxxx;Secure");※

NewCookie.valueOf("name=xxxx;Path=xxxx;Domain=xxxx;Comment=xxxx;Max-Age=xxxx;Secure");※

NewCookie.valueOf("name=xxxx;Comment=xxxx;Max-Age=xxxx;Secure");※

NewCookie.valueOf("name=xxxx;Path=xxxx;Domain=xxxx;Version=xxxx;");※

NewCookie.valueOf("name=xxxx;Path=xxxx;Domain=xxxx;"); ※

NewCookie.valueOf("name=xxxx;"); ※

注※

"xxxx"の部分に，プロパティの値を入れます。

24.2.10　Responseクラス

Responseクラスのメソッドを使用する場合の注意事項を次に示します。

fromResponse(Response response)メソッドの引数にはnullを指定しないでください。nullを指定したときの動作は保証されません。

次に示すのメソッドの引数にはnullを指定しないでください。nullを指定したときは，JAX-RS 1.1標準仕様のAPIドキュメントの記載と異なり，IllegalArgumentExceptionは発生しません。

created(URI location)

notModified(EntityTag tag)

notModified(String tag)

seeOther(URI location)

temporaryRedirect(URI location)

ok(Object entity, String type)の引数typeには，標準仕様に従った値を指定してください。それ以外の値を指定したときの動作は保証されません。

status(int status)メソッドの引数に，100未満または599を超える数値を指定しないでください。指定したときは，JAX-RS 1.1標準仕様のAPIドキュメントの記載と異なり，IllegalArgumentExceptionは発生しません。

24.2.11　Response.ResponsBuilderクラス

Response.ResponseBuilderクラスのメソッドを使用する場合の注意事項を次に示します。

build()メソッドを呼び出したあと，ResponseBuilderインスタンスは，JAX-RS 1.1標準仕様のAPIドキュメントの記載と異なり，okのステータスではなくno contentのステータスにリセットされます。

status(int status)メソッドの引数に，100未満または599を超える数値を指定しないでください。指定したときは，JAX-RS 1.1標準仕様のAPIドキュメントの記載と異なり，IllegalArgumentExceptionは発生しません。

24.2.12　UriBuilderクラス

UriBuilderクラスのメソッドを使用する場合の注意事項を次に示します。

なお，説明中の「UriBuilderオブジェクトのURI」とは，それぞれのメソッドを呼び出すときに，それまでのほかのメソッドの呼び出しですでにUriBuilderオブジェクトに構築されているURIのことを指します。

UriBuilderクラスのメソッドを使用する場合は，JAX-RS APIのドキュメントやRFC 2396，2732を参照の上，各メソッドの引数に使用できる文字および形式を使用してください。引数の文字や形式が不正な場合，そのメソッドを呼び出したり，build(Object... values)メソッドを呼び出したりしたときに例外がスローされることがあります。なお，次のメソッドでは，不正な文字は自動的にパーセントエンコードされます（すでにパーセントエンコードされている場合はそれ以上パーセントエンコードされません）。

fragment(java.lang.String fragment)

host(String host)

path(String path)

queryParam(java.lang.String name, java.lang.Object... values)

replacePath(String path)

replaceQuery(java.lang.String query)

replaceQueryParam(java.lang.String name, java.lang.Object... values)

segment(String... segments)

userInfo(String ui)

不透明なURIはサポートされません。階層的なURIに対してだけ使用してください。

テンプレートパラメタの使用はサポートされません。メソッドの引数にテンプレートパラメタが含まれる場合，動作は保証されません。

build(Object... values)メソッドには引数を指定しないでください。引数が指定されて呼び出された場合，動作は保証されません。

クエリパラメタの順序は保持されません。

port(int port)メソッドを使用する場合，65535を超える数値を指定しても，例外にはなりません。-1より小さい数値を指定すると，IllegalArgumentExceptionがスローされます。

replaceQuery(String query)メソッドを使用する場合，UriBuilderオブジェクトのURIに置き換える対象が存在しないときの動作は保証されません。

replaceQueryParam(String name, Object... values)メソッドの引数に，UriBuilderオブジェクトのURIに存在しないクエリパラメタを指定した場合，指定されたパラメタがURIに追加されます。

replaceQueryParam(String name, Object... values)メソッドのvalues引数にnullを指定した場合，JAX-RS 1.1標準仕様のAPIドキュメントの記載と異なり，既存のクエリパラメタは取り除かれず，IllegalArgumentExceptionがスローされます。

replacePath(String path)メソッドの引数にnullを指定した場合，JAX-RS 1.1標準仕様のAPIドキュメントの記載と異なり，既存のパスは取り除かれず，IllegalArgumentExceptionがスローされます。

24.2.13　Providerアノテーション

Providerアノテーションを使用する場合の注意事項を次に示します。

ExceptionMapperインタフェースを実装したクラスだけに使用できます。

24.3　アノテーション

ここでは，Application ServerがサポートするJAX-RS 1.1仕様のアノテーションについて説明します。

24.3.1　インジェクション用アノテーション

ここでは，JAX-RSエンジンがサポートするインジェクション用アノテーションについて説明します。

(1)　注意事項

(a)　複数のアノテーションを使用する場合

インジェクション用アノテーションは，パラメタ，フィールド，またはbeanプロパティそれぞれにつき一つだけ使用できます。一つのパラメタ，フィールド，またはbeanプロパティにつき複数のアノテーションを同時に指定した場合は，最も右のアノテーションだけが有効になります。最も右のアノテーションがJAX-RS 1.1仕様でない場合は，ほかのすべてのアノテーションが無視されてインジェクションは実行されません。

(b)　beanプロパティに使用する場合

インジェクション用アノテーションをbeanプロパティに使用する場合は，setterメソッドに対してメソッドレベルでアノテートしてください。

(c)　フィールドに使用する場合

ルートリソースクラスおよび例外マッピングプロバイダでは，コンストラクタおよびbeanプロパティのsetterメソッドから，インジェクション用アノテーションでアノテートされたフィールドを参照または変更しないでください。

コンストラクタ，フィールド，およびbeanプロパティへのインジェクションは，ルートリソースクラスおよび例外マッピングプロバイダがJAX-RSエンジンによってインスタンス化されるときに同時に行われます。このため，コンストラクタおよびbeanプロパティのsetterメソッドから，インジェクション用アノテーションでアノテートされたフィールドを参照した場合，取得される値は不定です。また，インジェクション用アノテーションでアノテートされたフィールドを変更した場合，フィールドへのインジェクションが失敗するか，または成功しても値が不定になります。

(2)　javax.ws.rs.HeaderParamアノテーション

javax.ws.rs.HeaderParamアノテーションはHTTPヘッダの値を取得するために使用します。アノテーションの値には，HTTPリクエストに含まれるHTTPヘッダの名称を指定します。

javax.ws.rs.HeaderParamアノテーションを指定できる対象を，次の表に示します。

表24‒3　 javax.ws.rs.HeaderParamアノテーションを指定できる対象

Webリソースまたはプロバイダ

コンストラクタのパラメタ

フィールド

beanプロパティ

メソッドのパラメタ

ルートリソースクラス

○

○

○

○

サブリソースクラス

×

×

×

○

例外マッピングプロバイダ

×

×

×

−

（凡例）

○：指定できることを示します。

×：指定できないことを示します。

−：該当するパラメタがないことを示します。

Webリソースまたはプロバイダについては，「17.　Webリソースとプロバイダ」の各項目を参照してください。

(3)　javax.ws.rs.CookieParamアノテーション

javax.ws.rs.CookieParamアノテーションはHTTP Cookieの値を取得するために使用します。アノテーションの値は，HTTPリクエストに含まれるCookieの名称を指定します。

javax.ws.rs.CookieParamアノテーションを指定できる対象を，次の表に示します。

表24‒4　 javax.ws.rs.CookieParamアノテーションを指定できる対象

Webリソースまたはプロバイダ

コンストラクタのパラメタ

フィールド

beanプロパティ

メソッドのパラメタ

アプリケーションサブクラス

×

×

×

−

ルートリソースクラス

○

○

○

○

サブリソースクラス

×

×

×

○

エンティティプロバイダ

×

×

×

−

コンテキストプロバイダ

×

×

×

−

例外マッピングプロバイダ

×

×

×

−

（凡例）

○：指定できることを示します。

×：指定できないことを示します。

−：該当するパラメタがないことを示します。

Webリソースまたはプロバイダについては，「17.　Webリソースとプロバイダ」の各項目を参照してください。

(4)　javax.ws.rs.MatrixParamアノテーション

javax.ws.rs.MatrixParamアノテーションはURIマトリクスパラメタの値を取得するために使用します。アノテーションの値は，HTTPリクエストに含まれるマトリクスパラメタの名称を指定します。

javax.ws.rs.MatrixParamアノテーションを指定できる対象を，次の表に示します。

表24‒5　 javax.ws.rs.Matrix parameterアノテーションを指定できる対象

Webリソースまたはプロバイダ

コンストラクタのパラメタ

フィールド

beanプロパティ

メソッドのパラメタ

アプリケーションサブクラス

×

×

×

−

ルートリソースクラス

○

○

○

○

サブリソースクラス

×

×

×

○

エンティティプロバイダ

×

×

×

−

コンテキストプロバイダ

×

×

×

−

例外マッピングプロバイダ

×

×

×

−

（凡例）

○：指定できることを示します。

×：指定できないことを示します。

−：該当するパラメタがないことを示します。

Webリソースまたはプロバイダについては，「17.　Webリソースとプロバイダ」の各項目を参照してください。

(5)　javax.ws.rs.QueryParamアノテーション

javax.ws.rs.QueryParamアノテーションはURIクエリパラメタの値を取得するために使用します。アノテーションの値は，HTTPリクエストに含まれるクエリパラメタの名称を指定します。

javax.ws.rs.QueryParamアノテーションを指定できる対象を，次の表に示します。

表24‒6　 javax.ws.rs.QueryParamを指定できる対象

Webリソースまたはプロバイダ

コンストラクタのパラメタ

フィールド

beanプロパティ

メソッドのパラメタ

アプリケーションサブクラス

×

×

×

−

ルートリソースクラス

○

○

○

○

サブリソースクラス

×

×

×

○

エンティティプロバイダ

×

×

×

−

コンテキストプロバイダ

×

×

×

−

例外マッピングプロバイダ

×

×

×

−

（凡例）

○：指定できることを示します。

×：指定できないことを示します。

−：該当するパラメタがないことを示します。

Webリソースまたはプロバイダについては，「17.　Webリソースとプロバイダ」の各項目を参照してください。

(6)　javax.ws.rs.PathParamアノテーション

javax.ws.rs.PathParamアノテーションはURIのパスの値を取得するために使用します。アノテーションの値には，テンプレートパラメタを指定します。

javax.ws.rs.PathParamアノテーションを指定できる対象を，次の表に示します。

表24‒7　 javax.ws.rs.PathParamアノテーションを指定できる対象

Webリソースまたはプロバイダ

コンストラクタのパラメタ

フィールド

beanプロパティ

メソッドのパラメタ

アプリケーションサブクラス

×

×

×

−

ルートリソースクラス

○

○

○

○

サブリソースクラス

×

×

×

○

エンティティプロバイダ

×

×

×

−

コンテキストプロバイダ

×

×

×

−

例外マッピングプロバイダ

×

×

×

−

（凡例）

○：指定できることを示します。

×：指定できないことを示します。

−：該当するパラメタがないことを示します。

Webリソースまたはプロバイダについては，「17.　Webリソースとプロバイダ」の各項目を参照してください。

(7)　javax.ws.rs.FormParamアノテーション

javax.ws.rs.FormParamアノテーションは，HTTPリクエストのエンティティボディに含まれるフォームパラメタの値を取得するために使用します。アノテーションの値はフォームパラメタの名称を指定します。

javax.ws.rs.FormParamアノテーションを指定できる対象を，次の表に示します。

表24‒8　 javax.ws.rs.FormParamアノテーションを指定できる対象

Webリソースまたはプロバイダ

コンストラクタのパラメタ

フィールド

beanプロパティ

メソッドのパラメタ

ルートリソースクラス

○

○

○

○

サブリソースクラス

×

×

×

○

例外マッピングプロバイダ

×

×

×

−

（凡例）

○：指定できることを示します。

×：指定できないことを示します。

−：該当するパラメタがないことを示します。

Webリソースまたはプロバイダについては，「17.　Webリソースとプロバイダ」の各項目を参照してください。

エンティティボディに含まれるフォームパラメタ数の上限値は，デフォルトでは10,000です。リクエストのパラメタ数が指定した値を超えた場合，エラーとなり（KDJJ10042-E），HTTPステータスコードに413を設定した，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。必要に応じてJ2EEサーバ用ユーザプロパティファイル（usrconf.properties）のwebserver.connector.limit.max_parameter_countプロパティで変更してください。J2EEサーバ用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバリファレンス 定義編(サーバ定義)」の「2.2.3　usrconf.properties（J2EEサーバ用ユーザプロパティファイル）」を参照してください。

(8)　javax.ws.rs.core.Contextアノテーション

javax.ws.rs.Contextアノテーションはコンテキストの値をインジェクトするために使用します。javax.ws.rs.Contextアノテーションを指定できる対象を，次の表に示します。

表24‒9　 javax.ws.rs.Contextアノテーションを指定できる対象（1）

Webリソースまたはプロバイダ

Context Application型

Context UriInfo型

Context HttpHeaders型

Context Request型

Context SecurityContext型

Context Providers型

ルートリソースクラス

コンストラクタのパラメタ

×

○

○

○

○

○

フィールド

×

○

○

○

○

○

beanプロパティ

×

○

○

○

○

○

メソッドのパラメタ

×

○

○

○

○

○

サブリソースクラス

コンストラクタのパラメタ

×

×

×

×

×

×

フィールド

×

×

×

×

×

×

beanプロパティ

×

×

×

×

×

×

メソッドのパラメタ

×

○

○

○

○

○

例外マッピングプロバイダ

コンストラクタのパラメタ

×

×

×

×

×

○

フィールド

×

○

○

○

○

○

beanプロパティ

×

○

○

○

○

○

（凡例）

○：指定できることを示します。

×：指定できないことを示します。

表24‒10　 javax.ws.rs.Contextアノテーションを指定できる対象（2）

Webリソースまたはプロバイダ

Context HttpServletRequest型

HttpServletResponse型

ServletContext型

ServletConfig型

ルートリソースクラス

コンストラクタのパラメタ

○※

○

○

○

フィールド

○※

○

○

○

beanプロパティ

○※

○

○

○

メソッドのパラメタ

○※

○

○

○

サブリソースクラス

コンストラクタのパラメタ

×

×

×

×

フィールド

×

×

×

×

beanプロパティ

×

×

×

×

メソッドのパラメタ

○※

○

○

○

例外マッピングプロバイダ

コンストラクタのパラメタ

○※

○

○

○

フィールド

○※

○

○

○

beanプロパティ

○※

○

○

○

（凡例）

○：指定できることを示します。

×：指定できないことを示します。

注※

エンティティボディおよびクエリパラメタは取得できません。エンティティパラメタを持つリソースメソッドで，ContextアノテーションでインジェクトされたHttpServletRequestインスタンスのgetReader()メソッドを呼び出した場合，例外マッピングプロバイダで処理できるjava.lang.IllegalStateExceptionがスローされます。

(9)　javax.ws.rs.DefaultValueアノテーション

javax.ws.rs.DefaultValueアノテーションは，次に示すアノテーションと組み合わせて使用できます。javax.ws.rs.DefaultValueアノテーションを使用すると，それぞれのアノテーションでアノテートされたパラメタにインジェクトする値が，HTTPリクエストにない場合のデフォルト値を指定できます。

MatrixParamアノテーション

QueryParamアノテーション

CookieParamアノテーション

HeaderParamアノテーション

FormParamアノテーション

例えば，インスタンスに対してクエリもしくはマトリクスパラメタがURIの要求に存在しないとき，または対象のフォームパラメタが要求のエンティティボディに存在しないときは，DefaultValueアノテーションに指定されている初期値が使用されます。

(10)　javax.ws.rs.Encodedアノテーション

javax.ws.rs.Encodedアノテーションは，URLエンコードされた値が自動でURLデコードされるのを無効化するために使用します。URLエンコードされた値が自動でURLデコードされるのは，次に示すインジェクション用アノテーションでアノテートされたパラメタ，フィールド，およびbeanプロパティです。

javax.ws.rs.MatrixParamアノテーション

javax.ws.rs.QueryParamアノテーション

javax.ws.rs.PathParamアノテーション

javax.ws.rs.Encodedアノテーションは，次に示す場所で使用できます。

ルートリソースクラス（クラスレベル）

サブリソースクラス（クラスレベル）

ルートリソースクラスのコンストラクタ（コンストラクタレベル）

ルートリソースクラスのコンストラクタのパラメタ（パラメタレベル）

リソースクラスのリソースメソッド，サブリソースメソッド，およびサブリソースロケータ（メソッドレベル）

リソースクラスのリソースメソッド，サブリソースメソッド，およびサブリソースロケータのそれぞれのパラメタ（パラメタレベル）

ルートリソースクラスのフィールド，およびbeanプロパティ（フィールドレベル，プロパティレベル）

パラメタレベル，フィールドレベル，プロパティレベルでは，前述のインジェクション用アノテーション（javax.ws.rs.MatrixParam，javax.ws.rs.QueryParam，javax.ws.rs.PathParam）と組み合わせて使用してください。

クラスレベルでjavax.ws.rs.Encodedアノテーションを使用した場合は，そのクラスのすべてのパラメタ，フィールド，およびbeanプロパティで，URLエンコードされた値が自動でURLデコードされるのを無効化できます。

コンストラクタレベルでjavax.ws.rs.Encodedアノテーションを使用した場合は，そのコンストラクタのすべてのパラメタで，URLエンコードされた値が自動でURLデコードされるのを無効化できます。

メソッドレベルでjavax.ws.rs.Encodedアノテーションを使用した場合は，そのリソースメソッド，サブリソースメソッド，またはサブリソースロケータのすべてのパラメタで，URLエンコードされた値が自動でURLデコードされるのを無効化できます。

24.3.2　ビルトイン要求メソッド識別子

ここでは，JAX-RSエンジンがサポートする要求メソッド識別子について説明します。

(1)　javax.ws.rs.DELETEアノテーション

javax.ws.rs.DELETEアノテーションは，アノテートされたメソッドがHTTP DELETEリクエストを処理することを指定します。javax.ws.rs.DELETEアノテーションが使用できる対象を次に示します。

ルートリソースクラスのpublicメソッド

サブリソースクラスのpublicメソッド

(2)　javax.ws.rs.GETアノテーション

javax.ws.rs.GETアノテーションは，アノテートされたメソッドがHTTP GETリクエストを処理することを示します。javax.ws.rs.GETアノテーションが使用できる対象を次に示します。

ルートリソースクラスのpublicメソッド

サブリソースクラスのpublicメソッド

(3)　javax.ws.rs.HEADアノテーション

javax.ws.rs.HEADアノテーションは，アノテートされたメソッドがHTTP HEADリクエストを処理することを示します。javax.ws.rs.HEADアノテーションが使用できる対象を次に示します。

ルートリソースクラスのpublicメソッド

サブリソースクラスのpublicメソッド

HTTP HEADリクエストを受けた場合，JAX-RSエンジンは次の優先順位で動作します。

HEADアノテーションでアノテートされたメソッドがあれば呼び出す。

HEADアノテーションでアノテートされたメソッドがなければ，GETアノテーションでアノテートされたメソッドを呼び出す。なお，そのメソッドが戻り値を返す場合は無視される。

HTTP HEADリクエストを処理するルートリソースクラスの例を次に示します。

package com.sample.resources;

import javax.ws.rs.HEAD;
import javax.ws.rs.Path;
import javax.ws.rs.core.Response;

//ルートリソースクラス
@Path("/root")
public class Resource {

  //リソースメソッド
  @HEAD
  public Response getValue() {

    String customHeader = "foo";
    String customHeaderValue = "bar";
    int httpStatus = 200;

    //ResponseBuilderを使用してResponseオブジェクトを構築する

    return Response.status(httpStatus).header(customHeader,
        customHeaderValue).build();
  }
}

ルートリソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。この例では，URL"http://sample.com/example/root"に対するHTTP HEADリクエストは，getValue()メソッドにディスパッチされます。getValue()メソッドが返すResponseオブジェクトがエンティティボディを含んでいても無視されます。

(4)　javax.ws.rs.OPTIONSアノテーション

javax.ws.rs.OPTIONSアノテーションは，アノテートされたメソッドがHTTP OPTIONSリクエストを処理することを示します。javax.ws.rs.OPTIONSアノテーションが使用できる対象を次に示します。

ルートリソースクラスのpublicメソッド

サブリソースクラスのpublicメソッド

HTTP OPTIONSリクエストのためのJAX-RSエンジンの動作を次に示します。

javax.ws.rs.OPTIONSアノテーションでアノテートされたメソッドを呼び出す。

javax.ws.rs.OPTIONSアノテーションでアノテートされたメソッドがなければ，Webリソースのアノテーションの情報を使用して，JAX-RSエンジンが自動的に応答する。

HTTP OPTIONSリクエストを処理するルートリソースクラスの例を次に示します。

package com.sample.resources;

import javax.ws.rs.OPTIONS;
import javax.ws.rs.Path;
import javax.ws.rs.core.Response;

//ルートリソースクラス
@Path("/root")
public class Resource {

  //リソースメソッド
  @OPTIONS
  public Response getValue() {
    String entity = "Some Contents";
    String customHeader = "foo";
    String customHeaderValue = "bar";
    int httpStatus = 200;

    //ResponseBuilderを使用してResponseオブジェクトを構築する

    return Response.status(httpStatus).header(customHeader,
        customHeaderValue).entity(entity).build();

  }
}

ルートリソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。この例では，URL"http://sample.com/example/root"に対するHTTP OPTIONSリクエストは，getValue()メソッドにディスパッチされます。

(5)　javax.ws.rs.POSTアノテーション

javax.ws.rs.POSTアノテーションは，アノテートされたメソッドがHTTP POSTリクエストを処理することを示します。javax.ws.rs.POSTアノテーションが使用できる対象を次に示します。

ルートリソースクラスのpublicメソッド

サブリソースクラスのpublicメソッド

(6)　javax.ws.rs.PUTアノテーション

javax.ws.rs.PUTアノテーションは，アノテートされたメソッドがHTTP PUTリクエストを処理することを示します。javax.ws.rs.PUTアノテーションが使用できる対象を次に示します。

ルートリソースクラスのpublicメソッド

サブリソースクラスのpublicメソッド

24.3.3　パス指定用アノテーション

ここでは，JAX-RSエンジンがサポートするパス指定用のアノテーションについて説明します。

(1)　javax.ws.rs.Pathアノテーション

javax.ws.rs.Pathアノテーションは，リソースのパスを指定します。クラスレベルで使用される場合，アノテートされたクラスはルートリソースクラスと見なされます。メソッドレベルで使用される場合，アノテートされたメソッドはサブリソースメソッドまたはサブリソースロケータと見なされます。javax.ws.rs.Pathアノテーションは次に示す場所で使用できます。

ルートリソースクラス（クラスレベル）

リソースクラス（ルートリソースクラスまたはサブリソースクラス）の要求メソッド識別子でアノテートされたpublicメソッド（メソッドレベル）：このメソッドはサブリソースメソッドです。

リソースクラス（ルートリソースクラスまたはサブリソースクラス）の要求メソッド識別子でアノテートされていないpublicメソッド（メソッドレベル）：このメソッドはサブリソースロケータです。

24.3.4　メディアタイプ宣言用アノテーション

ここでは，JAX-RSエンジンがサポートするメディアタイプ宣言用アノテーションについて説明します。

(1)　javax.ws.rs.Consumesアノテーション

javax.ws.rs.Consumesアノテーションは，WebリソースがHTTPリクエストでサポートするMIMEメディアタイプのリストを指定します。javax.ws.rs.Consumesアノテーションが使用できる対象を次に示します。

ルートリソースクラス（クラスレベル）

リソースメソッド（メソッドレベル）

サブリソースメソッド（メソッドレベル）

サブリソースクラス（クラスレベル）

javax.ws.rs.Consumesアノテーションが例外マッピングプロバイダに使用されている場合，無視されます。

(2)　javax.ws.rs.Producesアノテーション

javax.ws.rs.Producesアノテーションは，WebリソースがHTTPレスポンスでサポートするMIMEメディアタイプのリストを指定します。javax.ws.rs.Producesアノテーションが使用できる対象を次に示します。

ルートリソースクラス（クラスレベル）

リソースメソッド（メソッドレベル）

サブリソースメソッド（メソッドレベル）

サブリソースクラス（クラスレベル）

javax.ws.rs.Producesアノテーションが例外マッピングプロバイダに使用されている場合，無視されます。

24.4　コンテキスト

ルートリソースクラス，サブリソースクラス，および例外マッピングプロバイダでは，Contextアノテーションを使用してJAX-RS 1.1仕様で定義されるコンテキストを取得できます。JAX-RSエンジンでサポートしているコンテキストの種類は次のとおりです。

javax.ws.rs.core.UriInfo

javax.ws.rs.core.HttpHeaders

javax.ws.rs.core.Request

javax.ws.rs.core.SecurityContext

javax.ws.rs.core.ext.Providers

javax.servlet.ServletConfig

javax.servlet.ServletContext

javax.servlet.http.HttpServletRequest

javax.servlet.http.HttpServletResponse

コンテキストに含まれる情報はHTTPリクエストごとに異なりますが，プロバイダのインスタンスはシングルトンであるため，javax.ws.rs.core.ext.Providersに含まれる情報はWARファイルの単位で常に同一です。

ここではJAX-RSエンジンでサポートしているコンテキストの種類について説明します。

24.4.1　javax.ws.rs.core.UriInfo

javax.ws.rs.core.UriInfoは，URIを構成する各コンポーネント（クエリパラメタやマトリクスパラメタなど）を保持するコンテキストです。HTTPリクエストごとの情報を提供します。なお，javax.ws.rs.core.UriInfoの各メソッドで取得できるのは，正規化後の情報です。

ルートリソースクラスのフィールドにインジェクトされるjavax.ws.rs.core.UriInfoコンテキストの使用例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.UriInfo;

//ルートリソースクラス
@Path("/root")
public class Resource {
  //Contextアノテーションを使用してUriInfoをインジェクトするフィールド
  private @Context UriInfo uriInfo;

  //リソースメソッド
  @GET
  public String getValue() {
    String value = this.uriInfo.getQueryParameters().getFirst("query");
    return value;
  }
}

ルートリソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。この例で，URL"http://sample.com/example/root?query=10"に対するHTTP GETリクエストでは，まずuriInfoフィールドにjavax.ws.rs.core.UriInfoコンテキストがインジェクトされ，その後HTTP GETリクエストを処理できるgetValue()メソッドが呼び出されます。このため，getValue()メソッドでuriInfoフィールドからクエリパラメタ"query"を取得すると"10"という値が取得されます。

24.4.2　javax.ws.rs.core.HttpHeaders

javax.ws.rs.core.HttpHeadersは，HTTPリクエストのHTTPヘッダを保持するコンテキストです。

ルートリソースクラスのフィールドにインジェクトされるjavax.ws.rs.core.HttpHeadersの使用例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.HttpHeaders;

//ルートリソースクラス
@Path("/root")
public class Resource {
  //Contextアノテーションを使用してHttpHeadersをインジェクトするフィールド
  private @Context HttpHeaders httpHeaders;

//リソースメソッド
  @GET
  public String getValue () {
    String value = this.httpHeaders.getRequestHeader("Accept").get(0);
    return value;
  }
}

ルートリソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。この例で，Accept HTTPヘッダに"application/xml"を指定したURL"http://sample.com/example/root"に対するHTTP GETリクエストでは，まずhttpHeadersフィールドにjavax.ws.rs.core.HttpHeadersコンテキストがインジェクトされ，その後HTTP GETリクエストを処理できるgetValue()メソッドが呼び出されます。このため，getValue()メソッドでhttpHeadersフィールドからAccept HTTPヘッダの値を取得すると"application/xml"という値が取得されます。

24.4.3　javax.ws.rs.core.Request

javax.ws.rs.core.Requestは，RFC 2616で規定される「コンテントネゴシエーション（Content Negotiation）」に必要な機能を提供するコンテキストです。

ルートリソースクラスのフィールドにインジェクトされるjavax.ws.rs.core.Requestの使用例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.EntityTag;
import javax.ws.rs.core.Request;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.ResponseBuilder;
//ルートリソースクラス
@Path("/root")
public class Resource {
  //Contextアノテーションを使用してRequestをインジェクトするフィールド
  private @Context Request request;
  //コンテントネゴシエーションで利用するHTTP Entity Tag
  private EntityTag eTag = new EntityTag("a-resource-status-specific-tag");
  //リソースメソッド
  @GET
  public Response getData() {
ResponseBuilder rb = null;
    //コンテントネゴシエーション(プレコンディションの評価)を行う
    //  プレコンディションに合えばnull，合わなければ
    //  適切なETag HTTPヘッダやステータスコード(412: Precondition Failed) が
    //  設定されたResponseBuilderオブジェクトが取得される
    rb = request.evaluatePreconditions(this.eTag);
    if (rb != null) {
      //プレコンディションに合わない場合，ResponseBuilderオブジェクトから
      //HTTPレスポンスを生成してそのまま返す
      return rb.build();
    } else {
      //プレコンディションに合う場合，要求のデータを返す
      String data = "Some Information";
      return Response.ok().entity(data).build();
    }
  }
}

ルートリソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。この例で，If-Match HTTPヘッダに"a-resource-status-specific-tag"を指定したURL"http://sample.com/example/root"に対するHTTP GETリクエストでは，まずrequestフィールドにjavax.ws.rs.core.Requestコンテキストがインジェクトされ，その後HTTP GETリクエストを処理できるgetData()メソッドが呼び出されます。このため，getData()メソッドでは，コンテントネゴシエーション（この例ではHTTP リクエストのIf-Match HTTPヘッダとリソースが保持するHTTP EntityTagの比較）が行われ，"Some Information"という値が取得されます。

24.4.4　javax.ws.rs.core.SecurityContext

javax.ws.rs.core.SecurityContextは，処理中のHTTPリクエストに関連するセキュリティ情報を保持するコンテキストです。

ルートリソースクラスのフィールドにインジェクトされるjavax.ws.rs.core.SecurityContextの使用例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.SecurityContext;

//ルートリソースクラス
@Path("/root")
public class Resource {
  //Contextアノテーションを使用してSecurityContextをインジェクトするフィールド
  private @Context SecurityContext securityContext;

  //リソースメソッド
  @GET
  public String getValue () {
    String value = "Authentication Scheme: "
        + this.securityContext.getAuthenticationScheme()
        + ", User Principal: " + this.securityContext.getUserPrincipal()
        + ", Is secure: " + this.securityContext.isSecure()
        + ", Is user in role: " + this.securityContext.isUserInRole("admin");

    return value;
  }
}

セキュリティ情報を含むweb.xmlの例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app ...>
  ...
  <security-constraint>
     <web-resource-collection>
       <web-resource-name>Test Resource</web-resource-name>
       <url-pattern>/*</url-pattern>
       <http-method>GET</http-method>
     </web-resource-collection>
     <auth-constraint>
       <role-name>admin</role-name>
     </auth-constraint>
  </security-constraint>
  <login-config>
     <auth-method>BASIC</auth-method>
     <realm-name>jaxrs_server</realm-name>
  </login-config>
  <security-role>
     <role-name>admin</role-name>
  </security-role>
</web-app>

ルートリソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。この例で，適切な認証情報を指定したURL"http://sample.com/example/root"に対するHTTP GETリクエストでは，まずsecurityContextフィールドにjavax.ws.rs.core.SecurityContextコンテキストがインジェクトされ，その後HTTP GETリクエストを処理できるgetValue()メソッドが呼び出されます。getValue()メソッドでは，web.xmlの設定と実際の認証情報に基づいてセキュリティ情報が取得されます。

24.4.5　javax.ws.rs.core.ext.Providers

javax.ws.rs.core.ext.Providersは，デプロイされたWebリソースで動作するプロバイダを保持するコンテキストです。

ルートリソースクラスのフィールドにインジェクトされるjavax.ws.rs.core.ext.Providersの使用例を次に示します。

package com.sample.resources;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Context;
import javax.ws.rs.ext.Providers;

//ルートリソースクラス
@Path("root")
public class Resource{

  //Contextアノテーションを使用してProvidersをインジェクトするフィールド
  private @Context Providers providers;

  //リソースメソッド
  @GET
  public String getValue() {
    //providersフィールドから例外マッピングプロバイダを取得する
    return this.providers.getExceptionMapper(RuntimeException.class);
  }
}

ルートリソースクラスcom.sample.resources.Resourceとjava.lang.RuntimeExceptionを処理できる例外マッピングプロバイダcom.sample.providers.EntityProviderReaderを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。この例で，URL"http://sample.com/example/root"に対するHTTP GETリクエストでは，まずprovidersフィールドにjavax.ws.rs.core.ext.Providersコンテキストがインジェクトされ，その後HTTP GETリクエストを処理できるgetValue()メソッドが呼び出されます。このため，getValue()メソッドでprovidersフィールドからjava.lang.RuntimeExceptionを処理できる例外マッピングプロバイダを取得するとcom.sample.providers.EntityProviderReaderインスタンスが取得されます。

24.4.6　javax.servlet.ServletConfig

javax.servlet.ServletConfigはServlet仕様で定義されているクラスです。

ルートリソースクラスのフィールドにインジェクトされるjavax.servlet.ServletConfigの使用例を次に示します。

package com.sample.resources;

import javax.servlet.ServletConfig;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Context;

//ルートリソースクラス
@Path("/root")
public class Resource {
  //Contextアノテーションを使用してServletConfigをインジェクトするフィールド
  private @Context ServletConfig config;

  //リソースメソッド
  @GET
  public String getValue() {
    return this.config.getInitParameter("TestParam");
  }
}

追加の初期化パラメタ（init-param要素）を含むweb.xmlの例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app ...>
  <servlet>
    <servlet-name>CosminexusJaxrsServlet</servlet-name>
    <servlet-class>com.cosminexus.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <init-param>
      <param-name>com.cosminexus.jersey.config.property.packages</param-name>
      <param-value>com.sample.resources</param-value>
    </init-param>
    <init-param>
      <param-name>TestParam</param-name>
      <param-value>TestValue</param-value>
    </init-param>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxrsServlet</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

ルートリソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。この例で，URL"http://sample.com/example/root"に対するHTTP GETリクエストでは，まずconfigフィールドにjavax.servlet.ServletConfigコンテキストがインジェクトされ，その後HTTP GETリクエストを処理できるgetValue()メソッドが呼び出されます。このため，getValue()メソッドでconfigフィールドから初期化パラメタ"TestParam"を取得すると"TestValue"という値が取得されます。

24.4.7　javax.servlet.ServletContext

javax.servlet.ServletContextはServlet仕様で定義されているクラスです。

ルートリソースクラスのフィールドにインジェクトされるjavax.servlet.ServletContextの使用例を次に示します。

package com.sample.resources;

import javax.servlet.ServletContext;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Context;

//ルートリソースクラス
@Path("/root")
public class Resource {

  //Contextアノテーションを使用してServletContextをインジェクトするフィールド
  private @Context ServletContext context;

  //リソースメソッド
  @GET
  public String getValue() {
    return this.context.getInitParameter("Hitachi");
  }
}

コンテキストスコープの初期化パラメタ（context-param要素）を含むweb.xmlを次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app ...>
  ...
  <context-param>
    <param-name>TestParam</param-name>
    <param-value>TestValue</param-value>
  </context-param>
</web-app>

ルートリソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。この例で，URL"http://sample.com/example/root"に対するHTTP GETリクエストでは，まずcontextフィールドにjavax.servlet.ServletContextコンテキストがインジェクトされ，その後HTTP GETリクエストを処理できるgetValue()メソッドが呼び出されます。このため，getValue()メソッドでcontextはフィールドからコンテキストスコープの初期化パラメタ"TestParam"を取得すると"TestValue"という値が取得されます。

24.4.8　javax.servlet.http.HttpServletRequest

javax.servlet.http.HttpServletRequestはServlet仕様で定義されているクラスです。

ルートリソースクラスのフィールドにインジェクトされるjavax.servlet.http.HttpServletRequestの使用例を次に示します。

package com.sample.resources;

import javax.servlet.http.HttpServletRequest;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Context;

//ルートリソースクラス
@Path("/root")
public class Resource {

  //Contextアノテーションを使用してHttpServletRequestをインジェクトするフィールド
  private @Context HttpServletRequest httpRequest;

  //リソースメソッド
  @GET
  public String getValue() {
    return this.httpRequest.getParameter("Hitachi");

  }
}

ルートリソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。この例で，URL"http://sample.com/example/root?TestParam=TestValue"に対するHTTP GETリクエストでは，まずHttpRequestフィールドにjavax.servlet.http.HttpServletRequestコンテキストがインジェクトされ，その後HTTP GETリクエストを処理できるgetValue()メソッドが呼び出されます。このため，getValue()メソッドでhttpRequestフィールドからリクエストパラメタ"TestParam"を取得すると，"TestValue"という値が取得されます。

24.4.9　javax.servlet.http.HttpServletResponse

javax.servlet.http.HttpServletResponseはServlet仕様で定義されているクラスです。

ルートリソースクラスのフィールドにインジェクトされるjavax.servlet.http.HttpServletResponseの使用例を次に示します。

package com.sample.resources;

import java.io.IOException;
import javax.servlet.http.HttpServletResponse;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Context;

//ルートリソースクラス
@Path("/root")
public class Resource {

  //Contextアノテーションを使用してHttpServletResponseをインジェクトするフィールド
  private @Context HttpServletResponse httpResponse;

  //リソースメソッド
  @GET
  public void getValue() throws IOException {

    String entity = "Response mentioned using HttpServletResponse";

    httpResponse.setHeader("abc","xyz");
    httpResponse.getOutputStream().write(entity.getBytes());
    httpResponse.getOutputStream().flush();
    httpResponse.getOutputStream().close();

    return ;
  }
}

ルートリソースクラスcom.sample.resources.Resourceを含むWebアプリケーション（WARファイル）のコンテキストルートが"example"で，Webアプリケーションが"sample.com"というホストで公開されているとします。この例で，URL"http://sample.com/example/root"に対するHTTP GETリクエストでは，まずHttpResponseフィールドにjavax.servlet.http.HttpServletResponseがインジェクトされ，その後HTTP GETリクエストを処理できるgetValue()メソッドが呼び出されます。このため，HttpResponseクラスが応答の構築に使用される個所と，ルートリソースクラスcom.sample.resources.ResourceのgetValue()メソッドは同じになります。

25　RESTful Webサービス用クライアントAPIのサポート範囲

この章では，RESTful Webサービス用クライアントAPIの仕様およびサポート範囲について説明します。

なお，この章ではRESTful Webサービス用クライアントAPIを「クライアントAPI」と呼びます。

25.1　クライアントAPIのインタフェースおよびクラスのサポート範囲

ここでは，クライアントAPIのインタフェースおよびクラスのサポート範囲について説明します。クライアントAPIのインタフェースおよびクラスのサポート範囲を次の表に示します。

表25‒1　クライアントAPIのインタフェースおよびクラスのサポート範囲

項番

インタフェースまたはクラス

コンストラクタ／メソッド／フィールド

com.cosminexus.jersey.api.clientパッケージ

1

Client

create()

2

create(ClientConfig cc)

3

destroy()

4

getProperties()

5

handle(ClientRequest request)

6

resource(String u)

7

resource(URI u)

8

setChunkedEncodingSize(Integer chunkSize)

9

setConnectTimeout(Integer interval)

10

setFollowRedirects(Boolean redirect)

11

setReadTimeout(Integer interval)

12

ClientHandlerException

親クラスのメソッド※1

13

ClientRequest

clone()

14

create()

15

getEntity()

16

getHeaders()

17

getHeaderValue(Object headerValue)

18

getMethod()

19

getProperties()

20

getPropertyAsFeature(String name)

21

getPropertyAsFeature(String name, boolean defaultValue)

22

getURI()

23

setEntity(Object entity)

24

setMethod(String method)

25

setURI(java.net.URI uri)

26

ClientRequest.Builder

accept(MediaType... types)

27

accept(String... types)

28

acceptLanguage(Locale... locales)

29

acceptLanguage(String... locales)

30

build(URI uri, String method)

31

cookie(Cookie cookie)

32

entity(Object entity)

33

entity(Object entity, MediaType type)

34

entity(Object entity, String type)

35

header(String name, Object value)

36

type(MediaType type)

37

type(String type)

38

ClientResponse

bufferEntity()

39

close()

40

getAllow()

41

getClient()

42

getClientResponseStatus()

43

getCookies()

44

getEntity(Class<T> c)

45

getEntity(GenericType<T> gt)

46

getEntityInputStream()

47

getEntityTag()

48

getHeaders()

49

getLanguage()

50

getLastModified()

51

getLength()

52

getLocation()

54

getResponseDate()

55

getStatus()

56

getType()

57

hasEntity()

58

ClientResponse.Status

ACCEPTED

59

BAD_GATEWAY

60

BAD_REQUEST

61

CONFLICT

62

CREATED

63

EXPECTATION_FAILED

64

FORBIDDEN

65

FOUND

66

GATEWAY_TIMEOUT

67

GONE

68

HTTP_VERSION_NOT_SUPPORTED

69

INTERNAL_SERVER_ERROR

70

LENGTH_REQUIRED

71

METHOD_NOT_ALLOWED

72

MOVED_PERMANENTLY

73

NO_CONTENT

74

NON_AUTHORITIVE_INFORMATION

75

NOT_ACCEPTABLE

76

NOT_FOUND

77

NOT_IMPLEMENTED

78

NOT_MODIFIED

79

OK

80

PARTIAL_CONTENT

81

PAYMENT_REQUIRED

82

PRECONDITION_FAILED

83

PROXY_AUTHENTICATION_REQUIRED

84

REQUEST_ENTITY_TOO_LARGE

85

REQUEST_TIMEOUT

86

REQUEST_URI_TOO_LONG

87

REQUESTED_RANGE_NOT_SATIFIABLE

88

RESET_CONTENT

89

SEE_OTHER

90

SERVICE_UNAVAILABLE

91

TEMPORARY_REDIRECT

92

UNAUTHORIZED

93

UNSUPPORTED_MEDIA_TYPE

94

USE_PROXY

95

fromStatusCode(int statusCode)

96

getFamily()

97

getReasonPhrase()

98

getStatusCode()

99

toString()

100

valueOf(String name)

101

values()

102

GenericType

GenericType()

103

GenericType(Type genericType)

104

getRawClass()

105

getType()

106

UniformInterfaceException

getResponse()

107

WebResource

accept(MediaType... types)

108

accept(String... types)

109

acceptLanguage(Locale... locales)

110

acceptLanguage(String... locales)

111

cookie(Cookie cookie)

112

delete()

113

delete(Class<T> c)

114

delete(Class<T> c, Object requestEntity)

115

delete(GenericType<T> gt)

116

delete(GenericType<T> gt, Object requestEntity)

117

delete(Object requestEntity)

118

entity(Object entity)

119

entity(Object entity, MediaType type)

120

entity(Object entity, String type)

121

get(Class<T> c)

122

get(GenericType<T> gt)

123

getRequestBuilder()

124

getURI()

125

getUriBuilder()

126

head()

127

header(String name, Object value)

128

method(String method)

129

method(String method, Class<T> c)

130

method(String method, Class<T> c, Object requestEntity)

131

method(String method, GenericType<T> gt)

132

method(String method, GenericType<T> gt, Object requestEntity)

133

method(String method, Object requestEntity)

134

options(Class<T> c)

135

options(GenericType<T> gt)

136

path(String path)

137

post()

138

post(Class<T> c)

139

post(Class<T> c, Object requestEntity)

140

post(GenericType<T> gt)

141

post(GenericType<T> gt, Object requestEntity)

142

post(Object requestEntity)

143

put()

144

put(Class<T> c)

145

put(Class<T> c, Object requestEntity)

146

put(GenericType<T> gt)

147

put(GenericType<T> gt, Object requestEntity)

148

put(Object requestEntity)

149

queryParam(String key, String value)

150

queryParams(MultivaluedMap<String, String> params)

151

type(MediaType type)

152

type(String type)

153

uri(java.net.URI uri)

154

WebResource.Builder

accept(MediaType... types)

155

accept(String... types)

156

acceptLanguage(Locale... locales)

157

acceptLanguage(String... locales)

158

cookie(Cookie cookie)

159

delete()

160

delete(Class<T> c)

161

delete(Class<T> c, Object requestEntity)

162

delete(GenericType<T> gt)

163

delete(GenericType<T> gt, Object requestEntity)

164

delete(Object requestEntity)

165

entity(Object entity)

166

entity(Object entity, MediaType type)

167

entity(Object entity, String type)

168

get(Class<T> c)

169

get(GenericType<T> gt)

170

head()

171

header(String name, Object value)

172

method(String method)

173

method(String method, Class<T> c)

174

method(String method, Class<T> c, Object requestEntity)

175

method(String method, GenericType<T> gt)

176

method(String method, GenericType<T> gt, Object requestEntity)

177

method(String method, Object requestEntity)

178

options(Class<T> c)

179

options(GenericType<T> gt)

180

post()

181

post(Class<T> c)

182

post(Class<T> c, Object requestEntity)

183

post(GenericType<T> gt)

184

post(GenericType<T> gt, Object requestEntity)

185

post(Object requestEntity)

186

put()

187

put(Class<T> c)

188

put(Class<T> c, Object requestEntity)

189

put(GenericType<T> gt)

190

put(GenericType<T> gt, Object requestEntity)

191

put(Object requestEntity)

192

type(MediaType type)

193

type(String type)

com.cosminexus.jersey.api.client.configパッケージ

194

DefaultClientConfig

PROPERTY_BUFFER_RESPONSE_ENTITY_ON_EXCEPTION

195

PROPERTY_CHUNKED_ENCODING_SIZE

196

PROPERTY_CONNECT_TIMEOUT

197

PROPERTY_FOLLOW_REDIRECTS

198

PROPERTY_READ_TIMEOUT

199

getPropertyAsFeature(String featureName)

200

getFeatures()

201

getFeature(String featureName)

202

getProperties()

203

getProperty(String propertyName)

com.cosminexus.jersey.client.urlconnectionパッケージ

204

HTTPSProperties

PROPERTY_HTTPS_PROPERTIES

205

HTTPSProperties()

206

HTTPSProperties(HostnameVerifier hv)

207

HTTPSProperties(HostnameVerifier hv, SSLContext c)

208

getHostnameVerifier()

209

getSSLContext()

com.cosminexus.jersey.core.utilパッケージ

210

MultivaluedMapImpl※2

MultivaluedMapImpl()

211

add(String key, String value)

212

getFirst(String key)

213

putSingle(String key, String value)

注※1

ClientHandlerExceptionクラスはRuntimeExceptionクラスの派生クラスです。ClientHandlerExceptionクラスはRuntimeExceptionクラスのメソッドの範囲で使用してください。

注※2

MultivaluedMapImplクラスのコンストラクタおよびメソッドの仕様については，JAX-RS APIのドキュメントを参照してください。注意事項については「25.14　MultivaluedMapImplクラスのコンストラクタおよびメソッド仕様と注意事項」を参照してください。

25.1.1　サポートするプロパティとフィーチャ

ここでは，クライアントAPIによってサポートされているプロパティとフィーチャについて説明します。

(1)　フィーチャ

JAX-RSエンジンがサポートしているフィーチャとデータ型を次の表に示します。

表25‒2　JAX-RSエンジンがサポートしているフィーチャとデータ型

項番

フィーチャ名

データ型

1

com.sun.jersey.api.json.POJOMappingFeature

(JSONConfiguration.FEATURE_POJO_MAPPING)

Boolean

このフィーチャは変更可能なフィーチャマップに追加して使用します。使用方法の詳細は，「getFeatures()メソッド」を参照してください。

(2)　プロパティ

JAX-RSエンジンがサポートしているプロパティとデータ型を次の表に示します。

表25‒3　JAX-RSエンジンがサポートしているプロパティとデータ型

項番

プロパティ

データ型

1

com.sun.jersey.client.property.followRedirects

(ClientConfig.PROPERTY_FOLLOW_REDIRECTS)

Boolean

2

com.sun.jersey.client.property.readTimeout

(ClientConfig.PROPERTY_READ_TIMEOUT)

Integer

3

com.sun.jersey.client.property.connectTimeout

(ClientConfig.PROPERTY_CONNECT_TIMEOUT)

Integer

4

com.sun.jersey.client.property.chunkedEncodingSize

(ClientConfig.PROPERTY_CHUNKED_ENCODING_SIZE)

Integer

5

com.sun.jersey.client.property

.bufferResponseEntityOnException

(ClientConfig.PROPERTY_BUFFER_RESPONSE_ENTITY_ON_EXCEPTION)

Boolean

6

com.sun.jersey.client.impl.urlconnection

.httpsProperties

(HTTPSProperties.PROPERTY_HTTPS_PROPERTIES)

HTTPSProperties

これらのプロパティは変更可能なプロパティマップに追加して使用します。使用方法の詳細は次のメソッドを参照してください。

Clientクラス

getProperties()メソッド

ClientRequestクラス

getProperties()メソッド

DefaultClientConfigクラス

getProperties()メソッド

25.1.2　ClientRequestクラスとWebリソースクラスに含まれる情報

ClientRequestクラスとWebリソースクラスには次の情報が含まれます。

表25‒4　ClientRequestクラスとWebリソースクラスに含まれる情報

クラス

含まれる情報

ClientRequestクラス

WebリソースのURI

HTTPメソッド名

HTTPリクエストのエンティティボディ

HTTPヘッダ

プロパティマップ

Webリソースクラス

WebリソースのURI

HTTPリクエストのエンティティボディ

HTTPヘッダ

25.2　Clientクラスのメソッド仕様と注意事項

ここでは，Clientクラスのメソッドの仕様，および利用する場合の注意事項について説明します。

create()メソッド

説明

クライアント（Clientオブジェクト）を生成します。

構文

public static Client create()

パラメタ

ありません。

戻り値

生成されたクライアントを返します。

注意事項

このメソッドの実行結果は，生成しただけのDefaultClientConfigオブジェクトをccパラメタに指定してcreate(ClientConfig cc)メソッドを呼び出した場合と同じです。

create(ClientConfig cc)メソッド

説明

指定された設定でクライアント（Clientオブジェクト）を生成します。

構文

public static Client create(ClientConfig cc)

パラメタ

cc

クライアントを設定します。

戻り値

生成されたクライアントを返します。

注意事項

特定のプロパティ・フィーチャでClientオブジェクトを初期化したい場合に，このメソッドを使用します。プロパティとフィーチャについては「25.1.1　サポートするプロパティとフィーチャ」を参照してください。プロパティとフィーチャを設定する方法の詳細については，「getFeatures()メソッド」および「getProperties()メソッド」を参照してください。

ccパラメタにはDefaultClientConfigオブジェクトだけを指定してください。

destroy()メソッド

説明

クライアントを破棄します。クライアントに関連するすべてのシステムリソースが破棄されます。

このメソッドは，受信途中の応答がないときに呼び出してください。それ以外の場合，動作は保証されません。

このメソッドを呼び出したあとは，Clientオブジェクトを再利用してはいけません。再利用した場合，動作は保証されません。

構文

public void destroy()

パラメタ

ありません。

戻り値

ありません。

注意事項

ありません。

getProperties()メソッド

説明

変更可能なプロパティマップを取得します。

構文

public Map<String,Object> getProperties()

パラメタ

ありません。

戻り値

プロパティマップを返します。

注意事項

戻り値のプロパティマップには，プロパティを追加または変更できます。追加または変更できるプロパティについては，「25.1.1　サポートするプロパティとフィーチャ」を参照してください。プロパティについては「11.4.3　プロパティとフィーチャの設定」も参照してください。

getProperties()メソッドの使用例を次に示します。

// Clientオブジェクトを生成する
Client client = Client.create();
// 読み込みタイムアウト値を設定する
client.getProperties().put(ClientConfig.PROPERTY_READ_TIMEOUT, 10000);

// HTTPリクエストを生成する
ClientRequest cRequest = ClientRequest.create().build(new URI("http://test.com/"), "GET");
try{
  // HTTPレスポンスをClientResponseオブジェクトとして受信する
  ClientResponse cResponse = client.handle(cRequest);
} catch(ClientHandlerException e){
  // 適切な処理を実行する
}

この例では，まず，getPropertiesメソッドで変更可能なプロパティマップを取得し，読み込みタイムアウト値を10,000ミリ秒に設定しています。次にClientRequestオブジェクトを作成し，Clientクラスのhandleメソッドを利用してHTTP通信を行い，HTTPレスポンスをClientResponseオブジェクトとして受信しています。HTTPレスポンスが完全に読み込まれるまでに読み込みタイムアウトが発生した場合，エラーとなり（KDJJ18888-E），SocketTimeoutExceptionをラップしたClientHandlerExceptionがスローされます。

handle(ClientRequest request)メソッド

説明

指定されたClientRequestオブジェクトの内容でHTTPリクエストを処理し，ClientResponseオブジェクトとしてHTTPレスポンスを返します。

構文

public ClientResponse handle(ClientRequest request)

throws ClientHandlerException

パラメタ

request

HTTPリクエストです。

戻り値

HTTPレスポンスを返します。

例外

ClientHandlerException

処理中に問題が発生した場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストおよびHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。例外が発生する条件は環境などによって異なります。次に示すそれぞれのメソッドの注意事項も参照してください。

Clientクラス

getProperties()メソッド

resource(String u)メソッド

resource(URI u)メソッド

setChunkedEncodingSize(Integer chunkSize)メソッド

setConnectTimeout(Integer interval)メソッド

setFollowRedirects(Boolean redirect)メソッド

setReadTimeout(Integer interval)メソッド

ClientRequestクラス

getProperties()メソッド

setEntity(Object entity)メソッド

setMethod(String method)メソッド

setURI(java.net.URI uri)メソッド

ClientRequest.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

build(URI uri, String method)メソッド

cookie(Cookie cookie)メソッド

entity(Object entity)メソッド

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

handle(ClientRequest request)メソッドの使用例については「getProperties()メソッド」を参照してください。

resource(String u)メソッド

説明

クライアント（Clientオブジェクト）からWebResourceオブジェクトを生成します。

構文

public WebResource resource(String u)

パラメタ

u

WebリソースのURIです。

戻り値

WebResourceオブジェクトを返します。

注意事項

uパラメタにはnull以外の有効なURIを指定してください。nullを指定した場合，NullPointerExceptionがスローされます。それ以外の不正な値を指定した場合の動作は，Java SEのjava.net.URIクラスのcreate()メソッドと同じです。詳細については，JDKのドキュメントを参照してください。

resource(URI u)メソッド

説明

クライアント（Clientオブジェクト）からWebリソースを生成します。

構文

public WebResource resource(URI u)

パラメタ

u

WebリソースのURIです。

戻り値

WebResourceオブジェクトを返します。

注意事項

uパラメタには有効なURIを指定してください。また，URIにはRFC 2396で定義されている文字を使用してください。uパラメタは自動ではURIエンコーディングされません。必要に応じてURIエンコードした値をuパラメタに指定してください。

setChunkedEncodingSize(Integer chunkSize)メソッド

説明

HTTPリクエストのエンティティを，指定されたチャンクサイズでチャンク転送エンコーディングして送信するように設定します。

このメソッドは，getProperties()メソッドで取得したプロパティのマップにClientConfig.PROPERTY_CHUNKED_ENCODING_SIZEプロパティを設定する場合と機能は同じです。

構文

public void setChunkedEncodingSize(Integer chunkSize)

パラメタ

chunkSize

チャンクサイズを指定します。0以下の値が指定された場合，デフォルト値が適用されます。

戻り値

ありません。

注意事項

chunkSizeパラメタで設定した値によるクライアントの動作は，HttpURLConnectionクラスのsetChunkedStreamingMode()メソッドと同じです。詳細については，JDKのドキュメントを参照してください。

JAX-RSエンジンはchunkSizeパラメタに設定された値を検証しません。HTTP通信に先立って，そのままHttpURLConnectioinにコピーします。chunkSizeパラメタには，Java SEのHttpURLConnectionクラスのsetChunkedStreamingMode()メソッドの説明に従って値を設定してください。

クライアントのプロパティマップに，すでにClientConfig.PROPERTY_CHUNKED_ENCODING_SIZEで指定した値が含まれている場合，chunkSizeパラメタで指定された値が上書きされます。

chunkSizeパラメタで指定された値によってHTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

setConnectTimeout(Integer interval)メソッド

説明

接続タイムアウト値をミリ秒単位で設定します。

このメソッドは，getProperties()メソッドで取得したプロパティのマップにClientConfig.PROPERTY_CONNECT_TIMEOUTプロパティを設定する場合と機能は同じです。

構文

public void setConnectTimeout(Integer interval)

パラメタ

interval

接続タイムアウト値です。nullまたは0が指定された場合，タイムアウトされません。

戻り値

ありません。

注意事項

intervalパラメタで設定した値によるクライアントの動作は，HttpURLConnectionクラスのsetConnectTimeout()メソッドと同じです。詳細については，JDKのドキュメントを参照してください。

JAX-RSエンジンはintervalパラメタに設定された値を検証しません。HTTP通信に先立って，そのままHttpURLConnectioinにコピーします。intervalパラメタには，Java SEのHttpURLConnectionクラスのsetConnectTimeout()メソッドの説明に従って値を設定してください。

クライアントのプロパティマップに，すでにClientConfig.PROPERTY_CONNECT_TIMEOUTで指定した値が含まれている場合，intervalパラメタで指定された値が上書きされます。

intervalパラメタで指定された値によってHTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

setFollowRedirects(Boolean redirect)メソッド

説明

HTTPリダイレクトに自動的に従うべきかどうかを設定します。

このメソッドは，getProperties()メソッドで取得したプロパティのマップにClientConfig.PROPERTY_FOLLOW_REDIRECTSプロパティを設定する場合と機能は同じです。

構文

public void setFollowRedirects(Boolean redirect)

パラメタ

redirect

trueの場合，クライアントはステータスコードが300番台のHTTPレスポンスに記述されたURIに自動的にリダイレクトされます。

戻り値

ありません。

注意事項

redirectパラメタで設定した値によるクライアントの動作は，HttpURLConnectionクラスのsetInstanceFollowRedirects()メソッドと同じです。詳細については，JDKのドキュメントを参照してください。

JAX-RSエンジンはredirectパラメタに設定された値を検証しません。HTTP通信に先立って，そのままHttpURLConnectioinにコピーします。redirectパラメタには，Java SEのHttpURLConnectionクラスのsetInstanceFollowRedirects()メソッドの説明に従って値を設定してください。

クライアントのプロパティマップに，すでにClientConfig.PROPERTY_FOLLOW_REDIRECTS で指定した値が含まれている場合，redirectパラメタで指定された値が上書きされます。

redirectパラメタで指定された値によってHTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

setReadTimeout(Integer interval)メソッド

説明

読み込みタイムアウト値をミリ秒単位で設定します。

このメソッドは，getProperties()メソッドで取得したプロパティのマップにClientConfig.PROPERTY_READ_TIMEOUTプロパティを設定する場合と機能は同じです。

構文

public void setReadTimeout(Integer interval)

パラメタ

interval

読み込みタイムアウト値です。nullまたは0が指定された場合，タイムアウトされません。

戻り値

ありません。

注意事項

intervalパラメタで設定した値によるクライアントの動作は，HttpURLConnectionクラスのsetReadTimeout()メソッドと同じです。詳細については，JDKのドキュメントを参照してください。

JAX-RSエンジンはintervalパラメタに設定された値を検証しません。HTTP通信に先立って，そのままHttpURLConnectioinにコピーします。intervalパラメタには，Java SEのHttpURLConnectionクラスのsetReadTimeout()メソッドの説明に従って値を設定してください。

クライアントのプロパティマップに，すでにClientConfig.PROPERTY_READ_TIMEOUTで指定した値が含まれている場合，intervalパラメタで指定された値が上書きされます。

intervalパラメタで指定された値によってHTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

25.3　ClientHandlerExceptionクラスのメソッド仕様と注意事項

ClientHandlerExceptionクラスはRuntimeExceptionクラスの派生クラスです。ClientHandlerExceptionクラスはRuntimeExceptionクラスのメソッドの範囲で使用してください。

25.4　ClientRequestクラスのメソッド仕様と注意事項

ここでは，ClientRequestクラスのメソッドの仕様，および利用する場合の注意事項について説明します。

clone()メソッド

説明

HTTPリクエスト（ClientRequestオブジェクト）を複製します。

構文

public abstract ClientRequest clone()

パラメタ

ありません。

戻り値

複製されたHTTPリクエスト（ClientRequestオブジェクト）を返します。

注意事項

このメソッドによって複製されるClientRequestオブジェクトのエンティティは次のとおりです。

WebリソースのURI

HTTPメソッド名

HTTPリクエスト

HTTPヘッダ

ClientRequestオブジェクトのプロパティマップは複製されません。必要に応じて，複製されたClientRequestオブジェクトに追加してください。

create()メソッド

説明

ClientRequestオブジェクトを構築するためのビルダ（ClientRequest.Builderオブジェクト）を生成します。

構文

public static final ClientRequest.Builder create()

パラメタ

ありません。

戻り値

ビルダ（ClientRequest.Builderオブジェクト）を返します。

注意事項

使用例については「getProperties()メソッド」を参照してください。

getEntity()メソッド

説明

HTTPリクエストのエンティティを取得します。

構文

public abstract Object getEntity()

パラメタ

ありません。

戻り値

HTTPリクエストのエンティティを返します。

注意事項

ClientRequestクラスのsetEntity()メソッドで設定したエンティティの値が返ります。

ClientRequestクラスのsetEntity()メソッドでエンティティが設定されていなかったり，nullが指定されていたりした場合，nullが返ります。

getHeaders()メソッド

説明

HTTPヘッダのマップを取得します。

構文

public abstract MultivaluedMap<String,Object> getHeaders()

パラメタ

ありません。

戻り値

HTTPヘッダのマップを返します。

注意事項

ClientRequestオブジェクトに設定されているHTTPヘッダがMultivaluedMap<java.lang.String,java.lang.Object>の形式で返ります。HTTPヘッダはClientRequestオブジェクトの次のメソッドでも設定できます。

accept(MediaType... types)メソッド

accept(String... types)メソッド

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

cookie(Cookie cookie)メソッド

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

HTTPヘッダが一つも設定されていない場合，空のマップが返ります。

getHeaderValue(Object headerValue)メソッド

説明

指定されたHTTPヘッダの値を文字列に変換します。

構文

public static String getHeaderValue(Object headerValue)

パラメタ

headerValue

HTTPヘッダの値です。

戻り値

変換された文字列を返します。

注意事項

戻り値は，パラメタに指定されたオブジェクトのtoString()メソッドが返す値です。

getMethod()メソッド

説明

HTTPメソッドを取得します。

構文

public abstract String getMethod()

パラメタ

ありません。

戻り値

HTTPメソッドを返します。

注意事項

ClientRequestオブジェクトに設定されているHTTPメソッドの名前が文字列で返ります。HTTPメソッドは次のメソッドで設定できます。

ClientRequestクラスのsetMethod(String method)メソッド

ClientRequest.Builderクラスのbuild(URI uri, String method)メソッド

HTTPメソッドにnullが設定されている場合，nullが返ります。

getProperties()メソッド

説明

変更可能なプロパティマップを取得します。

構文

public abstract Map<String,Object> getProperties()

パラメタ

ありません。

戻り値

プロパティマップを返します。

注意事項

戻り値のプロパティマップにはプロパティを追加または変更できます。追加または変更できるプロパティについては，「25.1.1　サポートするプロパティとフィーチャ」を参照してください。プロパティについては「11.4.3　プロパティとフィーチャの設定」も参照してください。

getProperties()メソッドの使用例を次に示します。

// Clientオブジェクトを生成する
Client client = Client.create();
// HTTPリクエストを生成する
ClientRequest cRequest = ClientRequest.create().build(new URI("http://test.com/"), "GET");
// 読み込みタイムアウト値を設定する
cRequest.getProperties().put(ClientConfig.PROPERTY_READ_TIMEOUT, 10000);
try{
  // HTTPレスポンスをClientResponseオブジェクトとして受信する
  ClientResponse cResponse = client.handle(cRequest);
} catch(ClientHandlerException e){
  // 適切な処理を実行する
}

この例では，ClientRequestオブジェクトを生成したあと，ClientRequestオブジェクトのgetProperties()メソッドで変更可能なプロパティマップを取得し，読み込みタイムアウト値を10,000ミリ秒に設定しています。次に，そのClientRequestオブジェクトを指定してClientクラスのhandleメソッドを呼び出します。ClientRequestオブジェクトのプロパティはClientオブジェクトにコピーされます。ClientResponseオブジェクトとしてHTTPレスポンスを受信するとき，完全に読み込まれるまでに読み込みタイムアウトが発生した場合，エラーとなり（KDJJ18888-E），SocketTimeoutExceptionをラップしたClientHandlerExceptionがスローされます。

getPropertyAsFeature(String name)メソッド

説明

プロパティマップからBooleanのプロパティをフィーチャとして取得します。

構文

public boolean getPropertyAsFeature(String name)

パラメタ

name

プロパティ名です。

戻り値

指定されたプロパティがtrue値を持つBooleanの場合true，そうでない場合はfalseが返ります。

注意事項

ありません。

getPropertyAsFeature(String name, boolean defaultValue)メソッド

説明

プロパティマップからBooleanのプロパティをフィーチャとして取得します。

構文

public boolean getPropertyAsFeature(String name,

boolean defaultValue)

パラメタ

name

プロパティ名です。

defaultValue

指定されたプロパティが存在しない場合に仮定するデフォルト値です。

戻り値

指定されたプロパティがtrue値を持つBooleanの場合true，そうでない場合は指定されたデフォルト値が返ります。

注意事項

ありません。

getURI()メソッド

説明

HTTPリクエストのURIを取得します。URIにはリクエストの対象となるリソースを識別する情報が含まれます。

構文

public abstract URI getURI()

パラメタ

ありません。

戻り値

HTTPリクエストのURIを返します。

注意事項

ClientRequest オブジェクトに設定されているURIが返ります。URIは次のメソッドで設定できます。

ClientRequestクラスのsetURI(java.net.URI uri)メソッド

ClientRequest.Builderクラスのbuild(URI uri, String method)メソッド

URIにnullが設定されている場合，nullが返ります。

setEntity(Object entity)メソッド

説明

エンティティを設定します。

構文

public abstract void setEntity(Object entity)

パラメタ

entity

エンティティです。

戻り値

ありません。

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

setMethod(String method)メソッド

説明

HTTPメソッドを設定します。

構文

public abstract void setMethod(String method)

パラメタ

method

HTTPメソッド名です。

戻り値

ありません。

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

setURI(java.net.URI uri)メソッド

説明

HTTPリクエストのURIを設定します。URIにはリクエストの対象となるリソースを識別する情報を正しく指定してください。

構文

public abstract void setURI(URI uri)

パラメタ

uri

HTTPリクエストのURIです。

戻り値

ありません。

注意事項

uriパラメタには有効なURIを指定してください。また，URIにはRFC 2396で定義されている文字を使用してください。uriパラメタは自動ではURIエンコーディングされません。必要に応じてURIエンコードした値をuriパラメタに指定してください。

25.5　ClientRequest.Builderクラスのメソッド仕様と注意事項

ここでは，ClientRequest.Builderクラスのメソッドの仕様，および利用する場合の注意事項について説明します。

accept(MediaType... types)メソッド

説明

受信できるMIMEメディアタイプを追加します。

構文

public T accept(MediaType... types)

パラメタ

types

受信できるMIMEメディアタイプの配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typesパラメタに含まれるnullでない値がAccept HTTPヘッダに追加されます。nullの値は無視されAccept HTTPヘッダには追加されません。

Accept HTTPヘッダには，MediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Accept HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Builderクラス

accept(String... types)メソッド

header(String name, Object value)メソッド

WebResourceクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびaccept(MediaType... types)メソッドで，受信できるMIMEメディアタイプが一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept HTTPヘッダを追加しない場合の動作と同様です。

accept(String... types)メソッド

説明

受信できるMIMEメディアタイプを追加します。

構文

public T accept(String... types)

パラメタ

types

受信できるMIMEメディアタイプの配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typesパラメタに含まれるnullでない値がAccept HTTPヘッダに追加されます。nullの値は無視されAccept HTTPヘッダには追加されません。

Accept HTTPヘッダには，指定された値がそのまま設定されます。JAX-RSエンジンは指定された値を検証しません。標準仕様に従って値を指定してください。

Accept HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Buildeクラス

accept(MediaType... types)メソッド

header(String name, Object value)メソッド

WebResourceクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびaccept(String... types)メソッドで，受信できるMIMEメディアタイプが一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept HTTPヘッダを追加しない場合の動作と同様です。

acceptLanguage(Locale... locales)メソッド

説明

受信できる言語を追加します。

構文

public T acceptLanguage(Locale... locales)

パラメタ

locales

受信できる言語の配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

localesパラメタに含まれるnullでない値がAccept-Language HTTPヘッダに追加されます。nullの値は無視されAccept-Language HTTPヘッダには追加されません。

Accept-Language HTTPヘッダには，LocaleオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Accept-Language HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Builderクラス

header(String name, Object value)メソッド

acceptLanguage(String... locales)メソッド

WebResourceクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびacceptLanguage(Locale... locales)メソッドで，受信できる言語が一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept-Language HTTPヘッダを追加しない場合の動作と同様です。

acceptLanguage(String... locales)メソッド

説明

受信できる言語を追加します。

構文

public T acceptLanguage(String... locales)

パラメタ

locales

受信できる言語の配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

localesパラメタに含まれるnullでない値がAccept-Language HTTPヘッダに追加されます。nullの値は無視されAccept-Language HTTPヘッダには追加されません。

Accept-Language HTTPヘッダには，指定された値がそのまま設定されます。JAX-RSエンジンは指定された値を検証しません。標準仕様に従って値を指定してください。

Accept-Language HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Builderクラス

acceptLanguage(Locale... locales)メソッド

header(String name, Object value)メソッド

WebResourceクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびacceptLanguage(String... locales)メソッドで，受信できる言語が一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept-Language HTTPヘッダを追加しない場合の動作と同様です。

build(URI uri, String method)メソッド

説明

ClientRequestオブジェクトを構築します。

構文

public ClientRequest build(URI uri,

String method)

パラメタ

uri

HTTPリクエストのURIです。

method

HTTPメソッド名です。

戻り値

ClientRequestオブジェクトを返します。

注意事項

uriパラメタには有効なURIを指定してください。また，URIにはRFC 2396で定義されている文字を使用してください。uriパラメタは自動ではURIエンコーディングされません。必要に応じてURIエンコードした値をuriパラメタに指定してください。

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

cookie(Cookie cookie)メソッド

説明

Cookieを設定します。

構文

public T cookie(Cookie cookie)

パラメタ

cookie

設定するCookieです。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

null以外の値がCookie HTTPヘッダに追加されます。nullの値は無視されCookie HTTPヘッダには追加されません。

Cookie HTTPヘッダには，CookieオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Cookie HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Builderクラス

header(String name, Object value)メソッド

WebResourceクラス

cookie(Cookie cookie)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

cookie(Cookie cookie)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびcookie(Cookie cookie)メソッドで，Cookieが追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにCookie HTTPヘッダを追加しない場合の動作と同様です。

entity(Object entity)メソッド

説明

HTTPリクエストのエンティティを設定します。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。ジェネリクスをエンティティに指定する場合は，GenericEntityオブジェクトを使用できます。

構文

public T entity(Object entity)

パラメタ

entity

HTTPリクエストのエンティティです。

戻り値

ビルダ（ClientRequest.Builderオブジェクト）を返します。

注意事項

ありません。

entity(Object entity, MediaType type)メソッド

説明

HTTPリクエストのエンティティとそのMIMEメディアタイプを設定します。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。ジェネリクスをエンティティに指定する場合は，GenericEntityオブジェクトを使用できます。

構文

public T entity(Object entity,

MediaType type)

パラメタ

entity

HTTPリクエストのエンティティです。

type

MIMEメディアタイプです。

戻り値

ビルダ（ClientRequest.Builderオブジェクト）を返します。

注意事項

typeパラメタにnullが指定された場合，無視されます。Content-Type HTTPヘッダには設定されません。

Content-Type HTTPヘッダには，MediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダの値が次のメソッドですでに設定されていた場合，typeパラメタの値で上書きされます。

ClientRequest.Builderクラス

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびentity(Object entity, MediaType type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

entity(Object entity, String type)メソッド

説明

HTTPリクエストのエンティティとそのMIMEメディアタイプを設定します。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。ジェネリクスをエンティティに指定する場合は，GenericEntityオブジェクトを使用できます。

構文

public T entity(Object entity,

String type)

パラメタ

entity

HTTPリクエストのエンティティです。

type

MIMEメディアタイプです。

戻り値

ビルダ（ClientRequest.Builderオブジェクト）を返します。

注意事項

typeパラメタにnullまたは空の文字列が設定された場合，IllegalArgumentExceptionがスローされます。

Content-Type HTTPヘッダには，MediaTypeクラスのvalueOf(String)スタティックメソッドのパラメタにtypeパラメタを指定して構築したMediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtypeパラメタに指定される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダの値が次のメソッドですでに設定されていた場合，typeパラメタの値で上書きされます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびentity(Object entity, String type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

header(String name, Object value)メソッド

説明

HTTPヘッダを追加します。

構文

public T header(String name,

Object value)

パラメタ

name

HTTPヘッダ名です。

value

HTTPヘッダの値です。

戻り値

ビルダ（ClientRequest.Builderオブジェクト）を返します。

注意事項

nameパラメタとvalueパラメタ両方の値がnullの場合，呼び出しは無視されます。

nameパラメタの値がnullではない場合も，valueパラメタの値がnullのとき，呼び出しは無視されます。

nameパラメタの値がnullで，かつvalueパラメタの値がnullではない場合，エラーとなり（KDJJ18888-E），NullPointerExceptionをラップしたClientHandlerExceptionがスローされます。

このメソッドでContent-Length，Connection，Hostの各HTTPヘッダを設定することはできません。nameパラメタにこれらが指定された場合，valueパラメタの値がnullではないときでも，呼び出しは無視されます。なお，それぞれのHTTPヘッダはHttpURLConnectionによって設定されます。

nameパラメタで指定されたHTTPヘッダの値はvalueパラメタで指定されたnullではないオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。valueパラメタには標準仕様に従って値を指定してください。

accept，acceptLanguage，cookieの各HTTPヘッダは，次のメソッドでも追加できます。

ClientRequest.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

cookie(Cookie cookie)メソッド

WebResourceクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

cookie(Cookie cookie)メソッド

WebResource.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

cookie(Cookie cookie)メソッド

これらのメソッドおよびheader(String name, Object value)メソッドで，各HTTPヘッダが追加されていない場合の動作は，HttpURLConnectionオブジェクトに各HTTPヘッダを追加しない場合と同様です。

Content-Type HTTPヘッダが次のメソッドですでに設定されていた場合，valueパラメタの値で上書きされます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびheader(String name, Object value)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

type(MediaType type)メソッド

説明

MIMEメディアタイプを設定します。

構文

public T type(MediaType type)

パラメタ

type

MIMEメディアタイプです。

戻り値

ビルダ（ClientRequest.Builderオブジェクト）を返します。

注意事項

typeパラメタに指定されたnullでない値がContent-Type HTTPヘッダに設定されます。nullの値は無視されContent-Type HTTPヘッダには設定されません。

Content-Type HTTPヘッダには，MediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダが次のメソッドですでに設定されていた場合，値は上書きされます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびtype(MediaType type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前にHttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

type(String type)メソッド

説明

MIMEメディアタイプを設定します。

構文

public T type(String type)

パラメタ

type

MIMEメディアタイプです。

戻り値

ビルダ（ClientRequest.Builderオブジェクト）を返します。

注意事項

typeパラメタにnullまたは空の文字列が設定された場合，IllegalArgumentExceptionがスローされます。

Content-Type HTTPヘッダには，MediaTypeクラスのvalueOf(String)スタティックメソッドのパラメタにtypeパラメタを指定して構築したMediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtypeパラメタに指定される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダが次のメソッドですでに設定されていた場合，typeパラメタの値で上書きされます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびtype(String type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

25.6　ClientResponseクラスのメソッド仕様と注意事項

ここでは，ClientResponseクラスのメソッドの仕様，および利用する場合の注意事項について説明します。

bufferEntity()メソッド

説明

エンティティをバッファリングします。HTTPレスポンスのエンティティの入力となるストリームからすべてのデータが読み込まれ，メモリに格納されます。バッファリング後，入力ストリームはクローズされます。

構文

public void bufferEntity()

throws ClientHandlerException

パラメタ

ありません。

戻り値

ClientHandlerException

処理中に問題が発生した場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

ありません。

close()メソッド

説明

HTTPレスポンスを終了します。エンティティの入力ストリームはクローズされます。

構文

public void close()

throws ClientHandlerException

パラメタ

ありません。

戻り値

ClientHandlerException

処理中に問題が発生した場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

ありません。

getAllow()メソッド

説明

Allow HTTPヘッダから，リソースでサポートされるHTTPメソッドの集合を取得します。なお，Allow HTTPヘッダは，HTTP OPTIONSリクエストの場合に取得できます。

構文

public Set<String> getAllow()

パラメタ

ありません。

戻り値

リソースでサポートされるHTTPメソッドの集合を返します。すべてのメソッドは大文字で出力されます。

注意事項

HTTPレスポンスにAllow HTTPヘッダが存在しない場合，空の集合を返します。

getClient()メソッド

説明

クライアント（Clientオブジェクト）を取得します。

構文

public Client getClient()

パラメタ

ありません。

戻り値

クライアント（Clientオブジェクト）を返します。

注意事項

このメソッドで返されるClientオブジェクトは，ClientResponseオブジェクトを生成したClientオブジェクトです。

getClientResponseStatus()メソッド

説明

ステータスコードを取得します。

構文

public ClientResponse.Status getClientResponseStatus()

パラメタ

ありません。

戻り値

ステータスコードを返します。

HTTPレスポンスのステータスコードがResponse.Status列挙型で定義される定数値に対応していれば，そのResponse.Status列挙型定数値を返します。対応していなければ，nullを返します。

注意事項

ありません。

getCookies()メソッド

説明

Cookieのリストを取得します。HTTPレスポンスのSet-Cookie HTTPヘッダに値が設定されている場合，NewCookieオブジェクトのリストが返ります。

構文

public List<NewCookie> getCookies()

パラメタ

ありません。

戻り値

Cookie（NewCookieオブジェクト）のリストを返します。

注意事項

HTTPレスポンスにSet-Cookie HTTPヘッダが存在しない場合，空のリストを返します。

getEntity(Class<T> c)メソッド

説明

HTTPレスポンスのエンティティを取得します。取得されるエンティティがCloseableインタフェースを実装したクラスのインスタンスでない場合，入力ストリームはクローズされます。

構文

public <T> T getEntity(Class<T> c)

throws ClientHandlerException,

UniformInterfaceException

パラメタ

c

エンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

ClientHandlerException

処理中に問題が発生した場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

UniformInterfaceException

HTTPステータスコードが204 No Contentの場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

このメソッドは一度だけ呼び出せます。二度以上呼び出された場合，動作は保証されません。

getEntity(GenericType<T> gt)メソッド

説明

HTTPレスポンスのエンティティを取得します。取得されるエンティティがCloseableインタフェースを実装したクラスのインスタンスでない場合，入力ストリームはクローズされます。

構文

public <T> T getEntity(GenericType<T> gt)

throws ClientHandlerException,

UniformInterfaceException

パラメタ

gt

エンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

ClientHandlerException

処理中に問題が発生した場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

UniformInterfaceException

HTTPステータスコードが204 No Contentの場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

このメソッドは一度だけ呼び出せます。このメソッドが二度以上呼び出された場合，動作は保証されません。

getEntityInputStream()メソッド

説明

HTTPレスポンスの入力ストリームを取得します。

構文

public InputStream getEntityInputStream()

パラメタ

ありません。

戻り値

HTTPレスポンスの入力ストリームを返します。

注意事項

ありません。

getEntityTag()メソッド

説明

ETag HTTPヘッダの値を取得します。

構文

public EntityTag getEntityTag()

パラメタ

ありません。

戻り値

ETag HTTPヘッダの値を返します。

注意事項

HTTPレスポンスにETag HTTPヘッダがない場合，またはHttpURLConnectionがETag HTTPヘッダの値としてnullを返す場合にはnullを返します。

ETag HTTPヘッダの値が空の文字列であるか，または標準仕様に準拠していない場合は，IllegalArgumentExceptionがスローされます。

getHeaders()メソッド

説明

HTTPレスポンスのHTTPヘッダのマップを取得します。

構文

public MultivaluedMap<String,String> getHeaders()

パラメタ

ありません。

戻り値

HTTPレスポンスのHTTPヘッダのマップを返します。

注意事項

HTTPレスポンスにHTTPヘッダがない場合，空のマップを返します。

getLanguage()メソッド

説明

Content-Language HTTPヘッダの値を取得します。

構文

public String getLanguage()

パラメタ

ありません。

戻り値

Content-Language HTTPヘッダの値を返します。

注意事項

HTTPレスポンスにContent-Language HTTPヘッダがない場合，またはHttpURLConnectionがContent-Language HTTPヘッダの値としてnullを返す場合にはnullを返します。

getLastModified()メソッド

説明

Last-Modified HTTPヘッダの値を取得します。

構文

public Date getLastModified()

パラメタ

ありません。

戻り値

Last-Modified HTTPヘッダの値を返します。

注意事項

HTTPレスポンスにLast-Modified HTTPヘッダがない場合，またはHttpURLConnectionがLast-Modified HTTPヘッダの値としてnullを返す場合にはnullを返します。

Last-Modified HTTPヘッダの値が空の文字列の場合，または次に示す形式に従っていない場合，IllegalArgumentExceptionがスローされます。

EEE, dd MMM yyyy HH:mm:ss zzz

EEEE, dd-MMM-yy HH:mm:ss zzz

EEE MMM d HH:mm:ss yyyy

Dateのフォーマットにおける各パターン文字，特にロケールに依存する「E」および「M」については，Java SE仕様のSimpleDateFormatクラスに関する情報を参照してください。

getLength()メソッド

説明

Content-Length HTTPヘッダの値を取得します。

構文

public int getLength()

パラメタ

ありません。

戻り値

Content-Length HTTPヘッダの値が有効な数値の場合に整数値で返します。

注意事項

HTTPレスポンスにContent-Length HTTPヘッダが存在しない場合，HttpURLConnectionがContent-Length HTTPヘッダの値としてnullを返す場合，またはContent-Length HTTPヘッダの値が無効な整数値の場合には，-1を返します。

getLocation()メソッド

説明

Location HTTPヘッダの値を取得します。

構文

public URI getLocation()

パラメタ

ありません。

戻り値

Location HTTPヘッダの値を返します。

注意事項

HTTPレスポンスにLocation HTTPヘッダがない場合，またはHttpURLConnectionがLocation HTTPヘッダの値としてnullを返す場合にはnullを返します。

Location HTTPヘッダの値が不正なURIの場合は，IllegalArgumentExceptionがスローされます。

getResponseDate()メソッド

説明

Date HTTPヘッダの値を取得します。

構文

public Date getResponseDate()

パラメタ

ありません。

戻り値

Date HTTPヘッダの値を返します。

注意事項

HTTPレスポンスにDate HTTPヘッダがない場合，またはHttpURLConnectionがDate HTTPヘッダの値としてnullを返す場合にはnullを返します。

Date HTTPヘッダの値が空の文字列の場合，または次に示す日付の形式に従っていない場合，IllegalArgumentExceptionがスローされます。

EEE, dd MMM yyyy HH:mm:ss zzz

EEEE, dd-MMM-yy HH:mm:ss zzz

EEE MMM d HH:mm:ss yyyy

Dateのフォーマットにおける各パターン文字，特にロケールに依存する「E」および「M」については，Java SE仕様のSimpleDateFormatクラスに関する情報を参照してください。

getStatus()メソッド

説明

HTTPステータスコードを取得します。

構文

public int getStatus()

パラメタ

ありません。

戻り値

HTTPステータスコードを整数値で返します。

注意事項

ありません。

getType()メソッド

説明

Content-Type HTTPヘッダの値を取得します。

構文

public MediaType getType()

パラメタ

ありません。

戻り値

Content-Type HTTPヘッダの値を返します。

注意事項

HTTPレスポンスにContent-Type HTTPヘッダがない場合，またはHttpURLConnectionがContent-Type HTTPヘッダの値としてnullを返す場合にはnullを返します。

Content-Type HTTPヘッダの値からMediaTypeオブジェクトを構築できない場合，IllegalArgumentExceptionがスローされます。

hasEntity()メソッド

説明

エンティティが存在するかどうかを確認します。

構文

public boolean hasEntity()

パラメタ

ありません。

戻り値

HTTPレスポンスにエンティティが存在する場合，trueを返します。

注意事項

HTTP HEADリクエストでHTTPレスポンスを取得した場合はfalseを返します。

HttpURLConnectionがContent-Length HTTPヘッダの値として0より大きいか，または-1を返すときにtrueを返します。それ以外の場合はfalseを返します。

一般に，HttpURLConnectionは，チャンク転送エンコーディングでない場合でHTTPレスポンスにエンティティが存在するときに0より大きい整数値を返し，チャンク転送エンコーディングである場合に-1を返します。チャンク転送エンコーディングの詳細については，RFC 2616を参照してください。

次の場合，不正なHTTPレスポンスとなるため動作は保証されません。

チャンク転送エンコーディングである場合で，HTTPレスポンスにContent-Length HTTPヘッダがあるとき

チャンク転送エンコーディングでない場合で，Content-Length HTTPヘッダの値がHTTPレスポンスのエンティティに基づく適切な値でないとき

25.7　ClientResponse.Statusクラスの列挙型定数とメソッドの仕様

ここでは，ClientResponse.Statusクラスの列挙型定数，およびメソッドの仕様について説明します。

ClientResponse.Statusクラスの列挙型定数

ClientResponse.Statusクラスでは，HTTPステータスコードとして，次の列挙型定数が定義されています。定数ごとの構文およびHTTPステータスコードについて説明します。

表25‒5　ClientResponse.Statusクラスで定義されている列挙型定数

項番

定数名

構文

HTTPステータスコード

1

OK

public static final ClientResponse.Status OK

200 OK

2

CREATED

public static final ClientResponse.Status CREATED

201 Created

3

ACCEPTED

public static final ClientResponse.Status ACCEPTED

202 Accepted

4

NON_AUTHORITIVE_INFORMATION

public static final ClientResponse.Status NON_AUTHORITIVE_INFORMATION

203 Non-Authoritative Information

5

NO_CONTENT

public static final ClientResponse.Status NO_CONTENT

204 No Content

6

RESET_CONTENT

public static final ClientResponse.Status RESET_CONTENT

205 Reset Content

7

PARTIAL_CONTENT

public static final ClientResponse.Status PARTIAL_CONTENT

206 Partial Content

8

MOVED_PERMANENTLY

public static final ClientResponse.Status MOVED_PERMANENTLY

301 Moved Permantly

9

FOUND

public static final ClientResponse.Status FOUND

302 Found

10

SEE_OTHER

public static final ClientResponse.Status SEE_OTHER

303 See Other

11

NOT_MODIFIED

public static final ClientResponse.Status NOT_MODIFIED

304 Not Modified

12

USE_PROXY

public static final ClientResponse.Status USE_PROXY

305 Use Proxy

13

TEMPORARY_REDIRECT

public static final ClientResponse.Status TEMPORARY_REDIRECT

307 Temporary Redirect

14

BAD_REQUEST

public static final ClientResponse.Status BAD_REQUEST

400 Bad Request

15

UNAUTHORIZED

public static final ClientResponse.Status UNAUTHORIZED

401 Unauthorized

16

PAYMENT_REQUIRED

public static final ClientResponse.Status PAYMENT_REQUIRED

402 Payment Required

17

FORBIDDEN

public static final ClientResponse.Status FORBIDDEN

403 Forbidden

18

NOT_FOUND

public static final ClientResponse.Status NOT_FOUND

404 Not Found

19

METHOD_NOT_ALLOWED

public static final ClientResponse.Status METHOD_NOT_ALLOWED

405 Method Not Allowed

20

NOT_ACCEPTABLE

public static final ClientResponse.Status NOT_ACCEPTABLE

406 Not Acceptable

21

PROXY_AUTHENTICATION_REQUIRED

public static final ClientResponse.Status PROXY_AUTHENTICATION_REQUIRED

407 Proxy Authentication Required

22

REQUEST_TIMEOUT

public static final ClientResponse.Status REQUEST_TIMEOUT

408 Request Timeout

23

CONFLICT

public static final ClientResponse.Status CONFLICT

409 Conflict

24

GONE

public static final ClientResponse.Status GONE

410 Gone

25

LENGTH_REQUIRED

public static final ClientResponse.Status LENGTH_REQUIRED

411 Length Required

26

PRECONDITION_FAILED

public static final ClientResponse.Status PRECONDITION_FAILED

412 Precondition Failed

27

REQUEST_ENTITY_TOO_LARGE

public static final ClientResponse.Status REQUEST_ENTITY_TOO_LARGE

413 Request Entity Too Large

28

REQUEST_URI_TOO_LONG

public static final ClientResponse.Status REQUEST_URI_TOO_LONG

414 Request-URI Too Long

29

UNSUPPORTED_MEDIA_TYPE

public static final ClientResponse.Status UNSUPPORTED_MEDIA_TYPE

415 Unsupported Media Type

30

REQUESTED_RANGE_NOT_SATIFIABLE

public static final ClientResponse.Status REQUESTED_RANGE_NOT_SATIFIABLE

416 Requested Range Not Satisfiable

31

EXPECTATION_FAILED

public static final ClientResponse.Status EXPECTATION_FAILED

417 Expectation Failed

32

INTERNAL_SERVER_ERROR

public static final ClientResponse.Status INTERNAL_SERVER_ERROR

500 Internal Server Error

33

NOT_IMPLEMENTED

public static final ClientResponse.Status NOT_IMPLEMENTED

501 Not Implemented

34

BAD_GATEWAY

public static final ClientResponse.Status BAD_GATEWAY

502 Bad Gateway

35

SERVICE_UNAVAILABLE

public static final ClientResponse.Status SERVICE_UNAVAILABLE

503 Service Unavailable

36

GATEWAY_TIMEOUT

public static final ClientResponse.Status GATEWAY_TIMEOUT

504 Gateway Timeout

37

HTTP_VERSION_NOT_SUPPORTED

public static final ClientResponse.Status HTTP_VERSION_NOT_SUPPORTED

505 HTTP Version Not Supported

fromStatusCode(int statusCode)メソッド

説明

数値で表現されたステータスコードを対応するClientResponse.Statusオブジェクトに変換します。

構文

public static ClientResponse.Status fromStatusCode(int statusCode)

パラメタ

statusCode

数値で表現されたステータスコードです。

戻り値

ステータスコードに対応するClientResponse.Statusオブジェクトを返します。対応するものがない場合はnullを返します。

注意事項

ありません。

getFamily()メソッド

説明

ステータスコードの分類を取得します。

構文

public Response.Status.Family getFamily()

パラメタ

ありません。

戻り値

ステータスコードの分類を返します。

注意事項

ありません。

getReasonPhrase()メソッド

説明

説明文字列（Reason Phrase）を取得します。

構文

public String getReasonPhrase()

パラメタ

ありません。

戻り値

説明文字列（Reason Phrase）を返します。

注意事項

ありません。

getStatusCode()メソッド

説明

対応するステータスコードを取得します。

構文

public int getStatusCode()

パラメタ

ありません。

戻り値

ステータスコードを返します。

注意事項

ありません。

toString()メソッド

説明

説明文字列（Reason Phrase）を取得します。

構文

public String toString()

パラメタ

ありません。

戻り値

説明文字列（Reason Phrase）を返します。

注意事項

ありません。

valueOf(String name)メソッド

説明

指定された名称の列挙型定数を取得します。

この列挙型で宣言されている列挙型定数の識別子を厳密に指定してください。余分なホワイトスペースも許容されません。

構文

public static ClientResponse.Status valueOf(String name)

パラメタ

name

取得する列挙型定数名です。

戻り値

指定された名称の列挙型定数を返します。

例外

IllegalArgumentException

指定した名称の列挙型定数がない場合にスローされます。

NullPointerException

nameパラメタにnullが指定された場合にスローされます。

注意事項

ありません。

values()メソッド

説明

この列挙型で宣言されている列挙型定数を宣言されている順に含む配列を返します。このメソッドは例えば次のように繰り返し処理する場合に利用できます。

for (ClientResponse.Status c : ClientResponse.Status.values())
    System.out.println(c);

構文

public static ClientResponse.Status[] values()

パラメタ

ありません。

戻り値

この列挙型で宣言されている列挙型定数を宣言されている順に含む配列を返します。

注意事項

ありません。

25.8　GenericTypeクラスのコンストラクタおよびメソッド仕様と注意事項

ここでは，GenericTypeクラスのコンストラクタおよびメソッドの仕様，および利用する場合の注意事項について説明します。GenericTypeクラスは，型パラメタが解決されたジェネリクスの型情報を保持します。

GenericType()コンストラクタ

説明

GenericTypeオブジェクトを新規に構築します。対象となる型パラメタが解決されたジェネリックの型情報，およびそのジェネリックを宣言したクラスは型パラメタTから取得されます。このコンストラクタはprotectedスコープであるため，ユーザはサブクラスを作成する必要があります（多くの場合，匿名のサブクラスを作成します）。

構文

protected GenericType()

パラメタ

ありません。

戻り値

ありません。

注意事項

ありません。

GenericType(Type genericType)コンストラクタ

説明

GenericTypeオブジェクトを新規に構築します。対象となる型パラメタが解決されたジェネリックの型，およびそのジェネリックを宣言したクラスはgenericTypeパラメタから取得されます。

構文

public GenericType(Type genericType)

パラメタ

genericType

型パラメタが解決されたジェネリックを表現するjava.lang.Typeオブジェクトです。

戻り値

ありません。

例外

IllegalArgumentException

genericTypeパラメタがnullである場合，またはgenericTypeパラメタがjava.lang.Classオブジェクトでも，その型を宣言した型がクラスであるjava.lang.reflect.ParameterizedTypeオブジェクトでもない場合にスローされます。

注意事項

ありません。

getRawClass()メソッド

説明

保持する型パラメタが解決されたジェネリクスを宣言したクラスを取得します。

構文

public final Class<T> getRawClass()

パラメタ

ありません。

戻り値

保持する型パラメタが解決されたジェネリクスを宣言したクラスを返します。

注意事項

ありません。

getType()メソッド

説明

保持する型パラメタが解決されたジェネリクスの型を取得します。

構文

public final Type getType()

パラメタ

ありません。

戻り値

保持する型パラメタが解決されたジェネリクスの型を返します。

注意事項

ありません。

25.9　UniformInterfaceExceptionクラスのメソッド仕様と注意事項

ここでは，UniformInterfaceExceptionクラスのメソッドの仕様，および利用する場合の注意事項について説明します。UniformInterfaceExceptionクラスは，ここで説明するメソッドおよび親クラスのメソッドの範囲で使用してください。

getResponse()メソッド

説明

例外に関連するClientResponseオブジェクトを取得します。

構文

public ClientResponse getResponse()

パラメタ

ありません。

戻り値

ClientResponseオブジェクトを返します。

注意事項

ありません。

25.10　WebResourceクラスのメソッド仕様と注意事項

ここでは，WebResourceクラスのメソッドの仕様，および利用する場合の注意事項について説明します。

accept(MediaType... types)メソッド

説明

受信できるMIMEメディアタイプを追加します。

構文

public WebResource.Builder accept(MediaType... types)

パラメタ

types

受信できるMIMEメディアタイプの配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typesパラメタに含まれるnullでない値がAccept HTTPヘッダに追加されます。nullの値は無視されAccept HTTPヘッダには追加されません。

Accept HTTPヘッダには，MediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Accept HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

WebResourceクラス

accept(String... types)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびaccept(MediaType... types)メソッドで，受信できるMIMEメディアタイプが一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept HTTPヘッダを追加しない場合の動作と同様です。

accept(String... types)メソッド

説明

受信できるMIMEメディアタイプを追加します。

構文

public WebResource.Builder accept(String... types)

パラメタ

types

受信できるMIMEメディアタイプの配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typesパラメタに含まれるnullでない値がAccept HTTPヘッダに追加されます。nullの値は無視されAccept HTTPヘッダには追加されません。

Accept HTTPヘッダには，指定された値がそのまま設定されます。JAX-RSエンジンは指定された値を検証しません。標準仕様に従って値を指定してください。

Accept HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Buildeクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

WebResourceクラス

accept(MediaType... types)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびaccept(String... types)メソッドで，受信できるMIMEメディアタイプが一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept HTTPヘッダを追加しない場合の動作と同様です。

acceptLanguage(Locale... locales)メソッド

説明

受信できる言語を追加します。

構文

public WebResource.Builder acceptLanguage(Locale... locales)

パラメタ

locales

受信できる言語の配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

localesパラメタに含まれるnullでない値がAccept-Language HTTPヘッダに追加されます。nullの値は無視されAccept-Language HTTPヘッダには追加されません。

Accept-Language HTTPヘッダには，LocaleオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Accept-Language HTTPヘッダの値は次のメソッドでも変更できます。

ClientRequest.Builderクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

WebResourceクラス

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびacceptLanguage(Locale... locales)メソッドで，受信できる言語が一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept-Language HTTPヘッダを設定しない場合の動作と同様です。

acceptLanguage(String... locales)メソッド

説明

受信できる言語を追加します。

構文

public WebResource.Builder acceptLanguage(String... locales)

パラメタ

locales

受信できる言語の配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

localesパラメタに含まれるnullでない値がAccept-Language HTTPヘッダに追加されます。nullの値は無視されAccept-Language HTTPヘッダには追加されません。

Accept-Language HTTPヘッダには，指定された値がそのまま設定されます。JAX-RSエンジンは指定された値を検証しません。標準仕様に従って値を指定してください。

Accept-Language HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Builderクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

WebResourceクラス

acceptLanguage(Locale... locales)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびacceptLanguage(String... locales)メソッドで，受信できる言語が一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept-Language HTTPヘッダを追加しない場合の動作と同様です。

cookie(Cookie cookie)メソッド

説明

Cookieを設定します。

構文

public WebResource.Builder cookie(Cookie cookie)

パラメタ

cookie

設定するCookieです。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

null以外の値がCookie HTTPヘッダに追加されます。nullの値は無視されCookie HTTPヘッダには追加されません。

Cookie HTTPヘッダには，CookieオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Cookie HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Builderクラス

cookie(Cookie cookie)メソッド

header(String name, Object value)メソッド

WebResourceクラス

header(String name, Object value)メソッド

WebResource.Builderクラス

cookie(Cookie cookie)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびcookie(Cookie cookie)メソッドで，Cookieが追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにCookie HTTPヘッダを追加しない場合の動作と同様です。

delete()メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにはエンティティを含めません。また，レスポンスのエンティティも受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void delete()

throws UniformInterfaceException

パラメタ

ありません。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

delete(Class<T> c)メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T delete(Class<T> c)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

delete(Class<T> c, Object requestEntity)メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T delete(Class<T> c,

Object requestEntity)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

delete(GenericType<T> gt)メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T delete(GenericType<T> gt)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

delete(GenericType<T> gt, Object requestEntity)メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T delete(GenericType<T> gt,

Object requestEntity)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

delete(Object requestEntity)メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにエンティティを含めます。レスポンスのエンティティは受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void delete(Object requestEntity)

throws UniformInterfaceException

パラメタ

requestEntity

HTTPリクエストのエンティティです。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

entity(Object entity)メソッド

説明

HTTPリクエストのエンティティを設定します。

構文

public WebResource.Builder entity(Object entity)

パラメタ

entity

HTTPリクエストのエンティティです。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

entity(Object entity, MediaType type)メソッド

説明

HTTPリクエストのエンティティのMIMEメディアタイプを設定します。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。ジェネリクスをエンティティに指定する場合は，GenericEntityオブジェクトを使用できます。

構文

public WebResource.Builder entity(Object entity,

MediaType type)

パラメタ

entity

HTTPリクエストのエンティティです。

type

MIMEメディアタイプです。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typeパラメタに指定されたnullでない値がContent-Type HTTPヘッダに設定されます。nullの値は無視されContent-Type HTTPヘッダには設定されません。

Content-Type HTTPヘッダには，MediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダの値は次のメソッドでも変更できます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびentity(Object entity, MediaType type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

entity(Object entity, String type)メソッド

説明

HTTPリクエストのエンティティのMIMEメディアタイプを設定します。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。ジェネリクスをエンティティに指定する場合は，GenericEntityオブジェクトを使用できます。

構文

public WebResource.Builder entity(Object entity,

String type)

パラメタ

entity

HTTPリクエストのエンティティです。

type

MIMEメディアタイプです。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typeパラメタにnullまたは空の文字列が設定された場合，IllegalArgumentExceptionがスローされます。

typeパラメタに指定されたnullでない値がContent-Type HTTPヘッダに設定されます。

Content-Type HTTPヘッダには，MediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダの値は次のメソッドでも変更できます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびentity(Object entity, String type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

get(Class<T> c)メソッド

説明

HTTP GETメソッドを呼び出します。

構文

public <T> T get(Class<T> c)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

get(GenericType<T> gt)メソッド

説明

HTTP GETメソッドを呼び出します。

構文

public <T> T get(GenericType<T> gt)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

getRequestBuilder()メソッド

説明

ビルダ（WebResource.Builderオブジェクト）を取得します。

構文

public WebResource.Builder getRequestBuilder()

パラメタ

ありません。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

ありません。

getURI()メソッド

説明

WebリソースのURIを取得します。URIにはリクエストの対象となるリソースを識別する情報が含まれます。

構文

public URI getURI()

パラメタ

ありません。

戻り値

WebリソースのURIを返します。

注意事項

ありません。

getUriBuilder()メソッド

説明

URIビルダ（URIBuilderオブジェクト）を取得します。

構文

public UriBuilder getUriBuilder()

パラメタ

ありません。

戻り値

URIビルダ（URIBuilderオブジェクト）を返します。

注意事項

このWebResourceオブジェクトが保持するWebリソースのURIから作成されたURIビルダ（URIBuilderオブジェクト）が返ります。

head()メソッド

説明

HTTP HEADメソッドを呼び出します。

構文

public ClientResponse head()

パラメタ

ありません。

戻り値

HTTPレスポンスを返します。

注意事項

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

header(String name, Object value)メソッド

説明

HTTPヘッダを追加します。

構文

public WebResource.Builder header(String name,

Object value)

パラメタ

name

HTTPヘッダ名です。

value

HTTPヘッダの値です。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

nameパラメタとvalueパラメタ両方の値がnullの場合，呼び出しは無視されます。

nameパラメタの値がnullではない場合も，valueパラメタの値がnullのとき，呼び出しは無視されます。

nameパラメタの値がnullで，かつvalueパラメタの値がnullではない場合，エラーとなり（KDJJ18888-E），NullPointerExceptionをラップしたClientHandlerExceptionがスローされます。

このメソッドでContent-Length，Connection，Hostの各HTTPヘッダを設定することはできません。nameパラメタにこれらが指定された場合，valueパラメタの値がnullではないときでも，呼び出しは無視されます。なお，それぞれのHTTPヘッダはHttpURLConnectionによって設定されます。

nameパラメタで指定されたHTTPヘッダの値はvalueパラメタで指定されたnullではないオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。valueパラメタには標準仕様に従って値を指定してください。

accept，acceptLanguage，cookieの各HTTPヘッダは，次のメソッドでも追加できます。

ClientRequest.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

cookie(Cookie cookie)メソッド

WebResourceクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

cookie(Cookie cookie)メソッド

WebResource.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

cookie(Cookie cookie)メソッド

これらのメソッドおよびheader(String name, Object value)メソッドで，各HTTPヘッダが追加されていない場合の動作は，HttpURLConnectionオブジェクトに各HTTPヘッダを追加しない場合と同様です。

Content-Type HTTPヘッダが次のメソッドですでに設定されていた場合，valueパラメタの値で上書きされます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびheader(String name, Object value)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

method(String method)メソッド

説明

HTTPメソッドを呼び出します。リクエストにはエンティティを含めません。また，レスポンスのエンティティも受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void method(String method)

throws UniformInterfaceException

パラメタ

method

HTTPメソッド名です。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

method(String method, Class<T> c)メソッド

説明

HTTPメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T method(String method,

Class<T> c)

throws UniformInterfaceException

パラメタ

method

HTTPメソッドです。

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

method(String method, Class<T> c, Object requestEntity)メソッド

説明

HTTPメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T method(String method,

Class<T> c,

Object requestEntity)

throws UniformInterfaceException

パラメタ

method

HTTPメソッドです。

c

HTTPレスポンスのエンティティの型です。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

method(String method, GenericType<T> gt)メソッド

説明

HTTPメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T method(String method,

GenericType<T> gt)

throws UniformInterfaceException

パラメタ

method

HTTPメソッドです。

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

method(String method, GenericType<T> gt, Object requestEntity)メソッド

説明

HTTPメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T method(String method,

GenericType<T> gt,

Object requestEntity)

throws UniformInterfaceException

パラメタ

method

HTTPメソッドです。

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

method(String method, Object requestEntity)メソッド

説明

HTTPメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void method(String method,

Object requestEntity)

throws UniformInterfaceException

パラメタ

method

HTTPメソッドです。

requestEntity

HTTPリクエストのエンティティです。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

options(Class<T> c)メソッド

説明

HTTP OPTIONSメソッドを呼び出します。

構文

public <T> T options(Class<T> c)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

options(GenericType<T> gt)メソッド

説明

HTTP OPTIONSメソッドを呼び出します。

構文

public <T> T options(GenericType<T> gt)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

path(String path)メソッド

説明

このオブジェクト（WebResourceオブジェクト）から新しくWebResourceオブジェクトを生成します。生成されるオブジェクトが保持するWebリソースのURIは，このオブジェクトが保持するWebリソースのURIにパラメタで指定されたパスが追加されたURIです。

構文

public WebResource path(String path)

パラメタ

path

追加するパスです。

戻り値

新しく生成したWebResourceオブジェクトを返します。

注意事項

pathパラメタにnullが設定された場合，IllegalArgumentExceptionがスローされます。

pathパラメタにはnull以外の正しいパスを指定してください。無効な文字は，標準仕様に従って自動的にURLエンコードされます。

クエリストリングはパスの一部ではないため，疑問符（?）は無効な文字と見なされて自動的にURLエンコードされることに注意してください。エンコードされない文字は次のとおりです。

!　$　&　'　(　)　*　+　-　/　;　=　@　_　~　.　,

半角英数字（0〜9，A〜Z，a〜z）

すでにURLエンコードされたトークンは正しく認識されるため，二重にURLエンコードされることはありません。

このオブジェクト（WebResourceオブジェクト）が保持するWebリソースのURIとpathパラメタで指定されたパスの間には，必要に応じて自動的にスラッシュ（/）が挿入されます。またスラッシュ（/）が二重になるような場合は自動的に補正されます。

このオブジェクト（WebResourceオブジェクト）のエンティティは，このメソッドで新しく生成されたWebResourceオブジェクトにはコピーされません。

post()メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにはエンティティを含めません。また，レスポンスのエンティティも受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void post()

throws UniformInterfaceException

パラメタ

ありません。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

post(Class<T> c)メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T post(Class<T> c)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

post(Class<T> c, Object requestEntity)メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T post(Class<T> c,

Object requestEntity)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

post(GenericType<T> gt)メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T post(GenericType<T> gt)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

post(GenericType<T> gt, Object requestEntity)メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T post(GenericType<T> gt,

Object requestEntity)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

post(Object requestEntity)メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにエンティティを含めます。レスポンスのエンティティは受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void post(Object requestEntity)

throws UniformInterfaceException

パラメタ

requestEntity

HTTPリクエストのエンティティです。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put()メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにはエンティティを含めません。また，レスポンスのエンティティも受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void put()

throws UniformInterfaceException

パラメタ

ありません。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put(Class<T> c)メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T put(Class<T> c)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put(Class<T> c, Object requestEntity)メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T put(Class<T> c,

Object requestEntity)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put(GenericType<T> gt)メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T put(GenericType<T> gt)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put(GenericType<T> gt, Object requestEntity)メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T put(GenericType<T> gt,

Object requestEntity)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put(Object requestEntity)メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void put(Object requestEntity)

throws UniformInterfaceException

パラメタ

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

queryParam(String key, String value)メソッド

説明

このオブジェクト（WebResourceオブジェクト）から新しくWebResourceオブジェクトを生成します。生成されるオブジェクトが保持するWebリソースのURIは，このオブジェクトが保持するWebリソースのURIに，パラメタに指定されたクエリパラメタが追加されたURIです。

構文

public WebResource queryParam(String key,

String value)

パラメタ

key

クエリパラメタ名です。

value

クエリパラメタの値です。

戻り値

新しく生成したWebResourceオブジェクトを返します。

注意事項

keyパラメタまたはvalueパラメタのどちらかにnullが設定された場合，IllegalArgumentExceptionがスローされます。

keyパラメタおよびvalueパラメタには正しいクエリパラメタの名称および値を指定してください。無効な文字は，標準仕様に従って自動的にURLエンコードされます。

エンコードされない文字は次のとおりです。

!　$　'　(　)　*　-　/　;　?　@　_　~　.　,

半角英数字（0〜9，A〜Z，a〜z）

すでにURLエンコードされたトークンは正しく認識されるため，二重にURLエンコードされることはありません。

空白は「+」にエンコードされます。

新しく生成されるWebResourceオブジェクトのクエリパラメタは，このオブジェクト（WebResourceオブジェクト）のクエリパラメタに，パラメタに指定されたクエリパラメタが追加されたものです。なお，同じ名称のクエリパラメタがこのオブジェクトに存在している場合も含みます。

このオブジェクト（WebResourceオブジェクト）のエンティティは，このメソッドで新しく生成されたWebResourceオブジェクトにはコピーされません。

queryParams(MultivaluedMap<String, String> params)メソッド

説明

このオブジェクト（WebResourceオブジェクト）から新しくWebResourceオブジェクトを生成します。生成されるオブジェクトが保持するWebリソースのURIは，このオブジェクトが保持するWebリソースのURIに，パラメタに指定されたクエリパラメタが追加されたURIです。

構文

public WebResource queryParams(MultivaluedMap<String,String> params)

パラメタ

params

クエリパラメタのマップです。

戻り値

新しく生成したWebResourceオブジェクトを返します。

注意事項

paramsパラメタにnullが指定された場合，NullPointerExceptionがスローされます。

paramsパラメタで指定されたクエリパラメタのマップにnullであるキーが含まれている場合，IllegalArgumentExceptionがスローされます。

paramsパラメタで指定されたクエリパラメタのマップに含まれるキーと値の組み合わせのうち，キーがnull以外で値がnullであるものについては，キーだけが新しく生成されたWebResourceオブジェクトのクエリパラメタとして追加されます。

paramsパラメタには正しいクエリパラメタを指定してください。無効な文字は，標準仕様に従って自動的にURLエンコードされます。

エンコードされない文字は次のとおりです。

!　$　'　(　)　*　-　/　;　?　@　_　~　.　,

半角英数字（0〜9，A〜Z，a〜z）

すでにURLエンコードされたトークンは正しく認識されるため，二重にURLエンコードされることはありません。

空白は「+」にエンコードされます。

新しく生成されるWebResourceオブジェクトのクエリパラメタは，このオブジェクト（WebResourceオブジェクト）のクエリパラメタに，パラメタに指定されたクエリパラメタが追加されたものです。なお，同じ名称のクエリパラメタがこのオブジェクトに存在している場合も含みます。

このオブジェクト（WebResourceオブジェクト）のエンティティは，このメソッドで新しく生成されたWebResourceオブジェクトにはコピーされません。

type(MediaType type)メソッド

説明

MIMEメディアタイプを設定します。

構文

public WebResource.Builder type(MediaType type)

パラメタ

type

MIMEメディアタイプです。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typeパラメタに指定されたnullでない値がContent-Type HTTPヘッダに設定されます。nullの値は無視されContent-Type HTTPヘッダには設定されません。

Content-Type HTTPヘッダには，MediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダが次のメソッドですでに設定されていた場合，値は上書きされます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびtype(MediaType type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前にHttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

type(String type)メソッド

説明

MIMEメディアタイプを設定します。

構文

public WebResource.Builder type(String type)

パラメタ

type

MIMEメディアタイプです。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typeパラメタにnullまたは空の文字列が設定された場合，IllegalArgumentExceptionがスローされます。

Content-Type HTTPヘッダには，MediaTypeクラスのvalueOf(String)スタティックメソッドのパラメタにtypeパラメタを指定して構築したMediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtypeパラメタに指定される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダが次のメソッドですでに設定されていた場合，typeパラメタの値で上書きされます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびtype(String type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

uri(java.net.URI uri)メソッド

説明

このオブジェクト（WebResourceオブジェクト）から新しくWebResourceオブジェクトを生成します。

パラメタに指定されたURIにスラッシュ（/）で始まるパスコンポーネントが含まれていた場合，新しく生成されるWebResourceオブジェクトが保持するWebリソースのURIのパスは置き換えられます。スラッシュ（/）で始まるパスコンポーネントが含まれない場合，新しく生成されるWebResourceオブジェクトが保持するWebリソースのURIのパスは，このオブジェクト（WebResourceオブジェクト）のパスにそのパスコンポーネントが追加されたパスになります。

パラメタに指定されたURIにクエリパラメタが含まれていた場合，新しく生成されるWebResourceオブジェクトが保持するWebリソースのURIのクエリパラメタはそのクエリパラメタになります。このオブジェクトが保持するWebリソースのURIにクエリパラメタがあれば置き換えられます。

構文

public WebResource uri(URI uri)

パラメタ

uri

WebリソースのURIです。

戻り値

新しく生成したWebResourceオブジェクトを返します。

注意事項

uriパラメタには正しいURIを指定してください。uriパラメタは自動ではURLエンコーディングされません。必要に応じてURLエンコードした値をuriパラメタに指定してください。

このオブジェクト（WebResourceオブジェクト）のエンティティは，このメソッドで新しく生成されたWebResourceオブジェクトにはコピーされません。

uriパラメタにnullが指定された場合，NullPointerExceptionがスローされます。

25.11　WebResource.Builderクラスのメソッド仕様と注意事項

ここでは，WebResource.Builderクラスのメソッドの仕様，および利用する場合の注意事項について説明します。

accept(MediaType... types)メソッド

説明

受信できるMIMEメディアタイプを追加します。

構文

public T accept(MediaType... types)

パラメタ

types

受信できるMIMEメディアタイプの配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typesパラメタに含まれるnullでない値がAccept HTTPヘッダに追加されます。nullの値は無視されAccept HTTPヘッダには追加されません。

Accept HTTPヘッダには，MediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Accept HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

WebResourceクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

accept(String... types)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびaccept(MediaType... types)メソッドで，受信できるMIMEメディアタイプが一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept HTTPヘッダを追加しない場合の動作と同様です。

accept(String... types)メソッド

説明

受信できるMIMEメディアタイプを追加します。

構文

public T accept(String... types)

パラメタ

types

受信できるMIMEメディアタイプの配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typesパラメタに含まれるnullでない値がAccept HTTPヘッダに追加されます。nullの値は無視されAccept HTTPヘッダには追加されません。

Accept HTTPヘッダには，指定された値がそのまま設定されます。JAX-RSエンジンは指定された値を検証しません。標準仕様に従って値を指定してください。

Accept HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Buildeクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

WebResourceクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

accept(MediaType... types)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびaccept(String... types)メソッドで，受信できるMIMEメディアタイプが一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept HTTPヘッダを追加しない場合の動作と同様です。

acceptLanguage(Locale... locales)メソッド

説明

受信できる言語を追加します。

構文

public T acceptLanguage(Locale... locales)

パラメタ

locales

受信できる言語の配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

localesパラメタに含まれるnullでない値がAccept-Language HTTPヘッダに追加されます。nullの値は無視されAccept-Language HTTPヘッダには追加されません。

Accept-Language HTTPヘッダには，LocaleオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Accept-Language HTTPヘッダの値は次のメソッドでも変更できます。

ClientRequest.Builderクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

WebResourceクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびacceptLanguage(Locale... locales)メソッドで，受信できる言語が一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept-Language HTTPヘッダを設定しない場合の動作と同様です。

acceptLanguage(String... locales)メソッド

説明

受信できる言語を追加します。

構文

public T acceptLanguage(String... locales)

パラメタ

locales

受信できる言語の配列です。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

localesパラメタに含まれるnullでない値がAccept-Language HTTPヘッダに追加されます。nullの値は無視されAccept-Language HTTPヘッダには追加されません。

Accept-Language HTTPヘッダには，指定された値がそのまま設定されます。JAX-RSエンジンは指定された値を検証しません。標準仕様に従って値を指定してください。

Accept-Language HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Builderクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

WebResourceクラス

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

acceptLanguage(Locale... locales)メソッド

header(String name, Object value)メソッド

これらのメソッドおよびacceptLanguage(String... locales)メソッドで，受信できる言語が一つも追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにAccept-Language HTTPヘッダを追加しない場合の動作と同様です。

cookie(Cookie cookie)メソッド

説明

Cookieを設定します。

構文

public T cookie(Cookie cookie)

パラメタ

cookie

設定するCookieです。

戻り値

WebResourceオブジェクトを構築するためのビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

null以外の値がCookie HTTPヘッダに追加されます。nullの値は無視されCookie HTTPヘッダには追加されません。

Cookie HTTPヘッダには，CookieオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Cookie HTTPヘッダの値は次のメソッドでも追加できます。

ClientRequest.Builderクラス

cookie(Cookie cookie)メソッド

header(String name, Object value)メソッド

WebResourceクラス

cookie(Cookie cookie)メソッド

header(String name, Object value)メソッド

WebResource.Builderクラス

header(String name, Object value)メソッド

これらのメソッドおよびcookie(Cookie cookie)メソッドで，Cookieが追加されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにCookie HTTPヘッダを追加しない場合の動作と同様です。

delete()メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにはエンティティを含めません。また，レスポンスのエンティティも受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void delete()

throws UniformInterfaceException

パラメタ

ありません。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

delete(Class<T> c)メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T delete(Class<T> c)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

delete(Class<T> c, Object requestEntity)メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T delete(Class<T> c,

Object requestEntity)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

delete(GenericType<T> gt)メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T delete(GenericType<T> gt)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

delete(GenericType<T> gt, Object requestEntity)メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T delete(GenericType<T> gt,

Object requestEntity)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

delete(Object requestEntity)メソッド

説明

HTTP DELETEメソッドを呼び出します。リクエストにエンティティを含めます。レスポンスのエンティティは受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void delete(Object requestEntity)

throws UniformInterfaceException

パラメタ

requestEntity

HTTPリクエストのエンティティです。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

entity(Object entity)メソッド

説明

HTTPリクエストのエンティティを設定します。

構文

public T entity(Object entity)

パラメタ

entity

HTTPリクエストのエンティティです。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

エンティティパラメタに使用できるJavaの型については，「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

entity(Object entity, MediaType type)メソッド

説明

HTTPリクエストのエンティティのMIMEメディアタイプを設定します。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。ジェネリクスをエンティティに指定する場合は，GenericEntityオブジェクトを使用できます。

構文

public T entity(Object entity,

MediaType type)

パラメタ

entity

HTTPリクエストのエンティティです。

type

MIMEメディアタイプです。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typeパラメタに指定されたnullでない値がContent-Type HTTPヘッダに設定されます。nullの値は無視されContent-Type HTTPヘッダには設定されません。

Content-Type HTTPヘッダには，MediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダの値は次のメソッドでも変更できます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびentity(Object entity, MediaType type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

entity(Object entity, String type)メソッド

説明

HTTPリクエストのエンティティのMIMEメディアタイプを設定します。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。ジェネリクスをエンティティに指定する場合は，GenericEntityオブジェクトを使用できます。

構文

public T entity(Object entity,

String type)

パラメタ

entity

HTTPリクエストのエンティティです。

type

MIMEメディアタイプです。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typeパラメタにnullまたは空の文字列が設定された場合，IllegalArgumentExceptionがスローされます。

typeパラメタに指定されたnullでない値がContent-Type HTTPヘッダに設定されます。

Content-Type HTTPヘッダには，MediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダの値は次のメソッドでも変更できます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびentity(Object entity, String type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

get(Class<T> c)メソッド

説明

HTTP GETメソッドを呼び出します。

構文

public <T> T get(Class<T> c)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

get(GenericType<T> gt)メソッド

説明

HTTP GETメソッドを呼び出します。

構文

public <T> T get(GenericType<T> gt)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

head()メソッド

説明

HTTP HEADメソッドを呼び出します。

構文

public ClientResponse head()

パラメタ

ありません。

戻り値

HTTPレスポンスを返します。

注意事項

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

header(String name, Object value)メソッド

説明

HTTPヘッダを追加します。

構文

public T header(String name,

Object value)

パラメタ

name

HTTPヘッダ名です。

value

HTTPヘッダの値です。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

nameパラメタとvalueパラメタ両方の値がnullの場合，呼び出しは無視されます。

nameパラメタの値がnullではない場合も，valueパラメタの値がnullのとき，呼び出しは無視されます。

nameパラメタの値がnullで，かつvalueパラメタの値がnullではない場合，エラーとなり（KDJJ18888-E），NullPointerExceptionをラップしたClientHandlerExceptionがスローされます。

このメソッドでContent-Length，Connection，Hostの各HTTPヘッダを設定することはできません。nameパラメタにこれらが指定された場合，valueパラメタの値がnullではないときでも，呼び出しは無視されます。なお，それぞれのHTTPヘッダはHttpURLConnectionによって設定されます。

nameパラメタで指定されたHTTPヘッダの値はvalueパラメタで指定されたnullではないオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。valueパラメタには標準仕様に従って値を指定してください。

accept，acceptLanguage，cookieの各HTTPヘッダは，次のメソッドでも追加できます。

ClientRequest.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

cookie(Cookie cookie)メソッド

WebResourceクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

cookie(Cookie cookie)メソッド

WebResource.Builderクラス

accept(MediaType... types)メソッド

accept(String... types)メソッド

acceptLanguage(Locale... locales)メソッド

acceptLanguage(String... locales)メソッド

cookie(Cookie cookie)メソッド

これらのメソッドおよびheader(String name, Object value)メソッドで，各HTTPヘッダが追加されていない場合の動作は，HttpURLConnectionオブジェクトに各HTTPヘッダを追加しない場合と同様です。

Content-Type HTTPヘッダが次のメソッドですでに設定されていた場合，valueパラメタの値で上書きされます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

type(MediaType type)メソッド

type(String type)メソッド

これらのメソッドおよびheader(String name, Object value)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

method(String method)メソッド

説明

HTTPメソッドを呼び出します。リクエストにはエンティティを含めません。また，レスポンスのエンティティも受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void method(String method)

throws UniformInterfaceException

パラメタ

method

HTTPメソッド名です。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

method(String method, Class<T> c)メソッド

説明

HTTPメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T method(String method,

Class<T> c)

throws UniformInterfaceException

パラメタ

method

HTTPメソッドです。

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

method(String method, Class<T> c, Object requestEntity)メソッド

説明

HTTPメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T method(String method,

Class<T> c,

Object requestEntity)

throws UniformInterfaceException

パラメタ

method

HTTPメソッドです。

c

HTTPレスポンスのエンティティの型です。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

method(String method, GenericType<T> gt)メソッド

説明

HTTPメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T method(String method,

GenericType<T> gt)

throws UniformInterfaceException

パラメタ

method

HTTPメソッドです。

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

method(String method, GenericType<T> gt, Object requestEntity)メソッド

説明

HTTPメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T method(String method,

GenericType<T> gt,

Object requestEntity)

throws UniformInterfaceException

パラメタ

method

HTTPメソッドです。

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

method(String method, Object requestEntity)メソッド

説明

HTTPメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void method(String method,

Object requestEntity)

throws UniformInterfaceException

パラメタ

method

HTTPメソッドです。

requestEntity

HTTPリクエストのエンティティです。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

methodパラメタには，すべて大文字で「GET」「HEAD」「POST」「OPTIONS」「PUT」または「DELETE」のどれかを指定してください。

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

options(Class<T> c)メソッド

説明

HTTP OPTIONSメソッドを呼び出します。

構文

public <T> T options(Class<T> c)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

options(GenericType<T> gt)メソッド

説明

HTTP OPTIONSメソッドを呼び出します。

構文

public <T> T options(GenericType<T> gt)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

post()メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにはエンティティを含めません。また，レスポンスのエンティティも受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void post()

throws UniformInterfaceException

パラメタ

ありません。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

post(Class<T> c)メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにエンティティを含めません。なお，レスポンスのエンティティは受け取ります。

構文

public <T> T post(Class<T> c)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

post(Class<T> c, Object requestEntity)メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T post(Class<T> c,

Object requestEntity)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

post(GenericType<T> gt)メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T post(GenericType<T> gt)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

post(GenericType<T> gt, Object requestEntity)メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T post(GenericType<T> gt,

Object requestEntity)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

post(Object requestEntity)メソッド

説明

HTTP POSTメソッドを呼び出します。リクエストにエンティティを含めます。レスポンスのエンティティは受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void post(Object requestEntity)

throws UniformInterfaceException

パラメタ

requestEntity

HTTPリクエストのエンティティです。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put()メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにはエンティティを含めません。また，レスポンスのエンティティも受け取りません。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void put()

throws UniformInterfaceException

パラメタ

ありません。

戻り値

ありません。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put(Class<T> c)メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T put(Class<T> c)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put(Class<T> c, Object requestEntity)メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T put(Class<T> c,

Object requestEntity)

throws UniformInterfaceException

パラメタ

c

HTTPレスポンスのエンティティの型です。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，cパラメタがClientResponse型でない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put(GenericType<T> gt)メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T put(GenericType<T> gt)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put(GenericType<T> gt, Object requestEntity)メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

構文

public <T> T put(GenericType<T> gt,

Object requestEntity)

throws UniformInterfaceException

パラメタ

gt

HTTPレスポンスのエンティティの型を表現するGenericTypeオブジェクトです。

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

次のどちらかの条件を満たした場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

HTTPレスポンスのステータスコードが204である

HTTPレスポンスのステータスコードが300以上で，gtパラメタがClientResponse型を表現していない

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPレスポンスのエンティティに使用できるJavaの型については「25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

put(Object requestEntity)メソッド

説明

HTTP PUTメソッドを呼び出します。リクエストにエンティティを含めます。また，レスポンスのエンティティも受け取ります。

ステータスコードが300より小さい場合でレスポンスにエンティティが含まれるとき，そのエンティティは無視されます。

構文

public void put(Object requestEntity)

throws UniformInterfaceException

パラメタ

requestEntity

HTTPリクエストのエンティティです。

戻り値

指定されたGenericTypeオブジェクトで表現された型のオブジェクトを返します。

例外

UniformInterfaceException

HTTPレスポンスのステータスコードが300以上の場合にスローされます。ログにはKDJJ18888-Eのエラーメッセージが出力されます。

注意事項

HTTPリクエストのエンティティに使用できるJavaの型については「25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ」を参照してください。

HTTPリクエストまたはHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

type(MediaType type)メソッド

説明

MIMEメディアタイプを設定します。

構文

public T type(MediaType type)

パラメタ

type

MIMEメディアタイプです。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typeパラメタに指定されたnullでない値がContent-Type HTTPヘッダに設定されます。nullの値は無視されContent-Type HTTPヘッダには設定されません。

Content-Type HTTPヘッダには，MediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtoString()メソッドによって返される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダが次のメソッドですでに設定されていた場合，値は上書きされます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(String type)メソッド

これらのメソッドおよびtype(MediaType type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前にHttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

type(String type)メソッド

説明

MIMEメディアタイプを設定します。

構文

public T type(String type)

パラメタ

type

MIMEメディアタイプです。

戻り値

ビルダ（WebResource.Builderオブジェクト）を返します。

注意事項

typeパラメタにnullまたは空の文字列が設定された場合，IllegalArgumentExceptionがスローされます。

Content-Type HTTPヘッダには，MediaTypeクラスのvalueOf(String)スタティックメソッドのパラメタにtypeパラメタを指定して構築したMediaTypeオブジェクトのtoString()メソッドによって返される値が設定されます。JAX-RSエンジンはtypeパラメタに指定される値を検証しません。標準仕様に従って値を指定してください。

Content-Type HTTPヘッダが次のメソッドですでに設定されていた場合，typeパラメタの値で上書きされます。

ClientRequest.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResourceクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

type(String type)メソッド

WebResource.Builderクラス

entity(Object entity, MediaType type)メソッド

entity(Object entity, String type)メソッド

header(String name, Object value)メソッド

type(MediaType type)メソッド

これらのメソッドおよびtype(String type)メソッドで，MIMEメディアタイプが設定されない場合の動作は，HTTP通信を行う前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しない場合の動作と同様です。

25.12　DefaultClientConfigクラスの定数およびメソッドの仕様と注意事項

ここでは，DefaultClientConfigクラスの定数とメソッドの仕様，および利用する場合の注意事項について説明します。

PROPERTY_BUFFER_RESPONSE_ENTITY_ON_EXCEPTION定数

説明

例外発生時のレスポンスエンティティのバッファリングを設定するためのプロパティです。

構文

static final java.lang.String PROPERTY_BUFFER_RESPONSE_ENTITY_ON_EXCEPTION

注意事項

例外発生時のレスポンスエンティティのバッファリングの設定については，「13.1.2　共通定義ファイルの設定項目」を参照してください。プロパティについては「25.1.1　サポートするプロパティとフィーチャ」を参照してください。

PROPERTY_CHUNKED_ENCODING_SIZE定数

説明

チャンク転送エンコーディングを設定するためのプロパティです。

構文

static final java.lang.String PROPERTY_CHUNKED_ENCODING_SIZE

注意事項

チャンク転送エンコーディングの設定については，「13.1.2　共通定義ファイルの設定項目」を参照してください。プロパティについては「25.1.1　サポートするプロパティとフィーチャ」を参照してください。

PROPERTY_CONNECT_TIMEOUT定数

説明

クライアントソケットの接続タイムアウト値を設定するためのプロパティです。

構文

static final java.lang.String PROPERTY_CONNECT_TIMEOUT

注意事項

クライアントソケットの接続タイムアウト値の設定については，「13.1.2　共通定義ファイルの設定項目」を参照してください。プロパティについては「25.1.1　サポートするプロパティとフィーチャ」を参照してください。

PROPERTY_FOLLOW_REDIRECTS定数

説明

自動リダイレクトを設定するためのプロパティです。

構文

static final java.lang.String PROPERTY_FOLLOW_REDIRECTS

注意事項

自動リダイレクトの設定については，「13.1.2　共通定義ファイルの設定項目」を参照してください。プロパティについては「25.1.1　サポートするプロパティとフィーチャ」を参照してください。

PROPERTY_READ_TIMEOUT定数

説明

クライアントソケットの読み込みタイムアウト値を設定するためのプロパティです。

構文

static final java.lang.String PROPERTY_READ_TIMEOUT

注意事項

クライアントソケットの接続タイムアウト値の設定については，「13.1.2　共通定義ファイルの設定項目」を参照してください。プロパティについては「25.1.1　サポートするプロパティとフィーチャ」を参照してください。

getPropertyAsFeature(String featureName)メソッド

説明

Boolean型のプロパティをフィーチャとしてプロパティマップから取得します。

構文

public boolean getPropertyAsFeature(String name)

パラメタ

featurename

取得するプロパティ名（フィーチャ名）です。

戻り値

プロパティマップに指定された名称のBoolean型のプロパティがある場合でその値がtrueのときはtrueを，そのほかのときはfalseを返します。

注意事項

ありません。

getFeatures()メソッド

説明

すべてのフィーチャを含むマップを取得します。

構文

public Map<String,Boolean> getFeatures()

パラメタ

ありません。

戻り値

フィーチャのマップを返します。nullを返すことはありません。

注意事項

getFeatures()メソッドの使用例を次に示します。

// ClientConfigオブジェクトを生成する
ClientConfig cc = new DefaultClientConfig();
// ClientConfigオブジェクトにJSON POJOマッピングを有効にするための
// フィーチャを追加する
cc.getFeatures().put(JSONConfiguration.FEATURE_POJO_MAPPING, true);
// 上記で生成したClientConfigオブジェクトを指定して
// Clientオブジェクトを生成する
Client client = Client.create(cc);
// 読み込みタイムアウト値を設定する
client.getProperties().put(ClientConfig.PROPERTY_READ_TIMEOUT, 10000);

// JSONフォーマットにマッピングするPOJOオブジェクトを生成する
Pojo pojo = new Pojo();

// HTTPリクエストを生成し，マッピングされたPOJOオブジェクトを送信する
ClientRequest cRequest = ClientRequest.create().entity(pojo).type("application/json").build(new URI("http://example.com/example"), "POST");
try{
  // HTTPレスポンスをClientResponseオブジェクトとして受信する
  ClientResponse cResponse = client.handle(cRequest);
} catch(ClientHandlerException e){
  // 適切な処理を実行する
}

この例では，まず，getFeaturesメソッドで変更可能なプロパティマップを取得し，JSON POJOマッピングを有効にするためのフィーチャを追加しています。次にClientRequestオブジェクトを作成し，Clientクラスのhandle()メソッドを利用してHTTP通信を行い，HTTPレスポンスをClientResponseオブジェクトとして受信しています。HTTPリクエストのエンティティとして送信したPOJOオブジェクトは，JSON POJOマッピングによってJSONフォーマットでマッピングされています。これはJSON POJOマッピングを有効にするためのフィーチャを追加したことで実現されています。

getFeature(String featureName)メソッド

説明

フィーチャの値を取得します。

構文

public boolean getFeature(String featureName)

パラメタ

featureName

フィーチャ名です。

戻り値

指定された名称のフィーチャが存在する場合で値がtrueのときはtrueを，そのほかのときはfalseを返します。

注意事項

nullまたは空の文字列がfeatureNameパラメタに設定された場合はfalseを返します。

getProperties()メソッド

説明

クライアントに関連するすべてのフィーチャのマップを取得します。

構文

public Map<String,Object> getProperties()

パラメタ

ありません。

戻り値

フィーチャのマップを返します。nullを返すことはありません。

注意事項

getProperties()メソッドの使用例を次に示します。

// クライアントを設定する
ClientConfig cc = new DefaultClientConfig();

// 読み込みタイムアウト値を設定する
cc.getProperties().put(ClientConfig.PROPERTY_READ_TIMEOUT, 10000);

// クライアントの設定を利用してClientオブジェクトを生成する
Client client = Client.create(cc);

// HTTPリクエストを生成する
ClientRequest cRequest = ClientRequest.create().build(new URI("http://example.com/example"), "GET");
try{
  // HTTPレスポンスをClientResponseオブジェクトとして受信する
  ClientResponse cResponse = client.handle(cRequest);
} catch(ClientHandlerException e){
  // 適切な処理を実行する
}

この例では，まず，getPropertiesメソッドで変更可能なプロパティマップを取得し，読み込みタイムアウト値を10,000ミリ秒に設定しています。Clientクラスのcreate(ClientConfig cc)メソッドではこのクライアント設定を使って，クライアントインスタンスを作成します。次にClientRequestオブジェクトを作成し，Clientクラスのhandleメソッドを利用してHTTP通信を行い，HTTPレスポンスをClientResponseオブジェクトとして受信しています。HTTPレスポンスが完全に読み込まれるまでに読み込みタイムアウトが発生した場合，エラーとなり（KDJJ18888-E），SocketTimeoutExceptionをラップしたClientHandlerExceptionがスローされます。

getProperty(String propertyName)メソッド

説明

プロパティの値を取得します。

構文

public Object getProperty(String propertyName)

パラメタ

propertyName

プロパティ名です。

戻り値

プロパティの値を返します。propertyNameパラメタに指定された名称のパラメタが存在しない場合はnullを返します。

注意事項

nullまたは空の文字列がpropertyNameパラメタに指定された場合はnullを返します。

25.13　HTTPSPropertiesクラスの定数，コンストラクタおよびメソッドの仕様と注意事項

ここでは，HTTPSPropertiesクラスの定数，コンストラクタおよびメソッドの仕様，および利用する場合の注意事項について説明します。

PROPERTY_HTTPS_PROPERTIES定数

説明

HTTPSPropertiesオブジェクトを設定するためのプロパティです。変更可能なプロパティマップにHTTPSPropertiesオブジェクトを追加するときに使用します。プロパティについては「25.1.1　サポートするプロパティとフィーチャ」を参照してください。

構文

public static final java.lang.String PROPERTY_HTTPS_PROPERTIES

HTTPSProperties()コンストラクタ

説明

javax.net.ssl.SSLContextクラスのgetInstance()メソッドを引数に"SSL"を指定して生成したSSLContextオブジェクトからHTTPSPropertiesオブジェクトを構築します。構築されるHTTPSPropertiesオブジェクトは，javax.net.ssl.HostnameVerifierオブジェクトを含みません。

構文

public HTTPSProperties()

throws java.security.NoSuchAlgorithmException

パラメタ

ありません。

戻り値

ありません。

例外

NoSuchAlgorithmException

SSLContextオブジェクトが生成できなかった場合にスローされます。

注意事項

ありません。

HTTPSProperties(HostnameVerifier hv)コンストラクタ

説明

引数に指定されたjavax.net.ssl.HostnameVerifierオブジェクトとjavax.net.ssl.SSLContextクラスのgetInstance()メソッドを引数に"SSL"を指定して生成したSSLContextオブジェクトからHTTPSPropertiesオブジェクトを構築します。

構文

public HTTPSProperties(HostnameVerifier hv)

throws NoSuchAlgorithmException

パラメタ

hv

構築するHTTPSPropertiesオブジェクトに設定するHostnameVerifierオブジェクトです。

戻り値

ありません。

例外

NoSuchAlgorithmException

SSLContextオブジェクトが生成できなかった場合にスローされます。

注意事項

hvパラメタにnull値が設定された場合の動作は，HTTPリクエストを生成する前にHttpsURLConnectionクラスにHostnameVerifierオブジェクトを設定しない場合と同じです。

null以外の値をhvパラメタに指定した場合の動作は，同じ値をHttpsURLConnectionクラスのsetHostnameVerifier()メソッドに指定した場合と同じです。なお，JAX-RSエンジンはパラメタに指定された値を検証しません。パラメタには標準仕様に従って値を指定してください。

HTTPSProperties(HostnameVerifier hv, SSLContext c)コンストラクタ

説明

引数に指定されたjavax.net.ssl.HostnameVerifierおよびjavax.net.ssl.SSLContextオブジェクトからHTTPSPropertiesオブジェクトを構築します。

構文

public HTTPSProperties(HostnameVerifier hv,

SSLContext c)

パラメタ

hv

構築するHTTPSPropertiesオブジェクトに設定するHostnameVerifierです。

c

構築するHTTPSPropertiesオブジェクトに設定するSSLContextです。nullは指定できません。

戻り値

ありません。

注意事項

cパラメタにnullが設定された場合，IllegalArgumentExceptionがスローされます。

hvパラメタにnullが設定された場合の動作は，HTTPリクエストを生成する前にHttpsURLConnectionクラスにHostnameVerifierオブジェクトを設定しない場合と同じです。

null以外の値をhvパラメタに指定した場合の動作は，同じ値をHttpsURLConnectionクラスのsetHostnameVerifier()メソッドに指定した場合と同じです。

null以外の値をcパラメタに指定した場合の動作は，cパラメタに対してgetSocketFactory()メソッドを呼び出して取得した値をHttpsURLConnectionクラスのsetSSLSocketFactory()メソッドに指定した場合と同じです。

JAX-RSエンジンはパラメタに指定された値を検証しません。パラメタには標準仕様に従って値を指定してください。

getHostnameVerifier()メソッド

説明

HostnameVerifierオブジェクトを取得します。

構文

public HostnameVerifier getHostnameVerifier()

パラメタ

ありません。

戻り値

HostnameVerifierオブジェクトを返します。HostnameVerifierオブジェクトがこのオブジェクト（HTTPSPropertiesオブジェクト）に設定されていない場合はnullを返します。

注意事項

HostnameVerifierオブジェクトはHTTPSProperties(HostnameVerifier hv)コンストラクタおよびHTTPSProperties(HostnameVerifier hv, SSLContext c)コンストラクタで設定できます。

getSSLContext()メソッド

説明

SSLContextオブジェクトを取得します。

構文

public SSLContext getSSLContext()

パラメタ

ありません。

戻り値

SSLContextオブジェクトを返します。SSLContextオブジェクトがこのオブジェクト (HTTPSPropertiesオブジェクト) に設定されていない場合はnullを返します。

注意事項

SSLContextオブジェクトはHTTPSProperties(HostnameVerifier hv, SSLContext)コンストラクタで設定できます。

25.14　MultivaluedMapImplクラスのコンストラクタおよびメソッド仕様と注意事項

MultivaluedMapImplクラスは，javax.ws.rs.core.MultivaluedMapインタフェースの実装クラスです。MultivaluedMapImplクラスのメソッドの仕様についてはJAX-RS APIのドキュメントを参照してください。

ここでは，MultivaluedMapImplクラスのコンストラクタおよびメソッドを利用する場合の注意事項について説明します。

MultivaluedMapImplクラスはスレッドセーフではありません。

MultivaluedMapImplクラスは簡易的な実装クラスであり，最小限の機能だけを提供しています。javax.ws.rs.core.MultivaluedMapインタフェースのaddメソッド，getFirstメソッド，およびputSingleメソッドだけを使用できます。

java.util.Mapインタフェースのほかのメソッド（putメソッドやremoveメソッドなど）は呼び出すことができません。addメソッド，getFirstメソッド，およびputSingleメソッド以外のメソッドを使用した場合，JAX-RSエンジンの動作は保証されません。

MultivaluedMapImplクラスの機能が不足している場合は，javax.ws.rs.core.MultivaluedMapインタフェースを実装したクラスを個別に作成してください。

add(String key, String value)メソッド，およびputSingle(String key, String value)メソッドでvalueパラメタにnullが指定された場合，nullの代わりに空の文字列（""）が値として追加されます。

25.15　使用できるJavaの型とMIMEメディアタイプの組み合わせ

この節では，RESTful Webサービス用クライアントAPIのエンティティパラメタおよび戻り値に使用できるJavaの型とMIMEメディアタイプの組み合わせについて説明します。なお，POJOにJAXB仕様のアノテーションは使用しないでください。使用した場合，説明とは異なる動作になるおそれがあります。

25.15.1　HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ

HTTPリクエストのエンティティボディに使用できるJava型とMIMEメディアタイプの組み合わせを次の表に示します。なお，これ以外の組み合わせの場合，JAX-RSエンジンの動作は保証されません。

表25‒6　エンティティボディに使用できるJavaの型とMIMEメディアタイプの組み合わせ

項番

Javaの型

charset※1

Content-Type HTTPヘッダ

Content-Type HTTPヘッダ※2

（JAX-RSエンジン）

1

byte[]

×

任意(*/*)

application/octet-stream

2

java.lang.String

○

任意(*/*)

text/plain

3

java.io.InputStream

×

任意(*/*)

application/octet-stream

4

java.io.Reader

○

任意(*/*)

text/plain

5

java.io.File

×

任意(*/*)

application/octet-stream

6

javax.activation.DataSource

×

任意(*/*)

application/octet-stream

7

javax.xml.transform.Source※3

×

任意(*/*)

application/xml

8

javax.xml.bind.JAXBElement<String>※4

○

ext/xml，

application/xml，

application/*+xml

application/xml

9

XmlRootElementアノテーションでアノテートされたJAXBクラス※4

○

text/xml，

application/xml，

application/*+xml

application/xml

10

javax.ws.rs.core.MultivaluedMap<String,String>

○

application/x-www-form-urlencoded

application/x-www-form-urlencoded

11

javax.ws.rs.core.StreamingOutput

×

任意(*/*)

application/octet-stream

12

org.w3c.dom.Document

×

任意(*/*)

application/xml

13

java.awt.image.RenderedImage

×

image/jpeg

application/octet-stream

14

javax.ws.rs.core.GenericEntity<T>※5

△

Tに指定した型と同じMIMEメディアタイプです。

Tに指定した型と同じMIMEメディアタイプです。

15

POJO※6

×※7

application/json

application/octet-stream

（凡例）

任意(*/*)：すべてのMIMEメディアタイプをサポートしていることを示します。

注※1

Content-Type HTTPヘッダにcharsetパラメタが含まれる場合，HTTPリクエストに変換するときにその情報が考慮されるかどうかを示します。

○：考慮されます。Content-Type HTTPヘッダにcharsetパラメタが含まれない場合は，UTF-8が仮定されます。

△：Tに指定した型に依存します。

×：考慮されません。

注※2

ClientRequestオブジェクトまたはWebリソースオブジェクトで，Content-Type HTTPヘッダが指定されていない場合，エンティティがnull以外のときは，このカラムで指定したContent-Typeを考慮して，HTTPリクエストのContent-Type HTTPヘッダを設定します。

エンティティがnullのときの動作は，HTTPリクエストをする前に，HttpURLConnectionオブジェクトにContent-Type HTTPヘッダを設定しないときの動作と同じです。

注※3

次に示す実装クラスを使用できます。

・javax.xml.transform.stream.StreamSource

・javax.xml.transform.sax.SAXSource

・javax.xml.transform.dom.DOMSource

注※4

MIMEメディアタイプがapplication/fastinfosetまたはapplication/jsonの場合，エラーにならないで正常終了します。

注※5

Tにはこの表の項番1から項番13，および項番15の型を指定できます。

注※6

JSON POJOマッピングを有効にしてください。JSON POJOマッピングが有効でない場合の動作は，サポートされないJava型がエンティティパラメタに指定された場合の動作と同じです。JSON POJOマッピングを有効にする方法については「18.　JSON POJOマッピング」を参照してください。

注※7

Content-Type HTTPヘッダにcharsetパラメタを追加しないでください。

指定したJavaの型がサポートされていない型で，値がnullでない場合，エラーとなり（KDJJ10032-EおよびKDJJ18888-E），ClientHandlerExceptionがスローされます。ただし，指定したJavaの型がjavax.mail.internet.MimeMultipartで，MIMEメディアタイプがmultipart/*のときはエラーにならずに正常終了します。

次に示すJavaの型では，HTTPリクエストのエンティティボディが使用できないMIMEメディアタイプの場合，エラーとなり（KDJJ10032-EおよびKDJJ18888-E），ClientHandlerExceptionがスローされます。

javax.xml.bind.JAXBElement<String>

XmlRootElementアノテーションでアノテートされたJAXBクラス

javax.ws.rs.core.MultivaluedMap<String, String>

java.awt.image.RenderedImage

POJO

ただし，1.または2.でHTTPリクエストのエンティティボディのMIMEメディアタイプがapplication/fastinfosetまたはapplication/jsonのときは，エラーにならないで正常終了します。

HTTPリクエストおよびHTTPレスポンスの処理中に例外が発生した場合，エラーとなり（KDJJ18888-E），その例外をラップしたClientHandlerExceptionがスローされます。

また，HTTPメソッドの種類によっては次の注意事項があります。

HTTPメソッドがDELETE，HEAD，またはOPTIONSのどれかの場合，HTTPリクエストのエンティティボディにはnullでない値を指定しないでください。nullでない値が指定されたときはエラーとなり（KDJJ18888-E），ClientHandlerExceptionがスローされます。

HTTPメソッドがGETの場合，HTTPリクエストのエンティティボディにはnullでない値を指定しないでください。nullでない値が指定されたときは無視されます。

HTTPメソッドがPOSTまたはPUTでHTTPリクエストのエンティティボディにnullが指定された場合，送信されるHTTPリクエストにエンティティボディは含まれません。

25.15.2　HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ

戻り値に使用できるJava型とMIMEメディアタイプの組み合わせを次の表に示します。

表25‒7　エンティティボディの戻り値に使用できるJavaの型とMIMEメディアタイプの組み合わせ

項番

Javaの型

charset※1

MIMEメディアタイプ

1

byte[]

×

任意(*/*)

2

java.lang.String

○

任意(*/*)

3

java.io.InputStream

×

任意(*/*)

4

java.io.Reader

○

任意(*/*)

5

java.io.File※2

×

任意(*/*)

6

javax.activation.DataSource

×

任意(*/*)

7

javax.xml.transform.Source※3

×

任意(*/*)

8

javax.xml.bind.JAXBElement<String>※4，※5

×

text/xml，

application/xml，

application/*+xml

9

XmlRootElementアノテーションおよび/またはXmlTypeアノテーションでアノテートされたJAXBクラス※5

×

text/xml，

application/xml，

application/*+xml

10

javax.ws.rs.core.MultivaluedMap<String,String>

○

application/x-www-form-urlencoded

11

org.w3c.dom.Document

×

任意(*/*)

12

java.awt.image.RenderedImage

×

application/octet-stream，

image/jpeg

13

com.cosminexus.jersey.core.provider.EntityHolder<T>※6

△

Tに指定した型と同じMIMEメディアタイプです。

14

com.cosminexus.jersey.api.client.GenericType<T>※7

△

Tに指定した型と同じMIMEメディアタイプです。

15

POJO※8

○

application/json

（凡例）

任意(*/*)：すべてのMIMEメディアタイプをサポートしていることを示します。

注※1

Content-Type HTTPヘッダにcharsetパラメタが含まれる場合，HTTPレスポンスにインジェクトするときにその情報が考慮されるかどうかを示します。

○：考慮されます。Content-Type HTTPヘッダにcharsetパラメタが含まれない場合は，UTF-8が仮定されます。

△：Tに指定した型に依存します。

×：考慮されません。

注※2

JAX-RSエンジンは，ローカルマシンにtempディレクトリを作成し，一時ファイルを保存します。

注※3

次に示す実装クラスを使用できます。

・javax.xml.transform.stream.StreamSource

・javax.xml.transform.sax.SAXSource

・javax.xml.transform.dom.DOMSource

なお，javax.xml.transform.stream.StreamSource，またはjavax.xml.transform.sax.SAXSourceを使用する場合は，汎用型（ClientResponse）でHTTPレスポンスを受信し，ClientResponseクラスのgetEntity()メソッドでエンティティのオブジェクトを取得してください。またその際，getEntity()メソッドを呼び出す前に，必ずbufferEntity()メソッドを呼び出してください。汎用型（ClientResponse）でHTTPレスポンスを受信する方法については「11.4.1　Webリソースクライアントのユースケース」を参照してください。

注※4

この表の項番14のTとして使用します。これ以外の使用は保証されません。

注※5

MIMEメディアタイプがapplication/fastinfosetまたはapplication/jsonの場合，エラーにならないで正常終了します。

注※6

この表の項番14のTとして使用します。Tにはこの表の項番2から項番12，および項番15の型を指定できます。これ以外の使用は保証されません。

注※7

Tにはこの表の項番2から項番13，および項番15の型を指定できます。

注※8

JSON POJOマッピングを有効にしてください。JSON POJOマッピングが有効でない場合の動作は，サポートされないJava型がエンティティパラメタに指定された場合の動作と同じです。JSON POJOマッピングを有効にする方法については「18.　JSON POJOマッピング」を参照してください。

指定したJavaの型がサポートされない型の場合，エラーとなり（KDJJ10031-EおよびKDJJ18888-E），ClientHandlerExceptionがスローされます。

戻り値が次に示すJavaの型で，HTTPレスポンスのエンティティボディが使用できないMIMEメディアタイプの場合，エラーとなり（KDJJ10031-EまたはKDJJ18888-E），ClientHandlerExceptionがスローされます。

javax.xml.bind.JAXBElement<String>

XmlRootElementアノテーションおよび/またはXmlTypeアノテーションでアノテートされたJAXBクラス

javax.ws.rs.core.MultivaluedMap<String,String>

java.awt.image.RenderedImage

POJO

HTTPレスポンスのエンティティボディからの変換でIOExceptionが発生した場合，エラーとなり（KDJJ18888-E），ClientHandlerExceptionがスローされます。

HTTPレスポンスのエンティティボディからの変換でIOException以外の例外がスローされた場合は，対応する例外がスローされます。なお，ログを確認するときは，JAX-RS機能のログファイルではなくJ2EEサーバのログファイルを確認してください

java.awt.image.RenderedImageのエンティティパラメタでは，Content-Type HTTPヘッダがimage/*の場合，エラーとなり（KDJJ18888-E），java.io.IOExceptionをラップしたClientHandlerExceptionがスローされます。

com.cosminexus.jersey.api.client.GenericType<T>のエンティティパラメタでは，HTTPレスポンスにエンティティボディがある場合，Tが表の項番1のとき，エラーとなり（KDJJ10031-EおよびKDJJ18888-E），ClientHandlerExceptionがスローされます。

com.cosminexus.jersey.core.provider.EntityHolder<T>のエンティティパラメタでは，HTTPレスポンスにエンティティボディがある場合，次に示すどちらかのときにエラーとなり（KDJJ10003-E），javax.ws.rs.WebApplicationExceptionがスローされます。

Tがサポートされない型（表の項番1，項番13，および項番14）のとき

Tがサポートされる型（表の項番2から項番12，および項番15）だが，HTTPレスポンスのエンティティボディが使用できないMIMEメディアタイプのとき

クライアントAPIがJ2EEサーバ上で動作する場合，エンティティボディに含まれるフォームパラメタ数の上限値のデフォルトは10,000です。エンティティパラメタの型がjavax.ws.rs.core.MultivaluedMap<String,String>，またはcom.cosminexus.jersey.core.provider.GenericType<EntityHolder<javax.ws.rs.core.MultivaluedMap<String,String>>>のとき，レスポンスのパラメタ数が指定した値を超えたときは，RuntimeExceptionがスローされます。必要に応じてJ2EEサーバ用ユーザプロパティファイル（usrconf.properties）のwebserver.connector.limit.max_parameter_countプロパティで変更してください。なお，ログを確認するときは，JAX-RS機能のログファイルではなくJ2EEサーバのログファイルを確認してください。

HTTPレスポンスにContent-Type HTTPヘッダが存在しない場合，MIMEメディアタイプはapplication/octet-streamであると見なされます。

25.16　RESTful Webサービス用クライアントAPIのスレッドセーフ性

RESTful Webサービス用クライアントAPIのスレッドセーフ性について次の表に示します。

表25‒8　RESTful Webサービス用クライアントAPIのスレッドセーフ性

項番

インタフェースまたはクラス

コンストラクタ／メソッド／フィールド

スレッドセーフ性※1

com.cosminexus.jersey.api.clientパッケージ

1

Client

create()

○

2

create(ClientConfig cc)

○※2

3

destroy()

×

4

getProperties()

×

5

handle(ClientRequest request)

○※2

6

resource(String u)

○

7

resource(URI u)

○

8

setChunkedEncodingSize(Integer chunkSize)

×

9

setConnectTimeout(Integer interval)

×

10

setFollowRedirects(Boolean redirect)

×

11

setReadTimeout(Integer interval)

×

12

ClientRequest

すべてのメソッド

×

13

ClientRequest.Builder

すべてのメソッド

×

14

ClientResponse

すべてのメソッド

×

15

GenericType

すべてのメソッド

○

16

WebResource

accept(MediaType... types)

○

17

accept(String... types)

○

18

acceptLanguage(Locale... locales)

○

19

acceptLanguage(String... locales)

○

20

cookie(Cookie cookie)

○

21

delete()

○

22

delete(Class<T> c)

○

23

delete(Class<T> c, Object requestEntity)

△

24

delete(GenericType<T> gt)

○

25

delete(GenericType<T> gt, Object requestEntity)

△

26

delete(Object requestEntity)

△

27

entity(Object entity)

○

28

entity(Object entity, MediaType type)

○

29

entity(Object entity, String type)

○

30

get(Class<T> c)

○

31

get(GenericType<T> gt)

○

32

getRequestBuilder()

○

33

getURI()

○

34

getUriBuilder()

○

35

head()

○

36

header(String name, Object value)

○

37

method(String method)

○

38

method(String method, Class<T> c)

○

39

method(String method, Class<T> c, Object requestEntity)

△

40

method(String method, GenericType<T> gt)

○

41

method(String method, GenericType<T> gt, Object requestEntity)

△

42

method(String method, Object requestEntity)

△

43

options(Class<T> c)

○

44

options(GenericType<T> gt)

○

45

path(String path)

○

46

post()

○

47

post(Class<T> c)

○

48

post(Class<T> c, Object requestEntity)

△

49

post(GenericType<T> gt)

○

50

post(GenericType<T> gt, Object requestEntity)

△

51

post(Object requestEntity)

△

52

put()

○

53

put(Class<T> c)

○

54

put(Class<T> c, Object requestEntity)

△

55

put(GenericType<T> gt)

○

56

put(GenericType<T> gt, Object requestEntity)

△

57

put(Object requestEntity)

△

58

queryParam(String key, String value)

○

59

queryParams( MultivaluedMap<String,String> params)

○

60

type(MediaType type)

○

61

type(String type)

○

62

uri(URI uri)

○

63

WebResource.Builder

すべてのメソッド

×

com.cosminexus.jersey.api.client.configパッケージ

64

DefaultClientConfig

すべてのメソッド

×

65

Provider

−

○

（凡例）

○：スレッドセーフです。

△：要求エンティティ（requestEntityパラメタ）に指定するインスタンスがスレッドセーフの場合，スレッドセーフです。

×：スレッドセーフではありません。

−：メソッドはありません。

注※1

スレッドセーフではない場合，同じオブジェクトのこのメソッドを複数スレッドから呼び出さないでください。

注※2

引数に指定するクラスはスレッドセーフではありません。引数に指定するクラスのインスタンスはそれぞれのスレッドで生成してください。

第4編　拡張機能

26　WSDLインポート機能

この章では，WSDLのインポート機能について説明します。

26.1　WSDLインポート機能とは

WSDLインポート機能とは，wsdl:import要素を使用して，共通部品として別ファイルのWSDL定義を読み込む機能です。

WSDLインポート機能のイメージを次の図に示します。

図26‒1　WSDLインポート機能のイメージ

26.2　インポートできるWSDL定義

インポート対象のWSDL定義の条件，およびインポート時の留意点について説明します。

26.2.1　インポート対象のWSDL定義の条件

インポート対象のWSDL定義は，次の条件を満たしている必要があります。

ルート要素にwsdl:definitionsが指定されていること。

ルート要素にwsdl:definitions以外の形式のファイルを指定した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51200-E）。

WSDL定義にアクセス権限があること。

アクセス権限がないWSDL定義を指定した場合，JDKのエラーとなり，処理が終了されます。

インポート対象のWSDL定義の拡張子は任意です。

26.2.2　複数のWSDL定義のインポート

複数のWSDL定義を組み合わせてインポートできます。ただし，最初の開始点となるインポート元のWSDL定義に，wsdl:service要素を定義する必要があります。以降の階層では，wsdl:service要素以外の要素を組み合わせて，WSDL定義をインポートできます。wsdl:service要素が定義されていない場合の動作については，「20.1.16　wsdl:service要素」を参照してください。

WSDL定義の階層的なインポートの方法を，正しい場合の例および誤っている場合の例に分けて図に示します。

図26‒2　WSDL定義の階層的なインポート（正しい場合の例）

図26‒3　WSDL定義の階層的なインポート（誤っている場合の例）

26.2.3　WSDL定義の再帰的なインポート

WSDLインポート機能では，WSDL定義を再帰的にインポートできません。再帰的にインポートしようとしても，WSDL定義を読み込まないため，wsdl:import要素が無視されます。

WSDL定義の再帰的なインポートの例を次の図に示します。

図26‒4　WSDL定義の再帰的なインポートの例

26.3　wsdl:import要素の書式

26.3.1　書式と説明

wsdl:import要素の書式例を次に示します。

<wsdl:import namespace="インポート対象のWSDL定義の名前空間名"
location="インポート対象のWSDL定義のロケーション"/>

wsdl:import要素の属性について，それぞれ説明します。

(1)　namespace属性（wsdl:import要素）

インポート対象のWSDL定義の名前空間名を指定します。

インポート元のWSDL定義に記述するwsdl:import要素のnamespace属性には，インポート対象のWSDL定義の名前空間名（wsdl:definitions要素のtargetNamespace属性）と同じ名前空間名を指定してください。

インポート元のWSDL定義の名前空間と，インポート対象のWSDL定義の名前空間の関係を次の表に示します。

表26‒1　WSDL定義の名前空間の関係（インポート元／インポート対象）

項番

インポート元のWSDL定義

インポート対象のWSDL定義

条件

実行時の動作

1

wsdl:import要素のnamespace属性

wsdl:definitions要素のtargetNamespace属性

一致

正常終了します。

2

不一致

標準エラー出力とログに警告メッセージが出力され，処理が続行されます（KDJW51191-W）。

インポート対象のWSDL定義およびインポート元のWSDL定義の要素は，それぞれの名前空間に属します。

3

wsdl:definitions要素のtargetNamespace属性

一致

標準エラー出力とログに警告メッセージが出力され，処理が続行されます（KDJW51192-W）。インポート対象のWSDL定義およびインポート元のWSDL定義の要素は，同じ名前空間に属します。

4

不一致

正常終了します。

(2)　location属性（wsdl:import要素）

インポート対象のWSDL定義のロケーションを指定します。

location属性に指定する文字列の条件を次に示します。

URLの形式で相対パス，リモート，またはローカルにあるWSDLファイルを指定できます。

WARファイルに含まれるWSDLファイルは，メタデータとして発行されます（WSDLファイルを新たに生成する場合は除きます）。ただし，メタデータを発行するときに注意事項があります。メタデータを発行するときの注意事項については，「10.6.6　WSDL定義またはXML Schemaをインポート／インクルードしている場合の注意」を参照してください。

RFC 2396で規定される文字およびxsd:anyURIを満たす文字を使用してください。また，RFC 2732（IPv6アドレス）の規則に従った文字列も使用できます。

大文字と小文字は区別されません。

指定できる文字列の最大長の制限はありません。ただし，OSの制限を超えた場合は，エラーとなります。

location属性の記述例を次の表に示します。

表26‒2　location属性の指定例（WSDLインポート機能）

項番

指定内容

指定例

1

ローカルにあるWSDLファイルを相対パスで指定※1

./wsdl/input.wsdl

2

ローカルにあるWSDLファイルをURL（file://〜）で表現する絶対パスで指定※1，※2

file:///C:/tmp/wsdl/input.wsdl

3

リモートにあるWSDLファイルをURL（http:〜）で指定※3

http://example.com:8080/fromjava/test?wsdl

注※1

WSDLファイルを相対パスまたは絶対パスで指定する場合は，正しいパスを指定してください。パスを間違えてWSDLファイルが見つからない場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51197-EまたはKDJW51198-E）。

注※2

"C:/〜"のようにドライブ指定で始まる絶対パスの文字列は指定できません。指定した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51199-E）。

注※3

リモートのWSDLファイルをURLで指定する場合は，正しいURLを指定してください。パスを間違えて，WSDLファイルが見つからない場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51197-EまたはKDJW51198-E）。

27　カタログ機能

この章では，カタログ機能について説明します。

27.1　カタログ機能とは

カタログ機能とは，XML Catalogs 1.1仕様に基づき，マッピング（対応付け）を実行する機能です。マッピング（対応付け）には次の2通りがあります。

xsd:import要素のnamespace属性で指定するXMLスキーマの名前空間URIと，XMLスキーマのロケーションを示すURI参照とのマッピング

WSDLまたはXMLスキーマのロケーションを示すURI参照と，別のWSDLまたはXMLスキーマのロケーションを示すURI参照とのマッピング

カタログ機能によるマッピングを実行するには，マッピング情報を定義したカタログファイルを配置する必要があります。カタログ機能はWebサービスクライアントの開発時および実行時に利用できます。ただし，メタデータ発行時におけるカタログ機能の利用はサポートしていません。

カタログファイルについては，「27.6　カタログファイル」を参照してください。

27.2　カタログ機能の利用（Webサービスクライアントの開発時）

スタブベースのWebサービスクライアント開発時にカタログ機能を利用するには，cjwsimportコマンドの-catalogオプションでカタログファイルを指定してください。-catalogオプションについては，「14.1.1(2)　オプション一覧」を参照してください。

cjwsimportコマンドは，引数に指定したWSDLおよびそのWSDLが参照しているXMLスキーマの名前空間やロケーションを，カタログファイルのマッピング情報に従って別のWSDLまたはXMLスキーマのロケーションにマッピングします。cjwsimportコマンドは，マッピングされたロケーションにあるWSDLおよびXMLスキーマを読み込んでJavaコードを生成します。

27.2.1　マッピング対象

cjwsimportコマンドでの，カタログ機能のマッピング対象を表27-1に，cjwsimportコマンドの引数に指定したWSDLの記述におけるマッピング対象を表27-2に示します。

表27‒1　cjwsimportコマンドでのマッピング対象

項番

マッピング対象

サポート

1

cjwsimportコマンドの引数に指定したWSDLのロケーション

×

（凡例）

×：サポートしていません。

表27‒2　 cjwsimportの引数に指定したWSDLの記述におけるマッピング対象

項番

要素

属性

サポート

1

wsdl:import

namespace

×

2

location

○

3

xsd:import

namespace

○※

4

schemaLocation

○

5

xsd:include

schemaLocation

○

（凡例）

○：サポートしています。

×：サポートしていません。

注※

マッピングの対象になるのは，xsd:import要素にnamespace属性だけ存在する場合です。xsd:import要素に，namespace属性とschemaLocation属性の両方が含まれるときは，namespace属性はマッピングの対象になりません。

27.2.2　注意事項

Webサービスクライアントの開発時のカタログ機能は，次に示すロケーションや要素の値を変更しません。

cjwsimportコマンドが生成するサービスクラスのデフォルトのWSDLロケーション（WSDLロケーションを引数に持たないコンストラクタが使用するWSDLロケーション）

サービスクラスに付与するjavax.xml.ws.WebServiceClientアノテーションにあるwsdlLocation要素

これらのロケーションや要素の値を変更するには，cjwsimportコマンドの-wsdllocationオプションを利用してください。詳細については，「14.1.1　cjwsimportコマンド」を参照してください。

27.2.3　マッピング例

Webサービスクライアントの開発時に，カタログ機能を利用してWSDLが参照するXMLスキーマのロケーションをマッピングする例を次の図に示します。

図27‒1　WSDLが参照するXMLスキーマのロケーションのマッピング例

この図の例では，WSDLにあるxsd:include要素のschemaLocation属性に，リモートのXMLスキーマのロケーションを指定しています。また，次のようにカタログ機能が無効な場合と有効な場合の流れを示しています。

カタログ機能が無効な場合

cjwsimportコマンドはリモートにあるXMLスキーマを読み込んで，Javaコードを生成します。

カタログ機能が有効な場合

カタログファイルのマッピング情報に従って，xsd:include要素のschemaLocation属性に指定したリモートのXMLスキーマのロケーションを，ローカルにあるXMLスキーマのロケーションにマッピングします。cjwsimportコマンドはローカルにあるXMLスキーマを読み込んで，Javaコードを生成します。

27.3　カタログ機能の利用（Webサービスクライアントの実行時）

Webサービスクライアントの実行時では，カタログファイルを配置するだけでカタログ機能を利用できます。WSDLを変更したり，cjwsimportコマンドで-catalogオプションを指定して，開発済みのWebサービスクライアントを作成し直したりする必要はありません。カタログファイルの配置については，「27.6.2　カタログファイルの配置」を参照してください。

WSDLからサービスクラスにマッピングされたWSDLロケーション，およびサービスクラスのコンストラクタの引数に指定したWSDLロケーションをカタログファイルのマッピング情報に従って別のWSDLロケーションにマッピングし，サービスクラスを生成します。

27.3.1　マッピング対象

Webサービスクライアントの実行時におけるカタログ機能のマッピング対象について表27-3に，Webサービスクライアントの実行時に利用するWSDLの記述におけるマッピング対象を表27-4に示します。

表27‒3　Webサービスクライアントの実行時におけるカタログ機能のマッピング対象

項番

マッピング対象

サポート

1

サービスクラスのデフォルトのWSDLロケーション※1

○

2

サービスクラスのコンストラクタの引数に指定したWSDLロケーション※1

○

3

javax.xml.ws.ServiceクラスのAPIの引数に指定したWSDLロケーション※2

○

4

javax.xml.ws.WebServiceRefアノテーションのwsdlLocation要素に指定したWSDLロケーション※3

○

（凡例）

○：サポートしています。

注※1

サービスクラスのWSDLロケーションについては，「15.1.9　サービスおよびポートからサービスクラスへのマッピング」の「表15-17　サービスクラスが持つメソッド」を参照してください。

注※2

javax.xml.ws.ServiceクラスWSDLロケーションについては，「19.2.2(4)　javax.xml.ws.Serviceクラス」を参照してください。

注※3

javax.xml.ws.WebServiceRefアノテーションについては，「19.3　アノテーションのサポート範囲」を参照してください。

表27‒4　Webサービスクライアントの実行時に利用するWSDLの記述におけるマッピング対象

項番

要素

属性

サポート

1

wsdl:import

namespace

×

2

location

○

（凡例）

○：サポートしています。

×：サポートしていません。

27.3.2　注意事項

Webサービスクライアントの実行時のカタログ機能は，サービスクラスの生成時にXMLスキーマを必要としないので，次のマッピングを実行しません。

XMLスキーマの名前空間URIのマッピング

スキーマロケーションに関するマッピング

このため，カタログファイルにはWSDLロケーションに関するマッピング情報だけを記述してください。

27.3.3　マッピング例

Webサービスクライアントでサービスクラスを生成するときに，カタログ機能を利用してWSDLロケーションをマッピングする例を次の図に示します。

図27‒2　WSDLロケーションのマッピング例

この図の例では，サービスクラスのコンストラクタの引数に，リモートのWSDLロケーションを指定しています。また，次のようにカタログ機能が無効な場合と有効な場合の流れを示しています。

カタログ機能が無効な場合

リモートにあるWSDLを読み込み，サービスクラスを生成します。

カタログ機能が有効な場合

カタログファイルのマッピング情報に従って，引数に指定したリモートのWSDLロケーションがローカルにあるWSDLロケーションにマッピングされ，ローカルにあるWSDLを読み込み，サービスクラスを生成します。

27.4　カタログ機能の性能

カタログ機能利用時のオーバーヘッドの増加

カタログ機能は，Webサービスクライアントの実行時にサービスクラスのコンストラクタやjavax.xml.ws.ServiceクラスのAPIを呼び出すときに動作します。このため，カタログ機能を利用しない場合に比べると，サービスクラスの生成やjavax.xml.ws.ServiceクラスのAPIの実行に掛かる時間が，カタログファイルの読み込みに伴うオーバーヘッドの分，増加します。

カタログ機能利用時のオーバーヘッドの軽減

Webサービスクライアントの実行時のカタログ機能のオーバーヘッドを軽減する場合は，次の方法をお勧めします。

生成したサービスを再利用する

詳細については，「3.6.1(3)　サービスクラスの生成およびポートの取得」を参照してください。

javax.xml.ws.WebServiceRefアノテーションをフィールドなどにアノテートし，サービスクラスをインジェクションする

詳細については，「19.3　アノテーションのサポート範囲」を参照してください。

27.5　カタログ機能利用時の注意事項

カタログ機能とアドレッシング機能は併用できません。併用した場合の動作は保証されません。

Webサービスクライアントの実行時に，マッピング対象のWSDLロケーションを示すURI参照を，リモートにあるWSDLロケーションを示すURI参照にカタログ機能を利用してマッピングした場合，次に示すプロパティは適用されません。

com.cosminexus.jaxws.connect.timeout

com.cosminexus.jaxws.request.timeout

com.cosminexus.xml.ws.client.http.HostnameVerificationProperty

javax.xml.ws.security.auth.username

javax.xml.ws.security.auth.password

Webサービス開発時にカタログ機能を利用する場合，カタログファイルは半角英数字（0〜9，A〜Z，a〜z），空白，ピリオド（.），アンダースコア（_），コロン（:），スラッシュ（/），および¥を使用したディレクトリに配置してください。それ以外の文字が含まれるディレクトリに配置した場合，動作は保証されません。

27.6　カタログファイル

カタログファイルは，カタログ機能を利用する場合に配置するファイルです。このファイルにマッピング（対応付け）情報を定義します。カタログファイルのサポート範囲については，「21.　XML Catalogs 1.1のサポート範囲」を参照してください。ここでは，カタログファイルの構文および配置について説明します。

27.6.1　カタログファイルの構文

カタログファイルの構文は，XML Catalogs 1.1のスキーマ（W3C XML Schema for the XML Catalog），およびApplication ServerのJAX-WS機能でサポートされる範囲で記述します。

27.6.2　カタログファイルの配置

カタログファイルはOSのファイルシステムの制限とJava EE 6仕様に従い，次の場所に配置します。

(1)　Webサービスクライアントの開発時の場合

cjwsimportコマンドの-catalogオプションの引数にカタログファイルのパスを指定します。カタログファイルのファイル名は任意です。詳細については，「14.1.1(2)　オプション一覧」の「-catalogオプション指定時の注意事項」を参照してください。カタログファイルの読み込みに失敗した場合は，標準エラー出力に警告メッセージ（KDJW51221-W）が出力され，カタログ機能が無効な状態で処理が続行されます。

(2)　Webサービスクライアントの実行時の場合

カタログファイルを，クラスパス上のMETA-INFディレクトリの直下に"jax-ws-catalog.xml"という名称で配置します。カタログファイルの読み込みに失敗した場合は，ログファイルにメッセージ（KDJW30023-W）を出力し，カタログ機能が無効な状態で処理が続行されます。なお，複数のカタログファイルを配置した場合の動作は保証されません。例えば"jax-ws-catalog.xml"を格納した複数のJARファイルをクラスパスに追加したときなどの動作は保証されません。

27.6.3　カタログファイルの記述例

カタログ機能を利用して，リモートのWSDLロケーションをローカルにあるWSDLロケーションにマッピングする場合の，カタログファイルの記述例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="system">
    <system systemId="http://localhost:8080/fromjava/AddNumbersImplService?wsdl"
                 uri="./wsdl/UserInfo.wsdl"/>
</catalog>

28　添付ファイル機能（wsi:swaRef形式）

添付ファイル機能を使用すると，テキストデータだけでなく，画像データや音声データなどをWebサービスで扱えます。

この章では，添付ファイル機能の概要，および添付ファイル機能を使用した場合のマッピング規則について説明します。

28.1　添付ファイル機能とは（wsi:swaRef形式）

添付ファイル機能とは，SOAPメッセージにテキストや画像（バイナリデータ）などのファイルを添付した添付ファイル付きSOAPメッセージを送受信する機能です。

次に示す例を基に，添付ファイル機能の概要について説明します。

図28‒1　添付ファイル機能を使用したバイナリデータの送受信

SOAPメッセージにファイルを添付する場合，Webサービスを呼び出すJavaメソッドの引数に，javax.activation.DataHandlerクラスを使用します。ファイルを添付したJavaソースは，送信側のJAX-WSエンジンによってSOAPメッセージにマーシャルされ，受信側のJAX-WSエンジンによってJavaソースにアンマーシャルされます。受信側のJAX-WSエンジンは，アンマーシャルされたJavaソースのメソッドの引数から，添付ファイルを取得します。

なお，この機能は，WS-I Attachments Profile - Version 1.0仕様に従っているため，wsi:swaRef形式のWSDLを使用します。また，SOAP Messages with Attachmentsプロトコルを使用しているため，添付ファイル付きSOAPメッセージはMIME Multipart/Related構造でエンコードされます。

SAAJ 1.3仕様のAPIを使用して添付ファイル付きSOAPメッセージを送受信する場合は，「22.1　SAAJ 1.3仕様のサポート範囲」を参照してください。

28.2　添付ファイルのJavaインタフェース（wsi:swaRef形式）

ここでは，Javaインタフェース内で添付ファイルを指定するJava型について説明します。

28.2.1　添付ファイルに使用できるJava型

Javaインタフェースでの添付ファイルのJava型の使用可否を次の表に示します。

添付ファイルに使用できるJava型には，javax.xml.bind.annotation.XmlAttachmentRefアノテーションを付加する必要があります。添付ファイルに使用できない型にこのアノテーションを付加した場合，動作は保証されません。

表28‒1　添付ファイルとしてのJava型の使用可否

項番

Java型

使用可否

1

javax.activation.DataHandler

○

2

javax.xml.ws.Holder<DataHandler>

○

3

javax.activation.DataHandlerの配列型

△

4

javax.xml.ws.Holder<DataHandler>の配列型

×

5

javax.activation.DataHandlerを継承したデータ型

×

（凡例）

○：添付ファイルとして使用できます。

△：添付ファイルとして1次元配列だけ使用できます。多次元配列を使用した場合，動作は保証されません。

×：添付ファイルとして使用できません。

28.2.2　添付ファイルを指定できる個所

添付ファイルは，Javaインタフェースのメソッド引数，メソッド戻り値，およびユーザ定義型のフィールドで指定できます。ユーザ定義例外では指定できません。

Javaインタフェース内での添付ファイルの指定個所と，Java型の指定可否を次の表に示します。

表28‒2　添付ファイルのJava型の指定個所と指定可否

項番

Javaインタフェースでの指定個所

添付ファイルのJava型

指定可否

1

メソッド引数

javax.activation.DataHandler

○

2

javax.xml.ws.Holder<DataHandler>

○

3

javax.activation.DataHandlerの配列型

△

4

メソッド戻り値

javax.activation.DataHandler

○

5

javax.xml.ws.Holder<DataHandler>

×

6

javax.activation.DataHandlerの配列型

△

7

ユーザ定義型のフィールド

javax.activation.DataHandler

○

8

javax.xml.ws.Holder<DataHandler>

×

9

javax.activation.DataHandlerの配列型

△

10

ユーザ定義例外のフィールド

javax.activation.DataHandler

×

11

javax.xml.ws.Holder<DataHandler>

×

12

javax.activation.DataHandlerの配列型

×

（凡例）

○：指定できます。

△：1次元配列を使用する場合だけ指定できます。多次元配列で指定した場合，動作は保証されません。

×：指定できません。

28.2.3　javax.activation.DataHandler型に指定できる添付ファイル

javax.activation.DataHandler型は，JavaBeans Activation Framework（JAF）の型であるため，任意のMIMEタイプの添付ファイルを指定できます。添付ファイルの拡張子と，デフォルトで設定されるMIMEタイプのマッピングについては，「28.4.2(3)　添付ファイルの拡張子とMIMEタイプのマッピング」を参照してください。

28.3　添付ファイルのWSDL（wsi:swaRef形式）

添付ファイル付きSOAPメッセージを使用する場合，WSDL上に添付ファイルを定義できます。ここでは，添付ファイルを使用する場合のWSDLの記述と，WSDLとJava型のマッピングについて説明します。

28.3.1　添付ファイル使用時のWSDLの記述（wsi:swaRef形式）

WSDLで添付ファイルを扱う場合，wsi:swaRef形式で記述します。wsi:swaRef形式は，WSDLで添付ファイルを扱う形式としてWS-I Attachments Profile - Version 1.0で規定されています。

WS-I Attachments Profile - Version 1.0で規定された形式に基づいて，wsi:swaRef形式で記述したWSDLの例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="http://localhost"
  xmlns:wsi="http://ws-i.org/profiles/basic/1.1/xsd" ...>
  <wsdl:types>
    <schema elementFormDefault="qualified" targetNamespace="http://localhost"
      xmlns="http://www.w3.org/2001/XMLSchema">
      <import namespace="http://ws-i.org/profiles/basic/1.1/xsd"/>
      <element name="getUserData">
        <complexType>
          <sequence>
            <element name="in0" type="xsd:string"/>
            <element name="in1" type="wsi:swaRef"/>
          </sequence>
        </complexType>
      </element>
       ...
    </schema>
  </wsdl:types>
  <wsdl:message name="getUserDataRequest">
    <wsdl:part element="intf:getUserData" name="parameters"/>
  </wsdl:message>
  ...
  <wsdl:portType name="UserInfo">
    <wsdl:operation name="getUserData">
      <wsdl:input message="intf:getUserDataRequest" name="getUserDataRequest"/>
      ...
    </wsdl:operation>
  </wsdl:portType>
  ...
</wsdl:definitions>

この例では，getUserDataメソッドの引数（スキーマ定義のelement要素の型）に，添付ファイルを表すwsi:swaRef型を指定しています。

WSDLで添付ファイルを扱う場合の注意事項

swaRef型は，スキーマの要素の型（element要素のtype属性）に指定できます。属性の型（attribute要素のtype属性）に指定した場合，動作は保証されません。

swaRef型を指定しているXML Schemaでは，WSDLの例で示すように名前空間http://ws-i.org/profiles/basic/1.1/xsdをインポートする必要があります。インポートしていない場合，XML Processorのエラーが出力されます。

名前空間http://ws-i.org/profiles/basic/1.1/xsdをインポートするxsd:import要素のschemaLocation属性の形式と，使用可否を次の表に示します。

表28‒3　xsd:import要素のschemaLocation属性の形式と使用可否（swaRef型の使用時）

項番

schemaLocation属性

使用可否

1

指定しない

使用できます。※1

2

http://wsi.org/profiles/basic/1.1/swaref.xsd

使用できます。※1

3

項番1および項番2以外

使用できません。※2

注※1

cjwsimportコマンドは，Application ServerのJAX-WS機能の内部で保持する名前空間http://ws-i.org/profiles/basic/1.1/xsdのスキーマを参照します。

注※2

cjwsimportコマンドは，schemaLocation属性で指定した場所にあるスキーマを参照します。ただし，Application ServerのJAX-WS機能で内容を保証できないスキーマが参照されるため，サポート対象外となります。

ユーザ定義例外で添付ファイルは使用できないため，wsdl:fault要素から参照するスキーマの要素の型（element要素のtype属性）にswaRef型は指定できません。wsdl:fault要素から参照するスキーマの要素の型にswaRef型を指定した場合，動作は保証されません。

28.3.2　添付ファイルのJava型とWSDLのマッピング（wsi:swaRef形式）

添付ファイルのJava型からWSDLへのマッピング規則を次に示します。

添付ファイルのJava型からWSDLへのマッピング規則

添付ファイルのJava型は，swaRef型にマッピングされます。

wsdl:definitions要素で，swaRef型の名前空間が宣言されます。

swaRef型を指定しているXML Schemaで，swaRef型の名前空間がインポートされます。

添付ファイルのJava型とWSDLのマッピング例を次の図に示します。上記の「添付ファイルのJava型からWSDLへのマッピング規則」に示した番号と，次の図に示す番号は対応しています。

図28‒2　添付ファイルのJava型からWSDLへのマッピング例

28.3.3　WSDLから添付ファイルのJava型へのマッピング（wsi:swaRef形式）

WSDLから添付ファイルのJava型へのマッピング規則を次に示します。

WSDLから添付ファイルのJava型へのマッピング規則

WSDLのswaRef型は，添付ファイルのJava型へマッピングされます。

WSDLと添付ファイルのJava型のマッピング例を次の図に示します。上記の「WSDLから添付ファイルのJava型へのマッピング規則」に示した番号と，次の図に示す番号は対応しています。

図28‒3　WSDLから添付ファイルのJava型へのマッピング例

28.4　添付ファイル付きSOAPメッセージ（wsi:swaRef形式）

添付ファイル付きSOAPメッセージは，SOAP Messages with Attachmentsプロトコルを使用し，MIME Multipart/Related構造でエンコードされます。

添付ファイル付きSOAPメッセージの構造を次の図に示します。

図28‒4　添付ファイル付きSOAPメッセージの構造

添付ファイル付きSOAPメッセージの各部の説明を次の表に示します。

表28‒4　添付ファイル付きSOAPメッセージの各部の説明

各部の名称

説明

HTTPヘッダ

HTTPプロトコルに依存するヘッダ情報です。

HTTPヘッダとHTTPボディの境界文字列

HTTPヘッダとHTTPボディの境界を示す文字列です。

HTTPボディ

送信するメッセージを記述します。

ルートパートおよび添付ファイルパートから構成されます。

┣

MIMEパートの境界文字列

各MIMEパートの境界を示す文字列です。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

ルートパート

┃

┃

メッセージ本体を記述するパートです。

MIMEヘッダとMIMEボディから構成され，必ず1個定義します。

┣

MIMEヘッダ

ルートパートのヘッダ情報です。

┣

┃

MIMEヘッダとMIMEボディ間の境界文字列

ルートパートのMIMEヘッダとMIMEボディ間の境界を示す文字列です。

┗

MIMEボディ

メッセージ本体を記述します。

┗

SOAPエンベロープ

SOAPエンベロープを記述します。

┣

SOAPヘッダ

SOAPメッセージのヘッダ情報を記述します。

┗

SOAPボディ

SOAPメッセージの本文（XML）を記述します。

┣

MIMEパートの境界文字列

各MIMEパートの境界を示す文字列です。

┣

┃

┃

┃

┃

┃

┃

┃

┃

添付ファイルパート

┃

┃

添付ファイルの内容を記述するパートです。

MIMEヘッダとMIMEボディから構成され，0個以上定義します。

┣

MIMEヘッダ

添付ファイルパートのヘッダ情報です。

┣

┃

MIMEヘッダとMIMEボディ間の境界文字列

添付ファイルパートのMIMEヘッダとMIMEボディ間の境界を示す文字列です。

┗

MIMEボディ

添付ファイルの内容（バイナリデータ）を記述します。

┗

MIMEパートの終端文字列

MIMEパートの終端を表す文字列です。

28.4.1　添付ファイルからSOAPメッセージへのマッピング（wsi:swaRef形式）

添付ファイルからSOAPメッセージへマッピングするときの設定値について説明します。マッピング規則については，「28.4.2　添付ファイルからSOAPメッセージへのマッピングの注意事項（wsi:swaRef形式）」と合わせて確認してください。

(1)　HTTPヘッダ

添付ファイル使用時に，HTTPヘッダのフィールドおよびパラメタに設定される値を次の表に示します。

表28‒5　HTTPヘッダのフィールドおよびパラメタの設定値

項番

フィールド名

パラメタ名

設定値

1

Content-Type

−

"multipart/related"が設定されます。

2

type

SOAP 1.1仕様

"text/xml"が設定されます。

SOAP 1.2仕様

"application/soap+xml"が設定されます。

3

boundary

MIMEパートの境界文字列が設定されます。

（凡例）

−：Content-Typeに直接設定されることを示します。

1個以上の非ルートMIMEパートを列挙している場合（添付ファイル付きSOAPメッセージを送受信する場合）は，Content-Typeにmultipart/relatedが設定されます。MIMEパートがない場合，SOAP 1.1仕様のときは"text/xml"が，SOAP 1.2仕様のときは"application/soap+xml"が設定されます。

(2)　HTTPボディ

HTTPボディは，ルートパート，添付ファイルパート，および各パートの境界文字列で構成されます。添付ファイル使用時に，各パートおよび境界文字列に生成される内容，および設定される値を示します。

(a)　ルートパートのMIMEヘッダ

添付ファイル使用時に，ルートパートのContent-Typeフィールドに設定される値を次の表に示します。

表28‒6　ルートパートのフィールドの設定値

項番

フィールド名

設定値

1

Content-Type

SOAP 1.1仕様

"text/xml"が設定されます。

SOAP 1.2仕様

"application/soap+xml"が設定されます。

2

Content-Id

"グローバルに一意な値"＋"@"＋"jaxws.cosminexus.com"が設定されます。

(b)　ルートパートのMIMEボディ

添付ファイルを使用する場合，ルートパートのMIMEボディには，SOAPエンベロープがそのまま格納されます。SOAPエンベロープ内のSOAPボディから添付ファイルを参照する方法として，CID URLスキームが使用されます。

CID URLスキームの形式を次に示します。

"cid:"＋<添付ファイルパートのContent-Id>

(c)　ルートパートのMIMEヘッダとMIMEボディの境界文字列

ルートパートのMIMEヘッダとMIMEボディ間には，境界文字列として"CRLF"が設定されます。

(d)　添付ファイルパートのMIMEヘッダ

添付ファイル使用時に，添付ファイルパートのMIMEヘッダに設定される値を次の表に示します。

表28‒7　添付ファイルパートのMIMEヘッダの設定値

項番

フィールド名

パラメタ名

設定値

1

Content-Type

−

添付ファイルの種類に応じたMIMEタイプ※1が設定されます。

2

charset

DataHandlerオブジェクト生成時に指定した文字コード※2が設定されます。

3

Content-Transfer-Encoding

なし

"binary"が設定されます。

4

Content-Id

なし

"グローバルに一意な値"＋"@"＋"jaxws.cosminexus.com"が設定されます。

（凡例）

−：Content-Typeに直接設定されることを示します。

注※1

Content-Typeフィールドの設定値は，DataHandlerオブジェクトの生成方法によって，次のように異なります。

DataHandler(DataSource)コンストラクタで生成する場合

FileDataSourceの場合，入力となる添付ファイルの拡張子から，JAFによって決定されたMIMEタイプがContent-Typeフィールド値として設定されます。添付ファイルの拡張子とMIMEタイプのマッピングについては，「28.4.2(3)　添付ファイルの拡張子とMIMEタイプのマッピング」を参照してください。

DataHandler(Object, String)コンストラクタで生成する場合

DataHandlerオブジェクト生成時に，コンストラクタの第2引数に指定した内容（MIMEタイプ）がそのままContent-Typeフィールド値として設定されます。

注※2

例えば，DataHandlerオブジェクトの生成を次のように生成した場合，Content-Typeのcharsetには，第2引数に指定したcharsetパラメタ値「Shift_JIS」が設定されます。

DataHandler dhandler = new DataHandler ("あいうえお", "text/plain; charset=Shift_JIS");

添付ファイルのJava型であるjavax.activation.DataHandler型は，JavaBeans Activation Framework（JAF）の型であるため，任意のMIMEタイプの添付ファイルを指定できます。FileDataSourceを使用してDataHandlerオブジェクトを生成する場合の添付ファイルの拡張子と，デフォルトで設定されるMIMEタイプの対応については，「28.4.2(3)　添付ファイルの拡張子とMIMEタイプのマッピング」を参照してください。

(e)　添付ファイルパートのMIMEボディ

添付ファイルパートのMIMEボディには，添付ファイルの内容を表すバイナリデータが格納されます。

(f)　添付ファイルパートのMIMEヘッダとMIMEボディの境界文字列

添付ファイルパートのMIMEヘッダとMIMEボディの境界文字列は，ルートパートの場合と同様に，境界文字列として"CRLF"が設定されます。

(g)　各MIMEパート間の境界文字列

ルートパートと添付ファイルパート間，および添付ファイルパート間には，境界文字列として次の文字列が設定されます。

"CRLF"＋"--"＋"<HTTPヘッダのboundaryパラメタの値>"

(h)　MIMEパートの終端文字列

MIMEパートの終端には，終端文字列として次の文字列が設定されます。

"CRLF"＋"--"＋"<HTTPヘッダのboundaryパラメタの値>"＋"--"

(3)　HTTPヘッダとHTTPボディの境界文字列

HTTPヘッダとHTTPボディ間には，境界文字列として"CRLF"が設定されます。

28.4.2　添付ファイルからSOAPメッセージへのマッピングの注意事項（wsi:swaRef形式）

添付ファイルからSOAPメッセージをマッピングするときの注意事項について説明します。

(1)　MIMEパートの記述順序

MIMEパートは1個のルートパートと0個以上の添付ファイルパートで構成されます。

ルートパートは，MIMEパートの先頭に記述されます。ルートパートのあとに，添付ファイルパートが記述されます。

添付ファイルパートでは，Javaインタフェースで指定された引数や戻り値がマッピングされます。Javaインタフェースの指定内容と添付ファイルパートでの記述順序の対応を次の表に示します。

表28‒8　Javaインタフェースの指定内容と添付ファイルパートの記述順序

項番

Javaインタフェースでの指定個所

添付ファイルパートの記述順序

1

メソッド引数

メソッド引数に指定された順に記述されます。

2

メソッド戻り値

添付ファイルパートの先頭に記述されます。

3

配列型

配列内の要素順に記述されます。

4

ユーザ定義型

ユーザ定義型内での指定順に記述されます。

ユーザ定義型の中で指定したユーザ定義型で，添付ファイルのJava型を指定するときは，深さ優先順で添付ファイルパートが記述されます。

Javaインタフェースと添付ファイルパートのマッピング例を示します。

図28‒5　Javaインタフェースと添付ファイルパートのマッピング例

(2)　ルートパートから添付ファイルへのマッピング

ルートパートのSOAPボディに記述されるCID URLスキームには，対応する添付ファイルパートのContent-Idが記述されます。Content-Idによって，ルートパートから対応する添付ファイルパートが参照されます。

添付ファイル付きSOAPメッセージの一部を示します。背景色付きの太字部分がCID URLスキームと，対応する添付ファイルパートのContent-Idになります。

--uuid:73a28380-5de5-45e8-af15-c879e65d62a0
Content-Type: text/xml

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <getUserData xmlns="http://localhost">
      <in0>cid:d10ed73c-e9b7-418e-8201-ba920cccb214@jaxws.cosminexus.com</in0>
    </getUserData>
  </S:Body>
</S:Envelope>

--uuid:73a28380-5de5-45e8-af15-c879e65d62a0
Content-Id:<d10ed73c-e9b7-418e-8201-ba920cccb214@jaxws.cosminexus.com>
Content-Type: text/plain
Content-Transfer-Encoding: binary

[添付データ]
--uuid:73a28380-5de5-45e8-af15-c879e65d62a0--

(3)　添付ファイルの拡張子とMIMEタイプのマッピング

添付ファイルの拡張子と，デフォルトで設定されるMIMEタイプのマッピングを次の表に示します。

表28‒9　添付ファイルの拡張子とMIMEタイプの対応表

項番

添付ファイルの拡張子

設定されるMIMEタイプ

1

html，htm

text/html

2

txt，text

text/plain

3

gif，GIF

image/gif

4

ief

image/ief

5

jpeg，jpg，jpe，JPG

image/jpeg

6

tiff，tif

image/tiff

7

xwd

image/x-xwindowdump

8

ai，eps，ps

application/postscript

9

rtf

application/rtf

10

tex

application/x-tex

11

texinfo，texi

application/x-texinfo

12

t，tr，roff

application/x-troff

13

au

audio/basic

14

midi，mid

audio/midi

15

aifc

audio/x-aifc

16

aif，aiff

audio/x-aiff

17

wav

audio/x-wav

18

mpeg，mpg，mpe

video/mpeg

19

qt，mov

video/quicktime

20

avi

video/x-msvideo

この表にない拡張子を指定した場合，MIMEタイプは「application/octet-stream」が設定されます。

(4)　添付ファイルのデータサイズと添付ファイルパートへのマッピング

Javaインタフェースに指定する添付ファイルのデータサイズがnullの場合と，0バイト以上のデータがある場合では，添付ファイルパートへのマッピング方法が異なります。それぞれの場合のマッピングについて説明します。

(a)　添付ファイルのデータサイズがnullの場合

添付ファイルのデータサイズがnullの場合，添付ファイルパートにマッピングされません。MIMEパートを生成しないで，SOAPエンベロープだけが記述されます。また，SOAPボディの該当する引数の要素には，空の要素が指定されます。

添付ファイルのデータサイズがnullの場合のマッピング例を示します。

Webサービス呼び出しプログラム

...
UserInfoService service = new UserInfoService();
UserInfo impl = service.getUserInfo();

result = impl.getUserData( null );
...

SOAPメッセージ

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <getUserData xmlns="http://localhost">
    </getUserData>
  </S:Body>
</S:Envelope>

(b)　添付ファイルのデータサイズが0バイト以上の場合

添付ファイルのデータサイズが0バイト以上の場合，添付ファイルパートにマッピングされます。この場合，ルートパートと添付ファイルパートから構成されるマルチパートとなります。Javaインタフェースで複数の添付ファイルを指定している場合は，添付ファイルパートは複数記述されます。ただし，0バイトの場合は，添付ファイルパート内のMIMEボディは空となります。

28.4.3　SOAPメッセージから添付ファイルへのマッピング（wsi:swaRef形式）

JAX-WSエンジンは，受信した添付ファイル付きSOAPメッセージがWS-I Attachments Profile - Version 1.0仕様に従っている場合だけ，添付ファイル付きのSOAPメッセージから添付ファイルデータへのマッピングは保証されます。それ以外のSOAPメッセージを受信した場合の動作は保証されません。

28.5　添付ファイルのJavaインスタンスの生成と取得（wsi:swaRef形式）

添付ファイルをプログラムで扱うには，JAFのjavax.activationパッケージを使用する必要があります。ここでは，javax.activationパッケージを使用して，添付ファイルのインスタンスを生成する方法，およびデータを取得する方法について説明します。

JAFの仕様については，JAFのAPI仕様を参照してください。

28.5.1　添付ファイルのインスタンスを生成する方法（wsi:swaRef形式）

添付ファイルのオブジェクトとして，javax.activation.DataHandlerオブジェクトを生成します。javax.activation.DataHandlerクラスのコンストラクタを次の表に示します。

表28‒10　javax.activation.DataHandlerクラスのコンストラクタ

項番

利用ケース

コンストラクタ

引数の説明

1

ファイルを添付する

DataHandler(javax.activation.DataSource ds)

［第1引数］

javax.activation.DataSourceオブジェクトです。

javax.activation.FileDataSourceクラスのオブジェクトを指定できます。

2

メモリ上のオブジェクトを添付する

DataHandler(java.lang.Object obj, java.lang.String mimeType)

［第1引数］

Javaオブジェクトです。

［第2引数］

オブジェクトのMIMEタイプです。

指定できるMIMEタイプについては，「28.4.2(3)　添付ファイルの拡張子とMIMEタイプのマッピング」を参照してください。

添付ファイルとして送信するオブジェクトによって，javax.activation.DataHandlerオブジェクトを生成する方法が異なります。送信するオブジェクトごとに，生成する方法を示します。

(1)　存在するファイルを添付ファイルとして送信する方法

すでに存在するファイルを添付して送信する場合の手順を示します。

javax.activation.FileDataSourceオブジェクトを生成します。

送信する添付ファイルのファイルパスを引数に指定して，javax.activation.FileDataSourceオブジェクトを生成します。

javax.activation.FileDataSource fdSource =
 new javax.activation.FileDataSource("/tmp/sample.jpg");

javax.activation.DataHandlerオブジェクトを生成します。

javax.activation.FileDataSourceオブジェクトを引数に指定して，javax.activation.DataHandlerオブジェクトを生成します。

javax.activation.DataHandler dhandler =
 new javax.activation.DataHandler(fdSource);

(2)　Javaオブジェクトを添付ファイルとして送信する方法

Javaオブジェクトを添付ファイルとして送信する場合の手順を示します。

Javaオブジェクトを生成します。

ここでは，添付ファイルとして送信するjava.awt.Imageオブジェクトを生成します。

java.awt.Image attachments =
 Toolkit.getDefaultToolkit().createImage("sample.jpg");

javax.activation.DataHandlerオブジェクトを生成します。

Javaオブジェクトと，Javaオブジェクトに対応するMIMEタイプを引数に指定し，javax.activation.DataHandlerオブジェクトを生成します。

javax.activation.DataHandler dhandler = new
 javax.activation.DataHandler(attachments, "image/jpeg");

(3)　java.lang.Stringオブジェクトを添付ファイルとして送信する方法

java.lang.Stringオブジェクトを添付ファイルとして送信する場合の手順を示します。

java.lang.Stringオブジェクトを生成します。

添付ファイルとして送信する文字列のjava.lang.Stringオブジェクトを生成します。

java.lang.String attachments = new java.lang.String("あいうえお");

javax.activation.DataHandlerオブジェクトを生成します。

java.lang.StringオブジェクトとMIMEタイプを引数に指定し，javax.activation.DataHandlerオブジェクトを生成します。java.lang.Stringオブジェクトは，charsetパラメタに指定された文字コードでエンコードされます。

javax.activation.DataHandler dhandler = new javax.activation.DataHandler(attachments, "text/plain; charset=UTF-8");

(4)　javax.activation.DataHandlerオブジェクト生成時の注意事項

wsi:swaRef形式の添付ファイルとして送信するオブジェクトが，テキストファイル，XMLファイル，またはjava.lang.Stringオブジェクト（文字列）の場合，javax.activation.DataHandlerクラスのDataHandler（Object, String）コンストラクタを使用することで，オブジェクトに含まれる文字の文字コードを指定できます。

javax.activation.DataHandlerオブジェクトの生成時に文字コードを指定しない場合，送信するオブジェクトはデフォルトの文字コード（US-ASCII）でエンコードされます。送信するオブジェクトにデフォルトの文字コード（US-ASCII）以外の文字が含まれている場合は，不正な添付ファイルを送信する扱いとなるため，特に日本語を含む場合には，適切な文字コードを指定してください。

送信するオブジェクトがXMLファイルの場合，XML宣言に指定している文字コードは使用されません。デフォルトの文字コード（US-ASCII），またはjavax.activation.DataHandlerオブジェクトの生成時に指定した文字コードでエンコードされて，XMLファイルが送信されます。

文字コードを指定するには，DataHandler（Object, String）コンストラクタの第2引数で指定するオブジェクトのMIMEタイプにcharsetパラメタを付けます。DataHandler（Object, String）コンストラクタの第2引数の記述形式を次に示します。

送信するオブジェクトのMIMEタイプ＋";"＋"charset"＋"="＋文字コード※

注※

大文字または小文字を区別しません。また，JDKがサポートしていない文字コードおよび空文字を指定できません。

28.5.2　添付ファイルデータを取得する方法（wsi:swaRef形式）

添付ファイルのデータを取得する方法について説明します。各例に示す"dhandler"は，受信したjavax.activation.DataHandlerオブジェクトを表します。

(1)　添付ファイルをjava.io.InputStreamオブジェクトとして取得する方法

受信した添付ファイルをjava.io.InputStreamオブジェクトとして取得する場合，受信したjavax.activation.DataHandlerオブジェクトからgetInputStreamメソッドでjava.io.InputStreamオブジェクトを取得します。

java.io.InputStream stream = dhandler.getInputStream();

(2)　添付ファイルをjavax.activation.DataSourceオブジェクトとして取得する方法

受信した添付ファイルをjavax.activation.DataSourceオブジェクトとして取得する場合，受信したjavax.activation.DataHandlerオブジェクトからgetDataSourceメソッドで関連づけられたjavax.activation.DataSourceオブジェクトを取得します。

javax.activation.DataSource datasource = dhandler.getDataSource();

(3)　添付ファイルをJavaオブジェクトとして取得する方法

受信した添付ファイルをJavaオブジェクトとして取得する場合の手順を示します。ここでは，java.awt.Imageオブジェクトを取得する場合の例を示します。

添付ファイルのデータをオブジェクトとして取得します。

受信したjavax.activation.DataHandlerオブジェクトからgetContentメソッドでオブジェクトを取得します。

java.lang.Object content = dhandler.getContent();

添付ファイルのMIMEタイプを取得します。

受信したjavax.activation.DataHandlerオブジェクトに対して，getContentTypeメソッドを実行します。getContentTypeメソッドを実行することで，添付ファイルのMIMEタイプを取得できます。

java.lang.String mimetype = dhandler.getContentType();

（取得したmimetypeの内容）image/jpeg

オブジェクトを適切な型にキャストします。

添付ファイルのMIMEタイプに応じて，オブジェクトを適切な型にキャストします。

java.awt.Image attachment = (java.awt.Image) content;

(4)　添付ファイルをjava.lang.Stringオブジェクトとして取得する方法

受信した添付ファイルをJavaオブジェクトとして取得する場合の手順を示します。

添付ファイルのデータをオブジェクトとして取得します。

受信したjavax.activation.DataHandlerオブジェクトからgetContentメソッドでオブジェクトを取得します。

java.lang.Object content = dhandler.getContent();

添付ファイルのMIMEタイプを取得します。

受信したjavax.activation.DataHandlerオブジェクトに対し，getContentTypeメソッドを実行します。getContentTypeメソッドを実行することで添付ファイルのMIMEタイプおよび文字コードを取得できます。

java.lang.String mimetype = dhandler.getContentType();

（取得したmimetypeの内容）text/plain; charset=UTF-8

オブジェクトを適切な型にキャストします。

添付ファイルのMIMEタイプに応じて，オブジェクトを適切な型にキャストします。

java.lang.String attachment = (java.lang.String) content;

(5)　javax.activation.DataHandlerオブジェクト取得時の注意事項

wsi:swaRef形式の添付ファイルを含むMIME Multipart/Related構造のSOAPメッセージを受信すると，ストリーミングされたwsi:swaRef形式の添付ファイルとして操作できます。wsi:swaRef形式の添付ファイルの受信側では，javax.activation.DataHandlerオブジェクトが持つ入力ストリームからすべてのデータを読み込まないと受信処理が完了しないため，送信側の送信処理は受信側の受信処理が完了するまで待ち状態が続きます。

この状態を解消するためには，javax.activation.DataHandlerオブジェクトが持つjava.io.InputStreamオブジェクトからすべてのデータを読み込むか，javax.activation.DataHandlerクラスのwriteTo(java.io.OutputStream)メソッドを使用して入力ストリームのデータを出力ストリームに書き込む必要があります。

28.6　MIME Multipart/Related構造のSOAPメッセージの受信

1048576バイト以上のサイズのMIMEボディを含むMIME Multipart/Related構造のSOAPメッセージを受信した場合，JAX-WSエンジンはSOAPメッセージに含まれるMIMEボディを一時ファイルに出力します。

MIME Multipart/Related構造のSOAPメッセージの受信の詳細については，「10.24　MIME Multipart/Related構造のSOAPメッセージの受信」を参照してください。

29　SEIを起点とした開発の例（wsi:swaRef形式の添付ファイル使用時）

この章では，添付ファイルを使用して，SEIを起点としたWebサービスを開発する場合の例を説明します。

29.1　開発例の構成（SEI起点・wsi:swaRef形式の添付ファイル）

この章で説明する開発例では，SEIを起点としたWebサービスを開発します。開発するWebサービスは，添付ファイルを使用します。

開発するWebサービスの概要および利用する情報について説明します。

開発例の概要

社員番号，顔写真，社員名，所属というユーザ情報を管理し，Webサービスクライアントからの入力に対して，処理結果を返すWebサービスを新規に開発します。

Webサービスクライアントからの要求情報およびサーバからの応答情報を次の表に示します。

表29‒1　Webサービスクライアントからの要求情報

情報名

Javaデータ型

社員番号

java.lang.String

顔写真

javax.activation.DataHandler

表29‒2　サーバからの応答情報

情報名

Javaデータ型

登録確認メッセージ

java.lang.String

名前

java.lang.String

所属

java.lang.String

サーバからの応答情報は，ユーザ定義型クラスのUserDataクラスで保持されます。

Webサービス開発時のカレントディレクトリの構成を次の表に示します。

表29‒3　カレントディレクトリの構成（SEI起点・添付ファイル）

ディレクトリ

説明

c:¥temp¥jaxws¥works¥attachments

カレントディレクトリです。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

server¥

Webサービスの開発で使用します。

┣

┃

┃

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

┗

application.xml

「29.3.4　application.xmlを作成する」で作成します。

┣

┃

┃

┃

src¥

Webサービスのソースファイル（*.java）を格納します。「29.3.1　Webサービス実装クラスを作成する」および「29.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

┃

┃

┃

┃

┃

WEB-INF¥

WARファイルのWEB-INFディレクトリに対応します。

┣

web.xml

「29.3.3　web.xmlを作成する」で作成します。

┗

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「29.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

attachments_dynamic_generate.ear

「29.3.5　EARファイルを作成する」で作成します。

┗

attachments_dynamic_generate.war

┗

client¥

Webサービスクライアントの開発で使用します。

┣

┃

┃

┃

┃

src¥

Webサービスクライアントのソースファイル（*.java）を格納します。「29.5.1　サービスクラスを生成する」および「29.5.2　Webサービスクライアントの実装クラスを作成する」で使用します。

┣

┃

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「29.5.3　Webサービスクライアントの実装クラスをコンパイルする」で使用します。

┣

┃

image.jpg

Webサービスクライアントで使用するJPEGファイルで使用します。

┣

┃

┃

usrconf.cfg

「29.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

┗

usrconf.properties

「29.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

カレントディレクトリのパスは，開発する環境に合わせて変更してください。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebサービスとWebサービスクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

29.2　開発例の流れ（SEI起点・wsi:swaRef形式の添付ファイル）

この章で説明する開発例では，次の流れで開発および実行します。

Webサービスの開発

Webサービス実装クラスを作成する（29.3.1）

javacコマンドを実行し，Webサービス実装クラスをコンパイルする（29.3.2）

web.xmlを作成する（29.3.3）

application.xmlを作成する（29.3.4）

EARファイルを作成する（29.3.5）

デプロイと開始

EARファイルをデプロイする（29.4.1）

Webサービスを開始する（29.4.2）

Webサービスクライアントの開発

cjwsimportコマンドを実行し，サービスクラスを生成する（29.5.1）

Webサービスクライアントの実装クラスを作成する（29.5.2）

Webサービスクライアントの実装クラスをコンパイルする（29.5.3）

Webサービスの実行

Javaアプリケーション用オプション定義ファイルを作成する（29.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（29.6.2）

Webサービスクライアントを実行する（29.6.3）

29.3　Webサービスの開発例（SEI起点・wsi:swaRef形式の添付ファイル）

ここでは，SEIを起点とした場合のWebサービス（添付ファイルを使用）の開発例を説明します。

29.3.1　Webサービス実装クラスを作成する

Webサービスの処理を記述したWebサービス実装クラスを作成します。ここでは，受け取った要求メッセージの内容を計算して，応答メッセージを返すWebサービス実装クラスを作成します。

Webサービス実装クラスの作成例を次に示します。

package com.sample;

import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.xml.bind.annotation.XmlAttachmentRef;
import javax.activation.DataHandler;

@javax.jws.WebService(serviceName="UserInfoService",targetNamespace="http://sample.com")
public class UserInfoImpl{

    public UserData getUserData( String in0,
        @XmlAttachmentRef javax.activation.DataHandler in1 )
    throws UserInfoException{
        //社員情報への顔写真の登録処理
        ・・・・

        UserData userdata = new UserData();
        //登録した社員の名前と所属を設定
        if ( in0.equals("1") )
        {
            userdata.setName("Sato Taro");
            userdata.setSection("The personnel section");
        } if ( ・・・・) {
            ・・・・・
        } ・・・・

        //登録確認メッセージを設定
        if ( in1 == null )
        {
            userdata.setMessage("Failure(no image).");
        } else {
            userdata.setMessage("Success.");
        }
        return userdata;
    }

}

作成したUserInfoImpl.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥attachments¥server¥src¥com¥sample¥ディレクトリに保存します。

また，com.sample.UserInfoImplで使用しているユーザ定義型クラスcom.sample.UserDataを作成します。通常，ユーザ定義型クラスの作成は任意ですが，ここではユーザ定義型クラスを作成します。

ユーザ定義型クラスの作成例を次に示します。

package com.sample;

public class UserData{

    private java.lang.String message;
    private java.lang.String name;
    private java.lang.String section;

    public UserData(){
    }

    public java.lang.String getMessage() {
        return this.message;
    }

    public void setMessage(java.lang.String message) {
        this.message = message;
    }

    public java.lang.String getName() {
        return this.name;
    }

    public void setName(java.lang.String name) {
        this.name = name;
    }

    public java.lang.String getSection() {
        return this.section;
    }

    public void setSection(java.lang.String section) {
        this.section = section;
    }
}

作成したUserInfoImpl.javaは，UTF-8形式で，c:¥temp¥jaxws¥works¥attachments¥server¥src¥com¥sample¥ディレクトリに保存します。

またcom.sample.UserInfoImplでスローしている例外クラスcom.sample.UserInfoExceptionを作成します。通常，例外クラスの作成は任意ですが，ここでは例外クラスを作成します。

例外クラスの作成例を次に示します。

package com.sample;

public class UserInfoException extends Exception {
    String detail;

    public UserInfoException (String message, String detail) {
        super (message);
        this.detail = detail;
    }

    public String getDetail () {
        return detail;
    }
}

作成したUserInfoException.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥attachments¥server¥src¥com¥sample¥ディレクトリに保存します。

29.3.2　Webサービス実装クラスをコンパイルする

javacコマンドを実行して，Webサービス実装クラスをコンパイルします。javacコマンドについては，JDKのドキュメントを参照してください。

javacコマンドの実行例を次に示します。添付ファイル機能を使用したJavaプログラムをjavacコマンドでコンパイルする場合，javacコマンドの引数に"--add-modules=java.activation"を指定してください。

> cd c:¥temp¥jaxws¥works¥attachments¥server¥
> mkdir WEB-INF¥classes¥
> javac -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥CC¥client¥lib¥HiEJBClientStatic.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxp.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmstax.jar" -d WEB-INF¥classes¥ -s src src¥com¥sample¥UserInfoImpl.java src¥com¥sample¥UserData.java src¥com¥sample¥UserInfoException.java

javacコマンドが正常に終了すると，コンパイルしたクラスが，c:¥temp¥jaxws¥works¥attachments¥server¥WEB-INF¥classes¥com¥sample¥ディレクトリに出力されます。なお，コンパイルしたWebサービス実装クラスに対してhwsgenコマンドを実行すると，事前にエラーチェックができます。hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を，エラーチェックについては，「10.23.1　hwsgenコマンドによるエラーチェックについて」を参照してください。

29.3.3　web.xmlを作成する

WARファイルの構成要素として必要なweb.xmlを作成します。

web.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;fromjava&quot;</description>
  <display-name>Sample_web_service_fromjava</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/UserInfoService</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

作成したweb.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥attachments¥server¥WEB-INF¥ディレクトリに保存します。web.xmlの設定項目については，「3.4　web.xmlの作成」を参照してください。

29.3.4　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。

application.xmlの作成例を次に示します。なお，Webサービスとしてapplication.xmlに設定する項目はありません。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;fromjava&quot;</description>
  <display-name>Sample_application_fromjava</display-name>
  <module>
    <web>
      <web-uri>attachments_dynamic_generate.war</web-uri>
      <context-root>attachments_dynamic_generate</context-root>
    </web>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥attachments¥server¥META-INF¥ディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

29.3.5　EARファイルを作成する

jarコマンドを使用して，これまでに作成したファイルを含めたEARファイルを作成します。

EARファイルの作成例を次に示します。

> cd c:¥temp¥jaxws¥works¥attachments¥server¥
> jar cvf attachments_dynamic_generate.war .¥WEB-INF
> jar cvf attachments_dynamic_generate.ear .¥attachments_dynamic_generate.war .¥META-INF¥application.xml

正常に終了すると，c:¥temp¥jaxws¥works¥attachments¥server¥ディレクトリにattachments_dynamic_generate.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

29.4　デプロイと開始の例（SEI起点・wsi:swaRef形式の添付ファイル）

ここでは，添付ファイルを使用して，SEIを起点とした場合のデプロイと開始の例を説明します。

29.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxws¥works¥attachments¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxwsserver -nameserver corbaname::testserver:900 -f attachments_dynamic_generate.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

29.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxws¥works¥attachments¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxwsserver -nameserver corbaname::testserver:900 -name Sample_application_fromjava

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

29.5　Webサービスクライアントの開発例（SEI起点・wsi:swaRef形式の添付ファイル）

ここでは，添付ファイルを使用して，SEIを起点とした場合のWebサービスクライアントの開発例を説明します。

29.5.1　サービスクラスを生成する

cjwsimportコマンドを実行すると，サービスクラスなどWebサービスクライアントの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

cjwsimportコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥attachments¥client¥
> mkdir src¥
> mkdir classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes http://webhost:8085/attachments_dynamic_generate/UserInfoService?wsdl

正常に終了すると，c:¥temp¥jaxws¥works¥attachments¥client¥src¥com¥sample¥ディレクトリにJavaソースが生成されます。

生成物の一覧を次に示します。

表29‒4　サービスクラス生成時の生成物（SEI起点・添付ファイル）

ファイル名

説明

GetUserData.java

WSDL定義の要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

GetUserDataResponse.java

WSDL定義の応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

UserData.java

UserDataに対応するJavaBeanクラスです。

UserInfoImpl.java

WSDL定義の「サービス」に対応するSEIです。

UserInfoService.java

サービスクラスです。

UserInfoException.java

UserInfoExceptionに対応するJavaBeanクラスです。

UserInfoException_Exception.java

フォルトbeanのラッパ例外クラスです。

29.5.2　Webサービスクライアントの実装クラスを作成する

Webサービスを利用するWebサービスクライアントの実装クラスを作成します。

Webサービスに対して1回の呼び出しをするWebサービスクライアントの作成例を次に示します。

package com.sample.client;

import java.io.File;

import javax.activation.DataHandler;
import javax.activation.FileDataSource;

import com.sample.UserInfoImpl;
import com.sample.UserData;
import com.sample.UserInfoService;
import com.sample.UserInfoException_Exception;

public class TestClient {
    public static void main( String[] args ) {
        try {
            //DataHandlerオブジェクト生成
            File imagefile = new File("image.jpg");
            FileDataSource fdSource = new FileDataSource(imagefile);
            DataHandler dhandler = new DataHandler(fdSource);

            UserInfoService service = new UserInfoService();
            UserInfoImpl_port = service.getUserInfoImplPort();

            UserData userdata = port.getUserData( "1", dhandler );

            System.out.print( "[RESULT] " + userdata.getMessage() );
            System.out.println( " Name:" + userdata.getName()
                                    + ", Section:" + userdata.getSection() );
        }
        catch( UserInfoException_Exception e ){
            e.printStackTrace();
        }
        catch( Exception e ){
            e.printStackTrace();
        }
    }

}

作成したTestClient.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥attachments¥client¥src¥com¥sample¥client¥ディレクトリに保存します。

29.5.3　Webサービスクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービスクライアントをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥attachments¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥com¥sample¥client¥TestClient.java

正常に終了すると，c:¥temp¥jaxws¥works¥attachments¥client¥classes¥com¥sample¥client¥ディレクトリに，TestClient.classが生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

29.6　Webサービスの実行例（SEI起点・wsi:swaRef形式の添付ファイル）

ここでは，添付ファイルを使用して，SEIを起点とした場合のWebサービスクライアントの実行例を説明します。

29.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxws¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。

作成したJavaアプリケーション用オプション定義ファイルは，c:¥temp¥jaxws¥works¥attachments¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

29.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxws¥works¥attachments¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

29.6.3　Webサービスクライアントを実行する

cjclstartapコマンドを使用して，Webサービスクライアントを実行します。

Webサービスクライアントの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥attachments¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  com.sample.client.TestClient

正常に終了すると，Webサービスクライアントの実行結果が表示されます。実行結果の表示例を次に示します。

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxws¥works¥attachments¥client, PID = 2636)
[RESULT] Success. Name:Sato Taro, Section:The personnel section
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

30　添付ファイル機能（MTOM/XOP）

添付ファイル機能を使用することで，テキストデータだけでなく，画像データや音声データなどをWebサービスで扱えます。

この章では，添付ファイル機能の概要，および添付ファイル機能を使用した場合のマッピング規則について説明します。

30.1　添付ファイル機能とは（MTOM/XOP）

MTOM/XOP仕様形式の添付ファイル機能とは，SOAP Message Transmission Optimization Mechanism（MTOM）とXML-binary Optimized Packaging（XOP）の両機能を組み合わせ，SOAPメッセージ中にあるBase64形式のデータ（xsd:base64Binary型のXMLデータ）をバイナリデータとして送受信する機能です。この機能によって送受信されるデータは，MIME Multipart/Related構造のSOAPメッセージに添付されます。

次に示す例を基に，添付ファイル機能の概要について説明します。

図30‒1　添付ファイル機能を使用したバイナリデータの送受信

30.2　添付ファイルのJavaインタフェース（MTOM/XOP）

ここでは，Javaインタフェース内で添付ファイルを指定するJava型について説明します。

30.2.1　MTOM/XOP仕様形式の添付ファイルの対象

MTOM/XOP仕様形式の添付ファイルは，次に示す個所のBase64形式のデータにマッピングされるJava型がすべて対象です。

メソッド引数

メソッド戻り値

ユーザ定義型のフィールド

Base64形式のデータにマッピングされるJava型が複数ある場合，特定のJava型だけをMTOM/XOP仕様形式の添付ファイルの対象にすることはできません。

30.2.2　MTOM/XOP仕様形式の添付ファイルで使用するアノテーション

MTOM/XOP仕様形式の添付ファイルで使用するアノテーションは次のとおりです。

javax.xml.ws.soap.MTOM

javax.xml.bind.annotation.XmlMimeType

30.2.3　MTOM/XOP仕様形式の添付ファイルの使用方法

WebサービスでMTOM/XOP仕様形式の添付ファイルを使用するには，Webサービス実装クラスにjavax.xml.ws.soap.MTOMアノテーションをアノテートします。MTOM/XOP仕様形式の添付ファイルを使用したWebサービス実装クラスの例を次に示します。

package com.sample;

@MTOM
@BindingType(・・・)
public class UserInfoImpl implements UserInfo {

    public UserData setUserData(Image image)
        throws UserDefinedException {
        ・・・・・・
    }
}

また，javax.xml.ws.soap.MTOMアノテーションの代わりにjavax.xml.ws.soap.SOAPBindingインタフェースのフィールド値をjavax.xml.ws.BindingTypeアノテーションに指定することで，MTOM/XOP仕様形式の添付ファイルを使用できます。javax.xml.ws.soap.MTOMアノテーションとjavax.xml.ws.BindingTypeアノテーションに指定するjavax.xml.ws.soap.SOAPBindingインタフェースのフィールド値の関係を次の表に示します。

表30‒1　MTOMアノテーションとSOAPBindingインタフェースのフィールドの関係

項番

MTOMアノテーション

BindingTypeアノテーション

MTOM/XOP仕様形式の添付ファイル

アノテーション有無

enabled要素値

SOAPBindingインタフェースのフィールド値

フィールド値の記述可否

1

あり

true

SOAP11HTTP_BINDING

可

○

2

SOAP12HTTP_BINDING

可

○

3

SOAP11HTTP_MTOM_BINDING

可

○

4

SOAP12HTTP_MTOM_BINDING

可

○

5

false

SOAP11HTTP_BINDING

可

×

6

SOAP12HTTP_BINDING

可

×

7

SOAP11HTTP_MTOM_BINDING

否※

−

8

SOAP12HTTP_MTOM_BINDING

否※

−

9

なし

−

SOAP11HTTP_BINDING

可

×

10

SOAP12HTTP_BINDING

可

×

11

SOAP11HTTP_MTOM_BINDING

可

○

12

SOAP12HTTP_MTOM_BINDING

可

○

（凡例）

○：有効です。

×：無効です。

−：該当しません。

注※

Webサービス開始時にjavax.xml.ws.WebServiceExceptionが発生します。

javax.xml.ws.soap.MTOMアノテーションの代わりにjavax.xml.ws.soap.SOAPBindingインタフェースのフィールドを使用したWebサービス実装クラスの例を次に示します。

package com.sample;

@BindingType(SOAPBinding.SOAP11HTTP_MTOM_BINDING)
public class UserInfoImpl implements UserInfo {

    public UserData setUserData(Image image)
        throws UserDefinedException {
        ・・・・・・
    }
}

30.2.4　Document BareスタイルでのMTOM/XOP仕様形式の添付ファイル

Document BareスタイルのJavaクラスで，MTOM/XOP仕様形式の添付ファイルを使用し，Java型とMIMEタイプを関連づける場合，Java型をサービスメソッドの戻り値やパラメタに使用しないでください。Java型とMIMEタイプを関連づける場合は，ユーザ定義型のフィールドにJava型を使用し，そのフィールドのgetterメソッドにjavax.xml.bind.annotation.XmlMimeTypeアノテーションをアノテートします。

30.3　添付ファイルのWSDL（MTOM/XOP）

WSDLにMTOM/XOP仕様形式の添付ファイルが使用されていることを示す要素および属性はありません。そのため，WSDLからWebサービスがMTOM/XOP仕様形式の添付ファイルを使用しているかどうかを判別することはできません。

30.3.1　non-wrapperスタイルでのMTOM/XOP仕様形式の添付ファイル（MTOM/XOP）

non-wrapperスタイルのWSDLで，MTOM/XOP仕様形式の添付ファイルを使用し，xsd:base64Binary型にMIMEタイプを指定する場合，wsdl:part要素から参照されるxsd:element要素のtype属性にxsd:base64Binary型を使用しないでください。xsd:base64Binary型にMIMEタイプを指定する場合は，wsdl:part要素から参照されるxsd:element要素のtype属性に複合型を使用し，その複合型のxsd:element要素のtype属性にxsd:base64Binary型を指定し，xmime:expectedContentTypes属性を付与します。

(1)　WSDL内でのxop:Include要素の使用

xop:Include要素はMTOM/XOP仕様形式の添付ファイルのSOAPメッセージ中に出現し，ルートパートと添付ファイルパートを関連づける要素です。そのため，WSDLのスキーマ宣言にxop:Include要素を使用できません。WSDLのスキーマ宣言にxop:Include要素を使用した場合，動作は保証されません。

30.4　JAX-WSエンジンの動作

Webサービス側とWebサービスクライアント側のJAX-WSエンジンの動作について説明します。

30.4.1　Webサービス側JAX-WSエンジンの動作

Webサービス側JAX-WSエンジンでMTOM/XOP仕様形式の添付ファイルを使用できるかどうかは，Webサービス実装クラスに指定されているjavax.xml.ws.soap.MTOMアノテーション，またはjavax.xml.ws.BindingTypeアノテーションに指定するSOAPBindingインタフェースのフィールド値に依存します。MTOM/XOP仕様形式の添付ファイルの使用可否とリクエストメッセージを受信したときの動作を次の表に示します。

表30‒2　MTOM/XOP仕様形式の添付ファイルの使用可否とリクエストメッセージを受信したときの動作

項番

MTOM/XOP仕様形式の添付ファイル

受信したリクエストメッセージに含まれるデータ

受信の成功／失敗

しきい値と送信する添付ファイルサイズの関係※

送信するレスポンスメッセージに含まれるデータ

1

使用する

バイナリデータ

成功

しきい値≦添付ファイルのサイズ

バイナリデータ

2

Base64形式のデータ

成功

しきい値＞添付ファイルのサイズ

3

使用しない

バイナリデータ

成功

なし

Base64形式のデータ

4

Base64形式のデータ

成功

なし

注※

javax.activation.DataHandlerを使用した場合はしきい値で判定されません。常にバイナリデータとして送信します。

Webサービス実装クラスにjavax.xml.ws.soap.MTOMアノテーションを指定しない場合やjavax.xml.ws.BindingTypeアノテーションに指定するSOAPBindingインタフェースのフィールド値にSOAPBinding.SOAP11HTTP_MTOM_BINDINGおよびSOAPBinding.SOAP12HTTP_MTOM_BINDINGを指定しない場合，MTOM/XOP仕様形式の添付ファイルを使用しません。バイナリデータを含んだメッセージかどうかに関係なく，すべてのリクエストメッセージを受信します。また，レスポンスメッセージはBase64形式のデータを含んだメッセージを送信します。

(1)　javax.xml.bind.annotation.XmlMimeTypeアノテーションによる変化

Java型とMIMEタイプを関連づけるjavax.xml.bind.annotation.XmlMimeTypeアノテーションをSEIなどにアノテートしている場合とアノテートしていない場合では，MTOM/XOP仕様形式の添付ファイルで送信されるメッセージの添付ファイルパートにあるContent-Typeフィールドの値が変化します。javax.xml.bind.annotation.XmlMimeTypeアノテーションの可否と添付ファイルパートにあるContent-Typeフィールドの値の変化を次に示します。

XmlMimeTypeアノテーションをアノテートしている

添付ファイルパートにあるContent-Typeフィールドの値はXmlMimeTypeアノテーションのvalue要素の値となります。

XmlMimeTypeアノテーションをアノテートしていない

添付ファイルパートにあるContent-Typeフィールドの値は使用しているJava型に対応した初期値となります。初期値を次の表に示します。

表30‒3　Java型とContent-Typeの初期値

項番

Java型

Content-Typeの初期値

1

java.awt.Image

"image/png"

2

javax.xml.transform.Source

"application/xml"

3

javax.activation.DataHandler

javax.activation.DataHandlerオブジェクトのMIMEタイプ※

4

java.awt.Imageの配列型

"image/png"

5

javax.activation.DataHandlerの配列型

javax.activation.DataHandlerオブジェクトのMIMEタイプ※

6

java.util.List<Image>

"image/png"

7

java.util.List<DataHandler>

javax.activation.DataHandlerオブジェクトのMIMEタイプ※

8

javax.xml.ws.Holder<Image>

"image/png"

9

javax.xml.ws.Holder<Source>

"application/xml"

10

javax.xml.ws.Holder<DataHandler>

javax.activation.DataHandlerオブジェクトのMIMEタイプ※

11

byte[]

"application/octet-stream"

注※

DataHandlerを使用した場合，Content-Typeフィールドの設定値はDataHandlerオブジェクトの生成方法によって異なります。

DataHandler（DataSource）コンストラクタで生成する場合

FileDataSourceの場合，入力となるファイルデータの拡張子から，JAFによって決定されたMIMEタイプがContent-Typeフィールド値として設定されます。

DataHandler（Object, String）コンストラクタで生成する場合

DataHandlerオブジェクト生成時に，コンストラクタの第2引数に指定した内容（MIMEタイプ）がそのままContent-Typeフィールド値として設定されます。

30.4.2　Webサービスクライアント側JAX-WSエンジンの動作

Webサービスクライアント側JAX-WSエンジンでMTOM/XOP仕様形式の添付ファイルを使用できるかどうかは，SEIを取得する際に使用するMTOMFeatureクラスに依存します。MTOM/XOP仕様形式の添付ファイルの使用可否とメッセージを送受信したときの動作を次の表に示します。

表30‒4　MTOM/XOP仕様形式の添付ファイルの使用可否とメッセージを送受信したときの動作

項番

MTOM/XOP仕様形式の添付ファイル

しきい値と送信する添付ファイルサイズの関係※

送信するリクエストメッセージに含まれるデータ

受信したレスポンスメッセージに含まれるデータ

受信の成功／失敗

1

使用する

しきい値≦添付ファイルのサイズ

バイナリデータ

バイナリデータ

成功

2

Base64形式のデータ

成功

3

しきい値＞添付ファイルのサイズ

Base64形式のデータ

バイナリデータ

成功

4

Base64形式のデータ

成功

5

使用しない

−

Base64形式のデータ

バイナリデータ

成功

6

Base64形式のデータ

成功

（凡例）

−：該当しません。

注※

javax.activation.DataHandlerを使用した場合はしきい値で判定されません。常にバイナリデータとして送信します。

MTOMFeatureクラスはほかのFeatureクラスと同時に使用できます。MTOMFeatureクラスとほかのFeatureクラスを同時に使用した例を次に示します。

package com.sample;

・・・・・・

public class TestClient {

    public static void main(String[] args) {
        try {
            File portrait = new File("portrait.png");
            if (!portrait.exists() ) {
                throw new RuntimeException("Cannot file ¥"portrait.png¥".");
            }
            BufferedImage image = ImageIO.read(portrait);

            AddressingFeature addressingFeature = new AddressingFeature();
            MTOMFeature mtomFeature = new MTOMFeature();

            UserInfoService service = new UserInfoService();
            UserInfoImpl port = service.getUserInfoImplPort(addressingFeature, mtomFeature);

            UserData userData = port.getUserData(image);
            ・・・・・・
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

MTOMFeatureクラスの代わりに，javax.xml.ws.soap.SOAPBindingのsetMTOMEnabledメソッドを使用することで，MTOM/XOP仕様形式の添付ファイルを使用できるかどうかを設定できます。javax.xml.ws.soap.SOAPBindingのsetMTOMEnabledメソッドを使用した，MTOM/XOP仕様形式の添付ファイルの使用可否の設定例を次に示します。

package com.sample;

・・・・・・

public class TestClient {

    public static void main(String[] args) {
        try {
            File portrait = new File("portrait.png");
            if (!portrait.exists() ) {
                throw new RuntimeException("Cannot file ¥"portrait.png¥".");
            }
            BufferedImage image = ImageIO.read(portrait);

            UserInfoService service = new UserInfoService();
            UserInfoImpl port = service.getUserInfoImplPort();

            BindingProvider bindingProvider = (BindingProvider)port;
            Binding         binding         = bindingProvider.getBinding();
            SOAPBinding     soapBinding     = (SOAPBinding)binding;
            soapBinding.setMTOMEnabled(true);

            UserData userData = port.getUserData(image);
            ・・・・・・
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

MTOM/XOP仕様形式の添付ファイルの使用可否をjavax.xml.ws.soap.SOAPBindingのsetMTOMEnabledメソッドで設定する場合，先にMTOMFeatureクラスやjavax.xml.ws.soap.SOAPBindingのsetMTOMEnabledメソッドで使用可否を設定していると，あとからsetMTOMEnabledメソッドに設定した値は無効となり，使用可否の設定はできません。

SEIを取得する際にMTOMFeatureクラスを使用しない場合やjavax.xml.ws.soap.SOAPBindingのsetMTOMEnabledメソッドによるMTOM/XOP仕様形式の添付ファイルの使用可否を設定しない場合，MTOM/XOP仕様形式の添付ファイルを使用しません。リクエストメッセージはBase64形式のデータを含んだメッセージを送信します。また，バイナリデータを含んだメッセージかどうかに関係なく，すべてのレスポンスメッセージを受信します。

(1)　xmime:expectedContentTypes属性による変化

WSDLのスキーマ要素にxmime:expectedContentTypes属性がある場合とない場合では，MTOM/XOP仕様形式の添付ファイルで送信されるメッセージの添付ファイルパートにあるContent-Typeフィールドの値が変化します。xmime:expectedContentTypes属性の有無と添付ファイルパートにあるContent-Typeフィールドの値の変化を次に示します。

xmime:expectedContentTypes属性がある

添付ファイルパートにあるContent-Typeフィールドの値はxmime:expectedContentTypes属性に指定されている値となります。

xmime:expectedContentTypes属性がない

添付ファイルパートにあるContent-Typeフィールドの値は"application/octet-stream"となります。

30.5　MTOM/XOP仕様形式の添付ファイルのSOAPメッセージ

MTOM/XOP仕様形式の添付ファイルを使用した場合のSOAPメッセージは，SOAP Messages with Attachmentsプロトコルを使用し生成されたMIME multipart/related構造です。ここでは，MTOM/XOP仕様形式の添付ファイルのSOAPメッセージについて説明します。

MTOM/XOP仕様形式の添付ファイル付きSOAPメッセージの構造を次の図に示します。

図30‒2　MTOM/XOP仕様形式の添付ファイル付きSOAPメッセージの構造

MTOM/XOP仕様形式の添付ファイル付きSOAPメッセージの各部の説明を次の表に示します。

表30‒5　MTOM/XOP仕様形式の添付ファイル付きSOAPメッセージの各部の説明

各部の名称

説明

HTTPヘッダ

HTTPプロトコルに依存するヘッダ情報です。

HTTPヘッダとHTTPボディの境界文字列

HTTPヘッダとHTTPボディの境界を示す文字列です。

HTTPボディ

送信するメッセージを記述します。

ルートパートおよび添付ファイルパートから構成されます。

┣

MIMEパートの境界文字列

各MIMEパートの境界を示す文字列です。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

ルートパート

┃

┃

メッセージ本体を記述するパートです。

MIMEヘッダとMIMEボディから構成され，必ず1個定義します。

┣

MIMEヘッダ

ルートパートのヘッダ情報です。

┣

┃

MIMEヘッダとMIMEボディ間の境界文字列

ルートパートのMIMEヘッダとMIMEボディ間の境界を示す文字列です。

┗

MIMEボディ

メッセージ本体を記述します。

┗

SOAPエンベロープ

SOAPエンベロープを記述します。

┣

SOAPヘッダ

SOAPメッセージのヘッダ情報を記述します。

┗

SOAPボディ

SOAPメッセージの本文（XML）を記述します。

┣

MIMEパートの境界文字列

各MIMEパートの境界を示す文字列です。

┣

┃

┃

┃

┃

┃

┃

┃

┃

添付ファイルパート

┃

┃

MTOM/XOP仕様形式の添付ファイルの内容を記述するパートです。

MIMEヘッダとMIMEボディから構成され，0個以上定義します。

┣

MIMEヘッダ

添付ファイルパートのヘッダ情報です。

┣

┃

MIMEヘッダとMIMEボディ間の境界文字列

添付ファイルパートのMIMEヘッダとMIMEボディ間の境界を示す文字列です。

┗

MIMEボディ

MTOM/XOP仕様形式の添付ファイルの内容（バイナリデータ）を記述します。

┗

MIMEパートの終端文字列

MIMEパートの終端を表す文字列です。

30.5.1　添付ファイルからSOAPメッセージへのマッピング（MTOM/XOP）

添付ファイルからSOAPメッセージへマッピングするときの設定値について説明します。マッピング規則については，「30.5.2　添付ファイルからSOAPメッセージへのマッピングの注意事項（MTOM/XOP）」と合わせて確認してください。

(1)　HTTPヘッダ

MTOM/XOP仕様形式の添付ファイル使用時に，HTTPヘッダのフィールドおよびパラメタに設定される値を次の表に示します。

表30‒6　HTTPヘッダのフィールドおよびパラメタの設定値

項番

フィールド名

パラメタ名

設定値

1

Content-Type

−

"multipart/related"が設定されます。※

2

start

ルートパートのContent-Idが設定されます。

3

type

"application/soap+xml"が設定されます。

4

boundary

MIMEパートの境界文字列が設定されます。

5

start-info

SOAP 1.1仕様

"text/xml"が設定されます。

SOAP 1.2仕様

"application/soap+xml"が設定されます。

（凡例）

−：Content-Typeに直接設定されることを示します。

注※

MIMEパートがルートパートだけの場合や少なくとも1個の添付ファイルMIMEパートを並べている（MTOM/XOP仕様形式の添付ファイル付きSOAPメッセージである）場合でも，"multipart/related"を設定してください。

(2)　HTTPボディ

HTTPボディは，ルートパート，添付ファイルパート，および各パートの境界文字列で構成されます。添付ファイル使用時に，各パートに生成される内容，および設定される値を示します。

(a)　ルートパートのMIMEヘッダ

添付ファイル使用時に，ルートパートのフィールドに設定される値を次の表に示します。

表30‒7　ルートパートのフィールドおよびパラメタの設定値

項番

フィールド名

パラメタ名

設定値

1

Content-Type

−

"application/xop+xml"が設定されます。

2

charset

"utf-8"が設定されます。

3

type

SOAP 1.1仕様

"text/xml"が設定されます。

SOAP 1.2仕様

"application/soap+xml"が設定されます。

4

Content-Transfer-Encoding

なし

"binary"が設定されます。

5

Content-Id

なし

"rootpart*"＋"グローバルに一意な値"＋"@"＋"jaxws.cosminexus.com"が設定されます。

（凡例）

−：Content-Typeに直接設定されることを示します。

(b)　ルートパートのMIMEボディ

添付ファイルを使用する場合，ルートパートのMIMEボディには，SOAPエンベロープがそのまま格納されます。SOAPエンベロープ内のSOAPボディからMTOM/XOP仕様形式の添付ファイルを参照する方法として，XOPが使用されます。

(c)　添付ファイルパートのMIMEヘッダ

添付ファイル使用時に，添付ファイルパートのMIMEヘッダに設定される値を次の表に示します。

表30‒8　添付ファイルパートのフィールドおよびパラメタの設定値

項番

フィールド名

パラメタ名

設定値

1

Content-Type

−

XmlMimeTypeアノテーションのvalue要素に指定したMIMEタイプのテキスト表現が設定されます。※1，※2，※3

2

charset

MTOM/XOP仕様形式の添付ファイルの対象がSource型の場合，"UTF-8"が設定されます。※4

MTOM/XOP仕様形式の添付ファイルの対象がDataHandler型の場合，DataHandlerオブジェクト生成時に指定した文字コードが設定されます。※5

MTOM/XOP仕様形式の添付ファイルの対象が上記以外のJava型の場合，パラメタは出現しません。

3

Content-Transfer-Encoding

なし

"binary"が設定されます。

4

Content-Id

なし

"グローバルに一意な値"＋"@"＋"jaxws.cosminexus.com"が設定されます。

（凡例）

−：Content-Typeに直接設定されることを示します。

注※1

Content-Typeフィールドに設定されるMIMEタイプで，XMLを表すMIMEタイプである"text/xml"と"application/xml"では，"application/xml"をお勧めします。

注※2

XmlMimeTypeアノテーションのvalue要素にパラメタを持ったMIMEタイプを指定した場合，そのパラメタについてもContent-Typeフィールドに設定されます。

注※3

Content-Typeフィールドの設定値は，DataHandlerオブジェクトの生成方法によって，次のように異なります。

DataHandler(DataSource)コンストラクタで生成する場合

FileDataSourceの場合，入力となる添付ファイルの拡張子から，JAFによって決定されたMIMEタイプがContent-Typeフィールド値として設定されます。

DataHandler(Object, String)コンストラクタで生成する場合

DataHandlerオブジェクト生成時に，コンストラクタの第2引数に指定した内容（MIMEタイプ）がそのままContent-Typeフィールド値として設定されます。

注※4

xmime:expectedContentTypes属性またはjavax.xml.bind.annotation.XmlMimeTypeアノテーションで指定したMIMEタイプがcharsetを含む場合，Content-Type フィールドにあるcharsetの設定値は，指定したMIMEタイプに含まれるcharsetの値になります。

注※5

次のようにDataHandlerオブジェクトを生成して，MTOM/XOP仕様形式の添付ファイルとして送信した場合，Content-Typeのcharsetには，第2引数に指定したcharsetパラメタ値「Shift_JIS」が設定されます。

DataHandler dhandler = new DataHandler ("あいうえお", "text/plain; charset=Shift_JIS");

MTOM/XOP仕様形式の添付ファイルのJava型のjavax.activation.DataHandler型は，wsi:swaRef形式の添付ファイルとして使用できるJava型のjavax.activation.DataHandler型と同様に，JavaBeans Activation Framework(JAF)の型です。そのため，javax.activation.DataHandler型には任意のMIMEタイプの添付ファイルデータを指定できます。

30.5.2　添付ファイルからSOAPメッセージへのマッピングの注意事項（MTOM/XOP）

添付ファイルからSOAPメッセージをマッピングするときの注意事項について説明します。

(1)　MIMEパートの記述順序

MIMEパートは1個のルートパートと0個以上の添付ファイルパートで構成されます。

ルートパートは，MIMEパートの先頭に記述されます。ルートパートのあとに，添付ファイルパートが記述されます。

添付ファイルパートでは，Javaインタフェースで指定された引数や戻り値がマッピングされます。Javaインタフェースの指定内容と添付ファイルパートでの記述順序の対応を次の表に示します。

表30‒9　Javaインタフェースの指定内容と添付ファイルパートの記述順序

項番

Javaインタフェースでの指定内容

添付ファイルパートの記述順序

1

メソッド引数

メソッド引数に指定された順に記述されます。

2

メソッド戻り値

添付ファイルパートの先頭に記述されます。

3

配列型

配列内の要素順に記述されます。

4

ユーザ定義型

ユーザ定義型内での指定順に記述されます。

ユーザ定義型の中で指定したユーザ定義型で，添付ファイルのJava型を指定するときは，深さ優先順で添付ファイルパートが記述されます。

Javaインタフェースと添付ファイルパートのマッピング例を示します。

図30‒3　Javaインタフェースと添付ファイルパートのマッピング例

(2)　ルートパートから添付ファイルへのマッピング

MTOM/XOP仕様形式の添付ファイルの場合，ルートパートから添付ファイルパートへのマッピングにはXOP仕様で定められたXOP情報セットが使用されます。XOP情報セットがルートパートのSOAPボディに記述され，対応する添付ファイルパートのContent-Idが設定されます。Content-Idによって，ルートパートから対応する添付ファイルパートを参照できます。ルートパートから添付ファイルパートの参照例を次に示します。背景色付きの太字部分がCID URLスキームと，対応する添付ファイルパートのContent-Idになります。

-uuid:e63fe7dc-ad8a-4fb1-8f56-ce7b5841a06f
Content-Type: text/xml

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <getUserData xmlns="http://localhost">
      <in0>
        <xop:Include xmlns="http://www.w3.org/2004/08/xop/include" href="cid:39820675-44bb-4e28-9926-577bf27fa07c@jaxws.cosminexus.com"/>
      </in0>
    </getUserData>
  </S:Body>
</S:Envelope>

--uuid:e63fe7dc-ad8a-4fb1-8f56-ce7b5841a06f
Content-Id:<39820675-44bb-4e28-9926-577bf27fa07c@jaxws.cosminexus.com>
Content-Type: image/jpeg
Content-Transfer-Encoding: binary

[添付データ]
--e63fe7dc-ad8a-4fb1-8f56-ce7b5841a06f--

(a)　XOP情報セットの形式

ルートパートのSOAPボディに記述されるXOP情報セットの形式を次に示します。

"<xop: Include href=" ＋ <CID URLスキーム> ＋ "/>"

(b)　MTOM/XOP仕様形式の添付ファイルのデータサイズによるマッピング方法

MTOM/XOP仕様形式の添付ファイルは，マッピング元であるJava型とJavaインタフェースに指定する添付ファイルのデータサイズによって，添付ファイルパートへのマッピング方法が異なります。マッピング方法を次の表に示します。

表30‒10　MTOM/XOP仕様形式の添付ファイルのデータサイズによる添付ファイルパートへのマッピング

項番

Java型

添付ファイルのデータサイズ

添付ファイルパートへのマッピング

1

byte[]

null

マッピングしない※1

2

0バイトのデータ

マッピングする※2

3

0バイトより多いバイト数のデータ

マッピングする※3

4

java.awt.Image型

null

マッピングしない※1

5

0バイトのデータ

マッピングしない※1

6

0バイトより多いバイト数のデータ

マッピングする※3

7

javax.xml.transform.Source型

null

マッピングしない※1

8

0バイトのデータ

マッピングする※2

9

0バイトより多いバイト数のデータ

マッピングする※3

10

javax.activation.DataHandler型

null

マッピングしない※1

11

0バイトのデータ

マッピングする※2

12

0バイトより多いバイト数のデータ

マッピングする※3

注※1

wsi:swaRef形式の添付ファイルと異なり，ルートパートだけで構成されるマルチパートとなります。ルートパートにあるMIMEボディにはSOAPエンベロープを格納します。SOAPボディに該当する引数の要素は出現しません。添付ファイルデータがnullである場合のXMLへのマッピング例を次に示します。

Webサービス呼び出しプログラム

...
UserInfoService service = new UserInfoService();
UserInfo impl = service.getUserInfo(new MTOMFeature());

result = impl.getUserData(  null  );
...

SOAPメッセージ

--uuid:cbc0221b-8ee3-40a3-adc1-d5fa52a8d66e
Content-Id: <rootpart*cbc0221b-8ee3-40a3-adc1-d5fa52a8d66e@jaxws.cosminexus.com>
Content-Type: application/xop+xml;charset=utf-8;type="text/xml"
Content-Transfer-Encoding: binary

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:getUserData xmlns:ns2="http://localhost">
    </ns2:getUserData>
  </S:Body>
</S:Envelope>
--uuid:cbc0221b-8ee3-40a3-adc1-d5fa52a8d66e--

注※2

ルートパートとデータがない（MIMEボディが空である）添付ファイルパートから構成されるマルチパートとなります。Javaインタフェースで複数の添付ファイルデータを指定している場合は，添付ファイルパートは複数となります。

注※3

ルートパートと添付ファイルパートから構成されるマルチパートとなります。Javaインタフェースで複数の添付ファイルデータを指定している場合は，添付ファイルパートは複数となります。

30.5.3　SOAPメッセージから添付ファイルへのマッピング（MTOM/XOP）

JAX-WSエンジンは，受信した添付ファイル付きSOAPメッセージがMTOM/XOP仕様に従っている場合にだけ，添付ファイル付きSOAPメッセージから添付ファイルデータへのマッピングは保証されます。それ以外のSOAPメッセージを受信した場合の動作は保証されません。

30.6　注意事項

MTOM/XOP形式の添付ファイルを使用するときの注意事項を次に示します。

wsi:swaRef形式の添付ファイルと同時に使用できません。同時に使用した場合の動作は保証されません。

wsi:swaRef形式の添付ファイルと，一つのオペレーションで同時に送受信することはできません。

プロバイダ実装クラス（javax.xml.ws.providerインタフェースを実装するクラス）では使用できません。プロバイダ実装クラスでMTOM/XOP仕様形式の添付ファイルを使用した場合，動作は保証されません。

ハンドラフレームワークは併用できません。併用した場合の動作は保証されません。ハンドラフレームワークを使用する場合で添付ファイルを送受信したいときは，添付ファイル機能（wsi:swaRef形式）を使用してください。

WSS（Web Services-Security）は併用できません。併用した場合の動作は保証されません。

30.7　添付ファイルで使用できるJava型と送受信できるデータ（MTOM/XOP形式）

MTOM/XOP形式の添付ファイルには，送受信するデータに応じてbyte[]，およびそれ以外のJava型を使用できます。MTOM/XOP形式の添付ファイルで使用できるJava型と送受信できるデータを次の表に示します。

表30‒11　MTOM/XOP形式の添付ファイルで使用できるJava型と送受信できるデータ

項番

Java型

送受信できるデータ

1

byte[]

すべてのデータの送受信ができる。

2

javax.activation.DataHandler

3

java.awt.Image

イメージデータの送受信ができる。

4

javax.xml.transform.Source

XMLファイルの送受信ができる。

30.7.1　送信するデータごとのJavaオブジェクトの生成方法

MTOM/XOP形式の添付ファイルとして送信するデータに応じたJavaオブジェクトの生成方法を説明します。

(1)　存在するテキストファイルを送信する場合

すでに存在しているテキストファイルを送信する場合，byte[]を使用する方法とjavax.activation.DataHandlerを使用する方法があります。それぞれの手順を説明します。

(a)　byte[]を使用する方法

byte[]を使用して，すでに存在するテキストファイルを送信する場合の手順を次に示します。

java.io.FileInputStreamオブジェクトを生成します。

送信する添付ファイルデータのファイルパスを引数に指定して，java.io.FileInputStreamオブジェクトを生成します。

java.io.FileInputStream fileInputStream =
    new java.io.FileInputStream("sample.txt");

byte[]を生成します。

java.io.ByteArrayOutputStreamオブジェクトにjava.io.FileInputStreamオブジェクトから読み込んだバイトデータを書き込みます。

その後，java.io.ByteArrayOutputStreamクラスのtoByteArray()メソッドを使用して，byte[]を生成します。

java.io.ByteArrayOutputStream byteArrayOutputStream =
    new java.io.ByteArrayOutputStream();

int i = 0;
while ((i = fileInputStream.read()) != -1) {
    byteArrayOutputStream.write(i);
}

byte[] bytes = byteArrayOutputStream.toByteArray();

(b)　javax.activation.DataHandlerを使用する方法

javax.activation.DataHandlerを使用して，すでに存在するファイルを添付して送信する場合の手順を次に示します。

javax.activation.DataSourceオブジェクトを生成します。

送信する添付ファイルデータのファイルパスを引数に指定し，javax.activation.FileDataSourceオブジェクトを生成します。

javax.activation.FileDataSource fileDataSource =
    new javax.activation.FileDataSource("sample.txt");

javax.activation.DataHandlerオブジェクトを生成します。

javax.activation.FileDataSourceオブジェクトを引数に指定し，javax.activation.DataHandlerオブジェクトを生成します。

javax.activation.DataHandler dataHandler =
    new javax.activation.DataHandler(fileDataSource);

(2)　存在するイメージファイルを送信する場合

すでに存在しているイメージファイルを送信する場合，byte[]を使用する方法，javax.activation.DataHandlerを使用する方法，およびjava.awt.Imageを使用する方法があります。それぞれの手順を説明します。

(a)　byte[]を使用する方法

byte[]を使用して，すでに存在するイメージファイルを送信する場合の手順を示します。

java.io.FileInputStreamオブジェクトを生成します。

送信する添付ファイルデータのファイルパスを引数に指定し，java.io.FileInputStreamオブジェクトを生成します。

java.io.FileInputStream fileInputStream =
    new java.io.FileInputStream("sample.png");

byte[]を生成します。

java.io.ByteArrayOutputStreamオブジェクトにjava.io.FileInputStreamオブジェクトから読み込んだバイトデータを書き込みます。

その後，java.io.ByteArrayOutputStreamクラスのtoByteArray()メソッドを使用して，byte[]を生成します。

java.io.ByteArrayOutputStream byteArrayOutputStream =
    new java.io.ByteArrayOutputStream();

int i = 0;
while ((i = fileInputStream.read()) != -1) {
    byteArrayOutputStream.write(i);
}

byte[] bytes = byteArrayOutputStream.toByteArray();

(b)　javax.activation.DataHandlerを使用する方法

javax.activation.DataHandlerを使用して，すでに存在するイメージファイルを送信する場合の手順を示します。

javax.activation.DataSourceオブジェクトを生成します。

送信する添付ファイルデータのファイルパスを引数に指定し，javax.activation.FileDataSourceオブジェクトを生成します。

javax.activation.FileDataSource fileDataSource =
    new javax.activation.FileDataSource("sample.png");

javax.activation.DataHandlerオブジェクトを生成します。

javax.activation.FileDataSourceオブジェクトを引数に指定し，javax.activation.DataHandlerオブジェクトを生成します。

javax.activation.DataHandler dataHandler =
    new javax.activation.DataHandler(fileDataSource);

(c)　java.awt.Imageを使用する方法

java.awt.Imageをすでに存在するイメージファイルを送信する場合の手順を示します。

java.awt.Imageオブジェクトを生成します。

java.awt.ToolkitクラスにあるcreateImage(String)メソッドの引数に送信する添付ファイルデータのファイルパスを指定し，java.awt.Imageオブジェクトを生成します。

java.awt.Image image =
    Toolkit.getDefaultToolkit().createImage("sample.png");

(3)　存在するXMLファイルを送信する場合

すでに存在しているXMLファイルを送信する場合，byte[]を使用する方法，javax.activation.DataHandlerを使用する方法，およびjavax.xml.transform.Sourceを使用する方法があります。それぞれの手順を説明します。

(a)　byte[]を使用する方法

byte[]を使用して，すでに存在するXMLファイルを送信する場合の手順を示します。

java.io.FileInputStreamオブジェクトを生成します。

送信する添付ファイルデータのファイルパスを引数に指定し，java.io.FileInputStreamオブジェクトを生成する。

java.io.FileInputStream fileInputStream =
    new java.io.FileInputStream("sample.xml");

byte[]を生成します。

java.io.ByteArrayOutputStreamオブジェクトにjava.io.FileInputStreamオブジェクトから読み込んだバイトデータを書き込みます。

その後，java.io.ByteArrayOutputStreamクラスのtoByteArray()メソッドを使用して，byte[]を生成します。

java.io.ByteArrayOutputStream byteArrayOutputStream =
    new java.io.ByteArrayOutputStream();

int i = 0;
while ((i = fileInputStream.read()) != -1) {
    byteArrayOutputStream.write(i);
}

byte[] bytes = byteArrayOutputStream.toByteArray();

(b)　javax.activation.DataHandlerを使用する方法

javax.activation.DataHandlerを使用して，すでに存在するXMLファイルを送信する場合の手順を示します。

javax.activation.DataSourceオブジェクトを生成します。

送信する添付ファイルデータのファイルパスを引数に指定し，javax.activation.FileDataSourceオブジェクトを生成します。

javax.activation.FileDataSource fileDataSource =
    new javax.activation.FileDataSource("sample.xml");

javax.activation.DataHandlerオブジェクトを生成します。

javax.activation.FileDataSourceオブジェクトを引数に指定し，javax.activation.DataHandlerオブジェクトを生成します。

javax.activation.DataHandler dataHandler =
    new javax.activation.DataHandler(fileDataSource);

(c)　javax.xml.transform.Sourceを使用する方法

javax.xml.transform.Sourceを使用して，すでに存在するXMLファイルを送信する場合の手順を示します。

javax.xml.transform.Sourceオブジェクトを生成します。

送信する添付ファイルデータのファイルパスを引数に指定し，javax.xml.transform.stream.StreamSourceオブジェクトを生成します。

javax.xml.transform.stream.StreamSource streamSource =
    new javax.xml.transform.stream.StreamSource("sample.xml");

(4)　java.lang.Stringオブジェクトを送信する場合

java.lang.Stringオブジェクトを送信する場合byte[]を使用する方法，およびjavax.activation.DataHandlerを使用する方法があります。それぞれの手順を説明します。

(a)　byte[]を使用する方法

byte[]を使用して，java.lang.Stringオブジェクトを送信する場合の手順を示します。

java.lang.Stringオブジェクトを生成します。

java.lang.String str =
    new java.lang.String("あいうえお");

byte[]を生成します。

java.lang.StringクラスのgetBytes()メソッドを使用して，byte[]を生成します。

byte[] bytes =
    str.getBytes();

(b)　javax.activation.DataHandlerを使用する方法

javax.activation.DataHandlerを使用して，java.lang.Stringオブジェクトを送信する場合の手順を示します。

java.lang.Stringオブジェクトを生成します。

java.lang.String str =
    new java.lang.String("あいうえお");

javax.activation.DataHandlerオブジェクトを生成します。

java.lang.StringオブジェクトとMIMEタイプを引数に指定し，javax.activation.DataHandlerオブジェクトを生成します。

javax.activation.DataHandler dataHandler =
    new javax.activation.DataHandler(str, "text/plain; charset=UTF-8");

(5)　javax.activation.DataHandlerオブジェクト生成時の注意事項

MTOM/XOP仕様形式の添付ファイルで，テキストファイル，XMLファイル，またはjava.lang.Stringオブジェクト（文字列）をjavax.activation.DataHandlerオブジェクトとして送信する場合，wsi:swaRef形式の添付ファイルと同様にjavax.activation.DataHandlerクラスのDataHandler（Object, String）コンストラクタを使用することで，オブジェクトに含まれる文字の文字コードを指定できます。

DataHandler（Object, String）コンストラクタを使用した文字コードの指定方法などの詳細は，「28.5.1(4)　javax.activation.DataHandlerオブジェクト生成時の注意事項」を参照してください。

30.7.2　受信したデータの取得方法

MTOM/XOP仕様形式の添付ファイルで受信したデータがjavax.activation.DataHandlerオブジェクト以外（byte[]，java.awt.Imageオブジェクト，およびjavax.xml.transform.Sourceインスタンス）の場合，JAXBが受信したデータを適切なJavaオブジェクトに変換するため，アプリケーションで変換する必要はありません。

受信したデータがjavax.activation.DataHandlerオブジェクトの場合，wsi:swaRef形式の添付ファイルと同様の方法で，受信したデータを取得できます。

wsi:swaRef形式の添付ファイルの取得方法については，「28.5.2　添付ファイルデータを取得する方法（wsi:swaRef形式）」を参照してください。

(1)　javax.activation.DataHandlerオブジェクト取得時の注意事項

MTOM/XOP仕様形式の添付ファイルを含むMIME Multipart/Related構造のSOAPメッセージを受信すると，ストリーミングされたMTOM/XOP仕様形式の添付ファイルとして操作できます。MTOM/XOP仕様形式の添付ファイルの受信側では，javax.activation.DataHandlerオブジェクトが持つ入力ストリームからすべてのデータを読み込まないと受信処理が完了しないため，送信側の送信処理は受信側の受信処理が完了するまで待ち状態が続きます。

この状態を解消するためには，javax.activation.DataHandlerオブジェクトが持つjava.io.InputStreamオブジェクトからすべてのデータを読み込むか，javax.activation.DataHandlerクラスのwriteTo(java.io.OutputStream)メソッドを使用して入力ストリームのデータを出力ストリームに書き込む必要があります。

(2)　javax.xml.transform.Sourceオブジェクト取得時の注意事項

MTOM/XOP仕様形式の添付ファイルで受信したデータがjavax.xml.transform.Sourceオブジェクトの場合，ストリーミングされたMTOM/XOP仕様形式の添付ファイルとして操作できます。javax.xml.transform.Sourceオブジェクトは，JAXBがjavax.xml.transform.stream.StreamSourceオブジェクトに変換します。

MTOM/XOP仕様形式の添付ファイルの受信側では，javax.xml.transform.stream.StreamSourceオブジェクトが持つ入力ストリームからすべてのデータを読み込まないと受信処理が完了しないため，送信側の送信処理は受信側の受信処理が完了するまで待ち状態が続きます。

この状態を解消するためには，javax.xml.transform.stream.StreamSourceオブジェクトが持つjava.io.Readerオブジェクトからすべてのデータを読み込む必要があります。

30.8　MIME Multipart/Related構造のSOAPメッセージの受信

1048576バイト以上のサイズのMIMEボディを含むMIME Multipart/Related構造のSOAPメッセージを受信した場合，JAX-WSエンジンはSOAPメッセージに含まれるMIMEボディを一時ファイルに出力します。

MIME Multipart/Related構造のSOAPメッセージの受信の詳細については，「10.24　MIME Multipart/Related構造のSOAPメッセージの受信」を参照してください。

31　SEIを起点とした開発の例（MTOM/XOP仕様形式の添付ファイル使用時）

この章では，添付ファイルを使用して，SEIを起点としたWebサービスを開発する場合の例を説明します。

31.1　開発例の構成（SEI起点・MTOM/XOP仕様形式の添付ファイル）

この章で説明する開発例では，SEIを起点としたWebサービスを開発します。開発するWebサービスは，MTOM/XOP仕様形式の添付ファイルを使用します。

開発するWebサービスの概要および利用する情報について説明します。

開発例の概要

社員番号，顔写真，社員名，所属というユーザ情報を管理し，Webサービスクライアントからの入力に対して，処理結果を返すWebサービスを新規に開発します。

Webサービスクライアントからの要求情報およびサーバからの応答情報を次の表に示します。

表31‒1　Webサービスクライアントからの要求情報

情報名

Javaデータ型

社員番号

java.lang.String

顔写真

javax.activation.DataHandler

表31‒2　サーバからの応答情報

情報名

Javaデータ型

登録確認メッセージ

java.lang.String

社員名

java.lang.String

所属

java.lang.String

サーバからの応答情報は，ユーザ定義型クラスのUserDataクラスで保持されます。

Webサービス開発時のカレントディレクトリの構成を次の表に示します。

表31‒3　カレントディレクトリの構成（SEI起点・添付ファイル）

ディレクトリ

説明

c:¥temp¥jaxws¥works¥mtom¥

カレントディレクトリです。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

server¥

Webサービスの開発で使用します。

┣

┃

┃

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

┗

application.xml

「31.3.4　application.xmlを作成する」で作成します。

┣

┃

┃

┃

src¥

Webサービスのソースファイル（*.java）を格納します。「31.3.1　Webサービス実装クラスを作成する」および「31.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

┃

┃

┃

┃

WEB-INF¥

WARファイルのWEB-INFディレクトリに対応します。

┣

web.xml

「31.3.3　web.xmlを作成する」で作成します。

┗

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「31.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

mtom_dynamic_generate.ear

「31.3.5　EARファイルを作成する」で作成します。

┗

mtom_dynamic_generate.war

┗

client¥

Webサービスクライアントの開発で使用します。

┣

┃

┃

┃

┃

src¥

Webサービスクライアントのソースファイル（*.java）を格納します。「31.5.1　サービスクラスを生成する」および「31.5.2　Webサービスクライアントの実装クラスを作成する」で使用します。

┣

┃

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「31.5.3　Webサービスクライアントの実装クラスをコンパイルする」で使用します。

┣

┃

portrait.png

Webサービスクライアントで使用するPNGファイルで使用します。

┣

┃

┃

usrconf.cfg

「31.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

┗

usrconf.properties

「31.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

カレントディレクトリのパスは，開発する環境に合わせて変更してください。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebサービスとWebサービスクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

31.2　開発例の流れ（SEI起点・MTOM/XOP仕様形式の添付ファイル）

この章で説明する開発例では，次の流れで開発および実行します。

Webサービスの開発

Webサービス実装クラスを作成する（31.3.1）

Webサービス実装クラスをコンパイルする（31.3.2）

web.xmlを作成する（31.3.3）

application.xmlを作成する（31.3.4）

EARファイルを作成する（31.3.5）

デプロイと開始

EARファイルをデプロイする（31.4.1）

Webサービスを開始する（31.4.2）

Webサービスクライアントの開発

cjwsimportコマンドを実行し，サービスクラスを生成する（31.5.1）

Webサービスクライアントの実装クラスを作成する（31.5.2）

Webサービスクライアントの実装クラスをコンパイルする（31.5.3）

Webサービスの実行

Javaアプリケーション用オプション定義ファイルを作成する（31.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（31.6.2）

Webサービスクライアントを実行する（31.6.3）

31.3　Webサービスの開発例（SEI起点・MTOM/XOP仕様形式の添付ファイル）

ここでは，SEIを起点とした場合のWebサービス（添付ファイルを使用）の開発例を説明します。

31.3.1　Webサービス実装クラスを作成する

Webサービスの処理を記述したWebサービス実装クラスを作成します。ここでは，受け取った要求メッセージの内容を計算して，応答メッセージを返すWebサービス実装クラスを作成します。

Webサービス実装クラスの作成例を次に示します。

package com.sample;

import java.awt.Image;
import javax.jws.WebService;
import javax.xml.ws.soap.MTOM;
import javax.xml.bind.annotation.XmlMimeType;

@MTOM
@WebService(serviceName="UserInfoService",targetNamespace="http://sample.com")
public class UserInfoImpl {

    public UserData getUserData(String in0, @XmlMimeType("image/png")Image in1)
        throws UserInfoException {

　　　　//社員情報への顔写真の登録処理
　　　　・・・・

        UserData userdata = new UserData();
        //登録した社員の名前と所属を設定
        if (in0.equals("1")) {
            userdata.setName("Sato Taro");
            userdata.setSection("The personnel section");
        } if ( ・・・・) {
            ・・・・・
    　　} ・・・・

　　　　//登録確認メッセージを設定
        if (in1 == null) {
            userdata.setMessage("Failure(no image).");
        } else {
            userdata.setMessage("Success.");
        }
        return userdata;
}
}

作成したUserInfoImpl.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥mtom¥server¥src¥com¥sample¥ディレクトリに保存します。

また，com.sample.UserInfoImplで使用しているユーザ定義型クラスcom.sample.UserDataを作成します。通常，ユーザ定義型クラスの作成は任意ですが，ここではユーザ定義型クラスを作成します。

ユーザ定義型クラスの作成例を次に示します。

package com.sample;

import java.lang.String;

public class UserData {

    private String message;
    private String name;
    private String section;

    public UserData() {
    }

    public String getMessage() {
        return this.message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
    public String getName() {
        return this.name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getSection() {
        return this.section;
    }

    public void setSection(String section) {
        this.section = section;
    }
}

作成したUserData.javaは，UTF-8形式で，c:¥temp¥jaxws¥works¥mtom¥server¥src¥com¥sample¥ディレクトリに保存します。

またcom.sample.UserInfoImplでスローしている例外クラスcom.sample.UserInfoExceptionを作成します。通常，例外クラスの作成は任意ですが，ここでは例外クラスを作成します。

例外クラスの作成例を次に示します。

package com.sample;

import java.lang.Exception;
import java.lang.String;

public class UserInfoException extends Exception {

    String detail;

    public UserInfoException(String message, String detail) {
        super(message);
        this.detail = detail;
    }

    public String getDetail() {
        return detail;
    }
}

作成したUserInfoException.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥mtom¥server¥src¥com¥sample¥ディレクトリに保存します。

31.3.2　Webサービス実装クラスをコンパイルする

javacコマンドを実行して，Webサービス実装クラスをコンパイルします。javacコマンドについては，JDKのドキュメントを参照してください。

javacコマンドの実行例を次に示します。添付ファイル機能を使用したJavaプログラムをjavacコマンドでコンパイルする場合，javacコマンドの引数に"--add-modules=java.activation"を指定してください。

> cd c:¥temp¥jaxws¥works¥mtom¥server¥
> mkdir WEB-INF¥classes¥
> javac -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥CC¥client¥lib¥HiEJBClientStatic.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxp.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmstax.jar" -d WEB-INF¥classes¥ -s src src¥com¥sample¥UserInfoImpl.java src¥com¥sample¥UserData.java src¥com¥sample¥UserInfoException.java

javacコマンドが正常に終了すると，コンパイルしたクラスが，c:¥temp¥jaxws¥works¥mtom¥server¥WEB-INF¥classes¥com¥sample¥ディレクトリに出力されます。なお，コンパイルしたWebサービス実装クラスに対してhwsgenコマンドを実行すると，事前にエラーチェックができます。hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を，エラーチェックについては，「10.23.1　hwsgenコマンドによるエラーチェックについて」を参照してください。

31.3.3　web.xmlを作成する

WARファイルの構成要素として必要なweb.xmlを作成します。

web.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;mtom_dynamic_generate&quot;</description>
  <display-name>Sample_web_service_mtom_dynamic_generate</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/UserInfoService</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

作成したweb.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥mtom¥server¥WEB-INF¥ディレクトリに保存します。web.xmlの設定項目については，「3.4　web.xmlの作成」を参照してください。

31.3.4　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。

application.xmlの作成例を次に示します。なお，Webサービスとしてapplication.xmlに設定する項目はありません。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;mtom_dynamic_generate&quot;</description>
  <display-name>Sample_application_mtom_dynamic_generate</display-name>
  <module>
    <web>
      <web-uri>mtom_dynamic_generate.war</web-uri>
      <context-root>mtom_dynamic_generate</context-root>
    </web>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥mtom¥server¥META-INF¥ディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

31.3.5　EARファイルを作成する

jarコマンドを使用して，これまでに作成したファイルを含めたEARファイルを作成します。

EARファイルの作成例を次に示します。

> cd c:¥temp¥jaxws¥works¥mtom¥server¥
> jar cvf mtom_dynamic_generate.war .¥WEB-INF
> jar cvf mtom_dynamic_generate.ear .¥mtom_dynamic_generate.war .¥META-INF¥application.xml

正常に終了すると，c:¥temp¥jaxws¥works¥mtom_dynamic_generate¥server¥ディレクトリにmtom.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

31.4　デプロイと開始の例（SEI起点・MTOM/XOP仕様形式の添付ファイル）

ここでは，添付ファイルを使用して，SEIを起点とした場合のデプロイと開始の例を説明します。

31.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxws¥works¥mtom¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxwsserver -nameserver corbaname::testserver:900 -f mtom_dynamic_generate.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

31.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxws¥works¥mtom¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxwsserver -nameserver corbaname::testserver:900 -name Sample_application_mtom_dynamic_generate

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

31.5　Webサービスクライアントの開発例（SEI起点・MTOM/XOP仕様形式の添付ファイル）

ここでは，添付ファイルを使用して，SEIを起点とした場合のWebサービスクライアントの開発例を説明します。

31.5.1　サービスクラスを生成する

cjwsimportコマンドを実行すると，サービスクラスなどWebサービスクライアントの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

cjwsimportコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥mtom¥client¥
> mkdir src¥
> mkdir classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes http://webhost:8085/mtom_dynamic_generate/UserInfoService?wsdl

正常に終了すると，c:¥temp¥jaxws¥works¥mtom¥client¥src¥com¥sample¥ディレクトリにJavaソースが生成されます。

生成物の一覧を次の表に示します。

表31‒4　サービスクラス生成時の生成物（SEI起点・添付ファイル）

ファイル名

説明

GetUserData.java

WSDL定義の要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

GetUserDataResponse.java

WSDL定義の応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

UserData.java

UserDataに対応するJavaBeanクラスです。

UserInfoImpl.java

WSDL定義の「サービス」に対応するSEIです。

UserInfoService.java

サービスクラスです。

UserInfoException.java

UserInfoExceptionに対応するJavaBeanクラスです。

UserInfoException_Exception.java

フォルトbeanのラッパ例外クラスです。

31.5.2　Webサービスクライアントの実装クラスを作成する

Webサービスを利用するWebサービスクライアントの実装クラスを作成します。

Webサービスに対して1回の呼び出しをするWebサービスクライアントの作成例を次に示します。

package com.sample.client;

import java.awt.Image;
import java.io.File;

import javax.imageio.ImageIO;
import javax.xml.ws.soap.MTOMFeature;

import com.sample.UserInfoImpl;
import com.sample.UserData;
import com.sample.UserInfoService;
import com.sample.UserInfoException_Exception;

public class TestClient {

    public static void main( String[] args ) {
        try {
            // Imageオブジェクト生成
            File imageFile = new File("portrait.png");
            if (!imageFile.exists()) {
                throw new RuntimeException("Cannot find the file ¥"portrait.png¥".");
            }
            Image image = ImageIO.read(imageFile);

            UserInfoService service = new UserInfoService();
            UserInfoImpl port = service.getUserInfoImplPort(new MTOMFeature());

            UserData userdata = port.getUserData("1", image);
            System.out.print("[RESULT] " + userdata.getMessage());
            System.out.println(" Name:" + userdata.getName()
                              + ", Section:" + userdata.getSection());
        } catch(UserInfoException_Exception e) {
            e.printStackTrace();
        } catch(Exception e) {
            e.printStackTrace();
        }
    }
}

作成したTestClient.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥mtom¥client¥src¥com¥sample¥client¥ディレクトリに保存します。

31.5.3　Webサービスクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービスクライアントをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥mtom¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥com¥sample¥client¥TestClient.java

正常に終了すると，c:¥temp¥jaxws¥works¥mtom¥client¥classes¥com¥sample¥client¥ディレクトリに，TestClient.classが生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

31.6　Webサービスの実行例（SEI起点・MTOM/XOP仕様形式の添付ファイル）

ここでは，添付ファイルを使用して，SEIを起点とした場合のWebサービスクライアントの実行例を説明します。

31.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxws¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。

作成したJavaアプリケーション用オプション定義ファイルは，c:¥temp¥jaxws¥works¥mtom¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

31.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxws¥works¥mtom¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

31.6.3　Webサービスクライアントを実行する

cjclstartapコマンドを使用して，Webサービスクライアントを実行します。

Webサービスクライアントの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥mtom¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  com.sample.client.TestClient

正常に終了すると，Webサービスクライアントの実行結果が表示されます。実行結果の表示例を次に示します。

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxws¥works¥mtom¥client, PID = 2636)
[RESULT] Success. Name:Sato Taro, Section:The personnel section
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

32　ストリーミング

この章では，Application Serverのストリーミングの概要，使用方法および使用時の設定について説明します。

32.1　ストリーミングとは

ストリーミングとは，添付ファイル機能で添付ファイルを含むMIME Multipart/Related構造のSOAPメッセージを受信する際に，SOAPメッセージに含まれる大きいサイズのMIMEボディをメモリ上に展開しないで処理することで，Javaヒープサイズの制約を受けることなく大容量の添付ファイルを含むSOAPメッセージを受信する機能です。ストリーミングは，受信した添付ファイルを含むSOAPメッセージをjavax.activation.DataHandlerクラスにマッピングするときに使用できます。

ストリーミングを使用したバイナリデータの送受信を次の図に示します。

図32‒1　ストリーミングを使用したバイナリデータの送受信

ストリーミングは，MTOM/XOP仕様形式の添付ファイルを使用する場合にだけ使用できます。wsi:swaRef形式の添付ファイルでは使用できません。

32.2　ストリーミングの使用方法

ストリーミングを使用するには，添付ファイルを含むMIME Multipart/Related構造のSOAPメッセージを受信する側に設定する必要があります。ここではWebサービス側およびWebサービスクライアント側の使用方法を説明します。

32.2.1　Webサービス側

Webサービスでストリーミングを使用するには，Webサービス実装クラスにcom.sun.xml.ws.developer.StreamingAttachmentアノテーションをアノテートします。com.sun.xml.ws.developer.StreamingAttachmentアノテーションについては，「16.2.2　com.sun.xml.ws.developer.StreamingAttachmentアノテーション」を参照してください。

ストリーミングを使用したWebサービス実装クラスの例を次に示します。この例では，"C:/TMP"ディレクトリをストリーミングによる一時ファイルの出力先に指定し，添付ファイルを含むSOAPメッセージの詳細な解析をして，50,000バイト以上のMIMEボディを一時ファイルとして出力します。

package com.sample;

・・・・・・

@MTOM
@StreamingAttachment(dir="C:/TMP", parseEagerly=true, memoryThreshold=50000L)
@BindingType(・・・)
public class UserInfoImpl implements UserInfo {

    public DataHandler getUserInfo(DataHandler dataHandler)
        throws UserDefinedException {
        if (dataHandler instanceof StreamingDataHandler) {
            StreamingDataHandler sdh = null;
            try {
                sdh = (StreamingDataHandler)dataHandler;
                ・・・・・・
            } finally {
                try {
                    if (sdh != null) {
                        sdh.close();
                    }
                } catch(Exception ex) {
                    ・・・・・・
                }
            }
        }
        ・・・・・・
    }
}

Webサービス側でストリーミングを使用し，次の条件をすべて満たすリクエストメッセージを受信した場合，レスポンスメッセージに含まれるデータがBase64形式のデータになります。

リクエストメッセージのHTTPヘッダにあるAcceptフィールドにapplication/xop+xmlがない。

リクエストメッセージのルートパートにあるContent-Typeにapplication/xop+xmlがない。

32.2.2　Webサービスクライアント側

Webサービスクライアントでストリーミングを使用するには，SEIを取得する際にcom.sun.xml.ws.developer.StreamingAttachmentFeatureクラスを設定します。

com.sun.xml.ws.developer.StreamingAttachmentFeatureクラスについては，「19.2.4(1)　com.sun.xml.ws.developer.StreamingAttachmentFeatureクラス」を参照してください。

ストリーミングを使用したWebサービスクライアントの例を次に示します。この例では，"C:/TMP"ディレクトリをストリーミングによる一時ファイルの出力先に指定し，添付ファイルを含むSOAPメッセージの詳細な解析をし，50,000バイト以上のMIMEボディを一時ファイルとして出力します。

package com.sample;

・・・・・・

public class TestClient {

    public static void main(String[] args) {
        try {
            File portrait = new File("portrait.png");
            FileDataSource fileDataSource = new FileDataSource(portrait);
            DataHandler dataHandler = new DataHandler(fileDataSource);

            MTOMFeature mtomFeature = new MTOMFeature();
            StreamingAttachmentFeature streamingAttachmentFeature = new StreamingAttachmentFeature("C:/TMP", true, 50000L);

            UserInfoService service = new UserInfoService();
            UserInfoImpl port = service.getUserInfoImplPort(mtomFeature, streamingAttachmentFeature);
            DataHandler userData = port.getUserInfo(dataHandler);
            if (userData instanceof StreamingDataHandler) {
                StreamingDataHandler sdh = null;
                try {
                    sdh = (StreamingDataHandler)userData;
                    sdh.moveTo(file);
                    ・・・・・・
                } finally {
                    try {
                        if (sdh != null) {
                            sdh.close();
                        }
                    } catch(Exception ex) {
                        ・・・・・・
                    }
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

32.2.3　parseEagerlyによる変化

ストリーミングは，com.sun.xml.ws.developer.StreamingAttachmentアノテーションの要素やcom.sun.xml.ws.developer.StreamingAttachmentFeatureクラスの引数にあるparseEagerlyに指定した値で，添付ファイルを含むSOAPメッセージを解析するタイミング，解析の結果，およびSOAPメッセージに異常があるときに発生する例外が変わります。

parseEagerlyの値と変化を次の表に示します。

表32‒1　parseEagerlyの値と変化

項番

parseEagerlyの値

SOAPメッセージを解析するタイミング

SOAPメッセージに異常があるときに発生する例外

1

true

添付ファイルを含むSOAPメッセージをアンマーシャルしたとき

org.jvnet.mimepull.MIMEParsingException

2

false

ストリーミングされた添付ファイルを操作したとき

java.io.IOException

parseEagerlyの値は，添付ファイルを含むSOAPメッセージの異常をユーザアプリケーションではなく，アンマーシャル時に検知する場合には，trueを指定します。

32.2.4　ストリーミングされた添付ファイルの操作

ストリーミングを使用しているときに添付ファイルを含むMIME Multipart/Related構造のSOAPメッセージを受信すると，JAX-WSでは受信した添付ファイルをjavax.activation.DataHandlerクラスではなく，com.sun.xml.ws.developer.StreamingDataHandlerクラスにマッピングし，ストリーミングされた添付ファイルとして操作できます。

com.sun.xml.ws.developer.StreamingDataHandlerクラスについては，「19.2.4(2)　com.sun.xml.ws.developer.StreamingDataHandlerクラス」を参照してください。

ストリーミングされた添付ファイルを操作する例を次に示します。この例では，ストリーミングされた添付ファイルを"C:/portrait.png"として別名で出力します。

package com.sample;

・・・・・・

@MTOM
@StreamingAttachment(dir="C:/TMP", parseEagerly=true, memoryThreshold=50000L)
@BindingType(・・・)
public class UserInfoImpl implements UserInfo {

    public DataHandler getUserInfo(DataHandler dataHandler)
        throws UserDefinedException {
        if (dataHandler instanceof StreamingDataHandler) {
            File file = new File("C:/portrait.png");
            StreamingDataHandler sdh = null;
            try {
                sdh = (StreamingDataHandler)dataHandler;
                sdh.moveTo(file);
                ・・・・・・
            } finally {
                try {
                    if (sdh != null) {
                        sdh.close();
                    }
                } catch(Exception ex) {
                    ・・・・・・
                }
            }
        }
    }
}

(1)　ストリーミングされた添付ファイルの操作時の注意事項

ストリーミングされた添付ファイルを操作する場合の注意事項を次に示します。

ストリーミングを使用する場合，instanceof演算子を用いてcom.sun.xml.ws.developer.StreamingDataHandlerクラスを判別する必要があります。

一時ファイルに出力した添付ファイルは使用有無に関係なく，必ずcom.sun.xml.ws.developer.StreamingDataHandler#close()メソッドでクローズする必要があります。クローズしない場合，JAX-WSは一時ファイルを消去しません。

com.sun.xml.ws.developer.StreamingDataHandler#readOnce()メソッドおよびcom.sun.xml.ws.developer.StreamingDataHandler#moveTo(File)メソッドを呼び出したあとは，com.sun.xml.ws.developer.StreamingDataHandler#close()メソッドだけ呼び出すことができます。com.sun.xml.ws.developer.StreamingDataHandler#close()メソッド以外のメソッドを呼び出した場合，動作は保証されません。

com.sun.xml.ws.developer.StreamingDataHandler#readOnce()メソッドを呼び出した場合，添付ファイルが必要なくなった時点で取得した入力ストリームからデータをすべて読み読み込んだあとに入力ストリームをクローズし，com.sun.xml.ws.developer.StreamingDataHandler#close()メソッドを呼び出す必要があります。

com.sun.xml.ws.developer.StreamingDataHandler#readOnce()メソッドを呼び出した場合の例を次に示します。

package com.sample;
...

@MTOM
@StreamingAttachment(...)
...
public class UserInfoImpl implements UserInfo {

    public @XmlMimeType("application/octet-stream")
           DataHandler getUserInfo(
               @XmlMimeType("application/octet-stream")
               DataHandler dataHandler)
        throws ... {
        if (dataHandler instanceof StreamingDataHandler) {
            StreamingDataHandler sdh = null;
            try {
                sdh = (StreamingDataHandler)dataHandler;
                ...
                InputStream inputStream = sdh.readOnce();
                ...
                // 入力ストリームから添付ファイルのデータをすべて
                // 読み込む
                while ((inputStream.read()) != -1);

                // 入力ストリームをクローズする
                inputStream.close();
            } finally {
                try {
                    if (sdh != null) {
                        // StreamingDataHandlerクラスのclose()
                        // メソッドを呼び出す
                        sdh.close();
                    }
                } catch(Exception ex) {
                    ...
                }
            }
        }
        ...
    }
}

com.sun.xml.ws.developer.StreamingDataHandler#moveTo(File)メソッドを呼び出した場合，添付ファイルが必要なくなった時点でcom.sun.xml.ws.developer.StreamingDataHandler#close()メソッドを呼び出す必要があります。

com.sun.xml.ws.developer.StreamingDataHandler#moveTo(File)メソッドを呼び出したときに例外が発生した場合，com.sun.xml.ws.developer.StreamingDataHandler#readOnce()メソッドを呼び出して入力ストリームを取得し，その入力ストリームからデータをすべて読み込んだあとに入力ストリームのクローズを行い，com.sun.xml.ws.developer.StreamingDataHandler#close()メソッドを呼び出す必要があります。

com.sun.xml.ws.developer.StreamingDataHandler#moveTo(File)メソッドを呼び出した場合の例を次に示します。

package com.sample;
...

@MTOM
@StreamingAttachment(...)
...
public class UserInfoImpl implements UserInfo {

    public @XmlMimeType("application/octet-stream")
           DataHandler getUserInfo(
               @XmlMimeType("application/octet-stream")
               DataHandler dataHandler)
        throws ... {
        if (dataHandler instanceof StreamingDataHandler) {
            StreamingDataHandler sdh = null;
            try {
                File file = new File(...);
                sdh = (StreamingDataHandler)dataHandler;
                ...
                sdh.moveTo(file);
            } catch(Exception e)
                try {
                    if (sdh != null) {
                        InputStream inputStream = sdh.readOnce();

                        // 入力ストリームから添付ファイルのデータをすべて
                        // 読み込む
                        while ((inputStream.read()) != -1);

                        // 入力ストリームをクローズする
                        inputStream.close();
                    }
                } catch(Exception ex) {
                    ...
                }
            } finally {
                try {
                    if (sdh != null) {
                        // StreamingDataHandlerクラスのclose()
                        // メソッドを呼び出す
                        sdh.close();
                    }
                } catch(Exception ex) {
                    ...
                }
            }
        }
        ...
    }
}

com.sun.xml.ws.developer.StreamingDataHandler#readOnce()メソッドを呼び出していない，かつcom.sun.xml.ws.developer.StreamingDataHandler#moveTo(File)メソッドを呼び出していない場合，添付ファイルが必要なくなった時点でcom.sun.xml.ws.developer.StreamingDataHandler#readOnce()メソッドを呼び出して入力ストリームを取得し，その入力ストリームからデータをすべて読み込んだあとに入力ストリームをクローズし，com.sun.xml.ws.developer.StreamingDataHandler#close()メソッドを呼び出す必要があります。

com.sun.xml.ws.developer.StreamingDataHandlerクラスはjavax.activation.DataHandlerクラスのメソッドのうち，getContentType()メソッドだけ呼び出すことができます。それ以外のメソッドを呼び出した場合，動作は保証されません。

WebサービスクライアントまたはWebサービス実装クラスで，受信したjavax.activation.DataHandlerクラスまたはjavax.xml.ws.Holder <DataHandler>クラスのストリーミングされた添付ファイルをそのまま使用して送信しないでください。送信する場合，新たにjavax.activation.DataHandlerオブジェクトを生成して送信してください。

32.3　一時ファイル（ストリーミング）

ストリーミングを使用しているときに添付ファイルを含むMIME Multipart/Related構造のSOAPメッセージを受信する場合，SOAPメッセージに含まれるMIMEボディをメモリ上ではなく，一時ファイルに出力する場合があります。SOAPメッセージに含まれるMIMEボディをメモリ上に展開するか，一時ファイルに出力するかは，parseEagerlyに指定した値，MIMEパートの種類，およびMIMEボディのサイズによって決まります。

SOAPメッセージに含まれるMIMEボディの出力先を次の表に示します。

表32‒2　SOAPメッセージに含まれるMIMEボディの出力先

項番

MIMEパートの種類

parseEagerlyに指定した値

しきい値※とMIMEボディサイズの関係

MIMEボディの出力先

1

ルートパート

−

しきい値※≦MIMEボディのサイズ

メモリ上に展開しないで，一時ファイルに出力します。

2

しきい値※＞MIMEボディのサイズ

一時ファイルに出力しないで，メモリ上に展開します。

3

添付ファイルパート

true

しきい値※≦MIMEボディのサイズ

メモリ上に展開しないで，一時ファイルに出力します。

4

しきい値※＞MIMEボディのサイズ

一時ファイルに出力しないで，メモリ上に展開します。

5

false

なし

一時ファイルにも出力しないで，メモリ上にも展開しません。

（凡例）

−：指定した値はMIMEボディの出力先に影響しません。

注※

しきい値とは，com.sun.xml.ws.developer.StreamingAttachmentアノテーションのmemoryThreshold要素値またはcom.sun.xml.ws.developer.StreamingAttachmentFeatureクラスのmemoryThreshold値です。

SOAPメッセージに含まれるMIMEボディを一時ファイルに出力するかどうかは，各MIMEパートにあるMIMEボディについて判定して決定します。受信する添付ファイルを含むMIME Multipart/Related構造のSOAPメッセージに，ルートパートが一つ，添付ファイルパートが二つ存在する場合，一時ファイルを出力するかどうかの判定は3回実行します。

32.3.1　命名規則

命名規則の詳細については，「10.24.1(1)　命名規則」を参照してください。

なお，一時ファイルの出力先を指定しない場合，異なるプロセスのcjclstartapコマンドでストリーミングを使用したWebサービスクライアントを実行する際に，一時ファイルのファイル名が重複することがあります。そのため，com.sun.xml.ws.developer.StreamingAttachmentFeatureクラスのdir引数に一時ファイルの出力先を指定してください。

また，次の場合，一時ファイルの出力先として同じディレクトリを指定すると，一時ファイルのファイル名が重複することがあります。

複数のJ2EEサーバにストリーミングを使用したWebサービスまたはWebサービスクライアントを配置する場合

異なるプロセスのcjclstartapコマンドでストリーミングを使用したWebサービスクライアントを実行する場合

上記を組み合わせる場合

そのため，複数のJ2EEサーバにストリーミングを使用したWebサービスまたはWebサービスクライアントを配置する場合にはJ2EEサーバごとに，異なるプロセスのcjclstartapコマンドでストリーミングを使用したWebサービスクライアントを実行する場合にはプロセスごとに一時ファイルの出力先を変える必要があります。

32.3.2　出力と削除

出力と削除の詳細については，「10.24.1(2)　出力と削除」を参照してください。

32.3.3　見積もり方法

見積もり方法の詳細については，「10.24.1(3)　見積もり方法」を参照してください。

33　SEIを起点とした開発の例（ストリーミング使用時）

この章では，ストリーミングを使用して，SEIを起点としたWebサービスを開発する場合の例を説明します。

33.1　開発例の構成（SEI起点・ストリーミング）

この章で説明する開発例では，SEIを起点としたWebサービスを開発します。開発するWebサービスは，ストリーミングを使用します。なお，ここではJAX-WS 2.2仕様3.3節で説明されている，暗黙のSEIの形式（明示的なSEIを作成しない形式）のWebサービスを開発します。

開発するWebサービスの概要および利用する情報について説明します。

開発例の概要

社員番号，顔写真，社員名，所属というユーザ情報を管理し，Webサービスクライアントからの入力に対して，処理結果を返すWebサービスを新規に開発します。

Webサービスクライアントからの要求情報およびサーバからの応答情報を次の表に示します。

表33‒1　Webサービスクライアントからの要求情報

情報名

Javaデータ型

社員番号

java.lang.String

顔写真

javax.activation.DataHandler

表33‒2　サーバからの応答情報

情報名

Javaデータ型

登録確認メッセージ

java.lang.String

社員名

java.lang.String

所属

java.lang.String

サーバからの応答情報は，ユーザ定義型クラスのUserDataクラスで保持されます。

この章で説明する開発例では，次の表に示す構成のWebサービスを開発します。

表33‒3　Webサービスの構成（SEI起点・ストリーミング）

項番

項目

値

1

デプロイするJ2EEサーバの名称

jaxwsserver

2

Webサーバのホスト名とポート番号

webhost:8085

3

ネーミングサーバのURL

corbaname::testserver:900

4

コンテキストルート

streaming_dynamic_generate

5

スタイル

document/literal/wrapped

6

名前空間URI

http://sample.com

7

ポートタイプ

個数

1

8

ローカル名

UserInfoImpl

9

オペレーション

個数

1

10

ローカル名

GetUserData

11

サービス

個数

1

12

ローカル名

UserInfoService

13

ポート

個数

1

14

ローカル名

UserInfoImplPort

15

Webサービス実装クラス

com.sample.UserInfoImpl

16

Webサービス実装クラスで公開するメソッド

個数

1

17

メソッド名

getUserData

18

Webサービス実装内のメソッドでスローする例外

個数

1

19

クラス名

com.sample.UserInfoException

Webサービス開発時のカレントディレクトリの構成を次の表に示します。

表33‒4　カレントディレクトリの構成（SEI起点・ストリーミング）

ディレクトリ

説明

c:¥temp¥jaxws¥works¥streaming

カレントディレクトリです。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

server¥

Webサービスの開発で使用します。

┣

┃

┃

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

┗

application.xml

「33.3.4　application.xmlを作成する」で作成します。

┣

┃

┃

┃

src¥

Webサービスのソースファイル（*.java）を格納します。「33.3.1　Webサービス実装クラスを作成する」および「33.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

┃

┃

┃

┃

WEB-INF¥

WARファイルのWEB-INFディレクトリに対応します。

┣

web.xml

「33.3.3　web.xmlを作成する」で作成します。

┗

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「33.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

streaming_dynamic_generate.ear

「33.3.5　EARファイルを作成する」で作成します。

┗

streaming_dynamic_generate.war

┗

client¥

Webサービスクライアントの開発で使用します。

┣

┃

┃

┃

src¥

Webサービスクライアントのソースファイル（*.java）を格納します。「33.5.1　サービスクラスを生成する」および「33.5.2　Webサービスクライアントの実装クラスを作成する」で使用します。

┣

┃

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「33.5.3　Webサービスクライアントの実装クラスをコンパイルする」で使用します。

┣

┃

portrait.png

Webサービスクライアントで使用するPNGファイルで使用します。

┣

┃

┃

usrconf.cfg

「33.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

┗

usrconf.properties

「33.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

カレントディレクトリのパスは，開発する環境に合わせて変更してください。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebサービスとWebサービスクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

33.2　開発例の流れ（SEI起点・ストリーミング）

この章で説明する開発例では，次の流れで開発および実行します。

Webサービスの開発

Webサービス実装クラスを作成する（33.3.1）

javacコマンドを実行し，Webサービス実装クラスをコンパイルする（33.3.2）

web.xmlを作成する（33.3.3）

application.xmlを作成する（33.3.4）

EARファイルを作成する（33.3.5）

デプロイと開始

EARファイルをデプロイする（33.4.1）

Webサービスを開始する（33.4.2）

Webサービスクライアントの開発

cjwsimportコマンドを実行し，サービスクラスを生成する（33.5.1）

Webサービスクライアントの実装クラスを作成する（33.5.2）

Webサービスクライアントの実装クラスをコンパイルする（33.5.3）

Webサービスの実行

Javaアプリケーション用オプション定義ファイルを作成する（33.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（33.6.2）

Webサービスクライアントを実行する（33.6.3）

33.3　Webサービスの開発例（SEI起点・ストリーミング）

ここでは，SEIを起点とした場合のWebサービス（ストリーミングを使用）の開発例を説明します。

33.3.1　Webサービス実装クラスを作成する

Webサービスの処理を記述したWebサービス実装クラスを作成します。ここでは，受け取った要求メッセージの内容を計算して，応答メッセージを返すWebサービス実装クラスを作成します。

Webサービス実装クラスの作成例を次に示します。

package com.sample;

import javax.activation.DataHandler;
import javax.jws.WebService;
import javax.xml.ws.soap.MTOM;
import javax.xml.bind.annotation.XmlMimeType;
import com.sun.xml.ws.developer.StreamingAttachment;
import com.sun.xml.ws.developer.StreamingDataHandler;

@MTOM
@StreamingAttachment(dir="C:/TMP", parseEagerly=true, memoryThreshold=50000L)
@WebService(serviceName="UserInfoService",targetNamespace="http://sample.com")
public class UserInfoImpl {

    public UserData getUserData(String in0, @XmlMimeType("application/octet-stream")DataHandler in1)
        throws UserInfoException {

        if (in1 != null) {
            if (in1 instanceof StreamingDataHandler) {
                StreamingDataHandler sdh = null;
                try {
                    //社員情報への顔写真の登録処理
                    sdh = (StreamingDataHandler)in1;
                    ・・・・
                } catch(Exception e) {
                    throw new UserInfoException("Exception occurred.", e.getMessage());
                } finally {
                    try {
                        if (sdh != null) {
                            //データのクローズ
                            sdh.close();
                        }
                    } catch(Exception ex) {
                        ・・・・
                    }
                }
            }
        }

        UserData userdata = new UserData();
        //登録した社員の名前と所属を設定
        if (in0.equals("1")) {
            userdata.setName("Sato Taro");
            userdata.setSection("The personnel section");
        } if ( ・・・・) {
            ・・・・・
        } ・・・・

        //登録確認メッセージを設定
        if (in1 == null) {
            userdata.setMessage("Failure(no image).");
        } else {
            userdata.setMessage("Success.");
        }
        return userdata;
    }
}

作成したUserInfoImpl.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥streaming¥server¥src¥com¥sample¥ディレクトリに保存します。

また，com.sample.UserInfoImplで使用しているユーザ定義型クラスcom.sample.UserDataを作成します。通常，ユーザ定義型クラスの作成は任意ですが，ここではユーザ定義型クラスを作成します。

ユーザ定義型クラスの作成例を次に示します。

package com.sample;

import java.lang.String;

public class UserData {

    private String message;
    private String name;
    private String section;

    public UserData() {
    }

    public String getMessage() {
        return this.message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
    public String getName() {
        return this.name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getSection() {
        return this.section;
    }

    public void setSection(String section) {
        this.section = section;
    }
}

作成したUserData.javaは，UTF-8形式で，c:¥temp¥jaxws¥works¥streaming¥server¥src¥com¥sample¥ディレクトリに保存します。

またcom.sample.UserInfoImplでスローしている例外クラスcom.sample.UserInfoExceptionを作成します。通常，例外クラスの作成は任意ですが，ここでは例外クラスを作成します。

例外クラスの作成例を次に示します。

package com.sample;

import java.lang.Exception;
import java.lang.String;

public class UserInfoException extends Exception {

    String detail;

    public UserInfoException(String message, String detail) {
        super(message);
        this.detail = detail;
    }

    public String getDetail() {
        return detail;
    }
}

作成したUserInfoException.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥streaming¥server¥src¥com¥sample¥ディレクトリに保存します。

33.3.2　Webサービス実装クラスをコンパイルする

javacコマンドを実行して，Webサービス実装クラスをコンパイルします。javacコマンドについては，JDKのドキュメントを参照してください。

javacコマンドの実行例を次に示します。添付ファイル機能を使用したJavaプログラムをjavacコマンドでコンパイルする場合，javacコマンドの引数に"--add-modules=java.activation"を指定してください。

> cd c:¥temp¥jaxws¥works¥streaming¥server¥
> mkdir WEB-INF¥classes¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥CC¥client¥lib¥HiEJBClientStatic.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxp.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmstax.jar" -d WEB-INF¥classes¥ -s src src¥com¥sample¥UserInfoImpl.java src¥com¥sample¥UserData.java src¥com¥sample¥UserInfoException.java

javacコマンドが正常に終了すると，コンパイルしたクラスが，c:¥temp¥jaxws¥works¥streaming¥server¥WEB-INF¥classes¥com¥sample¥ディレクトリに出力されます。なお，コンパイルしたWebサービス実装クラスに対してhwsgenコマンドを実行すると，事前にエラーチェックができます。hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を，エラーチェックについては，「10.23.1　hwsgenコマンドによるエラーチェックについて」を参照してください。

33.3.3　web.xmlを作成する

WARファイルの構成要素として必要なweb.xmlを作成します。

web.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;streaming_dynamic_generate&quot;</description>
  <display-name>Sample_web_service_streaming_dynamic_generate</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/UserInfoService</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

作成したweb.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥streaming¥server¥WEB-INF¥ディレクトリに保存します。web.xmlの設定項目については，「3.4　web.xmlの作成」を参照してください。

33.3.4　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。

application.xmlの作成例を次に示します。なお，Webサービスとしてapplication.xmlに設定する項目はありません。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;streaming_dynamic_generate&quot;</description>
  <display-name>Sample_application_streaming_dynamic_generate</display-name>
  <module>
    <web>
      <web-uri>streaming_dynamic_generate.war</web-uri>
      <context-root>streaming_dynamic_generate</context-root>
    </web>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥streaming¥server¥META-INF¥ディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

33.3.5　EARファイルを作成する

jarコマンドを使用して，これまでに作成したファイルを含めたEARファイルを作成します。

EARファイルの作成例を次に示します。

> cd c:¥temp¥jaxws¥works¥streaming¥server¥
> jar cvf streaming_dynamic_generate.war .¥WEB-INF
> jar cvf streaming_dynamic_generate.ear .¥streaming_dynamic_generate.war .¥META-INF¥application.xml

正常に終了すると，c:¥temp¥jaxws¥works¥streaming¥server¥ディレクトリにstreaming_dynamic_generate.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

33.4　デプロイと開始の例（SEI起点・ストリーミング）

ここでは，ストリーミングを使用して，SEIを起点とした場合のデプロイと開始の例を説明します。

33.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxws¥works¥streaming¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxwsserver -nameserver corbaname::testserver:900 -f streaming_dynamic_generate.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

33.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxws¥works¥streaming¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxwsserver -nameserver corbaname::testserver:900 -name Sample_application_streaming_dynamic_generate

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

33.5　Webサービスクライアントの開発例（SEI起点・ストリーミング）

ここでは，添付ファイルを使用して，SEIを起点とした場合のWebサービスクライアントの開発例を説明します。

33.5.1　サービスクラスを生成する

cjwsimportコマンドを実行すると，サービスクラスなどWebサービスクライアントの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

cjwsimportコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥streaming¥client¥
> mkdir src¥
> mkdir classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes http://webhost:8085/streaming_dynamic_generate/UserInfoService?wsdl

正常に終了すると，c:¥temp¥jaxws¥works¥streaming¥client¥src¥com¥sample¥ディレクトリにJavaソースが生成されます。

生成物の一覧を次に示します。

表33‒5　サービスクラス生成時の生成物（SEI起点・添付ファイル）

ファイル名

説明

GetUserData.java

WSDL定義の要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

GetUserDataResponse.java

WSDL定義の応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

UserData.java

UserDataに対応するJavaBeanクラスです。

UserInfoImpl.java

WSDL定義の「サービス」に対応するSEIです。

UserInfoService.java

サービスクラスです。

UserInfoException.java

UserInfoExceptionに対応するJavaBeanクラスです。

UserInfoException_Exception.java

フォルトbeanのラッパ例外クラスです。

33.5.2　Webサービスクライアントの実装クラスを作成する

Webサービスを利用するWebサービスクライアントの実装クラスを作成します。

Webサービスに対して1回の呼び出しをするWebサービスクライアントの作成例を次に示します。

package com.sample.client;

import javax.activation.DataHandler;
import javax.activation.FileDataSource;
import javax.xml.ws.soap.MTOMFeature;
import java.io.File;

import com.sample.UserInfoImpl;
import com.sample.UserData;
import com.sample.UserInfoService;
import com.sample.UserInfoException_Exception;

public class TestClient {

    public static void main( String[] args ) {
        try {
            //DataHandlerオブジェクト生成
            File imageFile = new File("portrait.png");
            if (!imageFile.exists()) {
                throw new RuntimeException("Cannot find the file ¥"portrait.png¥".");
            }
            FileDataSource fdSource = new FileDataSource(imageFile);
            DataHandler dhandler = new DataHandler(fdSource);

            UserInfoService service = new UserInfoService();
            UserInfoImpl port = service.getUserInfoImplPort(new MTOMFeature());

            UserData userdata = port.getUserData("1", dhandler);
            System.out.print("[RESULT] " + userdata.getMessage());
            System.out.println(" Name:" + userdata.getName()
                              + ", Section:" + userdata.getSection());
        } catch(UserInfoException_Exception e) {
            e.printStackTrace();
        } catch(Exception e) {
            e.printStackTrace();
        }
    }
}

作成したTestClient.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥streaming¥client¥src¥com¥sample¥client¥ディレクトリに保存します。

33.5.3　Webサービスクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービスクライアントをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥streaming¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥com¥sample¥client¥TestClient.java

正常に終了すると，c:¥temp¥jaxws¥works¥streaming¥client¥classes¥com¥sample¥client¥ディレクトリに，TestClient.classが生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

33.6　Webサービスの実行例（SEI起点・ストリーミング）

ここでは，ストリーミングを使用して，SEIを起点とした場合のWebサービスクライアントの実行例を説明します。

33.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxws¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。

作成したJavaアプリケーション用オプション定義ファイルは，c:¥temp¥jaxws¥works¥streaming¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

33.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxws¥works¥streaming¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

33.6.3　Webサービスクライアントを実行する

cjclstartapコマンドを使用して，Webサービスクライアントを実行します。

Webサービスクライアントの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥streaming¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  com.sample.client.TestClient

正常に終了すると，Webサービスクライアントの実行結果が表示されます。実行結果の表示例を次に示します。

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxws¥works¥streaming¥client, PID = 2968)
[RESULT] Success. Name:Sato Taro, Section:The personnel section
KDJE40054-I The cjclstartap command was stopped. (PID = 2968, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

34　WS-RM 1.2機能

この章では，WS-RM 1.2機能（WebサービスReliable Messaging機能）について説明します。

34.1　WS-RM 1.2機能とは

WS-RM 1.2機能とは，WebサービスとWebサービスクライアントのSOAPメッセージのやり取りに，RMD（Reliable Messaging Destination）およびRMS（Reliable Messaging Source）を介することで，SOAPメッセージを確実に送受信するための機能です。RMSとRMDの間では，バックグラウンドでメッセージを受信したことを通知するAckメッセージを送信して，メッセージが相手先に届いたかどうかを管理しています。必要に応じてWS-RM 1.2機能が自動的にメッセージの再送や重複したメッセージの排除をして，通信の信頼性を高めています。

WS-RM 1.2機能を使用した場合のSOAPメッセージの送受信の流れを次に示します。

図34‒1　WS-RM 1.2機能を使用した場合のSOAPメッセージの送受信の流れ

DispatchインタフェースおよびProviderインタフェースは利用できません。

34.2　WS-RM 1.2機能を使用したメッセージの流れ

WS-RM 1.2機能を使用した場合の，メッセージの流れを次に示します。

図34‒2　WS-RM 1.2機能を使用したメッセージの流れ

WS-RM Policyの交換

メッセージの送信元と送信先の間で，WS-RM 1.2機能の使用の有無やWS-RM 1.2機能のWS-RM Policyを交換します。WSDLファイルに，WS-RM Policy仕様を記述することでWS-RM Policyを交換します。

シーケンス生成

アプリケーションメッセージを送信する前に，RMSとRMDはシーケンスを生成して，共有します。シーケンスとは，WS-RM 1.2機能で送信される一連のアプリケーションメッセージの集合に関するコンテキストです。シーケンス生成処理は，ポートのオブジェクトに対する初回Webサービスメソッド呼び出し時に自動で実行されます。

アプリケーションメッセージ送信

シーケンスを生成したあと，RMSはRMDにアプリケーションメッセージを送信します。送信するアプリケーションメッセージには，シーケンスの識別子とメッセージ番号が付与されます。

シーケンスクローズ

アプリケーションメッセージの送信が終了すると，RMSはシーケンスをクローズできます。シーケンスをクローズすると，新たにアプリケーションメッセージを送受信することはできません。シーケンスをクローズしても，関連するリソースは破棄しないで，保持されます。シーケンスのクローズ処理は，Webサービスクライアント側でcloseメソッドが呼び出されたときに実行されます。

シーケンス終了

アプリケーションメッセージの送信が終了すると，RMSはシーケンスを終了させます。シーケンスが終了すると，関連するリソースは破棄されます。再度シーケンスを生成するには，ポートのオブジェクトを取得し直し，Webサービスメソッドを呼び出します。

以降では，シーケンス生成に関するメッセージ，シーケンスクローズに関するメッセージ，およびシーケンス終了に関するメッセージをまとめて，シーケンスライフサイクルメッセージと呼びます。

34.3　WS-RM 1.2機能の送達保証

送達保証とは，SOAPメッセージを確実に送受信するために，SOAPメッセージ時の再送，重複排除，および順序制御をする機能です。

送達保証の種類およびApplication ServerのWS-RM 1.2機能でのサポート範囲を次の表に示します。

表34‒1　送達保証の種類とApplication ServerのWS-RM 1.2機能でのサポート範囲

項番

種類

動作

RMSの処理

RMDの処理

サポート

1

AtLeastOnce

少なくとも1回送達

再送

−

×

2

AtMostOnce

重複なく送達

−

重複排除

×

3

ExactlyOnce

1回だけ送達

再送

重複排除

○

4

InOrder

順序どおりに送達

−

順序制御

×

（凡例）

○：使用できます。

×：使用できません。

−：該当しません。

34.3.1　再送

WS-RM 1.2機能を使用している場合，アプリケーションメッセージが接続先に届かないときに，WS-RM Policyのアプリケーションメッセージの再送回数で設定した値を上限として，RMSから自動的にアプリケーションメッセージが再送されます。指定した回数再送されてもアプリケーションメッセージが届かない場合，クライアントのアプリケーションにjavax.xml.ws.WebServiceExceptionが返されます。

再送の条件を次に示します。

JAX-WSの動作定義ファイルや要求コンテキストで設定したクライアントソケットの読み込みタイムアウト値または接続タイムアウト値を超えてもレスポンスがなく，タイムアウトした場合

サーバとの接続が不意に切断され，レスポンスが何も受信できなかった場合

アプリケーションメッセージまたは自動的に再送されたアプリケーションメッセージへのレスポンスとして，Body要素が空のAckメッセージを受信した場合

アプリケーションメッセージまたは自動的に再送されたアプリケーションメッセージへのレスポンスとして，HTTPステータスコードの202，300番台，400番台，500番台を受信した場合

34.3.2　重複排除

以前受信したメッセージと同じメッセージを受信した場合，メッセージ送信先にはメッセージを届けないでRMDで破棄されます。アプリケーションは呼び出されません。

重複メッセージを受信した場合，次のメッセージをクライアントに返します。

すでにレスポンスを返しているリクエストと重複したリクエストを受信した場合

一度返したレスポンスと同じ内容を返します。

リクエスト処理中に，同じリクエストを重複して受信した場合

クライアントにBody要素が空のAckメッセージを返します。ただし，返すAckがないときはHTTPステータスコード202を返します。

34.4　WS-RM Policyの追加方法

WS-RM 1.2機能では，WSDLファイルにWS-RM Policyを追加することで，WS-RM 1.2機能を有効にします。追加する項目は次のとおりです。

WS-RM Policyで使用する名前空間プレフィクスを定義する

wsdl:definitions要素の子要素としてポリシーを定義する

wsdl:binding要素の子要素でポリシーを参照する

追加例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="TestJaxWsService"

<!-- 中略 -->

<!-- 1.WS-RM Policyで使用する名前空間プレフィクスを定義する -->
  xmlns:wsp="http://www.w3.org/ns/ws-policy"
  xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
  xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl">

<!-- 2.wsdl:definitions要素の子要素としてポリシーを定義する -->
  <wsp:Policy wsu:Id="WSRM_policy">
    <wsp:ExactlyOne>
      <wsp:All>
        <wsrmp:RMAssertion>
          <wsp:Policy>
            <wsrmp:DeliveryAssurance>
              <wsp:Policy>
                <wsrmp:ExactlyOnce/>
              </wsp:Policy>
            </wsrmp:DeliveryAssurance>
          </wsp:Policy>
        </wsrmp:RMAssertion>
        <wsaw:UsingAddressing/>
        <!-- その他の設定 -->
      </wsp:All>
    </wsp:ExactlyOne>
  </wsp:Policy>

  <wsdl:types>

<!-- 中略 -->

<!-- 3.wsdl:binding要素の子要素でポリシーを参照する -->
  <wsdl:binding name="testJaxWsBinding" type="tns:TestJaxWs">
    <wsp:PolicyReference URI="#WSRM_policy"/>

<!-- 後略 -->

背景色付きの太字で示す個所が，名前空間プレフィクスの定義，WS-RM Policyの定義，またはWS-RM Policyの参照個所です。

wsrmp:DeliveryAssurance要素以下は省略できます。wsrmp:DeliveryAssurance要素以下および「<!-- その他の設定 -->」以外は，そのまま記載します。「<!-- その他の設定 -->」は必要に応じて設定を追加します。「<!-- その他の設定 -->」としてWSDLに追加するプロパティについては「23.4　WS-Policyによる設定」を参照してください。

35　WSDLを起点とした開発の例（WS-RM 1.2機能使用時）

この章では，WS-RM 1.2機能を使用する場合に，WSDLを起点としたWebサービスを開発するときの例を説明します。

35.1　開発例の構成（WSDL起点・WS-RM 1.2）

この章では，WSDLを起点としたWebサービスを開発します。

開発するWebサービスの構成を次の表に示します。

表35‒1　Webサービスの構成（WSDL起点）

項番

項目

値

1

デプロイするJ2EEサーバの名称

jaxwsserver

2

Webサーバのホスト名とポート番号

webhost:8085

3

ネーミングサーバのURL

corbaname::testserver:900

4

コンテキストルート

wsrm

5

スタイル

document/literal/wrapped

6

名前空間URI

http://example.com/sample

7

ポートタイプ

個数

1

8

ローカル名

TestJaxWs

9

オペレーション

個数

1

10

ローカル名

jaxWsTest1

11

サービス

個数

1

12

ローカル名

TestJaxWsService

13

ポート

個数

1

14

ローカル名

testJaxWs

15

WSDLのファイル名

input.wsdl

Webサービス開発時のカレントディレクトリの構成を次の表に示します。

表35‒2　カレントディレクトリの構成（WSDL起点）

ディレクトリ

説明

c:¥temp¥jaxws¥works¥wsrm

カレントディレクトリです。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

server¥

Webサービスの開発で使用します。

┣

┃

┃

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

┗

application.xml

「35.3.7　application.xmlを作成する」で作成します。

┣

┃

┃

┃

src¥

Webサービスのソースファイル（*.java）を格納します。「35.3.3　SEIを生成する」および「35.3.5　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

┃

┃

┃

┃

WEB-INF¥

WARファイルのWEB-INFディレクトリに対応します。

┣

web.xml

「35.3.6　web.xmlを作成する」で作成します。

┣

classes¥

コンパイルしたクラスファイル（*.class）を格納します。

┗

wsdl¥

作成したwsdlを格納します。

┣

┃

┃

┃

temporary¥

Javaで記述，変換したものを基にWSDLを作成する場合に一時ファイルを格納します。このディレクトリの作成は任意です。

┣

src¥

┗

classes¥

┣

wsrm.ear

「35.3.8　EARファイルを作成する」で作成します。

┗

wsrm.war

┗

client¥

Webサービスクライアントの開発で使用します。

┣

┃

┃

┃

src¥

Webサービスクライアントのソースファイル（*.java）を格納します。「35.5.1　サービスクラスを生成する」および「35.5.2　Webサービスクライアントの実装クラスを作成する」で使用します。

┣

┃

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「35.5.4　Webサービスクライアントの実装クラスをコンパイルする」で使用します。

┣

┃

┃

usrconf.cfg

「35.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

┗

usrconf.properties

「35.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

カレントディレクトリのパスは，開発する環境に合わせて変更してください。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebサービスとWebサービスクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

35.2　開発例の流れ（WSDL起点・WS-RM 1.2）

この章で説明する開発例では，次の流れで開発および実行します。

Webサービスの開発

WSDLファイルを作成する（35.3.1）

WSDLファイルにWS-RM Policyを追加する（35.3.2）

cjwsimportコマンドを実行し，SEIを生成する（35.3.3）

Webサービス実装クラスを作成する（35.3.4）

Webサービス実装クラスをコンパイルする（35.3.5）

web.xmlを作成する（35.3.6）

application.xmlを作成する（35.3.7）

EARファイルを作成する（35.3.8）

デプロイと開始

EARファイルをデプロイする（35.4.1）

Webサービスを開始する（35.4.2）

Webサービスクライアントの開発

cjwsimportコマンドを実行し，サービスクラスを生成する（35.5.1）

Webサービスクライアントの実装クラスを作成する（35.5.2）

Webサービスクライアントの実装クラスにシーケンス終了処理を追加する（35.5.3）

Webサービスクライアントの実装クラスをコンパイルする（35.5.4）

Webサービスの実行

Javaアプリケーション用オプション定義ファイルを作成する（35.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（35.6.2）

Webサービスクライアントを実行する（35.6.3）

35.3　Webサービスの開発例（WSDL起点・WS-RM 1.2）

ここでは，WSDLを起点とした場合のWebサービスの開発例を説明します。

35.3.1　WSDLファイルを作成する

WSDLファイルを作成し，Webサービスのメタ情報を定義します。WSDL定義は，次の仕様のサポート範囲内で定義してください。

WSDL 1.1仕様

サポート範囲については，「20.1　WSDL 1.1仕様のサポート範囲」を参照してください。

XML Schema仕様

サポート範囲については，マニュアル「XML Processor ユーザーズガイド」を参照してください。

WS-I Basic Profile 1.1仕様

WSDLファイルの作成方法には，新規に作成する方法と，Javaソースを変換したものを利用して作成する方法の2種類があります。

(1)　新規にWSDLファイルを作成する

ここでは，WSDLファイル（input.wsdl）を作成します。作成したWSDLファイルは，UTF-8形式でc:¥temp¥jaxws¥works¥wsrm¥server¥WEB-INF¥wsdl¥ディレクトリに保存してください。

SOAP 1.1の場合の作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="TestJaxWsService"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://example.com/sample"
  targetNamespace="http://example.com/sample">

  <wsdl:types>
    <xsd:schema targetNamespace="http://example.com/sample">
      <!-- 要求メッセージの wrapper要素 -->
      <xsd:element name="jaxWsTest1" type="tns:jaxWsTest1"/>

      <!-- 応答メッセージの wrapper要素 -->
      <xsd:element name="jaxWsTest1Response" type="tns:jaxWsTest1Response"/>

      <!-- フォルトメッセージの wrapper要素 -->
      <xsd:element name="UserDefinedFault" type="tns:UserDefinedFault"/>

      <!-- 要求メッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="jaxWsTest1">
        <xsd:sequence>
          <xsd:element name="information" type="xsd:string"/>
          <xsd:element name="count" type="xsd:int"/>
        </xsd:sequence>
      </xsd:complexType>

      <!-- 応答メッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="jaxWsTest1Response">
        <xsd:sequence>
          <xsd:element name="return" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>

      <!-- フォルトメッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="UserDefinedFault">
        <xsd:sequence>
          <xsd:element name="additionalInfo" type="xsd:int"/>
          <xsd:element name="detail" type="xsd:string"/>
          <xsd:element name="message" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:schema>
  </wsdl:types>

  <!-- 要求メッセージ -->
  <wsdl:message name="jaxWsTest1Request">
    <wsdl:part name="inputParameters" element="tns:jaxWsTest1"/>
  </wsdl:message>

  <!-- 応答メッセージ -->
  <wsdl:message name="jaxWsTest1Response">
    <wsdl:part name="outputParameters" element="tns:jaxWsTest1Response"/>
  </wsdl:message>

  <!-- フォルトメッセージ -->
  <wsdl:message name="UserDefinedException">
    <wsdl:part name="fault" element="tns:UserDefinedFault"/>
  </wsdl:message>

  <!-- ポートタイプ -->
  <wsdl:portType name="TestJaxWs">
    <!-- オペレーション -->
    <wsdl:operation name="jaxWsTest1">
      <wsdl:input message="tns:jaxWsTest1Request"/>
      <wsdl:output message="tns:jaxWsTest1Response"/>
      <wsdl:fault name="UserDefinedFault"
        message="tns:UserDefinedException"/>
    </wsdl:operation>
  </wsdl:portType>

  <!-- バインディング(SOAP 1.1/HTTPバインディング) -->
  <wsdl:binding name="testJaxWsBinding" type="tns:TestJaxWs">
    <!-- document/literal/wrapped -->
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <!-- オペレーション -->
    <wsdl:operation name="jaxWsTest1">
      <soap:operation/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
      <wsdl:fault name="UserDefinedFault">
        <soap:fault name="UserDefinedFault" use="literal"/>
      </wsdl:fault>
    </wsdl:operation>
  </wsdl:binding>

  <!-- サービス -->
  <wsdl:service name="TestJaxWsService">
    <!-- ポート -->
    <wsdl:port name="testJaxWs" binding="tns:testJaxWsBinding">
      <soap:address location="http://webhost:8085/wsrm/TestJaxWsService"/>
    </wsdl:port>
  </wsdl:service>

</wsdl:definitions>

SOAP 1.2の場合の作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="TestJaxWsService"
  xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://example.com/sample"
  targetNamespace="http://example.com/sample">

  <wsdl:types>
    <xsd:schema targetNamespace="http://example.com/sample">
      <!-- 要求メッセージの wrapper要素 -->
      <xsd:element name="jaxWsTest1" type="tns:jaxWsTest1"/>

      <!-- 応答メッセージの wrapper要素 -->
      <xsd:element name="jaxWsTest1Response" type="tns:jaxWsTest1Response"/>

      <!-- フォルトメッセージの wrapper要素 -->
      <xsd:element name="UserDefinedFault" type="tns:UserDefinedFault"/>

      <!-- 要求メッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="jaxWsTest1">
        <xsd:sequence>
          <xsd:element name="information" type="xsd:string"/>
          <xsd:element name="count" type="xsd:int"/>
        </xsd:sequence>
      </xsd:complexType>

      <!-- 応答メッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="jaxWsTest1Response">
        <xsd:sequence>
          <xsd:element name="return" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>

      <!-- フォルトメッセージの wrapper要素が参照する型 -->
      <xsd:complexType name="UserDefinedFault">
        <xsd:sequence>
          <xsd:element name="additionalInfo" type="xsd:int"/>
          <xsd:element name="detail" type="xsd:string"/>
          <xsd:element name="message" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:schema>
  </wsdl:types>

  <!-- 要求メッセージ -->
  <wsdl:message name="jaxWsTest1Request">
    <wsdl:part name="inputParameters" element="tns:jaxWsTest1"/>
  </wsdl:message>

  <!-- 応答メッセージ -->
  <wsdl:message name="jaxWsTest1Response">
    <wsdl:part name="outputParameters" element="tns:jaxWsTest1Response"/>
  </wsdl:message>

  <!-- フォルトメッセージ -->
  <wsdl:message name="UserDefinedException">
    <wsdl:part name="fault" element="tns:UserDefinedFault"/>
  </wsdl:message>

  <!-- ポートタイプ -->
  <wsdl:portType name="TestJaxWs">
    <!-- オペレーション -->
    <wsdl:operation name="jaxWsTest1">
      <wsdl:input message="tns:jaxWsTest1Request"/>
      <wsdl:output message="tns:jaxWsTest1Response"/>
      <wsdl:fault name="UserDefinedFault"
        message="tns:UserDefinedException"/>
    </wsdl:operation>
  </wsdl:portType>

<!-- バインディング(SOAP 1.2/HTTPバインディング) -->
<wsdl:binding name="testJaxWsBinding" type="tns:TestJaxWs">
  <!-- document/literal/wrapped -->
  <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <!-- オペレーション -->
    <wsdl:operation name="jaxWsTest1">
      <soap12:operation/>
      <wsdl:input>
        <soap12:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap12:body use="literal"/>
      </wsdl:output>
      <wsdl:fault name="UserDefinedFault">
        <soap12:fault name="UserDefinedFault" use="literal"/>
      </wsdl:fault>
    </wsdl:operation>
  </wsdl:binding>

  <!-- サービス -->
  <wsdl:service name="TestJaxWsService">
    <!-- ポート -->
    <wsdl:port name="testJaxWs" binding="tns:testJaxWsBinding">
      <soap12:address location="http://webhost:8085/wsrm/TestJaxWsService"/>
    </wsdl:port>
  </wsdl:service>

</wsdl:definitions>

(2)　Javaソースを変換したものを基にWSDLファイルを作成する

ここでは，WSDL変換用に仮実装のWebサービス実装クラスと例外クラスを作成し，hwsgenコマンドのWSDL生成機能を実行して，コンパイル済みのJavaソースからWSDLファイルを作成します。作成したクラスは，javax.jws.WebServiceアノテーションでアノテートします。SOAP 1.2を使用する場合，さらにSOAP 1.2を指定したjavax.xml.ws.BindingTypeアノテーションでアノテートしてください。メソッドを実装する必要はありません。

SOAP 1.1を使用する場合とSOAP 1.2を使用する場合では，仮実装のWebサービス実装クラスとTestJaxWsService.wsdlでソースコードが異なります。

SOAP 1.1の場合の仮実装のWebサービス実装クラスの例を次に示します。

package com.example.sample;

@javax.jws.WebService
public class TestJaxWsImpl {

    public String jaxWsTest1(String information, int count)
        throws UserDefinedException
    {
        // 実装不要
        return null;
    }

}

SOAP 1.2の場合の仮実装のWebサービス実装クラスの例を次に示します。

package com.example.sample;

@javax.jws.WebService
@javax.xml.ws.BindingType(javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING)
public class TestJaxWsImpl {

    public String jaxWsTest1(String information, int count)
        throws UserDefinedException
    {
        // 実装不要
        return null;
    }

}

仮実装の例外クラスの例を次に示します。

package com.example.sample;

public class UserDefinedFault extends Exception{
    // 実装不要
    public int additionalInfo;
    public String detail;
    public String message;
}

作成したTestJaxWsImpl.javaとUserDefinedFault.javaをUTF-8形式でc:¥temp¥jaxws¥works¥wsrm¥server¥temporary¥src¥com¥example¥sample¥ディレクトリに保存し，コンパイルします。コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsrm¥server¥
> mkdir .¥temporary
> mkdir .¥temporary¥classes
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar" -d .¥temporary¥classes .¥temporary¥src¥com¥example¥sample¥TestJaxWsImpl.java .¥temporary¥src¥com¥example¥sample¥UserDefinedFault.java

コンパイルが正常に終了すると，c:¥temp¥jaxws¥works¥wsrm¥server¥temporary¥classes¥com¥example¥sample¥ディレクトリにTestJaxWsImpl.classとUserDefinedFault.classが生成されます。これらのクラスファイルを利用して，hwsgenコマンドのWSDL生成機能でWSDLファイルを作成します。

hwsgenコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsrm¥server¥
> mkdir .¥WEB-INF¥wsdl¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥hwsgen.bat" -r .¥WEB-INF¥wsdl -d .¥temporary¥classes -cp .¥temporary¥classes com.example.sample.TestJaxWsImpl

hwsgenコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥wsrm¥WEB-INF¥wsdl¥ディレクトリにTestJaxWsService.wsdlとTestJaxWsService_schema1.xsdが生成されます。c:¥temp¥jaxws¥works¥wsrm¥temporary¥classes¥ディレクトリにあるクラスは削除してください。

生成されたTestJaxWsService.wsdlとTestJaxWsService_schema1.xsdは，一部修正する必要があります。

SOAP 1.1の場合のTestJaxWsService.wsdlの修正例を次に示します。イタリック体になっている個所が，修正した個所です。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<definitions targetNamespace="http://example.com/sample" name="TestJaxWsImplService" xmlns:tns="http://example.com/sample" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/">
  <types>
    <xsd:schema targetNamespace="http://example.com/sample">
      <xsd:include schemaLocation="TestJaxWsImplService_schema1.xsd"/>
    </xsd:schema>
  </types>
  <message name="jaxWsTest1">
    <part name="parameters" element="tns:jaxWsTest1"/>
  </message>
  <message name="jaxWsTest1Response">
    <part name="parameters" element="tns:jaxWsTest1Response"/>
  </message>
  <message name="UserDefinedFault">
    <part name="fault" element="tns:UserDefinedFault"/>
  </message>
  <portType name="TestJaxWs">
    <operation name="jaxWsTest1">
      <input message="tns:jaxWsTest1"/>
      <output message="tns:jaxWsTest1Response"/>
      <fault message="tns:UserDefinedFault" name="UserDefinedFault"/>
    </operation>
  </portType>
  <binding name="testJaxWsBinding" type="tns:TestJaxWs">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
    <operation name="jaxWsTest1">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
      <fault name="UserDefinedFault">
        <soap:fault name="UserDefinedFault" use="literal"/>
      </fault>
    </operation>
  </binding>
  <service name="TestJaxWsService">
    <port name="testJaxWs" binding="tns:testJaxWsBinding">
      <soap:address location="http://webhost:8085/wsrm/TestJaxWsService"/>
    </port>
  </service>
</definitions>

SOAP 1.2の場合のTestJaxWsService.wsdlの修正例を次に示します。イタリック体になっている個所が，修正した個所です。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<definitions targetNamespace="http://example.com/sample" name="TestJaxWsImplService" xmlns:tns="http://example.com/sample" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns="http://schemas.xmlsoap.org/wsdl/">
  <types>
    <xsd:schema targetNamespace="http://example.com/sample">
      <xsd:include schemaLocation="TestJaxWsImplService_schema1.xsd"/>
    </xsd:schema>
  </types>
  <message name="jaxWsTest1">
    <part name="parameters" element="tns:jaxWsTest1"/>
  </message>
  <message name="jaxWsTest1Response">
    <part name="parameters" element="tns:jaxWsTest1Response"/>
  </message>
  <message name="UserDefinedFault">
    <part name="fault" element="tns:UserDefinedFault"/>
  </message>
  <portType name="TestJaxWs">
    <operation name="jaxWsTest1">
      <input message="tns:jaxWsTest1"/>
      <output message="tns:jaxWsTest1Response"/>
      <fault message="tns:UserDefinedFault" name="UserDefinedFault"/>
    </operation>
  </portType>
  <binding name="testJaxWsBinding" type="tns:TestJaxWs">
    <soap12:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
    <operation name="jaxWsTest1">
      <soap12:operation soapAction=""/>
      <input>
        <soap12:body use="literal"/>
      </input>
      <output>
        <soap12:body use="literal"/>
      </output>
      <fault name="UserDefinedFault">
        <soap12:fault name="UserDefinedFault" use="literal"/>
      </fault>
    </operation>
  </binding>
  <service name="TestJaxWsService">
    <port name="testJaxWs" binding="tns:testJaxWsBinding">
      <soap12:address location="http://webhost:8085/wsrm/TestJaxWsService"/>
    </port>
  </service>
</definitions>

TestJaxWsService_schema1.xsdの修正例を次に示します。イタリック体になっている個所が，修正した個所です。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" targetNamespace="http://example.com/sample" xmlns:tns="http://example.com/sample" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="UserDefinedFault" type="tns:UserDefinedFault"/>

  <xs:element name="jaxWsTest1" type="tns:jaxWsTest1"/>

  <xs:element name="jaxWsTest1Response" type="tns:jaxWsTest1Response"/>

  <xs:complexType name="jaxWsTest1">
    <xs:sequence>
      <xs:element name="arg0" type="xs:string" minOccurs="0"/>
      <xs:element name="arg1" type="xs:int"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="jaxWsTest1Response">
    <xs:sequence>
      <xs:element name="return" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="UserDefinedFault">
    <xs:sequence>
      <xs:element name="message" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

修正したTestJaxWsService.wsdlは，名前をinput.wsdlに変更して，c:¥temp¥jaxws¥works¥wsrm¥server¥WEB-INF¥wsdl¥ディレクトリに保存してください。

35.3.2　WSDLファイルにWS-RM Policyを追加する

新規に作成したWSDLファイルに，WS-RM Policyを追加します。追加する項目は次のとおりです。

WS-RM Policyで使用する名前空間プレフィクスを定義する

wsdl:definitions要素の子要素としてポリシーを定義する

wsdl:binding要素の子要素でポリシーを参照する

追加例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="TestJaxWsService"

<!-- 中略 -->

<!-- 1.WS-RM Policyで使用する名前空間プレフィクスを定義する -->
  xmlns:wsp="http://www.w3.org/ns/ws-policy"
  xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
  xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl">

<!-- 2.wsdl:definitions要素の子要素としてポリシーを定義する -->
  <wsp:Policy wsu:Id="WSRM_policy">
    <wsp:ExactlyOne>
      <wsp:All>
        <wsrmp:RMAssertion>
          <wsp:Policy>
        </wsrmp:RMAssertion>
        <wsaw:UsingAddressing/>
      </wsp:All>
    </wsp:ExactlyOne>
  </wsp:Policy>

  <wsdl:types>

<!-- 中略 -->

<!-- 3.wsdl:binding要素の子要素でポリシーを参照する -->
  <wsdl:binding name="testJaxWsBinding" type="tns:TestJaxWs">
    <wsp:PolicyReference URI="#WSRM_policy"/>
    <!-- document/literal/wrapped -->

<!-- 後略 -->

35.3.3　SEIを生成する

cjwsimportコマンドを実行すると，SEIなど，Webサービスの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

cjwsimportコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsrm¥server¥
> mkdir src¥
> mkdir WEB-INF¥classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -generateService -s src -d WEB-INF¥classes WEB-INF¥wsdl¥input.wsdl

cjwsimportコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥wsrm¥server¥src¥com¥example¥sample¥ディレクトリに，Javaソースが生成されます。com¥example¥sample¥（パッケージに対応するディレクトリパス）は，名前空間URIの記述によって変わります。名前空間URIとパッケージとのマッピングについては，「15.1.1　名前空間からパッケージ名へのマッピング」を参照してください。

生成物の一覧を次の表に示します。

表35‒3　SEI生成時の生成物（WSDL起点）

ファイル名

説明

JaxWsTest1.java

WSDL定義の「要求メッセージのwrapper要素が参照する型」に対応するJavaBeanクラスです。

JaxWsTest1Response.java

WSDL定義の「応答メッセージのwrapper要素が参照する型」に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

TestJaxWs.java

TestJaxWsポートタイプに対応するSEIです。

TestJaxWsImpl.java

TestJaxWsポートタイプに対応するスケルトンクラスです。

UserDefinedFault.java

WSDL定義の「フォルトメッセージのwrapper要素が参照する型」に対応するJavaBeanクラス（フォルトbean）です。

UserDefinedException.java

フォルトbeanのラッパ例外クラスです。

ファイル名のJaxWsTest1，TestJaxWs，およびTestJaxWsImplは，オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名の記述によって変わります。オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名とJavaソースとのマッピングについては，「15.　WSDLからJavaへのマッピング」を参照してください。

35.3.4　Webサービス実装クラスを作成する

スケルトンクラスにWebサービスの処理を追加し，Webサービス実装クラスを作成します。ここでは，受け取った要求メッセージの内容を，日付情報とともに応答メッセージとして返す処理を追加します。

Webサービス実装クラスの作成例を次に示します。

package com.example.sample;

import java.util.Calendar;
import javax.jws.WebService;

@WebService(endpointInterface = "com.example.sample.TestJaxWs", targetNamespace = "http://example.com/sample", serviceName = "TestJaxWsService", portName = "testJaxWs")
public class TestJaxWsImpl {

    public String jaxWsTest1(String information, int count)
        throws UserDefinedException
    {
        Calendar today = Calendar.getInstance();
        StringBuffer result = new StringBuffer( 256 );
        result.append( "We've got your #" );
        result.append( new Integer( count ) );
        result.append( " message ¥"" );
        result.append( information );
        result.append( "¥"! It's " );
        result.append( String.format( "%04d.%02d.%02d %02d:%02d:%02d", new Object[]{
            new Integer( today.get( Calendar.YEAR ) ),
            new Integer( today.get( Calendar.MONTH ) + 1 ),
            new Integer( today.get( Calendar.DAY_OF_MONTH ) ),
            new Integer( today.get( Calendar.HOUR_OF_DAY ) ),
            new Integer( today.get( Calendar.MINUTE ) ),
            new Integer( today.get( Calendar.SECOND ) ) } ) );
        result.append( " now. See ya!" );

        return result.toString();
    }

}

イタリック体になっている個所が，スケルトンに対して追加した実装です。

35.3.5　Webサービス実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービス実装クラスをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsrm¥server¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;.¥WEB-INF¥classes" -d .¥WEB-INF¥classes src¥com¥example¥sample¥TestJaxWsImpl.java

javacコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥wsrm¥server¥WEB-INF¥classes¥com¥example¥sample¥ディレクトリのTestJaxWsImpl.classが上書きされます。

javacコマンドについては，JDKのドキュメントを参照してください。

35.3.6　web.xmlを作成する

WARファイルの構成要素として必要なweb.xmlを作成します。

web.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;wsrm&quot;</description>
  <display-name>Sample_web_service_wsrm</display-name>
  <listener>
    <listener-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/TestJaxWsService</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

作成したweb.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥wsrm¥server¥WEB-INF¥ディレクトリに保存します。web.xmlの設定項目については，「3.4　web.xmlの作成」を参照してください。

35.3.7　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。

application.xmlの作成例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;wsrm&quot;</description>
  <display-name>Sample_application_wsrm</display-name>
  <module>
    <web>
      <web-uri>wsrm.war</web-uri>
      <context-root>wsrm</context-root>
    </web>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥wsrm¥server¥META-INF¥ディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

35.3.8　EARファイルを作成する

jarコマンドを使用して，EARファイルを作成します。

EARファイルの作成例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsrm¥server¥
> jar cvf wsrm.war .¥WEB-INF
> jar cvf wsrm.ear .¥wsrm.war .¥META-INF¥application.xml

jarコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥wsrm¥server¥ディレクトリにwsrm.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

35.4　デプロイと開始の例（WSDL起点・WS-RM 1.2）

ここでは，WSDLを起点とした場合のデプロイと開始の例を説明します。

35.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsrm¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxwsserver -nameserver corbaname::testserver:900 -f wsrm.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

35.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsrm¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxwsserver -nameserver corbaname::testserver:900 -name Sample_application_wsrm

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

35.5　Webサービスクライアントの開発例（WSDL起点・WS-RM 1.2）

ここでは，WSDLを起点とした場合のWebサービスクライアントの開発例を説明します。

35.5.1　サービスクラスを生成する

cjwsimportコマンドを実行すると，サービスクラスなどWebサービスクライアントの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

Webサービスの開発と同じ環境で，Webサービスクライアントを開発する場合の実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsrm¥client¥
> mkdir src¥
> mkdir classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes ..¥server¥WEB-INF¥wsdl¥input.wsdl

Webサービスの開発と異なる環境で，Webサービスクライアントを開発する場合の実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsrm¥client¥
> mkdir src¥
> mkdir classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes http://webhost:8085/wsrm/TestJaxWsService?wsdl

正常に終了すると，c:¥temp¥jaxws¥works¥wsrm¥client¥src¥com¥example¥sample¥ディレクトリにJavaソースが生成されます。com¥example¥sample¥（パッケージに対応するディレクトリパス）は，名前空間URIの記述によって変わります。名前空間URIとパッケージとのマッピングについては，「15.1.1　名前空間からパッケージ名へのマッピング」を参照してください。

生成物の一覧を次の表に示します。

表35‒4　サービスクラス生成時の生成物（WSDL起点）

ファイル名

説明

JaxWsTest1.java

WSDL定義の「要求メッセージのwrapper要素が参照する型」に対応するJavaBeanクラスです。

JaxWsTest1Response.java

WSDL定義の「応答メッセージのwrapper要素が参照する型」に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

TestJaxWs.java

TestJaxWsポートタイプに対応するSEIです。

TestJaxWsService.java

サービスクラスです。

UserDefinedFault.java

WSDL定義の「フォルトメッセージのwrapper要素が参照する型」に対応するJavaBeanクラスです。

UserDefinedException.java

フォルトbeanのラッパ例外クラスです。

ファイル名のJaxWsTest1，TestJaxWs，およびTestJaxWsServiceは，オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名の記述によって変わります。オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名とJavaソースとのマッピングについては，次の個所を参照してください。

「15.1.2　ポートタイプからSEI名へのマッピング」

「15.1.3　オペレーションからメソッド名へのマッピング」

「15.1.4　メッセージのパートからパラメタおよび戻り値へのマッピング（wrapperスタイルの場合）」

「15.1.5　メッセージのパートからパラメタおよび戻り値へのマッピング（non-wrapperスタイルの場合）」

35.5.2　Webサービスクライアントの実装クラスを作成する

Webサービスを利用するWebサービスクライアントの実装クラスを作成します。

Webサービスに対して1回の呼び出しをするWebサービスクライアントの実装クラスの作成例を次に示します。

package com.example.sample.client;

import com.example.sample.TestJaxWs;
import com.example.sample.TestJaxWsService;
import com.example.sample.UserDefinedException;

public class TestClient {
    public static void main( String[] args ) {
        try {
            TestJaxWsService service = new TestJaxWsService();
            TestJaxWs port = service.getTestJaxWs();

            String returnValue = port.jaxWsTest1( "Invocation test.", 1003 );

            System.out.println( "[RESULT] " + returnValue );
        }
        catch( UserDefinedException e ){
            e.printStackTrace();
        }
    }

}

作成したTestClient.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥wsrm¥client¥src¥com¥example¥sample¥client¥ディレクトリに保存します。com.example.sample，TestJaxWs，TestJaxWsService，TestJaxWs，およびjaxWsTest1は，生成されたJavaソースのパッケージ名，クラス名，およびクラス内のメソッド名によって変わります。異なる構成のWebサービスを開発する場合には，パッケージ名，クラス名，およびクラス内のメソッド名の記述を見直す必要があります。

35.5.3　Webサービスクライアントの実装クラスにシーケンス終了処理を追加する

Webサービスクライアントの実装クラスに，シーケンス終了処理を追加します。シーケンス終了処理の追加例を次に示します。

package com.example.sample.client;

import com.example.sample.TestJaxWs;
import com.example.sample.TestJaxWsService;
import com.example.sample.UserDefinedException;
import com.sun.xml.ws.Closeable;

public class TestClient {
    public static void main( String[] args ) {
        TestJaxWsService service = null;
        TestJaxWs port = null;
        try {
            service = new TestJaxWsService();
            port = service.getTestJaxWs();

            String returnValue = port.jaxWsTest1( "Invocation test.", 1003 );

            System.out.println( "[RESULT] " + returnValue );
        }
        catch( UserDefinedException e ){
            e.printStackTrace();
        }
        finally {
            if( port != null ) {
                ((Closeable)port).close();
            }
        }
    }

}

35.5.4　Webサービスクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービスクライアントの実装クラスをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsrm¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥com¥example¥sample¥client¥TestClient.java

javacコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥wsrm¥client¥classes¥com¥example¥sample¥client¥ディレクトリに，TestClient.classが生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

35.6　Webサービスの実行例（WSDL起点・WS-RM 1.2）

ここでは，WSDLを起点とした場合のWebサービスクライアントの実行例を説明します。

35.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxws¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>
add.jvm.arg=-Dejbserver.server.prf.PRFID=<PRF ID>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。

作成したJavaアプリケーション用オプション定義ファイルは，UTF-8形式でc:¥temp¥jaxws¥works¥wsrm¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

35.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxws¥works¥wsrm¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

35.6.3　Webサービスクライアントを実行する

cjclstartapコマンドを使用して，Webサービスクライアントを実行します。

Webサービスクライアントの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥wsrm¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  com.example.sample.client.TestClient

cjclstartapコマンドが正常に終了すると，Webサービスクライアントの実行結果が表示されます。実行結果の表示例を次に示します。

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxws¥works¥wsrm¥client, PID = 2636)
--------------------
[RESULT] We've got your #1003 message "Invocation test."! It's 2007.11.28 14:50:50 now. See ya!
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

36　ハンドラフレームワーク

Application ServerのJAX-WS機能では，JAX-WS 2.2仕様で規定されたハンドラフレームワークを使用して，Webサービスの機能を拡張できます。

この章では，ハンドラフレームワークの概要，処理の流れ，および使用時の設定について説明します。

36.1　ハンドラフレームワークとは

ハンドラフレームワークとは，SOAPメッセージを送受信するときに，JAX-WSエンジン内で処理をインターセプトして，処理を追加する機能（フレームワーク）です。WebサービスクライアントとWebサービス実装クラスまたはプロバイダ実装クラスの間に複数のハンドラを追加し，Webサービスの機能を拡張できます。

ハンドラフレームワークの処理の流れを次の図に示します。

図36‒1　ハンドラフレームワークの処理の流れ

ハンドラの処理内容は，アウトバウンド／インバウンド，および要求／応答の組み合わせごとに異なります。組み合わせと処理内容を次の表に示します。

表36‒1　アウトバウンド／インバウンドおよび要求／応答の組み合わせと処理内容

アウトバウンド

／インバウンド

要求／

応答

処理内容

アウトバウンド

要求

Webサービスクライアントが要求メッセージを送信する動作を表します。

この処理で「メッセージを振り分ける」とは，要求メッセージをWebサービスに送信することを意味します。

応答

Webサービス実装クラスまたはプロバイダ実装クラスが応答メッセージを送信する動作を表します。

この処理で「メッセージを振り分ける」とは，応答メッセージをWebサービスクライアントに送信することを意味します。ただし，one-wayオペレーションでは応答メッセージを送信しないため，アウトバウンドは動作しません。

インバウンド

要求

Webサービス実装クラスまたはプロバイダ実装クラスが要求メッセージを受信する動作を表します。

この処理で「メッセージを振り分ける」とは，要求メッセージをWebサービス実装クラスまたはプロバイダ実装クラスに割り当てることを意味します。

応答

Webサービスクライアントが応答メッセージを受信する動作を表します。

この処理で「メッセージを振り分ける」とは，応答メッセージをWebサービスクライアントに割り当てることを意味します。ただし，one-wayオペレーションでは応答メッセージを受信しないため，インバウンドは動作しません。

ハンドラでは，メッセージコンテキストを取得できます。メッセージコンテキストについては，「19.2.5　メッセージコンテキストの使用」を参照してください。

ハンドラフレームワークのアーキテクチャについては，JAX-WS 2.2仕様を参照してください。

36.2　Webサービスセキュリティ機能を使用する場合の注意事項

WebサービスクライアントにWeb Services - Security（Webサービスセキュリティ機能）を適用する場合， Webサービスセキュリティハンドラとこの章で説明するハンドラフレームワークとを，併用できません。

Web Services - SecurityおよびWebサービスセキュリティハンドラについては，マニュアル「アプリケーションサーバ Webサービスセキュリティ構築ガイド」を参照してください。

36.3　EJBのWebサービスに適用する場合の注意事項

EJBのWebサービスにハンドラフレームワークを適用する場合，EJBのWebサービスに適用されたハンドラフレームワークがWebコンテナで動作するため，EJBコンテナが提供する機能を同時に適用できません。EJBコンテナが提供する機能については，「10.19　EJBのWebサービス呼び出し」を参照してください。

36.4　ハンドラの型

JAX-WS 2.2仕様は，論理ハンドラとプロトコルハンドラの二つを定義しています。また，プロトコルハンドラは，SOAPハンドラを定義しています。それぞれのハンドラの説明を次に示します。

論理ハンドラ

javax.xml.ws.handler.LogicalHandlerインタフェースを実装するハンドラです。

プロトコルハンドラ

javax.xml.ws.handler.LogicalHandlerインタフェースを除く，javax.xml.ws.handler.Handlerのすべての継承インタフェースを実装するハンドラです。

SOAPハンドラ

javax.xml.ws.handler.soap.SOAPHandlerインタフェースを実装するハンドラです。

ハンドラの関係（クラス階層）を次の図に示します。

図36‒2　ハンドラのクラス階層

Application ServerのJAX-WS機能では，論理ハンドラとSOAPハンドラを使用できます。

論理ハンドラでもSOAPハンドラでもないハンドラをハンドラチェインに設定した場合，Webサービス側のJAX-WSエンジンでは，Webサービス初期化時にログおよび標準エラー出力にエラーメッセージが出力されます（KDJW00009-E）。Webサービスクライアント側のJAX-WSエンジンでは，ポートを取得しようとしたときに，javax.xml.ws.WebServiceExceptionがスローされます。

javax.xml.ws.handler.LogicalHandlerインタフェースおよびjavax.xml.ws.handler.soap.SOAPHandlerインタフェースの両方を実装するハンドラ（論理ハンドラでもSOAPハンドラでもあるハンドラ）は論理ハンドラと見なされます。

36.5　ハンドラチェインの編成と実行順序

ハンドラチェインは，論理ハンドラがSOAPハンドラに先行するように編成されます。論理ハンドラ同士，およびSOAPハンドラ同士の順序は，ハンドラチェインの設定に含まれる順序に従います。

ハンドラチェインの編成の例を次に示します。

図36‒3　ハンドラチェインの編成の例

JAX-WSエンジンでは，この図に示すように，次の順序でハンドラが実行されます。

アウトバウンドのメッセージの場合：

L1→L2→L3→S1→S2→S3→S4→S5→S6

インバウンドのメッセージの場合：

S6→S5→S4→S3→S2→S1→L3→L2→L1

アウトバウンドのメッセージに対しては，最初のハンドラからハンドラチェインの順序に，インバウンドのメッセージに対しては，最後のハンドラからハンドラチェインの順序とは逆順に実行されます。

ただし，ハンドラによって例外がスローされた場合，またはhandleMessageメソッドまたはhandleFaultメソッドによってfalseが返された場合は，ハンドラ処理の方向が変わります。

ここでは，handleMessageメソッド，handleFaultメソッド，およびcloseメソッドごとに処理についてそれぞれ説明します。

36.5.1　handleMessageメソッドの処理

handleMessageメソッドについて，trueを返す場合，falseを返す場合，および例外をスローする場合の処理について説明します。

(1)　trueを返す場合

handleMessageメソッドがtrueを返す場合，JAX-WSエンジンは現在実行中の方向のままハンドラを処理します。それ以上ハンドラがなければ，メッセージを振り分けます。

要求処理の流れを次の図に示します。

図36‒4　handleMessageでtrueを返す場合の処理（要求）

応答処理の流れを次の図に示します。

図36‒5　handleMessageでtrueを返す場合の処理（応答）

(2)　falseを返す場合

要求メッセージを処理しているhandleMessageメソッドがfalseを返す場合，JAX-WSエンジンはメッセージとハンドラ処理の方向を逆転させて，前のハンドラのhandleMessageメソッドを呼び出します。それ以上ハンドラがなければ，メッセージを振り分けます。

要求処理でハンドラ2がfalseを返す場合の流れを次の図に示します。

図36‒6　handleMessageでfalseを返す場合の処理（要求）

JAX-WSエンジンは，メッセージコンテキストに設定されたメッセージを変更しません。したがって，要求メッセージはそのままWebサービスクライアントに振り分けられます。意図した応答メッセージが振り分けられなかったWebサービスクライアントでは，javax.xml.ws.WebServiceExceptionがスローされます。

応答メッセージを処理しているhandleMessageメソッドがfalseを返す場合，メッセージの方向は変えません。ただし，以降のハンドラをすべて省略して，メッセージを振り分けます。

応答処理でハンドラ2がfalseを返す場合の流れを次の図に示します。

図36‒7　handleMessageでfalseを返す場合の処理（応答）

(3)　ProtocolExceptionまたはそのサブクラスをスローする場合

要求メッセージを処理しているhandleMessageメソッドがProtocolExceptionまたはそのサブクラスをスローする場合，JAX-WSエンジンはメッセージとハンドラ処理の方向を逆転させて，前のハンドラのhandleFaultメソッドを呼び出します。それ以上ハンドラがなければ，メッセージを振り分けます。

要求処理でハンドラ2がProtocolExceptionをスローする場合の流れを次の図に示します。

図36‒8　handleMessageでProtocolExceptionをスローする場合の処理（要求）

JAX-WSエンジンは，フォルトメッセージを生成して伝搬させます。生成するメッセージは，SOAPのバージョンによって次の表のとおりに異なります。

表36‒2　JAX-WSエンジンが生成するフォルトメッセージ（ProtocolExceptionスロー・要求）

バージョン

フォルトメッセージ

SOAP 1.1仕様

Webサービスクライアント側

faultcodeはQName soapenv:Client

Webサービス側

faultcodeはQName soapenv:Server

SOAP 1.2仕様

Webサービスクライアント側

soapenv12:CodeはQName soapenv12:Sender

Webサービス側

soapenv12:CodeはQName soapenv12:Receiver

応答メッセージを処理しているhandleMessageメソッドがProtocolExceptionまたはそのサブクラスをスローする場合，メッセージの方向は変えません。ただし，以降のハンドラをすべて省略して，例外をそのままスローします。

応答処理でハンドラ2がProtocolExceptionをスローする場合の流れを次の図に示します。

図36‒9　handleMessageでProtocolExceptionをスローする場合の処理（応答）

Webサービス側の場合，JAX-WSエンジンは例外をSOAPフォルトに変換して送信します。フォルトメッセージの変換については，「10.4.1(2)　ランタイム例外のバインディング」を参照してください。

(4)　ほかのランタイム例外をスローする場合

要求メッセージを処理しているhandleMessageメソッドがほかのランタイム例外をスローする場合，JAX-WSエンジンはメッセージとハンドラ処理の方向を逆転させます。また，以降のハンドラをすべて省略し，例外をそのままスローします。

要求処理でハンドラ2がRuntimeExceptionをスローする場合の流れを次の図に示します。

図36‒10　handleMessageでRuntimeExceptionをスローする場合の処理（要求）

Webサービス側の場合，JAX-WSエンジンは例外をSOAPフォルトに変換して送信します。フォルトメッセージの変換については，「10.4.1(2)　ランタイム例外のバインディング」を参照してください。

Webサービスクライアント側の場合，JAX-WSエンジンは例外をjavax.xml.ws.WebServiceExceptionでラップして，WebServiceExceptionをスローします。

応答メッセージを処理しているhandleMessageメソッドがランタイム例外をスローする場合，メッセージの方向は変えません。ただし，以降のハンドラをすべて省略して，メッセージを振り分けます。

応答処理でハンドラ2がRuntimeExceptionをスローする場合の流れを次の図に示します。

図36‒11　handleMessageでRuntimeExceptionをスローする場合の処理（応答）

Webサービス側の場合，JAX-WSエンジンは例外をSOAPフォルトに変換して送信します。フォルトメッセージの変換については，「10.4.1(2)　ランタイム例外のバインディング」を参照してください。

Webサービスクライアント側の場合，JAX-WSエンジンは例外をjavax.xml.ws.WebServiceExceptionでラップして，WebServiceExceptionをスローします。

36.5.2　handleFaultメソッドの処理

handleMessageメソッドについて，trueを返す場合，falseを返す場合，および例外をスローする場合の処理について説明します。

(1)　trueを返す場合

handleFaultメソッドがtrueを返す場合，JAX-WSエンジンは現在実行中の方向のままハンドラを処理します。それ以上ハンドラがなければ，メッセージを振り分けます。

応答処理の流れを次の図に示します。

図36‒12　handleFaultでtrueを返す場合の処理（応答）

(2)　falseを返す場合

handleFaultメソッドがfalseを返す場合，JAX-WSエンジンは現在実行中の方向のまま，以降のハンドラをすべて省略してメッセージを振り分けます。

応答処理でハンドラ2がfalseを返す場合の流れを次の図に示します。

図36‒13　handleFaultでfalseを返す場合の処理（応答）

(3)　ProtocolExceptionまたはそのサブクラスをスローする場合

handleFaultメソッドがProtocolExceptionまたはそのサブクラスをスローする場合，JAX-WSエンジンは，現在実行中の方向のまま，以降のハンドラをすべて省略して例外をスローします。

応答処理でハンドラ2がProtocolExceptionをスローする場合の流れを次の図に示します。

図36‒14　handleFaultでProtocolExceptionを返す場合の処理（応答）

Webサービス側の場合，JAX-WSエンジンは例外をSOAPフォルトに変換し，もともと保持しているSOAPフォルトを置き換えます。したがって，実際は新たに生成されたフォルトメッセージを送信します。フォルトメッセージの変換については，「10.4.1(2)　ランタイム例外のバインディング」を参照してください。

(4)　ほかのランタイム例外をスローする場合

handleFaultメソッドがほかのランタイム例外をスローする場合，JAX-WSエンジンは，現在実行中の方向のまま，以降のハンドラをすべて省略してメッセージを振り分けます。

応答処理でハンドラ2がRuntimeExceptionをスローする場合の流れを次の図に示します。

図36‒15　handleFaultでRuntimeExceptionを返す場合の処理（応答）

Webサービス側の場合，JAX-WSエンジンは例外をSOAPフォルトに変換し，もともと保持しているSOAPフォルトを置き換えます。したがって，実際には新たに生成されたフォルトメッセージを送信します。フォルトメッセージの変換については，「10.4.1(2)　ランタイム例外のバインディング」を参照してください。

Webサービスクライアント側の場合，JAX-WSエンジンは例外をjavax.xml.ws.WebServiceExceptionでラップして，WebServiceExceptionをスローします。

36.5.3　closeメソッドの処理

JAX-WSエンジンは，応答メッセージをWebサービスクライアントに振り分ける直前に，すでに呼び出したハンドラのcloseメソッドを呼び出します。

closeメソッドは，呼び出しと逆順に呼び出されます。したがって，要求メッセージを処理しているときにハンドラの処理を逆転させた場合，呼び出さなかったハンドラのcloseメソッドは呼び出しません。しかし，要求メッセージを処理するときにすべてのハンドラを実行していれば，応答メッセージの処理でハンドラの呼び出しを省略したとしても，すべてのハンドラのcloseメソッドを，要求メッセージを処理したときと逆順に呼び出します。

また，one-wayオペレーションの場合は，Webサービス側とWebクライアント側で次のように呼び出す順序が異なります。

Webサービス側

Webサービス実装クラスまたはプロバイダ実装クラスの呼び出し後に，すでに呼び出したハンドラのcloseメソッドを，one-wayメッセージを処理したときと逆順に呼び出します。

Webクライアント側

HTTPレスポンス受信後に，すでに呼び出したハンドラのcloseメソッドを，one-wayメッセージを処理したときと逆順に呼び出します。

36.6　ハンドラの初期化と破棄

ハンドラを初期化するとき，およびハンドラを破棄するときのJAX-WSエンジンの動作について説明します。

Webサービス側

ハンドラがjavax.annotation.PostConstructアノテーションでアノテートされたメソッドを持つ場合，Webサービスを初期化するときに，そのメソッドが呼び出されます。

ハンドラがjavax.annotation.PreDestoryアノテーションでアノテートされたメソッドを持つ場合，Webサービスを破棄するときに，そのメソッドが呼び出されます。

Webサービスクライアント側

ハンドラがjavax.annotation.PostConstructアノテーションやjavax.annotation.PreDestoryアノテーションでアノテートされたメソッドを持っていても，それらのメソッドは呼び出されません。

36.7　SOAPヘッダが含まれる場合のハンドラの動作と設定

ハンドラ，Webサービス実装クラス，およびスタブベースのWebサービスクライアントでは，SOAPメッセージに処理できるSOAPヘッダを設定できます。プロバイダ実装クラスおよびディスパッチベースのWebサービスクライアントにSOAPヘッダを設定しても，処理できないので注意してください。

ここでは，Webサービス側およびWebサービスクライアント側に分けて，SOAPヘッダを含むSOAPメッセージを受信した場合のハンドラの動作について説明します。また，SOAPヘッダの設定方法について説明します。

36.7.1　SOAPヘッダが含まれる場合のハンドラの動作（Webサービス側）

SOAPヘッダが含まれるSOAPメッセージを受信した場合，SOAPヘッダのsoap:mustUnderstand属性の設定値によって，ハンドラの処理が異なります。soap:mustUnderstand属性が"1"の場合，およびsoap:mustUnderstand属性が"1"以外の場合に分けて処理内容を示します。

(1)　soap:mustUnderstand属性が"1"の場合

soap:mustUnderstand属性が"1"のSOAPヘッダを持つSOAPメッセージを受信した場合，設定されたハンドラのどれか，またはWebサービス実装クラス内で，そのSOAPヘッダを処理できれば，すべてのハンドラが呼び出されます。

ハンドラでSOAPヘッダを処理できる場合のハンドラの処理を次の図に示します。

図36‒16　ハンドラでSOAPヘッダを処理できる場合の処理（Webサービス側）

この図の例では，要素名tns:headerAを処理できるハンドラ3が設定されているとしています。このとき，tns:headerAのSOAPヘッダを受信した場合，ハンドラ3，ハンドラ2，およびハンドラ1のすべてのハンドラが呼び出されます。

Webサービス実装クラスでSOAPヘッダを処理できる場合のハンドラの処理を次の図に示します。

図36‒17　Webサービス実装クラスでSOAPヘッダを処理できる場合の処理（Webサービス側）

Webサービス実装クラスだけが要素名tns:headerSを処理できるとした場合も，ハンドラで処理できる場合と同様にすべてのハンドラが呼び出されます。

soap:mustUnderstand属性が"1"のSOAPヘッダを持つSOAPメッセージを受信した場合，次のようなときはfaultcodeにsoap:MustUnderstandが設定されたSOAPフォルトが返されます。

設定されたハンドラのどれかがSOAPヘッダを処理できない

Webサービス実装クラス内でSOAPヘッダを処理できない

プロバイダ実装クラスが使用されている

SOAPヘッダを処理できない場合のハンドラの処理は，次の図のようになります。

図36‒18　SOAPヘッダを処理できない場合のハンドラの処理（Webサービス側）

(2)　soap:mustUnderstand属性が"1"以外の場合

soap:mustUnderstand属性が"1"以外の場合，設定されているすべてのハンドラが呼び出されます。

soap:mustUnderstand属性が"1"以外の場合，ハンドラの処理は次の図のようになります。

図36‒19　soap:mustUnderstand属性が"1"以外の場合のハンドラの処理（Webサービス側）

この図の例では，ハンドラもWebサービス実装クラスも要素tns:headerZを処理できませんが，soap:mustUnderstand属性が"1"以外の場合はSOAPフォルトにはならないで，すべてのハンドラが呼び出されます。

36.7.2　SOAPヘッダが含まれる場合のハンドラの動作（Webサービスクライアント側）

SOAPヘッダが含まれるSOAPメッセージを受信した場合，SOAPヘッダのsoap:mustUnderstand属性の設定値によって，ハンドラの処理が異なります。soap:mustUnderstand属性が"1"の場合，およびsoap:mustUnderstand属性が"1"以外の場合に分けて処理内容を示します。

(1)　soap:mustUnderstand属性が"1"の場合

soap:mustUnderstand属性が"1"のSOAPヘッダを持つSOAPメッセージを受信した場合，設定されたハンドラのどれか，またはWebサービスクライアント内で，そのSOAPヘッダを処理できれば，すべてのハンドラが呼び出されます。

ハンドラでSOAPヘッダを処理できる場合のハンドラの処理を次の図に示します。

図36‒20　ハンドラでSOAPヘッダを処理できる場合の処理（Webサービスクライアント側）

この図の例では，要素名tns:headerAを処理できるハンドラ3が設定されているとしています。このとき，tns:headerAのSOAPヘッダを受信した場合，ハンドラ3，ハンドラ2，およびハンドラ1のすべてのハンドラが呼び出されます。

Webサービス実装クラスでSOAPヘッダを処理できる場合のハンドラの処理を次の図に示します。

図36‒21　Webサービス実装クラスでSOAPヘッダを処理できる場合の処理（Webサービスクライアント側）

Webサービス実装クラスだけが要素名tns:headerCLを処理できるとした場合も，ハンドラで処理できる場合と同様にすべてのハンドラが呼び出されます。

soap:mustUnderstand属性が"1"のSOAPヘッダを持つSOAPメッセージを受信し，次のような場合はjavax.xml.ws.soap.SOAPFaultExceptionが返され，エラーとなります（KDJW10022-E）。

設定されたハンドラのどれかがSOAPヘッダを処理できない

Webサービスクライアント内でSOAPヘッダを処理できない

Webサービスクライアントがディスパッチベースで開発されている

SOAPヘッダを処理できない場合のハンドラの処理は，次の図のようになります。

図36‒22　SOAPヘッダを処理できない場合のハンドラの処理（Webサービスクライアント側）

(2)　soap:mustUnderstand属性が"1"以外の場合

soap:mustUnderstand属性が"1"以外の場合，設定されているすべてのハンドラが呼び出されます。

soap:mustUnderstand属性が"1"以外の場合，ハンドラの処理は次の図のようになります。

図36‒23　soap:mustUnderstand属性が"1"以外の場合のハンドラの処理（Webサービスクライアント側）

この図の例では，ハンドラもWebサービス実装クラスも要素tns:headerCLを処理できませんが，soap:mustUnderstand属性が"1"以外の場合はエラーにはならないで，すべてのハンドラが呼び出されます。

36.7.3　処理できるSOAPヘッダの設定方法

ハンドラ，Webサービス実装クラス，およびWebサービスクライアントに分けて，処理できるSOAPヘッダの設定方法を説明します。

(1)　SOAPヘッダをハンドラで設定する場合

javax.xml.ws.handler.soap.SOAPHandlerインタフェースを実装したハンドラクラスを作成し，getHeaders()メソッドで，処理できるSOAPヘッダのQNameを含むjava.util.Setを返します。ハンドラでの設定例を次に示します。

public class MySOAPHandler implements SOAPHandler<SOAPMessageContext> {
  private final static Set<QName> headers;

  static {
    headers = new HashSet<QName>();
    headers.add(new QName("http://test.org/handler/", "headerA"));
  }

  public Set<QName> getHeaders(){
    return headers;
  }
  （以下，そのほかの実装は省略）
}

(2)　SOAPヘッダをWebサービス実装クラスで設定する場合

SEIを起点として開発する場合，Webサービス実装クラスにjavax.jws.WebParamアノテーションでアノテートした引数を持つメソッドを定義します。javax.jws.WebParamアノテーションでは，次に示す設定を定義します。

header属性にtrueを設定する。

mode属性にjavax.jws.WebParam.Mode.INまたはjavax.jws.WebParam.Mode.INOUTを設定する。

Webサービス実装クラスでの設定例を次に示します。

@WebService
@SOAPBinding (parameterStyle= javax.jws.soap.SOAPBinding.ParameterStyle.BARE)
@HandlerChain (file="handlerchainfile.xml")
public class MyWebService{
  @WebMethod(operationName = "webMethod")
  public String webMethod(
    @WebParam(targetNamespace="http://test.org/handler/", name="message")
    String message,
    @WebParam(targetNamespace="http://test.org/handler/", name="headerS", header = true, WebParam.Mode.IN)
    String headerS
  ){
    （以下，メソッドの実装は省略）
  }
}

WSDLを起点に開発する場合は，WSDL 1.1仕様およびApplication ServerのJAX-WS機能のサポート範囲内で，soap:header要素をWSDLに記述します。Application ServerのJAX-WS機能でのsopa:header要素の記述については，「20.1.22　soap:header要素」を参照してください。

(3)　SOAPヘッダをWebサービスクライアントで設定する場合

接続するWebサービスのメタデータであるWSDLに，soap:header要素が含まれる場合は，そのsoap:header要素を処理できます。WSDLの例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:tns="http://test.org/handler/"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
             targetNamespace="http://test.org/handler/"
             name="HandlerTest01Service">

  <types>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
               version="1.0"
               targetNamespace="http://test.org/handler/">
      <xs:element name="headerCL" nillable="true" type="xs:string"></xs:element>
      <xs:element name="message" nillable="true" type="xs:string"></xs:element>
      <xs:element name="testResponse" nillable="true" type="xs:string"></xs:element>
    </xs:schema>
  </types>

  <message name="test">
    <part name="message" element="tns:message"></part>
    <part name="headerCL" element="tns:headerCL"></part>
  </message>
  <message name="testResponse">
    <part name="testResponse" element="tns:testResponse"></part>
    <part name="headerCL" element="tns:headerCL"></part>
  </message>

  <portType name="HandlerTest01">
    <operation name="test" parameterOrder="message headerCL">
      <input message="tns:test"></input>
      <output message="tns:testResponse"></output>
    </operation>
  </portType>
  <binding name="HandlerTest01Binding" type="tns:HandlerTest01">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"></soap:binding>
    <operation name="test">
      <soap:operation soapAction=""></soap:operation>
      <input>
        <soap:body use="literal" parts="message"></soap:body>
        <soap:header message="tns:test" part="headerCL" use="literal"></soap:header>
      </input>
      <output>
        <soap:body use="literal" parts="testResponse"></soap:body>
        <soap:header message="tns:testResponse" part="headerCL" use="literal"></soap:header>
      </output>
    </operation>
  </binding>

  <service name="HandlerTest01Service">
    <port name="HandlerTest01Port" binding="tns:HandlerTest01Binding">
      <soap:address location="http://localhost:80/SOAPHeaderTest/HandlerTestService431"></soap:address>
    </port>
  </service>
</definitions>

この場合は，要素名{http://test.org/handler/}headerCLのSOAPヘッダを処理できます。WSDLのsoap:header要素については「20.1.22　soap:header要素」を参照してください。

36.8　ハンドラの配置

ハンドラの実装クラスの配置について説明します。

Webサービス側

ハンドラの実装クラスは，次に示す場所に配置します。

POJOのWebサービスの場合：WARファイルのクラスパス上

EJBのWebサービスの場合：EJB JARファイルのクラスパス上

WARファイルまたはEJB JARファイルのクラスパス上であれば，WARファイルやEJB JARファイルに含まれていなくてもかまいません。

Webサービスクライアント側

ハンドラの実装クラスは，Webサービスクライアントのクラスパス上に配置してください。

36.9　ハンドラチェインの設定

Webサービス実装クラスおよびWebサービスクライアントでは，動的なハンドラチェインの設定が利用できます。

ここでは，ハンドラチェインの設定方法と設定例について説明します。

36.9.1　Webサービス側のハンドラチェインの設定

Webサービス側でハンドラチェインを設定する場合，javax.jws.HandlerChainアノテーションでSEI，Webサービス実装クラス，またはプロバイダ実装クラスをアノテートし，javax.jws.HandlerChainアノテーションのfile要素でハンドラチェイン設定ファイルを指定します。

javax.jws.HandlerChainアノテーションでWebサービス実装クラスをアノテートした例を示します。

package com.sample;

@javax.jws.WebService
@javax.jws.HandlerChain(file="handlers.xml")
public class AddNumbersImpl{

    public int add( int number1, int number2 ) throws AddNumbersFault{
      ...
    }

}

この例では，Webサービス実装クラスcom.sample.AddNumbersImplにハンドラチェイン設定ファイルhandlers.xmlで定義されたハンドラチェインを関連づけています。

ハンドラチェイン設定ファイルは，Webサービスごとに必要になります。複数のWebサービスで共有してもかまいませんが，その場合は，同じ設定が適用されます。

javax.jws.HandlerChainアノテーションについては，「16.2.3　javax.jws.HandlerChainアノテーション」を参照してください。

(1)　ハンドラチェイン設定ファイル

ハンドラチェイン設定ファイルは，ハンドラを使用してWebサービスに処理を追加した場合に，ハンドラチェインの構成を定義するファイルです。javax.jws.HandlerChainアノテーションのfile要素で指定します。

ハンドラチェイン設定ファイルのサポート範囲については，「19.4　ハンドラチェイン設定ファイルのサポート範囲」を参照してください。ここでは，ハンドラチェイン設定ファイルの構文および配置について説明します。

(a)　ハンドラチェイン設定ファイルの構文

ハンドラチェイン設定ファイルの構文は，Java EE 5仕様の標準スキーマ（Java EE Web Services Metadata Handler Chain Schema），およびApplication ServerのJAX-WS機能でサポートされる範囲で記述します。

標準のスキーマは，Java EE 5の名前空間URI（http://java.sun.com/xml/ns/javaee/）にアクセスすることで参照できます。ハンドラチェイン設定ファイルの記述例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
  <handler-chain>
    <handler>
      <handler-class>org.test.handler.LoggingHandler</handler-class>
    </handler>
  </handler-chain>
</handler-chains>

(b)　ハンドラチェイン設定ファイルの配置

ハンドラチェイン設定ファイルは，次に示す場所に格納します。

POJOのWebサービスの場合：WARファイルのWEB-INFディレクトリ以下

EJBのWebサービスの場合：EJB JAR

OSのファイルシステムの制限とJava EE 5仕様に従っていて，WARファイルまたはEJB JARファイルに格納できれば，ファイル名，WEB-INFディレクトリ以下のディレクトリ名，EJB JARのディレクトリ名，およびパスの長さに制限はありません。

(2)　SOAPロールとアクタの設定

SOAPロールおよびアクタの設定を省略した場合，または空文字を指定した場合は，デフォルトの値が設定されます。デフォルトの値は，SOAP 1.1仕様のSOAPメッセージの場合は"http://schemas.xmlsoap.org/soap/actor/next"，SOAP 1.2仕様のSOAPメッセージの場合は"http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver"です。

(3)　soap:mustUnderstand属性の設定

soap:mustUnderstand属性には，"0"，"1"，"true"，または"false"を設定してください。それ以外の値を設定した場合は，"0"または"false"が設定されているものと見なされます。

36.9.2　Webサービスクライアント側のハンドラチェインの設定

Webサービスクライアント側でハンドラチェインを設定する場合，JAX-WS APIを使用します。使用できるJAX-WS APIについては，「19.2　APIのサポート範囲」を参照してください。

(1)　ハンドラチェインを設定するコードの追加

Webサービスクライアント側のハンドラチェインの設定には，次の二つの方法があります。

サービスクラスへ設定する方法

ポートへ設定する方法

それぞれの設定方法について説明します。

(a)　サービスクラスへのハンドラチェインの設定

APIを使用して，サービスクラスにハンドラチェインを設定するコードを追加したWebサービスクライアントの例を示します。

package com.example.sample.client;

import com.example.sample.TestJaxWs;
import com.example.sample.TestJaxWsService;
import com.example.sample.UserDefinedException;

public class TestClient {
    public static void main( String[] args ) {
        try {
            TestJaxWsService service = new TestJaxWsService();
            //ハンドラリゾルバを生成してサービスクラスに設定
            SampleHandlerResolver handlerResolver = new SampleHandlerResolver();
            service.setHandlerResolver( handlerResolver );
            TestJaxWs port = service.getTestJaxWs();

            String returnValue = port.jaxWsTest1( "Invocation test.", 1003 );

            System.out.println( "[RESULT] " + returnValue );
        }
        catch( UserDefinedException e ){
            e.printStackTrace();
        }
    }
}

ハンドラリゾルバの例を示します。

package com.example.sample.client;

import java.util.ArrayList;
import java.util.List;

import javax.xml.ws.handler.HandlerResolver;
import javax.xml.ws.handler.PortInfo;
import javax.xml.ws.soap.SOAPBinding;

public class SampleHandlerResolver implements HandlerResolver{
    //このハンドラリゾルバで保持するハンドラチェイン
    private List<Handler> handlerChain = new ArrayList<Handler>();

    //都合のよい方法でハンドラチェインにハンドラを追加しておく
    //ここではコンストラクタで追加する
    public SampleHandlerResolver(){
        this.handlerChain.add( new SomeHandler() );
    }

    //ハンドラチェインを返す
    public List<Handler> getHandlerChain( PortInfo portInfo ){
        //portInfoオブジェクトの内容を調べ
        //このハンドラリゾルバで処理可能であればハンドラチェインを返す
        if( portInfo.getBindingID().equals( SOAPBinding.SOAP11HTTP_BINDING )
            && portInfo.getPortName().equals( ... )
            && portInfo.getServiceName().equals( ... ) ){
            return this.handlerChain;
        }
        else{
            ...
        }
    }
}

javax.xml.ws.Service#setHandlerResolverメソッドで設定されたハンドラリゾルバへの変更は，それ以前に同じServiceオブジェクトから取得されたポートのハンドラチェインには影響しません。

(b)　ポートへのハンドラチェインの設定

APIを使用して，ポートにハンドラチェインを設定するコードを追加したWebサービスクライアントの例を示します。

package com.example.sample.client;

import java.util.ArrayList;
import java.util.List;

import javax.xml.ws.Binding;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.handler.Handler;

import com.example.sample.TestJaxWs;
import com.example.sample.TestJaxWsService;
import com.example.sample.UserDefinedException;

public class TestClient {
    public static void main( String[] args ) {
        try {
            TestJaxWsService service = new TestJaxWsService();
            TestJaxWs port = service.getTestJaxWs();

            //ポートに設定するハンドラチェインを生成
            List<Handler> handlerChain = new ArrayList<Handler>();
            //ハンドラチェインにハンドラを追加
            handlerChain.add( new SomeHandler() );

            //javax.xml.ws.Bindingを取得
            Binding binding = ( ( BindingProvider )port ).getBinding();

            //javax.xml.ws.Bindingを使用してポートにハンドラチェインを設定
            binding.setHandlerChain(handlerChain);

            String returnValue = port.jaxWsTest1( "Invocation test.", 1003 );
            System.out.println( "[RESULT] " + returnValue );
        }
        catch( UserDefinedException e ){
            e.printStackTrace();
        }
    }
}

サービスクラスとサービスクラスから取得したポートの両方にハンドラチェインを設定した場合は，ポートに設定されているハンドラチェインを使用します。また，javax.xml.ws.Binding#setHandlerChainメソッドで設定されたハンドラチェインは，ポートの取得元になったServiceオブジェクトのハンドラチェインには影響しません。

(2)　SOAPロールとアクタの設定

SOAPロールおよびアクタの設定を省略した場合，または空文字を指定した場合は，デフォルトの値が設定されます。デフォルトの値は，SOAP 1.1仕様のSOAPメッセージの場合は"http://schemas.xmlsoap.org/soap/actor/next"，SOAP 1.2仕様のSOAPメッセージの場合は"http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver"です。

(3)　soap:mustUnderstand属性の設定

soap:mustUnderstand属性には，"0"，"1"，"true"，または"false"を設定してください。それ以外の値を設定した場合は，"0"または"false"が設定されているものと見なされます。

37　アドレッシング機能

この章では，Application Serverのアドレッシング機能で実現できる通信方式，および使用時の設定について説明します。

37.1　アドレッシング機能とは

アドレッシング機能とは，一般的な転送プロトコルと通信システムによって与えられるサーバ名やポート番号などの情報を標準化し，特定のトランスポートまたは通信システムから，Webサービスやメッセージを独立させるための機能です。アドレッシング機能では，同期通信と非同期通信の2種類の通信方式をサポートしています。

37.1.1　同期通信

(1)　同期通信の流れ

同期通信の場合，Webサービスにあるサービスメソッドの呼び出しのリクエストメッセージをWebサービスクライアントから送信し，Webサービスから結果のレスポンスメッセージを受信します。

同期通信の流れを次に示します。

図37‒1　同期通信の流れ

(2)　同期通信の設定方法

同期通信を使用するには，アドレッシング・ヘッダのwsa:ReplyTo/wsa:Address要素に，WS-Addressing 1.0仕様で規定されている匿名URIである"http://www.w3.org/2005/08/addressing/anonymous"を設定します。

次の条件の場合に，アドレッシング・ヘッダに設定する内容の例を示します。

WebサービスのURI

http://localhost/addressing/AddNumbersImplService

Webサービスを呼び出す際のAction値

http://sample.com/input

匿名URI

http://www.w3.org/2005/08/addressing/anonymous

このメッセージを表すユニークなID

uuid:4cfb4248-a552-4e33-a610-6af94f2aad07

<To xmlns="http://www.w3.org/2005/08/addressing">
  http://localhost/addressing/AddNumbersImplService
</To>
<Action xmlns=http://www.w3.org/2005/08/addressing>
  http://sample.com/input
</Action>
<ReplyTo xmlns="http://www.w3.org/2005/08/addressing">
  <Address>http://www.w3.org/2005/08/addressing/anonymous</Address>
</ReplyTo>
<MessageID xmlns="http://www.w3.org/2005/08/addressing">
  uuid:4cfb4248-a552-4e33-a610-6af94f2aad07
</MessageID>

37.1.2　非同期通信

(1)　非同期通信の流れ

アドレッシング機能を使用した非同期通信の場合，WebサービスクライアントはWebサービスにあるサービスメソッドを呼び出すリクエストメッセージを送信したあと，Webサービスから結果のレスポンスメッセージを受信しないで処理を終了します。Webサービスは，レスポンスメッセージをほかのWebサービスに対して送信します。

非同期通信の流れを次に示します。

図37‒2　非同期通信の流れ

(2)　非同期通信の設定方法

非同期通信を使用するには，アドレッシング・ヘッダのwsa:ReplyTo/wsa:Address要素やwsa:FaultTo/wsa:Address要素に，レスポンスメッセージを送信するWebサービスのURLを設定します。

次の条件の場合に，アドレッシング・ヘッダに設定する内容の例を示します。

WebサービスのURI

http://localhost/addressing/AddNumbersImplService

Webサービスを呼び出す際のAction値

http://sample.com/input

Webサービスが正常終了した際の応答メッセージ送信先URL

http://localhost/responseserver/ResponseServerImplService

Webサービスが異常終了した際の応答メッセージ送信先URL

http://localhost/responseserver/FaultServerImplService

このメッセージを表すユニークなID

uuid:b19439fa-7a29-4045-93d9-56d6a2183afd

<To xmlns="http://www.w3.org/2005/08/addressing">
  http://localhost/addressing/AddNumbersImplService
</To>
<Action xmlns="http://www.w3.org/2005/08/addressing">
  http://sample.com/input
</Action>
<ReplyTo xmlns="http://www.w3.org/2005/08/addressing">
  <Address>
    http://localhost/responseserver/ResponseServerImplService
  </Address>
</ReplyTo>
<FaultTo xmlns="http://www.w3.org/2005/08/addressing">
  <Address>
    http://localhost/responseserver/FaultServerImplService
  </Address>
</FaultTo>
<MessageID xmlns="http://www.w3.org/2005/08/addressing">
  uuid:b19439fa-7a29-4045-93d9-56d6a2183afd
</MessageID>

(3)　非同期通信の注意事項

非同期通信を使用するときの注意事項について説明します。

Webサービスがレスポンスメッセージの送信に失敗しても，Webサービスクライアントにはエラーは返りません。

アドレッシング・ヘッダのwsa:ReplyTo/wsa:Address要素やwsa:FaultTo/wsa:Address要素に，wsa:To要素に設定したWebサービスと同じURLを設定した場合，レスポンスメッセージの送信元と送信先が同じになり，通信が無限ループになるおそれがあります。

Webサービス側のJAX-WSエンジンは，リクエストメッセージとしてフォルトメッセージを受信した場合，サーバエラー（HTTPコード：500）として処理します。そのため，フォルトメッセージをリクエストメッセージとして受信するWebサービスは作成できません。

プロキシを経由している場合，非同期通信は使用できません。非同期通信を使用する場合，レスポンスメッセージはプロキシを経由しないで，ほかのWebサービスに送信してください。

37.2　WSDLの拡張要素と拡張属性

WS-Addressing 1.0仕様では，WSDLに記述する二つの拡張要素と一つの拡張属性が定義されています。ここでは，このWSDL拡張要素と拡張属性について説明します。

37.2.1　WSDLの拡張要素

Application Serverで使用できるWS-Addressing 1.0仕様のWSDL拡張要素を次に示します。

(1)　wsaw:UsingAddressing要素

Webサービスでアドレッシング機能が有効かどうかを示します。

この要素は，wsdl:definitions/wsdl:binding要素，またはwsdl:definitions/wsdl:service/wsdl:port要素の子要素として記述できます。この要素を記述したWebサービスでは，アドレッシング機能が有効になります。

wsdl:required属性

リクエストメッセージにアドレッシング・ヘッダが必須かどうかを示します。

この属性に"true"を指定した場合，アドレッシング・ヘッダは必須です。"false"を指定した場合，アドレッシング・ヘッダは任意です。

なお，wsaw:UsingAddressing要素には，子要素または名前空間"http://www.w3.org/2006/05/addressing/wsdl"に属する属性は記述できません。記述した場合，cjwsimportコマンド実行時に標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

(2)　wsaw:Anonymous要素

アドレッシング・ヘッダの応答エンドポイント（wsa:From/wsa:Address要素，wsa:ReplyTo/wsa:Address要素，およびwsa:FaultTo/wsa:Address要素）に匿名URIを使用できるかどうかを示します。

この要素は，wsdl:definitions/wsdl:binding/wsdl:operation要素の子要素として記述できます。指定できる値は次のとおりです。

optional

リクエストメッセージの応答エンドポイントに匿名URIを使用するかどうかは任意です。

required

リクエストメッセージの応答エンドポイントとして，常に匿名URIを使用する必要があります。

prohibited

リクエストメッセージの応答エンドポイントとして，匿名URIを使用してはいけません。

wsaw:Anonymous要素に上記以外の値は設定できません。上記以外の値を設定した場合，cjwsimportコマンド実行時に標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。また，wsaw:Anonymous要素には子要素または名前空間"http://www.w3.org/2006/05/addressing/wsdl"に属する属性は記述できません。記述した場合，cjwsimportコマンド実行時に標準エラー出力とログにエラーメッセージが出力され，cjwsimportコマンドの処理が終了されます（KDJW51029-E）。

なお，Webサービス側のJAX-WSエンジンが発行したWSDLファイルや，hwsgenコマンドで生成したWSDLファイルには，この要素は記述されていません。匿名URIが指定された場合の動作を制御する場合，この要素を記述したWSDLファイルを用意してください。

(3)　wsam:Addressing要素

Webサービスでアドレッシング機能が有効かどうかを示します。JAX-WS 2.2仕様（WS-Addressing 1.0 Metadata）では，wsaw:UsingAddressing要素ではなくこの要素を使用します。wsaw:UsingAddressing要素と同時に指定した場合は，どちらかの要素でアドレッシング・ヘッダを必須と指定することで，リクエストメッセージのアドレッシング・ヘッダが必須であることを示します。

この要素は，wsdl:definitions/wsdl:binding要素またはwsdl:definitions/wsdl:service/wsdl:port要素の子要素として記述できます。この要素を記述した場合，この要素での設定が優先されます。

wsp:Optional属性

リクエストメッセージにアドレッシング・ヘッダが必須であるかどうかを示します。

この属性がtrueの場合，アドレッシング・ヘッダが任意であることを示します。falseまたはこの属性が省略された場合は，アドレッシング・ヘッダが必須であることを示します。

(4)　wsam:AnonymousResponses要素

リクエストメッセージにアドレッシング・ヘッダが含まれる場合，応答エンドポイント（wsa:From/wsa:Address要素，wsa:ReplyTo/wsa:Address要素，wsa:FaultTo/wsa:Address要素）に，匿名URIを指定する必要があることを示します。

この要素は，wsdl:definitions/wsdl:binding/wsam:Addressing/wsp:Policyまたはwsdl:definitions/wsdl:service/wsdl:port/wsam:Addressing/wsp:Policyの子要素として記述できます。

(5)　wsam:NonAnonymousResponses要素

リクエストメッセージにアドレッシング・ヘッダが含まれる場合，応答エンドポイント（wsa:From/wsa:Address要素，wsa:ReplyTo/wsa:Address要素，wsa:FaultTo/wsa:Address要素）に，非匿名URIを指定する必要があることを示します。

この要素は，wsdl:definitions/wsdl:binding/wsam:Addressing/wsp:Policyまたはwsdl:definitions/wsdl:service/wsdl:port/wsam:Addressing/wsp:Policyの子要素として記述できます。

(6)　WSDL拡張要素の注意事項

WSDL拡張要素の内，次に示す要素を使用する場合の注意事項を説明します。

wsaw:Anonymous要素

サービス側JAX-WSエンジンが発行するWSDLファイルやhwsgenコマンドが生成するWSDLファイルには，この要素は現れません。この要素を使用して匿名URIが指定された場合の動作を制御するためには，この要素を記述したWSDLファイルを用意する必要があります。

37.2.2　WSDLの拡張属性

Application Serverで使用できるWS-Addressing 1.0仕様のWSDL拡張属性を次に示します。

wsaw:Action属性

wsdl:input要素，wsdl:output要素，およびwsdl:fault要素とアドレッシング・ヘッダのAction値を結びつけるための拡張属性です。

この属性は，wsdl:portType/wsdl:operation要素の子要素であるwsdl:input要素，wsdl:output要素，およびwsdl:fault要素の拡張属性として記述できます。それ以外の要素の拡張属性として記述した場合は，無視されます。この属性に空白を設定した場合，空白がそのままAction値として使用されます。また，空文字（""）を設定した場合，wsaw:Action属性が無視されます。

この属性がWSDLに記述されている場合，cjwsimportコマンドで生成されるSEIに，javax.xml.ws.Actionアノテーションやjavax.xml.ws.FaultActionアノテーションが付与されます。javax.xml.ws.Actionアノテーションについては「16.2.13　javax.xml.ws.Actionアノテーション」を，javax.xml.ws.FaultActionアノテーションについては「16.2.15　javax.xml.ws.FaultActionアノテーション」を参照してください。

wsaw:Action属性を使用した場合のマッピング例を次に示します。

図37‒3　wsaw:Action属性を使用した場合のマッピング例

37.3　アドレッシング機能で使用するアノテーションの注意事項

アドレッシング機能を使用するときの注意事項について説明します。

javax.xml.ws.soap.Addressingアノテーションをサービス実装クラスに指定してください。

cjwsimportコマンドを実行して生成されたサービス実装クラスのスケルトンクラスには，javax.xml.ws.soap.Addressingアノテーションがマッピングされません。そのため，サービス実装クラスのスケルトンクラスを使用する場合は，javax.xml.ws.soap.Addressingアノテーションを指定する必要があります。

アドレッシング機能で使用できるアノテーションについては，「16.2.1　アノテーション一覧」を参照してください。

37.4　フォルトメッセージ

ここでは，アドレッシング機能を使用した場合のフォルトメッセージについて説明します。

37.4.1　サポートしていないサブサブコード

WS-Addressing 1.0仕様では，フォルトメッセージで使用されるサブサブコードがあらかじめ規定されています。あらかじめ規定されているサブサブコードのうち，Application Serverでサポートしていないサブサブコードを次に示します。

wsa:InvalidEPR

wsa:DuplicateMessageID

wsa:ActionMismatch※

注※

SOAP 1.1仕様の場合，サポートしています。

37.4.2　フォルトメッセージの注意事項

アドレッシング機能を使用するときの注意事項について説明します。

サブコードにwsa:MessageAddressingHeaderRequiredを含むフォルトメッセージ

Webサービス側のJAX-WSエンジンが，サブコードにwsa:MessageAddressingHeaderRequiredを含むフォルトメッセージ※1を送信する場合，フォルトメッセージのサブサブコードにサブコードと同じ値（wsa:MessageAddressingHeaderRequired）を設定します。

サブコードにwsa:ActionNotSupportedを含むフォルトメッセージ

Webサービス側のJAX-WSエンジンが，サブコードにwsa:ActionNotSupportedを含むフォルトメッセージ※2を送信する場合，フォルトメッセージのサブサブコードに値を設定しません。

注※1

アドレッシング・ヘッダに，必須の要素がないフォルトメッセージ

注※2

アドレッシング・ヘッダのwsa:Action要素の値がWebサービス側のwsa:Action値と異なるフォルトメッセージ

37.5　Webサービス側のJAX-WSエンジンの動作（アドレッシング機能使用時）

ここでは，アドレッシング機能を使用した場合の，Webサービス側のJAX-WSエンジンの動作について説明します。

37.5.1　リクエストメッセージ受信時の動作

アドレッシング機能を使用する場合，サービス実装クラスに指定するjavax.xml.ws.soap.Addressingアノテーションに設定されている要素の内容によって，リクエストメッセージを受信したときの動作が異なります。javax.xml.ws.soap.Addressingアノテーションと，リクエストメッセージを受信したときの動作の関係を次の表に示します。

表37‒1　javax.xml.ws.soap.Addressingアノテーションとリクエストメッセージ受信時の動作

項番

javax.xml.ws.soap.Addressingアノテーション

リクエストメッセージ受信時の動作

アドレッシング・ヘッダ

通信

enabled要素

required要素

リクエストメッセージ

レスポンスメッセージ

1

true

true

○

○

成功

2

×

×

（フォルトメッセージ）

失敗

3

false

○

○

成功

4

×

×

成功

5

false

true

○

×

成功

6

×

×

成功

7

false

○

×

成功

8

×

×

成功

（凡例）

○：アドレッシング・ヘッダがあります。

×：アドレッシング・ヘッダはありません。

サービス実装クラスにjavax.xml.ws.soap.Addressingアノテーションを指定しないと，アドレッシング機能は無効となります。その場合，アドレッシング・ヘッダの有無に関係なく，Webサービスはリクエストメッセージを受信します。また，アドレッシング機能が無効になっているため，受信したリクエストメッセージにアドレッシング・ヘッダが設定されていた場合も，Webサービスはアドレッシング・ヘッダなしのレスポンスメッセージを送信します。また，one-wayオペレーションはレスポンスメッセージが存在しないため，one-wayオペレーションを使用したアドレッシング機能はサポートしていません。one-wayオペレーションでアドレッシング機能を使用した場合の動作は保証されません。

37.5.2　レスポンスメッセージ

ここでは，レスポンスメッセージについて説明します。

(1)　レスポンスメッセージの送信先

リクエストメッセージに含まれるアドレッシング・ヘッダの応答エンドポイントに匿名URI以外を使用している場合，wsa:From/wsa:Address要素，wsa:ReplyTo/wsa:Address要素，およびwsa:FaultTo/wsa:Address要素の有無によって，レスポンスメッセージの送信先が異なります。

各要素の有無とレスポンスメッセージの送信先の関係を次の表に示します。

表37‒2　レスポンスメッセージの送信先

項番

アドレッシング・ヘッダ

送信するレスポンスメッセージの種類

レスポンスメッセージの送信先

wsa:From/wsa:Address要素

wsa:ReplyTo/wsa:Address要素

wsa:FaultTo/wsa:Address要素

1

存在しない

存在しない

存在しない

正常メッセージ

HTTPの送信元

2

異常メッセージ

HTTPの送信元

3

存在する

正常メッセージ

HTTPの送信元

4

異常メッセージ

wsa:FaultTo/wsa:Address要素

5

存在する

存在しない

正常メッセージ

wsa:ReplyTo/wsa:Address要素

6

異常メッセージ

wsa:ReplyTo/wsa:Address要素

7

存在する

正常メッセージ

wsa:ReplyTo/wsa:Address要素

8

異常メッセージ

wsa:FaultTo/wsa:Address要素

9

存在する

存在しない

存在しない

正常メッセージ

HTTPの送信元

10

異常メッセージ

HTTPの送信元

11

存在する

正常メッセージ

HTTPの送信元

12

異常メッセージ

wsa:FaultTo/wsa:Address要素

13

存在する

存在しない

正常メッセージ

wsa:ReplyTo/wsa:Address要素

14

異常メッセージ

wsa:ReplyTo/wsa:Address要素

15

存在する

正常メッセージ

wsa:ReplyTo/wsa:Address要素

16

異常メッセージ

wsa:FaultTo/wsa:Address要素

(2)　http://www.w3.org/2005/08/addressing/none指定時の動作

http://www.w3.org/2005/08/addressing/noneは，WS-Addressing 1.0仕様でメッセージを送信しないことを示すURIです。このURIがアドレッシング・ヘッダのwsa:ReplyTo/wsa:Address要素やwsa:FaultTo/wsa:Address要素に設定されている場合，レスポンスメッセージは送信されません。

37.5.3　wsaw:Anonymous要素指定時の動作

WSDLにwsaw:UsingAddressing要素とwsaw:Anonymous要素の両方が記述されている場合，受信したリクエストメッセージのアドレッシング・ヘッダにある応答エンドポイントの値によっては，リクエストメッセージの受信に失敗し，フォルトメッセージを返されることがあります。wsaw:Anonymous要素とWebサービス側のJAX-WSエンジンの動作の関係を次の表に示します。

表37‒3　wsaw:Anonymous要素とサービス側のJAX-WSエンジンの動作

項番

wsaw:Anonymous要素の値

応答エンドポイントの値

Webサービス側のJAX-WSエンジンの動作

1

optional

匿名URI

正常終了

2

非匿名URI

正常終了

3

required

匿名URI

正常終了

4

非匿名URI

受信失敗（フォルトメッセージ）

5

prohibited

匿名URI

受信失敗（フォルトメッセージ）

6

非匿名URI

正常終了

wsaw:Anonymous要素の指定値については，「37.2.1　WSDLの拡張要素」を参照してください。

37.5.4　Addressingアノテーション指定時の動作

サービス実装クラスにjavax.xml.ws.soap.Addressingアノテーションを指定した場合，Webサービス側のJAX-WSエンジンが発行するWSDLファイルや，hwsgenコマンドを実行して生成されるWSDLファイルは次のようになります。

WSDLファイルには，wsaw:UsingAddressing要素だけでなく，wsdl:input要素にwsaw:Action属性も付与されます。付与される値は，WS-Addressing 1.0仕様で決められているデフォルトのAction値です。デフォルトのAction値については，WS-Addressing 1.0仕様を参照してください。

javax.xml.ws.soap.Addressingアノテーションのrequired要素に"false"を指定した場合，WSDLファイルにはwsaw:UsingAddressing要素のwsdl:required属性が付与されません。

37.5.5　Actionアノテーション指定時の動作

SEIのメソッドに指定するjavax.xml.ws.Actionアノテーションのfault要素に，メソッドのthrows節で宣言した例外クラス以外を示したjavax.xml.ws.FaultActionアノテーションを指定した場合，javax.xml.ws.FaultActionアノテーションは無視されます。

37.5.6　wsa:Action要素指定時の動作

ここでは，wsa:Action要素の値，およびwsa:Action要素指定時の注意事項について説明します。

(1)　wsa:Action要素の値

アドレッシング・ヘッダのwsa:Action要素の値は，次の条件によって変化します。

SEIのメソッドにjavax.xml.ws.Actionアノテーションが指定されているか

WSDLにwsaw:Action属性が記述されているか

javax.xml.ws.Actionアノテーションおよびwsaw:Action属性と，wsa:Action要素の値の関係を次の表に示します。

表37‒4　wsa:Action要素の値

項番

Actionアノテーション

wsaw:Action属性

wsa:Action要素の値

1

指定あり

記述あり

Actionアノテーションの値

2

記述なし

Actionアノテーションの値

3

指定なし

記述あり

WSDLのwsaw:Action属性の値

4

記述なし

WS-Addressing 1.0仕様で決められているデフォルトのAction値

非同期通信の応答用またはフォルト用のWebサービスが使用するアドレッシング・ヘッダのwsa:Action要素の値も，上記のとおりに指定してください。

(2)　リクエストメッセージ受信時の注意事項

リクエストメッセージを受信するときの注意事項について説明します。

wsa:Action要素の値が，受信したリクエストメッセージのアドレッシング・ヘッダとサービス側のJAX-WSエンジンが使用するアドレッシング・ヘッダで異なる場合，Webサービスの呼び出しに失敗します。Webサービス側のJAX-WSエンジンでエラーが発生し，WS-Addressing 1.0仕様で規定されているサブサブコードであるwsa:ActionNotSupportedを含んだフォルトメッセージが送信されます。

受信したリクエストメッセージのアドレッシング・ヘッダのwsa:Action要素の値とSOAPActionの値が異なる場合，エラーが発生します。ただし，SOAPActionの値が空文字（""）の場合は，wsa:Action要素の値が空文字以外でもエラーは発生しません。エラーが発生した場合は，Webサービス側のJAX-WSエンジンは，WS-Addressing 1.0仕様で規定されているサブサブコードであるwsa:ActionMismatchを含んだフォルトメッセージを送信します。

37.5.7　wsa:MessageID要素を指定していない場合の動作

wsa:MessageID要素を含まないアドレッシング・ヘッダは，正常ではないと見なされます。そのため，Webサービス側のJAX-WSエンジンでエラーが発生し，WS-Addressing 1.0仕様で規定されているサブコードであるwsa:MessageAddressingHeaderRequiredを含んだフォルトメッセージを送信します。

37.6　Webサービスクライアント側のJAX-WSエンジンの動作（アドレッシング機能使用時）

ここでは，アドレッシング機能を使用した場合の，Webサービスクライアント側のJAX-WSエンジンの動作について説明します。

37.6.1　メッセージ送受信時の動作

アドレッシング機能は，取得したSEIにマッピングされるWSDLの設定内容に従います。ただし，AddressingFeatureクラスを使用してSEIを取得した場合は，AddressingFeatureクラスの設定内容が優先されるため，クラス生成時に設定した引数でメッセージを送受信したときの動作を指定できます。

AddressingFeatureクラスと，メッセージを送信したときの動作の関係を次の表に示します。

表37‒5　AddressingFeatureクラスとメッセージ送信時の動作

項番

AddressingFeatureクラス

リクエストメッセージ送信時の動作

enabled

required

responses

1

true

True

Responses.ALL

○

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

2

False

Responses.ALL

○

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

3

false

True

Responses.ALL

×

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

4

False

Responses.ALL

×

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

（凡例）

○：メッセージにアドレッシング・ヘッダが付与されます。

×：メッセージにアドレッシング・ヘッダは付与されません。

AddressingFeatureクラスと，メッセージを受信したときの動作の関係を次の表に示します。

表37‒6　AddressingFeatureクラスとメッセージ受信時の動作

項番

AddressingFeatureクラス

レスポンスメッセージ受信時の動作

enabled

required

responses

アドレッシング・ヘッダ

通信

1

true

true

Responses.ALL

○

成功

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

2

Responses.ALL

×

失敗

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

3

false

Responses.ALL

○

成功

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

4

Responses.ALL

×

成功

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

5

false

true

Responses.ALL

○

成功

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

6

Responses.ALL

×

成功

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

7

false

Responses.ALL

○

成功

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

8

Responses.ALL

×

成功

Responses.ANONYMOUS

Responses.NON_ANONYMOUS

（凡例）

○：アドレッシング・ヘッダがあります。

×：アドレッシング・ヘッダはありません。

注

AddressingFeatureクラスのresponses属性の指定は，クライアント側JAX-WSエンジンの動作には影響しません。

37.6.2　AddressingFeatureクラスと匿名URI

AddressingFeatureクラスを使用してSEIを取得した場合，Webサービスクライアント側のJAX-WSエンジンはアドレッシング・ヘッダのwsa:ReplyTo/wsa:Address要素に匿名URIを設定します。そのとき，次に示すWebサービスを呼び出すと，匿名URIが使用できないため，サービスメソッドの呼び出し時にWebServiceExceptionが発生します。

WSDLのwsaw:Anonymous要素に"prohibited"が指定されているWebサービス

wsam:Addressing要素の子要素にwsam:NonAnonymousResponses要素が指定されているWebサービス

wsa:Anonymous要素に"prohibited"が指定されているWebサービスや，wsam:Addressing要素の子要素にwsam:NonAnonymousResponses要素が設定されているWebサービスと通信する場合は，非匿名URIを設定したアドレッシング・ヘッダを作成してください。

37.6.3　wsaw:Action属性およびwsam:Action属性の注意事項

クライアント側JAX-WSエンジンが送信するリクエストメッセージのアドレッシングヘッダにあるwsa:Action要素の値は，WSDLに記述する属性によって異なります。wsa:Action要素の値には，次の値が設定されます。

wsaw:Action属性を記述する場合

wsaw:Action属性値が設定されます。

wsam:Action属性を記述する場合

wsam:Action属性値が設定されます。

wsam:Action属性およびwsaw:Action属性を記述する場合

wsam:Action属性値が設定されます。

記述しない場合

仕様で決められているデフォルト値のAction値が設定されます。

デフォルトのAction値については，WS-Addressing 1.0 Metadata仕様を参照してください。

37.6.4　wsa:Action要素の注意事項

Webサービスクライアント側のJAX-WSエンジンが受信したレスポンスメッセージで，アドレッシング・ヘッダのwsa:Action要素の値とSOAPActionの値が異なる場合の動作は保証されません。

37.6.5　SEIの取得に関する注意事項

W3CEndpointReferenceクラスのgetPort(Class<T>, WebServiceFeature...)メソッドを使用すると，WebServiceExceptionが発生してSEIを取得できません。SEIを取得する場合は，ServiceクラスのgetPort(EndpointReference, Class<T>, WebServiceFeature...)メソッドを使用してください。

38　SEIを起点とした開発の例（アドレッシング機能使用時）

この章では，アドレッシング機能を使用する場合に，SEIを起点としたWebサービスを開発するときの例を説明します。

38.1　開発例の構成（SEI起点・アドレッシング）

この章で説明する開発例では，SEIを起点としたWebサービスを開発します。

開発するWebサービスの構成を次の表に示します。

表38‒1　Webサービスの構成（SEI起点・アドレッシング）

項番

項目

値

1

デプロイするJ2EEサーバの名称

jaxwsserver

2

Webサーバのホスト名とポート番号

webhost:8085

3

ネーミングサーバのURL

corbaname::testserver:900

4

コンテキストルート

addressing_dynamic_generate

5

スタイル

document/literal/wrapped

6

名前空間URI

http://sample.com

7

ポートタイプ

個数

1

8

ローカル名

AddNumbersImpl

9

オペレーション

個数

3

10

ローカル名1

add

11

ローカル名2

add2

12

ローカル名3

add3

13

サービス

個数

1

14

ローカル名

AddNumbersImplService

15

ポート

個数

1

16

ローカル名

AddNumbersImplPort

17

Webサービス実装クラス

com.sample.AddNumbersImpl

18

Webサービス実装クラスで公開するメソッド

個数

3

19

メソッド名1

add

20

メソッド名2

add2

21

メソッド名3

add3

22

Webサービス実装クラスのメソッドでスローする例外

個数

1

23

クラス名

com.sample.AddNumbersFault

Webサービス開発時のカレントディレクトリの構成を次に示します。

表38‒2　カレントディレクトリの構成（SEI起点・アドレッシング）

ディレクトリ

説明

c:¥temp¥jaxws¥works¥addressing

カレントディレクトリです。

┣

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

┃

server¥

Webサービスの開発で使用します。

┣

┃

┃

META-INF¥

EARファイルのMETA-INFディレクトリに対応します。

┗

application.xml

「38.3.4　application.xmlを作成する」で作成します。

┣

┃

┃

┃

src¥

Webサービスのソースファイル（*.java）を格納します。「38.3.1　Webサービス実装クラスを作成する」および「38.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

┃

┃

┃

┃

WEB-INF¥

WARファイルのWEB-INFディレクトリに対応します。

┣

web.xml

「38.3.3　web.xmlを作成する」で作成します。

┗

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「38.3.2　Webサービス実装クラスをコンパイルする」で使用します。

┣

┃

addressing_dynamic_generate.ear

「38.3.5　EARファイルを作成する」で作成します。

┗

addressing_dynamic_generate.war

┗

client¥

Webサービスクライアントの開発で使用します。

┣

┃

┃

┃

┃

src¥

Webサービスクライアントのソースファイル（*.java）を格納します。「38.5.1　サービスクラスを生成する」および「38.5.2　Webサービスクライアントの実装クラスを作成する」で使用します。

┣

┃

┃

classes¥

コンパイルしたクラスファイル（*.class）を格納します。「38.5.3　Webサービスクライアントの実装クラスをコンパイルする」で使用します。

┣

┃

┃

usrconf.cfg

「38.6.1　Javaアプリケーション用オプション定義ファイルを作成する」で作成します。

┗

usrconf.properties

「38.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する」で作成します。

カレントディレクトリのパスは，開発する環境に合わせて変更してください。

なお，以降の説明では，この表に示すディレクトリおよびファイル名を使用します。コマンド実行例やJavaソースなどで背景色付きの太字になっている部分は，この例で使用する指定値や生成される値を示します。構築する環境に合わせて読み替えてください。

また，この章で説明する開発例では，WebサービスとWebサービスクライアントを同じ環境で開発しますが，別の環境で開発することもできます。別の環境で開発する場合は，それぞれの環境に合わせて，カレントディレクトリのパスを読み替えてください。

38.2　開発例の流れ（SEI起点・アドレッシング）

この章で説明する開発例では，次の流れで開発および実行します。

Webサービスの開発

Webサービス実装クラスを作成する（38.3.1）

javacコマンドを実行し，Webサービス実装クラスをコンパイルする（38.3.2）

web.xmlを作成する（38.3.3）

application.xmlを作成する（38.3.4）

EARファイルを作成する（38.3.5）

デプロイと開始

EARファイルをデプロイする（38.4.1）

Webサービスを開始する（38.4.2）

Webサービスクライアントの開発

cjwsimportコマンドを実行し，サービスクラスを生成する（38.5.1）

Webサービスクライアントの実装クラスを作成する（38.5.2）

Webサービスクライアントの実装クラスをコンパイルする（38.5.3）

Webサービスの実行

Javaアプリケーション用オプション定義ファイルを作成する（38.6.1）

Javaアプリケーション用ユーザプロパティファイルを作成する（38.6.2）

Webサービスクライアントを実行する（38.6.3）

38.3　Webサービスの開発例（SEI起点・アドレッシング）

ここでは，SEIを起点とした場合のWebサービス（アドレッシング機能を使用）の開発例を説明します。

38.3.1　Webサービス実装クラスを作成する

Webサービスの処理を記述したWebサービス実装クラスを作成します。ここでは，受け取った要求メッセージの内容を計算して，応答メッセージを返すWebサービス実装クラスを作成します。

Webサービス実装クラスの作成例を次に示します。

package com.sample;

import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.xml.ws.Action;
import javax.xml.ws.FaultAction;

@WebService(name = "AddNumbers", targetNamespace = "http://sample.com/")
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT, use=SOAPBinding.Use.LITERAL, parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
interface AddNumbers {

    @Action(input = "http://sample.com/input",
            output = "http://sample.com/output")
    public int add(int number1, int number2) throws AddNumbersFault;

    public int add2(int number1, int number2) throws AddNumbersFault;

    @Action(input = "http://sample.com/input3",
            output = "http://sample.com/output3",
            fault = {@FaultAction(className = AddNumbersFault.class, value = "http://sample.com/fault3")})
    public int add3(int number1, int number2) throws AddNumbersFault;
}

作成したAddNumbers.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥addressing¥server¥src¥com¥sample¥ディレクトリに保存します。

次に，SEIを実装したWebサービスの本体を作成します。ここでは，受け取った要求メッセージの内容を計算して応答メッセージとして返すWebサービス実装クラスcom.sample.AddNumbersImplを作成します。

Webサービスの本体の作成例を次に示します。

package com.sample;

import javax.jws.WebService;
import javax.xml.ws.soap.Addressing;

@Addressing
@WebService(endpointInterface = "com.sample.AddNumbers")
public class AddNumbersImpl implements AddNumbers {

    public int add(int number1, int number2) throws AddNumbersFault {
        return impl(number1, number2);
    }

    public int add2(int number1, int number2) throws AddNumbersFault {
        return impl(number1, number2);
    }

    public int add3(int number1, int number2) throws AddNumbersFault {
        return impl(number1, number2);
    }

    int impl(int number1, int number2) throws AddNumbersFault {
        if (number1 < 0 || number2 < 0) {
            throw new AddNumbersFault("Negative numbers can't be added!",
                                      "Numbers: " + number1 + ", " + number2);
        }
        return number1 + number2;
    }
}

作成したAddNumbersImpl.javaは，UTF-8形式で，c:¥temp¥jaxws¥works¥addressing¥server¥src¥com¥sample¥ディレクトリに保存します。

また，com.sample.AddNumbersImplクラスでスローしている例外クラスcom.sample.AddNumbersFaultを作成します。

例外クラスの作成例を次に示します。

package com.sample;

public class AddNumbersFault extends Exception {

    String detail;

    public AddNumbersFault(String message, String detail) {
        super(message);
        this.detail = detail;
    }

    public String getDetail() {
        return detail;
    }
}

作成したAddNumbersFault.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥addressing¥server¥src¥com¥sample¥ディレクトリに保存します。

38.3.2　Webサービス実装クラスをコンパイルする

javacコマンドを実行して，Webサービス実装クラスをコンパイルします。javacコマンドについては，JDKのドキュメントを参照してください。

javacコマンドの実行例を次に示します。添付ファイル機能を使用したJavaプログラムをjavacコマンドでコンパイルする場合，javacコマンドの引数に"--add-modules=java.activation"を指定してください。

> cd c:¥temp¥jaxws¥works¥addressing¥server¥
> mkdir WEB-INF¥classes¥
> javac -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxp.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmstax.jar" -d WEB-INF¥classes¥ -s src src¥com¥sample¥AddNumbers.java src¥com¥sample¥AddNumbersImpl.java src¥com¥sample¥AddNumbersFault.java

javacコマンドが正常に終了すると，コンパイルしたクラスが，c:¥temp¥jaxws¥works¥addressing¥server¥WEB-INF¥classes¥com¥sample¥ディレクトリに出力されます。なお，コンパイルしたWebサービス実装クラスに対してhwsgenコマンドを実行すると，事前にエラーチェックができます。hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を，エラーチェックについては，「10.23.1　hwsgenコマンドによるエラーチェックについて」を参照してください。

38.3.3　web.xmlを作成する

WARファイルの構成要素として必要なweb.xmlを作成します。

web.xmlの作成例を次に示します。

<<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <description>Sample web service &quot;addressing_dynamic_generate&quot;</description>
  <display-name>Sample_web_service_addressing_dynamic_generate</display-name>
  <listener>
    <listener-class>

com.cosminexus.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <description>Endpoint servlet for Cosminexus JAX-WS</description>
    <display-name>Endpoint_servlet_for_Cosminexus_JAX_WS</display-name>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <servlet-class>
      com.cosminexus.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CosminexusJaxwsServlet</servlet-name>
    <url-pattern>/AddNumbersImplService</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

バージョン2.5のweb.xmlを作成する場合は，web-app要素のversion属性を"2.5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"にしてください。

作成したweb.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥addressing¥server¥WEB-INF¥ディレクトリに保存します。web.xmlの設定項目については，「3.4　web.xmlの作成」を参照してください。

38.3.4　application.xmlを作成する

EARファイルの構成要素として必要なapplication.xmlを作成します。

application.xmlの作成例を次に示します。なお，Webサービスとしてapplication.xmlに設定する項目はありません。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;addressing_dynamic_generate&quot;</description>
  <display-name>Sample_application_addressing_dynamic_generate</display-name>
  <module>
    <web>
      <web-uri>addressing_dynamic_generate.war</web-uri>
      <context-root>addressing_dynamic_generate</context-root>
    </web>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

作成したapplication.xmlは，UTF-8形式でc:¥temp¥jaxws¥works¥addressing¥server¥META-INF ¥ディレクトリに保存します。application.xmlを作成するときの注意事項については，マニュアル「アプリケーションサーバ アプリケーション開発ガイド」の「5.2.2　application.xml編集時の注意事項」を参照してください。

38.3.5　EARファイルを作成する

jarコマンドを使用して，これまでに作成したファイルを含めたEARファイルを作成します。

EARファイルの作成例を次に示します。

> cd c:¥temp¥jaxws¥works¥addressing¥server¥
> jar cvf addressing_dynamic_generate.war .¥WEB-INF
> jar cvf addressing_dynamic_generate.ear .¥addressing_dynamic_generate.war .¥META-INF¥application.xml

jarコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥addressing¥server ¥ディレクトリにaddressing_dynamic_generate.earが作成されます。

jarコマンドについては，JDKのドキュメントを参照してください。

38.4　デプロイと開始の例（SEI起点・アドレッシング）

ここでは，アドレッシング機能を使用する場合に，SEIを起点としたときのデプロイと開始の例を説明します。

38.4.1　EARファイルをデプロイする

cjimportappコマンドを使用して，作成したEARファイルをJ2EEサーバにデプロイします。

デプロイの例を次に示します。

> cd c:¥temp¥jaxws¥works¥addressing¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjimportapp" jaxwsserver -nameserver corbaname::testserver:900 -f addressing_dynamic_generate.ear

cjimportappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjimportapp（J2EEアプリケーションのインポート）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションをデプロイ（インポート）する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.3　J2EEアプリケーションのインポート」を参照してください。

38.4.2　Webサービスを開始する

cjstartappコマンドを使用して，Webサービスを開始します。

Webサービスを開始する例を次に示します。

> cd c:¥temp¥jaxws¥works¥addressing¥server¥
> "%COSMINEXUS_HOME%¥CC¥admin¥bin¥cjstartapp" jaxwsserver -nameserver corbaname::testserver:900 -name Sample_application_addressing_dynamic_generate

cjstartappコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjstartapp（J2EEアプリケーションの開始）」を参照してください。

運用管理ポータルを使用して，J2EEアプリケーションを開始する方法については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「12.3.1　J2EEアプリケーションの開始」を参照してください。

38.5　Webサービスクライアントの開発例（SEI起点・アドレッシング）

ここでは，SEIを起点とした場合のWebサービスクライアント（アドレッシング機能を使用）の開発例を説明します。

38.5.1　サービスクラスを生成する

cjwsimportコマンドを実行すると，サービスクラスなどWebサービスクライアントの開発に必要なJavaソースが生成されます。cjwsimportコマンドについては，「14.1.1　cjwsimportコマンド」を参照してください。

cjwsimportコマンドの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥addressing¥client¥
> mkdir src¥
> mkdir classes¥
> "%COSMINEXUS_HOME%¥jaxws¥bin¥cjwsimport.bat" -s src -d classes http://webhost:8085/addressing_dynamic_generate/AddNumbersImplService?wsdl

cjwsimportコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥addressing¥client¥src¥com¥sample¥ディレクトリにJavaソースが生成されます。

生成物の一覧を次の表に示します。

表38‒3　サービスクラス生成時の生成物（SEI起点・アドレッシング）

ファイル名

説明

Add.java

WSDL定義の「オペレーション」の要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

AddResponse.java

WSDL定義の「オペレーション」の応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

Add2.java

WSDL定義の「オペレーション」の要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

Add2Response.java

WSDL定義の「オペレーション」の応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

Add3.java

WSDL定義の「オペレーション」の要求メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

Add3Response.java

WSDL定義の「オペレーション」の応答メッセージのwrapper要素が参照する型に対応するJavaBeanクラスです。

ObjectFactory.java

JAXB 2.2仕様のObjectFactoryクラスです。

package-info.java

package-info.javaファイルです。

AddNumbers.java

WSDL定義の「サービス」に対応するサービスエンドポイントインタフェース（SEI）です。

AddNumbersImplService.java

サービスクラスです。

AddNumbersFault.java

WSDL定義のAddNumbersFaultに対応するJavaBeanクラスです。

AddNumbersFault_Exception.java

フォルトbeanのラッパ例外クラスです。

ファイル名のAdd，Add2，Add3，AddNumbers，およびAddNumbersImplServiceは，オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名の記述によって変わります。オペレーションのローカル名，ポートタイプのローカル名，およびサービスのローカル名のマッピングについては，次の個所を参照してください。

「15.1.2　ポートタイプからSEI名へのマッピング」

「15.1.3　オペレーションからメソッド名へのマッピング」

「15.1.4　メッセージのパートからパラメタおよび戻り値へのマッピング（wrapperスタイルの場合）」

「15.1.5　メッセージのパートからパラメタおよび戻り値へのマッピング（non-wrapperスタイルの場合）」

38.5.2　Webサービスクライアントの実装クラスを作成する

Webサービスを利用するWebサービスクライアントの実装クラスを作成します。

Webサービスに対して3回の呼び出しをするWebサービスクライアントの作成例を次に示します。

package com.sample.client;

import javax.xml.namespace.QName;
import javax.xml.ws.soap.AddressingFeature;
import javax.xml.ws.wsaddressing.W3CEndpointReference;
import javax.xml.ws.wsaddressing.W3CEndpointReferenceBuilder;

import com.sample.AddNumbers;
import com.sample.AddNumbersImplService;
import com.sample.AddNumbersFault_Exception;

public class TestClient {

    int number1 = 10;
    int number2 = 10;
    int negativeNumber = -10;

    public static void main(String[] args) {
        TestClient client = new TestClient();

        client.existActionAnnotation1();
        client.existActionAnnotation2();
        client.notExistActionAnnotation();
        client.existFaultActionAnnotation();
        client.notExistFaultActionAnnotation();
    }

    public void existActionAnnotation1() {
        System.out.println("existActionAnnotation1");
        try {
            AddressingFeature feature = new AddressingFeature();

            AddNumbersImplService service = new AddNumbersImplService();
            AddNumbers stub = service.getAddNumbersImplPort(feature);
            int result = stub.add(number1, number2);
            assert result == 20;
        } catch (Exception ex) {
            ex.printStackTrace();
            assert false;
        }
    }

    public void existActionAnnotation2() {
        System.out.println("existActionAnnotation2");
        try {
            AddressingFeature feature = new AddressingFeature();
            W3CEndpointReferenceBuilder eprBuilder = new W3CEndpointReferenceBuilder();
            eprBuilder.address("http://webhost:8085/addressing_dynamic_generate/AddNumbersImplService");
            eprBuilder.serviceName(new QName("http://sample.com/", "AddNumbersImplService"));
            eprBuilder.endpointName(new QName("http://sample.com/", "AddNumbersImplPort"));
            W3CEndpointReference epr = eprBuilder.build();

            AddNumbersImplService service = new AddNumbersImplService();
            AddNumbers stub = service.getPort(epr, AddNumbers.class, feature);
            int result = stub.add(number1, number2);
            assert result == 20;
        } catch (Exception ex) {
            ex.printStackTrace();
            assert false;
        }
    }

    public void notExistActionAnnotation() {
        System.out.println("notExistActionAnnotation");
        try {
            AddressingFeature feature = new AddressingFeature();

            AddNumbersImplService service = new AddNumbersImplService();
            AddNumbers stub = service.getAddNumbersImplPort(feature);
            int result = stub.add2(number1, number2);
            assert result == 20;
        } catch (Exception ex) {
            ex.printStackTrace();
            assert false;
        }
    }

    public void existFaultActionAnnotation() {
        System.out.println("existFaultActionAnnotation");
        try {
            AddressingFeature feature = new AddressingFeature();

            AddNumbersImplService service = new AddNumbersImplService();
            AddNumbers stub = service.getAddNumbersImplPort(feature);
            stub.add3(negativeNumber, number2);
            assert false;
        } catch (AddNumbersFault_Exception e) {
            System.out.println("This is expected exception");
        } catch (Exception e) {
            e.printStackTrace();
            assert false;
        }
    }

    public void notExistFaultActionAnnotation() {
        System.out.println("notExistFaultActionAnnotation");
        try {
            AddressingFeature feature = new AddressingFeature();

            AddNumbersImplService service = new AddNumbersImplService();
            AddNumbers stub = service.getAddNumbersImplPort(feature);
            stub.add(negativeNumber, number2);
            assert false;
        } catch (AddNumbersFault_Exception ex) {
            System.out.println("This is expected exception");
        } catch (Exception e) {
            e.printStackTrace();
            assert false;
        }
    }
}

作成したTestClient.javaは，UTF-8形式でc:¥temp¥jaxws¥works¥addressing¥client¥src¥com¥sample¥client¥ディレクトリに保存します。

なお，com.sample，AddNumbers，AddNumbersImplService，AddNumbersImplPort，add，add2，およびadd3は，生成されたJavaソースのパッケージ名，クラス名，およびクラス内のメソッド名によって変わります。異なる構成のWebサービスを開発する場合には，パッケージ名，クラス名，およびクラス内のメソッド名の記述を見直す必要があります。

38.5.3　Webサービスクライアントの実装クラスをコンパイルする

javacコマンドを使用して，作成したWebサービスクライアントをコンパイルします。

コンパイルの例を次に示します。

> cd c:¥temp¥jaxws¥works¥addressing¥client¥
> javac -encoding UTF-8 -cp "%COSMINEXUS_HOME%¥jaxws¥lib¥cjjaxws.jar;%COSMINEXUS_HOME%¥CC¥javaee¥1100¥lib¥javaee-api.jar;%COSMINEXUS_HOME%¥jaxp¥lib¥csmjaxb.jar;.¥classes" -d .¥classes src¥com¥sample¥client¥TestClient.java

javacコマンドが正常に終了すると，c:¥temp¥jaxws¥works¥addressing¥client¥classes¥com¥sample¥client¥ディレクトリに，TestClient.classが生成されます。

javacコマンドについては，JDKのドキュメントを参照してください。

38.6　Webサービスの実行例（SEI起点・アドレッシング）

ここでは，SEIを起点とした場合のWebサービスクライアント（アドレッシング機能使用時)の実行例を説明します。

38.6.1　Javaアプリケーション用オプション定義ファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用オプション定義ファイル（usrconf.cfg）を作成します。

Javaアプリケーション用オプション定義ファイルの作成例を次に示します。

add.class.path=<Application Serverのインストールディレクトリ>¥jaxws¥lib¥cjjaxws.jar
add.class.path=.¥classes
ejb.client.log.directory=logs
add.jvm.arg=-Dcosminexus.home=<Application Serverのインストールディレクトリ>
add.jvm.arg=-Dejbserver.server.prf.PRFID=<PRF ID>

<Application Serverのインストールディレクトリ>の部分は，Application Serverをインストールしているパスを絶対パスで指定します。

作成したJavaアプリケーション用オプション定義ファイルは，c:¥temp¥jaxws¥works¥addressing¥client¥ディレクトリに保存します。Javaアプリケーション用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.1　usrconf.cfg（Javaアプリケーション用オプション定義ファイル）」を参照してください。

38.6.2　Javaアプリケーション用ユーザプロパティファイルを作成する

Webサービスを実行するときに必要なJavaアプリケーション用ユーザプロパティファイルを作成します。

ここでは特に設定を変更しないため，c:¥temp¥jaxws¥works¥addressing¥client¥ディレクトリにusrconf.propertiesという名称の空のファイルを作成します。Javaアプリケーション用ユーザプロパティファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「12.2.2　usrconf.properties（Javaアプリケーション用ユーザプロパティファイル）」を参照してください。

38.6.3　Webサービスクライアントを実行する

cjclstartapコマンドを使用して，Webサービスクライアントを実行します。

Webサービスクライアントの実行例を次に示します。

> cd c:¥temp¥jaxws¥works¥addressing¥client¥
> "%COSMINEXUS_HOME%¥CC¥client¥bin¥cjclstartap"  com.sample.client.TestClient

cjclstartapコマンドが正常に終了すると，Webサービスクライアントの実行結果が表示されます。実行結果の表示例を次に示します。

KDJE40053-I The cjclstartap command will now start. (directory for the user definition file = c:¥temp¥jaxws¥works¥addressing¥client, PID = 2636)
existActionAnnotation1
existActionAnnotation2
notExistActionAnnotation
existFaultActionAnnotation
This is expected exception
notExistFaultActionAnnotation
This is expected exception
KDJE40054-I The cjclstartap command was stopped. (PID = 2636, exit status = 0)

イタリック体になっている個所は，実行したタイミングや環境によって変わります。

cjclstartapコマンドについては，マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjclstartap（Javaアプリケーションの開始）」を参照してください。

第5編　トラブルシュート

39　障害対策

この章では，WebサービスまたはWebリソースの運用中に発生した障害の対策について説明します。

39.1　障害の種類と対策

WebサービスまたはWebリソースの運用中に発生する障害として，次に示す現象が考えられます。

WebサービスまたはWebリソースが正常に動作しない場合

プログラムの実行中に異常終了する

プログラムが意図したとおりに動作しない

WebサービスまたはWebリソースが正常に動作する場合

期待した性能が出ない

プログラムが正常に動作しない場合，ログやコンソールにエラーメッセージ，または警告メッセージが出力され，異常終了します。または正常に終了しても，意図したとおりに動作しない場合も考えられます。

また，プログラムが正常に動作している場合でも，プログラムまたはコンポーネントの処理能力が，期待した性能に届かない場合が考えられます。

それぞれの場合について，対策方法を説明します。なお，EJBのWebサービス呼び出しをする際に，EJBコンテナ内で障害が発生する場合があります。EJBコンテナで発生した障害については，マニュアル「アプリケーションサーバ 機能解説 保守／移行編」の「8.9　EJBコンテナのトレース取得ポイント」を参照してください。

なお，WebサービスおよびWebリソースに関するメッセージは，JP1/IM連携用システムログメッセージマッピングファイルに定義できません。このため，WebサービスおよびWebリソースに関するメッセージをJP1イベントに変換してJP1イベントを発行することはできません。JP1/IM連携用システムログメッセージマッピングファイルについては，マニュアル「アプリケーションサーバリファレンス 定義編(サーバ定義)」の「8.3　JP1/IM連携用システムログメッセージマッピングファイル」を参照してください。

39.1.1　プログラムの実行中に異常終了する場合

プログラムの実行中に異常終了した場合の対策の流れを次の図に示します。

図39‒1　警告，エラーメッセージ出力時の調査の流れ

作成したプログラムが正常に動作しないで，エラーメッセージまたは警告メッセージが出力される場合，ログに出力されたメッセージの内容から原因を調査してください。調査の対象となるログは，稼働ログおよび例外ログになります。各ログに出力された情報，および例外のスタックトレースの情報を基に，原因を調査してください。

なお，コマンド実行時に発生した警告メッセージおよびエラーメッセージは，コマンド稼働ログ，またはコマンド例外ログに出力されます。ログについては，「39.3　ログ」を参照してください。

発生した障害がプログラム以外に原因があると判断され，原因が解決できない場合は，障害情報を取得してシステム管理者に連絡してください。障害情報については，「39.2　障害発生時に取得する資料」を参照してください。

39.1.2　プログラムが意図したとおりに動作しない場合

エラーメッセージや警告メッセージが出力されない場合でも，不良などが原因で，作成したプログラムが意図したとおりに動作しないことがあります。この場合，プログラムからWebサービスまたはWebリソースの実装に対して，意図したSOAPメッセージ（Webサービスの場合）またはHTTPメッセージ（Webリソースの場合）が送信されていないおそれがあります。プログラムが意図したとおりに動作しないときには，送受信されているメッセージの内容を解析して，意図したメッセージが送信されているかどうか確認してください。

通信ログの出力内容については，「39.3.5　ログのフォーマット」を参照してください。

SOAPメッセージの通信の流れを次の図に示します。

図39‒2　通信ログの出力（Webサービスの場合）

HTTPメッセージの通信の流れを次の図に示します。

図39‒3　通信ログの出力（Webリソースの場合）

39.1.3　期待した性能が出ない場合

プログラムは正常に動作しているのに，実行時の性能が期待どおりにならない場合があります。原因として，プログラムの問題のほかに，Webサーバやデータベースなどのコンポーネントの問題が考えられます。コンポーネントに問題がある場合は，性能解析トレース（PRF）を使用した調査が有効です。性能解析トレースを使用すれば，各レイヤの処理時間や，リクエストの状況などが解析できます。リクエストの流れを追って，どこで遅延が発生しているかを確認してください。

性能解析トレースを使用した調査方法については，「39.4.3　性能解析トレースによる性能解析方法」を参照してください。

各機能レイヤの処理時間の例を次の図に示します。

図39‒4　各機能レイヤの処理時間の例

39.2　障害発生時に取得する資料

システム管理者へ連絡が必要になる障害，または対処方法がわからない障害が発生した場合は，次に示す障害情報を取得して，システム管理者に連絡してください。

なお，ファイル名の「?」は面数を表します。

稼働ログ（cjwmessage?.logまたはcjrmessage?.log）

例外ログ（cjwexception?_?.logまたはcjrexception?_?.log）

保守ログ（cjwmessage?.logまたはcjrmessage?.log）

通信ログ（cjwtransport?_?.logまたはcjrtransport?_?.log）

コマンドの稼働ログ（cjwsimport?.log，cjwapt?.log）

コマンドの例外ログ（cjwsimportex?_?.log，cjwaptex?_?.log）

コマンドの保守ログ（cjwsimport?.log，cjwapt?.log）

性能解析トレース

ユーザプログラム独自のログ（ある場合だけ）

共通定義ファイル（cjwconf.propertiesまたはcjrconf.properties）

プロセス別の定義ファイル

WebサービスのDDファイル（web.xml，cosminexus-jaxws.xml）

サーバおよびクライアントに設定したシステムプロパティとシステムクラスパス

サーバおよびクライアントの標準出力と標準エラー出力

Component ContainerおよびWebサーバのログ

Component Containerで規定する障害時取得情報

J2EEサーバのユーザ定義ファイル

J2EEサーバの保守情報

サーバ管理コマンドのユーザ定義ファイル

サーバ管理コマンドの保守情報

J2EEサーバの標準出力，標準エラー出力

J2EEサーバ側のTPBrokerのログ

EJBクライアントアプリケーションに設定したシステムプロパティ，およびシステムクラスパス

EJBクライアントアプリケーションの標準出力，標準エラー出力

Component Containerで規定する障害時取得情報の取得方法については，マニュアル「アプリケーションサーバ 機能解説 保守／移行編」の「4.3.1　Component Containerのログの取得」を参照してください。

39.3　ログ

WebサービスまたはWebリソースの開発時，および実行時に出力されるログについて説明します。

39.3.1　ログの種類

出力されるログの種類，および概要を次の表に示します。

表39‒1　ログの種類

項番

分類

概要

1

稼働ログ

稼働状態が出力されます。発生した問題の現象を確認して，問題を取り除くために使用します。

2

例外ログ

例外のスタックトレースが出力されます。発生した例外の詳細を確認するために使用します。

3

保守ログ

保守情報が出力されます。

4

通信ログ※

送受信したメッセージが出力されます。アプリケーション開発時や障害調査時に，送受信した内容を確認するために使用します。

注※

JAX-WS機能の場合，通信ログを有効にするには，動作定義ファイルのcom.cosminexus.jaxws.logger.runtime.transport.client_dumpプロパティ（通信ログの出力（Webサービスクライアント側）），およびcom.cosminexus.jaxws.logger.runtime.transport.server_dumpプロパティ（通信ログの出力（Webサービス側））に値を設定してください。

プロパティについては，「10.1.2　共通定義ファイルの設定項目」を参照してください。

JAX-RS機能の場合，通信ログを有効にするには，動作定義ファイルのcom.cosminexus.jaxrs.logger.runtime.transport.client.levelプロパティ（通信ログの出力レベル（Webリソースクライアント側）），およびcom.cosminexus.jaxrs.logger.runtime.transport.server.levelプロパティ（通信ログの出力レベル（Webリソース側））に値を設定してください。

プロパティについては，「13.1.2　共通定義ファイルの設定項目」を参照してください。

ログが出力される機能と出力されるログの対応を次の表に示します。

表39‒2　機能と出力されるログの対応

項番

機能

出力されるログ

稼働ログ

例外ログ

保守ログ

通信ログ

1

WebサービスおよびWebリソース

○

○

○

○

2

WebサービスクライアントおよびWebリソースクライアント

○

○

○

○

3

cjwsimportコマンド

○

○

○

−

（凡例）

○：ログが出力されます。

−：ログが出力されません。

39.3.2　ログファイルのローテーション

Application ServerのJAX-WS機能とJAX-RS機能では，ログを複数のファイルへローテーションして出力します。ここでは，ログファイルのローテーションについて説明します。

(1)　ローテーションの方式

Application ServerのJAX-WS機能とJAX-RS機能では，WebサービスまたはWebリソースがJ2EEサーバ上で動作する場合に，出力するログの種類ごとにローテーションの切り替え方式を設定できます。ログの種類とローテーションの切り替えの設定可否を次の表に示します。

表39‒3　ログの種類とローテーションの切り替えの設定可否

項番

ログの種類

ローテーションの切り替えの設定可否

1

稼働ログ

○

2

例外ログ

×

3

保守ログ

○

4

通信ログ

×

（凡例）

○：ローテーションの切り替え方式を設定できます。

×：ローテーションの切り替え方式を設定できません。

注

デフォルトでは，出力先ファイルが指定したファイルサイズになると，出力先を次のファイルに切り替えます（ラップアラウンドモード）。詳細は，マニュアル「アプリケーションサーバ 機能解説 保守／移行編」の「3.　トラブルシューティングのための準備」を参照してください。

Javaアプリケーションの開始コマンド（cjclstartapコマンド）で起動するWebサービスクライアントのログ，Webリソースクライアントのログ，またはコマンドラインインタフェースを実行する場合のログでは，ローテーションの切り替え方式を設定できません。

39.3.3　ログの出力先

利用する場面ごとに，ログの出力先について説明します。

(1)　J2EEサーバ上のWebサービス，およびWebサービスクライアントを利用する場合

J2EEサーバ上で動作するWebサービス，およびWebサービスクライアント（サーブレットやEJBなど）のログの出力先を次の表に示します。

表39‒4　ログの出力先（J2EEサーバ上で動作するWebサービスやWebサービスクライアントの場合）

項番

ログの種類

出力先ディレクトリ

ファイル名

1

稼働ログ

<ejb.server.log.directory>/CJW

ラウンドアップ方式の場合

cjwmessage?.log

シフト方式の場合

カレントログファイル：cjwmessage.log

バックアップファイル：cjwmessage?.log

2

例外ログ

<ejb.server.log.directory>/CJW

cjwexception?_?.log

3

保守ログ

<ejb.server.log.directory>/CJW/maintenance

ラウンドアップ方式の場合

cjwmessage?.log

シフト方式の場合

カレントログファイル：cjwmessage.log

バックアップファイル：cjwmessage?.log

4

通信ログ

<ejb.server.log.directory>/CJW

cjwtransport?_?.log

注意事項

<ejb.server.log.directory>は，J2EEサーバのログの出力先になります。詳細については，マニュアル「アプリケーションサーバ 機能解説 保守／移行編」の「3.3.6　J2EEサーバのログ取得の設定」を参照してください。

ファイル名の「?」は面数を表します。

ログ初期化処理前に問題が発生した場合は，Component Containerの稼働ログ（cjmessage?.log）にログが出力されます。

カレントログファイルとは，出力先のログファイルを示します。

バックアップファイルとは，ローテーションによってバックアップされるログファイルを示します。

(2)　コマンドラインインタフェースでWebサービスクライアントを利用する場合

Javaアプリケーションの開始コマンド（cjclstartap）で，Webサービスクライアントを起動する場合のログの出力先を次の表に示します。

表39‒5　ログの出力先（コマンドラインインタフェースでWebサービスクライアントを利用する場合）

項番

ログの種類

出力先ディレクトリ

ファイル名

1

稼働ログ

<ejbserver.client.log.directory>/

<ejbserver.client.ejb.log>/

<ejbserver.client.log.appid>/CJW

cjwmessage?.log

2

例外ログ

<ejbserver.client.log.directory>/

<ejbserver.client.ejb.log>/

<ejbserver.client.log.appid>/CJW

cjwexception?_?.log

3

保守ログ

<ejbserver.client.log.directory>/

<ejbserver.client.ejb.log>/

<ejbserver.client.log.appid>/CJW/maintenance

cjwmessage?.log

4

通信ログ

<ejbserver.client.log.directory>/

<ejbserver.client.ejb.log>/

<ejbserver.client.log.appid>/CJW

cjwtransport?_?.log

注意事項

<ejbserver.client.log.directory>，<ejbserver.client.ejb.log>，および<ejbserver.client.log.appid>は，EJBクライアントアプリケーションのシステムログの出力先になります。詳細については，マニュアル「アプリケーションサーバ機能解説 保守／移行編」の「4.5.2　EJBクライアントアプリケーションのシステムログの出力先」を参照してください。

ファイル名の「?」は面数を表します。

ログ初期化処理前に問題が発生した場合は，Component Containerの稼働ログ（cjclmessage?.log）にログが出力されます。

(3)　コマンドを実行する場合

コマンドを実行する場合のログの出力先を次の表に示します。

表39‒6　ログの出力先（コマンドを実行する場合）

項番

ログの種類

出力先ディレクトリ

ファイル名

1

稼働ログ

<コマンドログ出力先ディレクトリ（com.cosminexus.jaxws.tool.log.directory）>

cjwsimportコマンドの場合：cjwsimport?.log

2

例外ログ

<コマンドログ出力先ディレクトリ（com.cosminexus.jaxws.tool.log.directory）>

cjwsimportコマンドの場合：cjwsimportex?_?.log

3

保守ログ

<コマンドログ出力先ディレクトリ（com.cosminexus.jaxws.tool.log.directory）>/maintenance

cjwsimportコマンドの場合：cjwsimport?.log

注意事項

<コマンドログ出力先ディレクトリ（com.cosminexus.jaxws.tool.log.directory）>は動作定義ファイルのプロパティで設定します。デフォルトの出力先は，<Application Serverのインストールディレクトリ>/jaxws/logsになります。

プロパティについては，「10.1.2　共通定義ファイルの設定項目」を参照してください。

ファイル名の「?」は面数を表します。

(4)　J2EEサーバ上のWebリソース，およびWebリソースクライアントを利用する場合

J2EEサーバ上で動作するWebリソース，およびWebリソースクライアント（サーブレットやEJBなど）のログの出力先を次の表に示します。

表39‒7　ログの出力先（J2EEサーバ上で動作するWebリソースやWebリソースクライアントの場合）

項番

ログの種類

出力先ディレクトリ

ファイル名

1

稼働ログ

<ejb.server.log.directory>/CJR

ラウンドアップ方式の場合

cjrmessage?.log

シフト方式の場合

カレントログファイル：

cjrmessage.log

バックアップファイル：

cjrmessage?.log

2

例外ログ

<ejb.server.log.directory>/CJR

cjrexception?_?.log

3

保守ログ

<ejb.server.log.directory>/CJR/maintenance

ラウンドアップ方式の場合

cjrmessage?.log

シフト方式の場合

カレントログファイル：

cjrmessage.log

バックアップファイル：

cjrmessage?.log

4

通信ログ

<ejb.server.log.directory>/CJR

cjrtransport?_?.log

注意事項

<ejb.server.log.directory>は，J2EEサーバのログの出力先になります。詳細については，マニュアル「アプリケーションサーバ 機能解説 保守／移行編」の「3.3.6　J2EEサーバのログ取得の設定」を参照してください。

ファイル名の「?」は面数を表します。

ログ初期化処理前に問題が発生した場合は，Component Containerの稼働ログ（cjrmessage?.log）にログが出力されます。

カレントログファイルとは，出力先のログファイルを示します。

バックアップファイルとは，ローテーションによってバックアップされるログファイルを示します。

(5)　コマンドラインインタフェースでWebリソースクライアントを利用する場合

Javaアプリケーションの開始コマンド（cjclstartap）で，Webリソースクライアントを起動する場合のログの出力先を次の表に示します。

表39‒8　ログの出力先（コマンドラインインタフェースでWebリソースクライアントを利用する場合）

項番

ログの種類

出力先ディレクトリ

ファイル名

1

稼働ログ

<ejbserver.client.log.directory>/

<ejbserver.client.ejb.log>/

<ejbserver.client.log.appid>/CJR

cjrmessage?.log

2

例外ログ

<ejbserver.client.log.directory>/

<ejbserver.client.ejb.log>/

<ejbserver.client.log.appid>/CJR

cjrexception?_?.log

3

保守ログ

<ejbserver.client.log.directory>/

<ejbserver.client.ejb.log>/

<ejbserver.client.log.appid>/CJR/maintenance

cjrmessage?.log

4

通信ログ

<ejbserver.client.log.directory>/

<ejbserver.client.ejb.log>/

<ejbserver.client.log.appid>/CJR

cjrtransport?_?.log

注意事項

<ejbserver.client.log.directory>，<ejbserver.client.ejb.log>，および<ejbserver.client.log.appid>は，EJBクライアントアプリケーションのシステムログの出力先になります。詳細については，マニュアル「アプリケーションサーバ機能解説 保守／移行編」の「4.5.2　EJBクライアントアプリケーションのシステムログの出力先」を参照してください。

ファイル名の「?」は面数を表します。

ログ初期化処理前に問題が発生した場合は，Component Containerの稼働ログ（cjclmessage?.log）にログが出力されます。

39.3.4　ログの重要度と出力条件

ログの重要度，および出力条件について説明します。

(1)　ログの重要度

ログの重要度，およびメッセージの出力内容を次の表に示します。

表39‒9　重要度の意味と出力内容

項番

重要度

メッセージの意味

メッセージ出力内容

1

ERROR

重大な障害を示すメッセージレベルです。

問題が発生して，処理が継続できなかった場合に出力されます。

処理を継続するには，対処が必要です。

メッセージIDのインジケータから，-Eのメッセージが出力されます。メッセージには，発生した例外などの障害情報および対処方法が出力されます。

2

WARN

潜在的な問題を示すメッセージレベルです。

問題が発生していても，処理が継続できる場合に出力されます。

早急な対処は必要ありませんが，対処することが望ましい潜在的な問題があります。

メッセージIDのインジケータから，-Wのメッセージが出力されます。メッセージには，発生した例外などの障害情報および対処の内容が出力されます。

（例）

定義が誤りなので，デフォルトの値を使用した。

3

INFO

情報を提供するメッセージレベルです。

対処は必要ありませんが，通知する必要がある情報が出力されます。

メッセージIDのインジケータが，-Iのメッセージを出力します。メッセージには通知する内容が出力されます。

（例）

コマンドの処理が開始した。

4

DEBUG

DEBUGレベルのメッセージです。

障害の要因調査で使用する情報です。

メッセージIDがKDJW99999-I（Webサービスの場合）またはKDJJ99999-I（Webリソースの場合）のメッセージが出力されます。

（例）

実行時の環境，メソッドトレースなど。

設定ファイルにログレベルの定義をした場合，出力されるログの重要度については，「39.3.6　ログの設定方法」を参照してください。

(2)　稼働ログ／例外ログ／保守ログの出力条件

稼働ログ，例外ログ，および保守ログは，動作定義ファイルに設定したログの定義によって出力内容が変更されます。

稼働ログ，例外ログ，および保守ログの出力条件を次の表に示します。

表39‒10　稼働ログ／例外ログ／保守ログの出力条件（イベントの重要度）

ログの種類

ログの定義

発生したイベントの重要度

ERROR

WARN

INFO

DEBUG

稼働ログ

例外ログ※

NONE

−

−

−

−

ERROR

○

−

−

−

WARN

○

○

−

−

INFO

○

○

○

−

DEBUG

○

○

○

○

保守ログ

NONE

−

−

−

−

ALL

○

○

○

○

（凡例）

○：ログが出力されます。

−：ログが出力されません。

注※

例外ログは例外情報がない場合は出力されません。なお，例外情報とは，イベントを発生する原因となった例外のスタックトレースを指します。

ログの定義のデフォルト設定は，稼働ログと例外ログの出力レベルが「INFO」，保守ログの出力レベルが「ALL」です。つまり，デフォルト設定の状態で重要度が「ERROR」のイベントが発生した場合，稼働ログ，保守ログ，および例外ログのすべてにログが出力されます。

出力される稼働ログおよび例外ログの量は，ログの定義をNONE，ERROR，WARN，INFO，DEBUGへと変更するごとに増加する可能性が高くなります。より多くのログが出力されるようにログの定義を変更することを，出力レベルを上げると呼びます。ログの量が増加すると，全体の処理速度が低下するおそれがあるので，出力レベルを上げる場合は，処理速度や面数の見積もりに注意してください。

(3)　通信ログの出力条件

通信ログは，動作定義ファイルに設定したログの定義によって出力内容が変更されます。ただし，Webサービスクライアント，Webサービス，Webリソースクライアント，またはWebリソースによって，設定するプロパティが異なります。設定するプロパティを次に示します。

com.cosminexus.jaxws.logger.runtime.transport.client_dump（Webサービスクライアント側）

com.cosminexus.jaxws.logger.runtime.transport.server_dump（Webサービス側）

com.cosminexus.jaxrs.logger.runtime.transport.client.level（Webリソースクライアント側）

com.cosminexus.jaxrs.logger.runtime.transport.server.level（Webリソース側）

通信ログの定義，および出力内容を次の表に示します。

表39‒11　通信ログの出力条件（Webサービスクライアント側またはWebリソースクライアント側）

ログの定義

出力内容

ALL

送受信メッセージが常に出力されます。

HEADER

受信メッセージのHTTPヘッダが常に出力されます。

ERROR_HEADER

受信メッセージのHTTPヘッダがエラーのときだけ出力されます。

NONE

送受信メッセージは出力されません。

表39‒12　通信ログの出力条件（Webサービス側またはWebリソース側）

ログの定義

出力内容

ALL

WebサービスまたはWebリソースの送受信メッセージが常に出力されます。受信時は，HTTPのリクエスト情報も出力されます。

HEADER

受信メッセージのHTTPヘッダおよびHTTPのリクエスト情報が常に出力されます。

ERROR_HEADER

受信メッセージのHTTPヘッダおよびHTTPのリクエスト情報がエラーのときだけ出力されます（Webサービスの場合に設定できます）。

NONE

WebサービスまたはWebリソースの送受信メッセージは出力されません。

通信ログの量は，ログの定義がNONE，ERROR_HEADER，HEADER，ALLの順に増加します。ログの量が増加すると，全体の処理速度が低下するおそれがあるので，ログの定義のデフォルト設定を変更する場合は，処理速度や面数の見積もりに注意してください。

39.3.5　ログのフォーマット

稼働ログ，保守ログ，例外ログおよび通信ログのフォーマットについて説明します。

(1)　稼働ログと保守ログのフォーマット

稼働ログおよび保守ログの出力項目と出力内容を次の表に示します。

表39‒13　稼働ログと保守ログのフォーマット

項目

出力内容

番号

トレースコードの通番（4桁）です。0000から始まり，9999まで行くと，0000に戻ります。

日付

出力時の日付（yyyy/mm/dd形式）

時刻

出力時の時刻（hh:mm:ss.nnn形式）

アプリケーション名

WebサービスおよびWebサービスクライアントの場合：「cjw」

cjwsimportコマンドの場合：「cjwsimport」

WS-RM 1.2機能の場合：「wsrm」

WebリソースおよびWebリソースクライアントの場合：「cjr」

プロセス識別子

プロセス識別子（16進数）

スレッド識別子

スレッド識別子（16進数）

メッセージID

メッセージID

メッセージ種別

メッセージ種別

ER：エラーメッセージを表示したことを表します。

EC：例外をキャッチしたことを表します。

なし：上記以外のトレース情報を表します。

メッセージテキスト

メッセージの本体

CRLF

レコード終端記号

(2)　例外ログと通信ログのフォーマット

例外ログと通信ログの出力項目と出力内容を次の表に示します。

表39‒14　例外ログと通信ログのフォーマット

項目

出力内容

日付

出力時の日付（yyyy/mm/dd形式）

時刻

出力時の時刻（hh:mm:ss形式）

Sourceクラス名

ログを発行したクラス名

レベル

ログの重要度

メッセージ

メッセージの本体

JAX-WS機能の通信ログの出力例を次に示します。

2008/10/14 13:09:44 com.cosminexus.xml.ws.transport.http.client.HttpTransportPipe process
情報: KDJW30011-I http client message
---[HTTP request]---
SOAPAction: ""
Content-Type: text/xml;charset="utf-8"
X-hitachi-rootAp: MTgxNDczMTYyLzE2ODgvMC84MDI=
X-hitachi-clientAp: MTgxNDczMTYyLzE2ODgvMC84MDI=
Accept: text/xml, multipart/related, text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
<?xml version="1.0" ?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><ns2:jaxWsTest1 xmlns:ns2="http://example.com/sample"><information>Invocation test.</information><count>1003</count></ns2:jaxWsTest1></S:Body></S:Envelope>
2008/10/14 13:09:45 com.cosminexus.xml.ws.transport.http.client.HttpTransportPipe process
情報: KDJW30012-I http client message
---[HTTP response 200]---
HTTP/1.1 200 OK
Keep-alive: timeout=3, max=100
Date: Tue, 14 Oct 2008 04:09:44 GMT
Content-type: text/xml;charset=utf-8
Connection: Keep-Alive
Transfer-encoding: chunked
Server: Cosminexus HTTP Server
<?xml version="1.0" ?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><ns2:jaxWsTest1Response xmlns:ns2="http://example.com/sample"><return>We've got your #1003 message &quot;Invocation test.&quot;! It's 2008.10.14 13:09:45 now. See ya!</return></ns2:jaxWsTest1Response></S:Body></S:Envelope>

JAX-RS機能の通信ログの出力例を次に示します。

サーバ側

Sep 10, 2011 7:57:48 PM com.cosminexus.jersey.api.container.filter.LoggingFilter filter
INFO: KDJJ30013-I 1 * Server in-bound request
1 > POST http://sample.com/example/root/path%20value;matrix=matrix%20value?query=query%20value
1 > user-agent: Java/1.5.0_11
1 > host: sample.com
1 > accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
1 > connection: keep-alive
1 > content-type: application/x-www-form-urlencoded
1 > content-length: 19
1 >
form=form%2520value

Sep 10, 2011 7:57:48 PM com.cosminexus.jersey.api.container.filter.LoggingFilter$Adapter finish
INFO: KDJJ30015-I 1 * Server out-bound response
1 < 200
1 < Content-Type: text/html
1 <
matrix%20value path%20value form%20value query%20value

クライアント側

Aug 27, 2012 10:30:06 AM com.cosminexus.jersey.api.client.filter.LoggingFilter printRequest
INFO: KDJJ30026-I 1 * Client out-bound request
1 > POST http://sample.com/example
1 > Content-Type: text/plain
1 >
requestEntity

Aug 27, 2012 10:30:06 AM com.cosminexus.jersey.api.client.filter.LoggingFilter printResponse
INFO: KDJJ30027-I 1 * Client in-bound response
1 < 200
1 < Content-Type: text/html
1 <
responseEntity

JAX-RS機能の場合，動作定義ファイルにプロパティを設定していなくても，次に示すサーブレット初期化パラメタと値をweb.xmlに含めることで，Webリソースを含むWebアプリケーションごとに，通信ログを出力するかどうかを設定できます。

項番

サーブレット初期化パラメタ

値

動作

1

com.sun.jersey.spi.container.ContainerRequestFilters

com.cosminexus.jersey.api.container.filter.LoggingFilter

HTTPリクエストの情報が通信ログに出力されます。

2

com.sun.jersey.spi.container.ContainerResponseFilters

com.cosminexus.jersey.api.container.filter.LoggingFilter

HTTPレスポンスの情報が通信ログに出力されます。

注

この値以外を指定した場合，設定は無視されます。

動作定義ファイルにプロパティを設定している場合，Webリソースを含むWebアプリケーションごとに，通信ログを出力するかどうかを設定することはできません。

エンティティの情報の出力を抑止するかどうかも，Webリソースを含むWebアプリケーションごとに設定できます。サーブレット初期化パラメタと値を次に示します。

項番

サーブレット初期化パラメタ

値

動作

1

com.sun.jersey.config.feature.logging.DisableEntitylogging

true

エンティティの情報が通信ログに出力されません。

false

エンティティの情報が通信ログに出力されます。

注

trueまたはfalse以外の値を指定した場合，共通定義ファイル（cjrconf.properties）で取得したプロパティの値が使用されて，エンティティの情報が通信ログに出力されます。なお，web.xmlで指定した値は無視されます。

(3)　通信ログの文字エンコーディング

SOAPメッセージ（Webサービスの場合）やHTTPメッセージ（Webリソースの場合）の文字エンコーディングとは関係なく，通信ログには次に示す動作定義ファイルのプロパティで指定した文字エンコーディングが適用されます。デフォルトは，プラットフォーム依存のエンコーディングです。

com.cosminexus.jaxws.logger.runtime.transport.encodingプロパティ（Webサービスの場合）

com.cosminexus.jaxrs.logger.runtime.transport.encodingプロパティ（Webリソースの場合）

メッセージの文字エンコーディングと通信ログの文字エンコーディングが異なる場合，組み合わせによっては通信ログ内の一部の文字が不正になるおそれがあります。例えば，メッセージの文字エンコーディングがUTF-8，通信ログの文字エンコーディングがMS932の場合，メッセージ内にMS932に存在しない文字が含まれていると，その文字は通信ログ内で不正となります。そのため，WebサービスまたはWebリソース開発時には，使用できる文字コードまたは文字セットを規定して，WebサービスクライアントまたはWebリソースクライアントの開発者に通知することをお勧めします。

また，使用する機能によっても次の注意事項があります。

添付ファイル（wsi:swaRef形式，およびMTOM/XOP仕様形式）を送受信する場合，添付ファイルにはバイナリデータが含まれたり，異なる文字エンコーディング形式の文字列が含まれたりするため，ルートパートのSOAPエンベロープも含めて，通信ログの文字が不正になるおそれがあります。

(4)　通信ログに出力されるHTTPヘッダ名

通信ログに出力されるHTTPヘッダ名は，実際に送受信されるHTTPメッセージ（SOAPメッセージを含むHTTPメッセージ）に関係なく，常に先頭文字だけが大文字になります。

例）Content-type

39.3.6　ログの設定方法

出力レベル，サイズ，および面数を動作定義ファイルで指定します。

JAX-WS機能の動作定義ファイルの設定例を次に示します。

com.cosminexus.jaxws.logger.runtime.message.level=INFO
com.cosminexus.jaxws.logger.runtime.message.file_num=2
com.cosminexus.jaxws.logger.runtime.message.file_size=2097152

com.cosminexus.jaxws.logger.runtime.maintenance.level=ALL
com.cosminexus.jaxws.logger.runtime.maintenance.file_num=2
com.cosminexus.jaxws.logger.runtime.maintenance.file_size=16777216

com.cosminexus.jaxws.logger.runtime.exception.level=INFO
com.cosminexus.jaxws.logger.runtime.exception.file_num=2
com.cosminexus.jaxws.logger.runtime.exception.file_size=16777216

com.cosminexus.jaxws.logger.runtime.transport.client_dump=NONE
com.cosminexus.jaxws.logger.runtime.transport.server_dump=NONE
com.cosminexus.jaxws.logger.runtime.transport.file_num=2
com.cosminexus.jaxws.logger.runtime.transport.file_size=16777216
com.cosminexus.jaxws.logger.runtime.transport.encoding=DEFAULT

com.cosminexus.jaxws.logger.cjwsimport.message.level=INFO
com.cosminexus.jaxws.logger.cjwsimport.message.file_num=2
com.cosminexus.jaxws.logger.cjwsimport.message.file_size=2097152

com.cosminexus.jaxws.logger.cjwsimport.exception.level=INFO
com.cosminexus.jaxws.logger.cjwsimport.exception.file_num=2
com.cosminexus.jaxws.logger.cjwsimport.exception.file_size=16777216

com.cosminexus.jaxws.logger.cjwsimport.maintenance.level=ALL
com.cosminexus.jaxws.logger.cjwsimport.maintenance.file_num=2
com.cosminexus.jaxws.logger.cjwsimport.maintenance.file_size=16777216

JAX-RS機能の動作定義ファイルの設定例を次に示します。

com.cosminexus.jaxrs.logger.runtime.message.level=INFO
com.cosminexus.jaxrs.logger.runtime.message.file_num=2
com.cosminexus.jaxrs.logger.runtime.message.file_size=2097152

com.cosminexus.jaxrs.logger.runtime.maintenance.level=ALL
com.cosminexus.jaxrs.logger.runtime.maintenance.file_num=2
com.cosminexus.jaxrs.logger.runtime.maintenance.file_size=16777216

com.cosminexus.jaxrs.logger.runtime.exception.level=INFO
com.cosminexus.jaxrs.logger.runtime.exception.file_num=2
com.cosminexus.jaxrs.logger.runtime.exception.file_size=16777216

com.cosminexus.jaxrs.logger.runtime.transport.server.level=NONE
com.cosminexus.jaxrs.logger.runtime.transport.client.level=NONE
com.cosminexus.jaxrs.logger.runtime.transport.file_num=2
com.cosminexus.jaxrs.logger.runtime.transport.file_size=16777216
com.cosminexus.jaxrs.logger.runtime.transport.encoding=DEFAULT

39.3.7　ログの見積もり

各ログファイルの見積もり方法について説明します。

(1)　使用するモデルおよびログの設定

ログの見積もり方法は，次に示すモデル1およびモデル2を例に説明します。

モデル1：正常系

WebサービスクライアントまたはWebリソースクライアントからリクエストを送信し，WebサービスまたはWebリソースが正常にレスポンスを返す場合のモデルです。

モデル2：異常系

WebサービスまたはWebリソースでRuntimeExceptionが発生する場合のモデルです。WebリソースにはRuntimeExceptionを処理できる例外マッピングプロバイダが存在しないものとします。

WebサービスクライアントまたはWebリソースクライアントでは，オブジェクトの再利用を前提にしています。オブジェクトの再利用については，「3.6.4　注意事項」または「11.4.5　注意事項」を参照してください。

JAX-WS機能の場合，WebサービスクライアントやWebサービスを実装する形態によってさまざまです。必要に応じてモデルを追加してください。主な観点を次に示します。

Webサービス実装クラスやプロバイダ実装クラスおよびスタブベースのWebサービスクライアントやディスパッチベースのWebサービスクライアントのバリエーション。

SOAP 1.1仕様およびSOAP 1.2仕様のSOAPメッセージのバリエーション。

wsi:swaRef形式およびMTOM/XOP仕様形式の添付ファイルのSOAPメッセージのバリエーション。

JAX-RS機能の場合，JAX-RS仕様の性質上HTTPリクエストやHTTPレスポンスを送受信する方法は，WebリソースクライアントやWebリソースを実装する形態によってさまざまです。必要に応じてモデルを追加してください。主な観点を次に示します。

リソースメソッドのエンティティパラメタ，その他のパラメタ，および戻り値の型や要求メソッド識別子のバリエーション。

例外マッピングプロバイダの有無および例外マッピングプロバイダが処理できる例外のバリエーション。

Pathアノテーションの使用方法によるバリエーション。

このモデルで使用するログの設定を示します。

稼働ログ，例外ログ，および保守ログの設定は，デフォルト値のまま変更しません。

通信ログの設定は，次のプロパティにそれぞれ「ALL」を指定します。

JAX-WS機能の場合

com.cosminexus.jaxws.logger.runtime.transport.client_dump

com.cosminexus.jaxws.logger.runtime.transport.server_dump

JAX-RS機能の場合

com.cosminexus.jaxrs.logger.runtime.transport.client.level

com.cosminexus.jaxrs.logger.runtime.transport.server.level

ログの設定値およびデフォルト値については，「10.1.2　共通定義ファイルの設定項目」または「13.1.2　共通定義ファイルの設定項目」を参照してください。

(2)　JAX-WS機能のログの見積もり方法

モデル1およびモデル2の各ログの出力結果を次の表に示します。

次の表にある「起動時」とはアプリケーション開始時，「終了時」とはアプリケーション停止時，「1リクエスト処理時」とはWebサービスによる1リクエストの処理を表します。出力量はこれらの期間に出力されるログの量を示します。

表39‒15　起動時，1リクエスト処理時，停止時の各ログの出力例（モデル1／モデル2）

項番

ログの種類

出力量

起動時

1リクエスト処理時

終了時

1

稼働ログ

0.7KB

モデル1：0.0KB

モデル2：0.3KB

0.3KB

2

例外ログ

0KB

モデル1：0KB

モデル2※：5KB

0KB

3

通信ログ

0KB

0.3KB＋HTTPリクエスト＋HTTPレスポンス量

0KB

4

保守ログ

2.4KB

モデル1：3.2KB

モデル2：3.6KB

0.4KB

注※

例外のスタックトレースの量になります。

各ログの見積もり式を次に示します。この結果を基に，各ログファイル一つのファイルサイズ，およびファイル面数を求めます。

[単位時間当たりのログの出力量] ＝
   [初期化時の出力量]
   ＋[モデル1の1リクエスト処理時の出力量]×総リクエスト数×モデル1のリクエストの割合
   ＋[モデル2の1リクエスト処理時の出力量]×総リクエスト数×モデル2のリクエストの割合
        :
   ＋[モデルnの1リクエスト処理時の出力量]×総リクエスト数×モデルnのリクエストの割合
   ＋[終了時の出力量]

この式を基に，例を使用して各ファイルの見積もり方法を説明します。

想定する例として，1分間に平均100件のリクエストがあるようなシステムで，ログを3時間ラップアラウンドされないようにログファイルのサイズと個数を見積もるものとします。全リクエスト中，モデル1のリクエストが80%，モデル2のリクエストが20%を占めるとすると，3時間では計18,000リクエスト（100リクエスト／分×180分）が到着します。

この場合，稼働ログの出力量を計算すると，次のとおりになります。

0.7KB（初期化時の出力量）
＋{0KB×18000}（モデル1の全リクエスト処理時の出力量）×0.8（モデル1のリクエストの割合）
＋{0.3KB×18000}（モデル2の全リクエスト処理時の出力量）×0.2（モデル2のリクエストの割合）
＋0.3KB（終了時の出力量）
＝1081KB

計算の結果，ファイルサイズとファイル面数はデフォルト値で間に合います。

同様に，保守ログの出力量を計算すると，次のとおりになります。

2.4KB（初期化時の出力量）
＋{3.2KB×18000}（モデル1の全リクエスト処理時の出力量）×0.8（モデル1のリクエストの割合）
＋{3.6KB×18000}（モデル2の全リクエスト処理時の出力量）×0.2（モデル2のリクエストの割合）
＋0.4KB（終了時の出力量）
＝59043KB≒57.6MB

計算の結果，ログファイル一つ当たり15MBとすると，面数は四つとなります。

注意事項

通信ログでは，HTTPリクエストやHTTPレスポンスの内容によって，出力量が変化します。添付ファイルを使用して通信する場合は，通信ログにも添付ファイルの内容が記録されるため，特に大きな添付ファイルを使用しているときは，通信ログファイルのサイズや面数を考慮する必要があります。

(3)　JAX-RS機能のログの見積もり方法

モデル1およびモデル2の各ログの出力結果を次の表に示します。

次の表にある「起動時」とはアプリケーション開始時，「終了時」とはアプリケーション停止時，「1リクエスト処理時」とはWebリソースによる1リクエストの処理を表します。出力量はこれらの期間に出力されるログの量を示します。

表39‒16　起動時，1リクエスト処理時，停止時の各ログの出力例（モデル1／モデル2）

項番

ログの種類

出力量

起動時

1リクエスト処理時

終了時

1

稼働ログ

1KB

モデル1：0KB

モデル2：0.3KB

0KB

2

例外ログ

0KB

モデル1：0KB

モデル2※：1.1KB

0KB

3

通信ログ

0KB

0.3KB＋HTTPリクエスト＋HTTPレスポンス量

0KB

4

保守ログ

23KB

モデル1：0KB

モデル2：0.3KB

0KB

注※

例外のスタックトレースの量になります。

各ログの見積もり式を次に示します。この結果を基に，各ログファイル一つのファイルサイズ，およびファイル面数を求めます。

[単位時間当たりのログの出力量] ＝
   [起動時の出力量]
   ＋[モデル1の1リクエスト処理時の出力量]×総リクエスト数×モデル1のリクエストの割合
   ＋[モデル2の1リクエスト処理時の出力量]×総リクエスト数×モデル2のリクエストの割合
        :
   ＋[モデルnの1リクエスト処理時の出力量]×総リクエスト数×モデルnのリクエストの割合
   ＋[終了時の出力量]

この式を基に，例を使用して各ファイルの見積もり方法を説明します。

想定する例として，1分間に平均100件のリクエストがあるようなシステムで，ログを3時間ラップアラウンドされないようにログファイルのサイズと個数を見積もるものとします。全リクエスト中，モデル1のリクエストが80%，モデル2のリクエストが20%を占めるとすると，3時間では計18,000リクエスト（100リクエスト／分×180分）が到着します。

この場合，稼働ログの出力量を計算すると，次のとおりになります。

1KB（初期化時の出力量）
＋{0KB×18000}（モデル1の1リクエスト処理時の出力量）×0.8（モデル1のリクエストの割合）
＋{0.3KB×18000}（モデル2の全リクエスト処理時の出力量）×0.2（モデル2のリクエストの割合）
＋0KB（終了時の出力量）
＝1081KB

計算の結果，ファイルサイズとファイル面数はデフォルト値で間に合います。

同様に，保守ログの出力量を計算すると，次のとおりになります。

23KB(初期化時の出力量)
＋{0KB×18000}（モデル1の1リクエスト処理時の出力量）×0.8（モデル1のリクエストの割合）
＋{0.3KB×18000}（モデル2の全リクエスト処理時の出力量）×0.2（モデル2のリクエストの割合）
＋0KB（終了時の出力量）
＝1103KB

計算の結果，ファイルサイズとファイル面数はデフォルト値で間に合います。

注意事項

通信ログでは，HTTPリクエストやHTTPレスポンスの内容によって，出力量が変化します。JSON形式のデータを使用して通信する場合は，通信ログにもJSON形式のデータが記録されるため，特に大きなJSON形式のデータを使用しているときは，通信ログファイルのサイズや面数を考慮する必要があります。

39.4　性能解析トレース（PRF）

性能解析トレースとは，性能解析や障害を調査するためのトレース情報を指します。性能解析トレースを参照することで，システムの性能ボトルネックや，障害が発生した場合の，リクエスト処理の到達度合いを解析できます。

アプリケーションサーバが提供する性能解析トレースについては，マニュアル「アプリケーションサーバ 機能解説 保守／移行編」の「4.6　性能解析トレース」を参照してください。

39.4.1　性能解析トレースの取得レベル

Application ServerのJAX-WS機能またはJAX-RS機能で使用できる性能解析トレースの取得レベルを次の表に示します。

表39‒17　性能解析トレースの取得レベル一覧

項番

取得レベル

目的

1

標準レベル

（デフォルト）

Application ServerのJAX-WS機能またはJAX-RS機能とその他の機能との境界（入口と出口）が識別できるトレース情報が出力されます。

2

詳細レベル

標準レベルの出力内容に加えて，Application ServerのJAX-WS機能またはJAX-RS機能の内部処理のトレース情報が出力されます。

3

保守レベル

障害発生時などに保守情報を取得するためのレベルで，通常は使用しません。

39.4.2　性能解析トレースのトレース出力情報

Application ServerのJAX-WS機能またはJAX-RS機能で出力する性能解析トレースのトレース出力情報を次の表に示します。

表39‒18　性能解析トレースのトレース出力情報

項番

ファイル項目

内容

1

イベントID

トレース取得ポイントのイベントIDです。

2

クライアントアプリケーション情報

ルートアプリケーション情報の有効範囲内のWebサービスクライアント，Webサービス間で一意の情報です。ただし，WS-RM 1.2機能の場合，一意ではありません。オプション情報を参照してください。

3

ルートアプリケーション情報

一連のリクエストに対する処理で，一意の情報です。ただし，WS-RM 1.2機能の場合，一意ではありません。オプション情報を参照してください。

4

リターンコード

トレース取得ポイントの種別（正常終了または異常終了）です。

5

インタフェース名

トレース取得ポイントのクラス名です。

6

オペレーション名

トレース取得ポイントのメソッド名です。

7

オプション情報

オプション情報です。

ここでは，クライアントアプリケーション情報とルートアプリケーション情報の有効範囲，およびトレース取得ポイントについて説明します。

(1)　クライアントアプリケーション情報とルートアプリケーション情報の有効範囲

クライアントアプリケーション情報とルートアプリケーション情報の有効範囲を，Webサービスの場合およびWebリソースの場合に分けて説明します。

(a)　Webサービスの場合

次の図を基に，Webサービスの場合のクライアントアプリケーション情報とルートアプリケーション情報の有効範囲について説明します。

図39‒5　クライアントアプリケーション情報とルートアプリケーション情報の有効範囲（Webサービスの場合）

ルートアプリケーション情報（通信番号，プロセスID，およびIPアドレスから構成されます）は，一連のリクエストに対する処理で一意となります。

Javaアプリケーションの開始コマンド（cjclstartap）で開始したWebサービスクライアント（A）からWebサービス（B）にリクエストが送信されると，Webサービス（B）がWebサービスクライアントになります。さらに，Webサービス（B）がWebサービスクライアントになって，ほかのWebサービス（C）および（D）にリクエストが送信されると，AからDまでが一意の値となります。

クライアントアプリケーション情報（通信番号，プロセスID，およびIPアドレスから構成されます）は，ルートアプリケーション情報の有効範囲内のWebサービスクライアント，およびWebサービスの一連のリクエストに対する処理で一意となります。

クライアントアプリケーション情報（1）〜（4）は，異なるクライアントアプリケーション情報になります。

(b)　Webリソースの場合

次の図を基に，Webリソースの場合のクライアントアプリケーション情報とルートアプリケーション情報の有効範囲について説明します。

図39‒6　クライアントアプリケーション情報とルートアプリケーション情報の有効範囲（Webリソースの場合）

この図では，Webリソースクライアント（A）とWebリソース／Webリソースクライアント（B）はRESTful Webサービス用クライアントAPIを使用しています。Webリソース／Webリソースクライアント（B），Webリソース（C）およびWebリソース（D）はJAX-RSエンジンで動作しているWebリソースです。

ルートアプリケーション情報は，クライアントがRESTful Webサービス用クライアントAPIを呼び出してから，呼び出し結果のHTTPレスポンスを受けるまでの一連のリクエストに対する処理で一意となります。

一方，クライアントアプリケーション情報はそれぞれの呼び出しにおいて一意となります。図中のクライアントアプリケーション情報（1）〜（5）は，それぞれ異なる一意の値を持っています。

クライアントが，次のどちらかの操作によって返されるClientResponseオブジェクトから，それぞれ操作とは連続しないでHTTPレスポンスのエンティティを取り出した場合でも，ルートアプリケーション情報およびクライアントアプリケーション情報は，一連の呼び出しにおいて一意となります。

Clientクラスのhandleメソッド

WebResourceクラスまたはWebResource.Builderクラスのmethodメソッド，またはHTTPメソッドに対応する各メソッド

イメージを次の図で説明します。なお，図中ではクライアントアプリケーション情報の範囲がルートアプリケーション情報の範囲と同じなので，クライアントアプリケーション情報は省略しています。

図39‒7　連続しない呼び出しとアプリケーション情報

この場合，WebResourceクラスのget(Class)メソッドとClientResponseクラスのgetEntity(Class)メソッドの連続しない呼び出しでのルートアプリケーション情報（図中の「ルートアプリケーション情報（2）」）は，HTTP通信の接続から要求・応答まで一度に実行されるWebResourceクラスのpost(Class, Object)メソッドのルートアプリケーション情報（図中の「ルートアプリケーション情報（1）」）と同様に一意です。

また，Clientクラスのhandle(Class)メソッドとClientResponseクラスのgetEntity(Class)メソッドの連続しない呼び出しでのルートアプリケーション情報（図中の「ルートアプリケーション情報（3）」）も一意です。

(2)　性能解析トレースのトレース取得ポイント

Application ServerのJAX-WS機能で出力する性能解析トレースのトレース取得ポイントを次の図に示します。なお，WS-RM 1.2機能を使用する場合は，ここに記載する以外の性能解析トレースも出力されます。詳細については，「39.4.2(2)(c)　WS-RM 1.2機能使用時のトレース取得ポイント」を参照してください。

(a)　POJOのWebサービス呼び出し時のトレース取得ポイント

POJOのWebサービス呼び出し時のトレース取得ポイントについて，request-responseオペレーションの場合を図39-8に，one-wayオペレーションの場合を図39-9に示します。ただし，one-wayオペレーションでプロバイダ実装クラスがnullを返すときの，トレース取得ポイントについては，図39-8を参照してください。

図39‒8　POJOのWebサービス呼び出し時のトレース取得ポイント（request-responseオペレーション）

図39‒9　POJOのWebサービス呼び出し時のトレース取得ポイント（one-wayオペレーション）

各トレース取得ポイントとイベントIDの対応を次の表に示します。

表39‒19　標準レベルでのトレース取得ポイントと出力される情報（JAX-WS機能・POJOのWebサービス）

図中の番号

取得ポイント

出力される情報

イベントID

オプション情報

1

Webサービスクライアントライブラリの開始時

スタブベースの場合

0xA400

−

ディスパッチベースの場合

0xA420

2

WebサービスクライアントライブラリのHTTPメッセージ送信前

0xA404

エンドポイントURL

3

JAX-WSエンジンのサーブレット開始時

0xA408

コンテキストルート

4

Webサービス呼び出し前

Webサービス実装クラスの場合

0xA40C

サービスメソッド名

プロバイダ実装クラスの場合

0xA424

−

5

Webサービス呼び出し後

Webサービス実装クラスの場合

0xA410

異常終了の場合は例外名

プロバイダ実装クラスの場合

0xA428

6

JAX-WSエンジンのHTTPメッセージ送信前

0xA414※

−

7

WebサービスクライアントライブラリのHTTPメッセージ受信後

0xA418

異常終了の場合は例外名

8

Webサービスクライアントライブラリ終了時

スタブベースの場合

0xA41C

異常終了の場合は例外名

ディスパッチベースの場合

0xA42C

（凡例）

−：オプション情報はありません。

注※

Webサービス呼び出し後にプロバイダ実装クラスがnullを返した場合，トレースを取得しません。

表39‒20　詳細レベルでのトレース取得ポイントと出力される情報（JAX-WS機能・POJOのWebサービス）

図中の番号

取得ポイント

出力される情報

イベントID

オプション情報

9

ハンドラ呼び出し前

0xA430※

ハンドラの位置とハンドラクラス名

10

ハンドラ呼び出し後

0xA434※

異常終了の場合は例外名

11

WebサービスクライアントライブラリのHTTPメッセージ送信後

0xA438

異常終了の場合は例外名

12

アンマーシャル前

スタブべース，およびWebサービス実装クラスの場合

0xA43C

−

ディスパッチベース，およびプロバイダ実装クラスの場合

0xA450※

13

アンマーシャル後

スタブべース，およびWebサービス実装クラスの場合

0xA440

−

ディスパッチベース，およびプロバイダ実装クラスの場合

0xA454※

14

JAX-WSエンジンのHTTPメッセージ送信後

0xA444※

異常終了の場合は例外名

15

JAX-WSエンジンのサーブレット終了時

0xA448

異常終了の場合は例外名

（凡例）

−：オプション情報はありません。

注※

Webサービス呼び出し後にプロバイダ実装クラスがnullを返した場合，トレースを取得しません。

(b)　EJBのWebサービス呼び出し時のトレース取得ポイント

request-responseオペレーションの場合の，EJBのWebサービス呼び出し時のトレース取得ポイントを次の図に示します。なお，Webサービスクライアントのトレース取得ポイントは，POJOのWebサービス呼び出し時と同じです。また，one-wayオペレーションの場合の，Webサービスにおけるトレース取得ポイントについては，「図39-9　POJOのWebサービス呼び出し時のトレース取得ポイント（one-wayオペレーション）」の「サービスの呼び出し」を「EJBコンテナの呼び出し」に読み替えてください。

図39‒10　EJBのWebサービス呼び出し時のトレース取得ポイント（request-responseオペレーション）

各トレース取得ポイントとイベントIDの対応を次の表に示します。

表39‒21　標準レベルでのトレース取得ポイントと出力される情報（JAX-WS機能・EJBのWebサービス）

図中の番号

取得ポイント

出力される情報

イベントID

オプション情報

1

JAX-WSエンジンのサーブレット開始時

0xA408

コンテキストルート

2

EJBコンテナ呼び出し前

Webサービス実装クラス

0xA40E

サービスメソッド名

3

EJBのメソッド呼び出し前

0x8482

−

4

EJBのメソッド呼び出し後

0x8483

−

5

EJBコンテナ呼び出し後

Webサービス実装クラス

0xA412

異常終了の場合は例外名

6

JAX-WSエンジンのHTTPメッセージ送信前

0xA414

異常終了の場合は例外名

（凡例）

−：オプション情報はありません。

表39‒22　詳細レベルでのトレース取得ポイントと出力される情報（JAX-WS機能・EJBのWebサービス）

図中の番号

取得ポイント

出力される情報

イベントID

オプション情報

7

ハンドラ呼び出し前

0xA430

ハンドラの位置とハンドラクラス名

8

ハンドラ呼び出し後

0xA434

異常終了の場合は例外名

9

アンマーシャル前

Webサービス実装クラス

0xA43C

−

10

アンマーシャル後

Webサービス実装クラス

0xA440

−

11

JAX-WSエンジンのHTTPメッセージ送信後

0xA444

異常終了の場合は例外名

12

JAX-WSエンジンのサーブレット終了時

0xA448

異常終了の場合は例外名

（凡例）

−：オプション情報はありません。

(c)　WS-RM 1.2機能使用時のトレース取得ポイント

WS-RM 1.2機能でシーケンスライフサイクルメッセージを送受信するときに出力される性能解析トレースのトレース取得ポイントを次の図に示します。

図39‒11　シーケンスライフサイクルメッセージ送受信時のトレース取得ポイント

各トレース取得ポイントとイベントIDの対応を次の表に示します。

表39‒23　標準レベルでのトレース取得ポイントと出力される情報（WS-RM 1.2機能のライフサイクルメッセージ）

図中の番号

取得ポイント

出力される情報

イベントID

オプション情報

1

Webサービスクライアント側WS-RM 1.2機能開始時

0xA4B0

次のどれかが出力されます。

CreateSequence

CloseSequence,[SequenceID]

TerminateSequence,[SequenceID]

2

Webサービスクライアント側シーケンスライフサイクルメッセージ送信前

0xA4B1

次のどれかが出力されます。

CreateSequence

CloseSequence,[SequenceID]

TerminateSequence,[SequenceID]

3

Webサービス側WS-RM 1.2機能開始時

0xA4B2

次のどれかが出力されます。

CreateSequence

CloseSequence,[SequenceID]

TerminateSequence,[SequenceID]

4

Webサービス側WS-RM 1.2機能終了時

0xA4B3

次のどれかが出力されます。

CreateSequence,[SequenceID]

CloseSequence,[SequenceID]

TerminateSequence,[SequenceID]

異常終了の場合は例外名

5

Webサービスクライアント側シーケンスライフサイクルメッセージ受信後

0xA4B4

次のどれかが出力されます。

CreateSequence

CloseSequence,[SequenceID]

TerminateSequence,[SequenceID]

異常終了の場合は例外名

6

Webサービスクライアント側WS-RM 1.2機能終了時

0xA4B5

次のどれかが出力されます。

CreateSequence,[SequenceID]

CloseSequence,[SequenceID]

TerminateSequence,[SequenceID]

異常終了の場合は例外名

WS-RM 1.2機能のシーケンストラフィックメッセージの性能解析トレースのトレース取得ポイントを次の図に示します。

図39‒12　シーケンストラフィックメッセージのトレース取得ポイント

各トレース取得ポイントとイベントIDの対応を次の表に示します。

表39‒24　標準レベルでのトレース取得ポイントと出力される情報（WS-RM 1.2機能のシーケンストラフィックメッセージ）

図中の番号

取得ポイント

出力される情報

イベントID

オプション情報

7

リクエストでのWebサービスクライアント側WS-RM 1.2機能開始時

0xA4B6

[SequenceID],[MessageNumber]

8

リクエストでのWebサービスクライアント側WS-RM 1.2機能終了時

0xA4B7

次のどちらかが出力されます。

[SequenceID],[MessageNumber]

異常終了の場合は例外名

9

リクエストでのWebサービス側WS-RM 1.2機能開始時

0xA4B8

[SequenceID],[MessageNumber]

10

リクエストでのWebサービス側WS-RM 1.2機能終了時

0xA4B9

次のどちらかが出力されます。

[SequenceID],[MessageNumber]

異常終了の場合は例外名

11

レスポンスでのWebサービス側WS-RM 1.2機能開始時※1

0xA4BA

[SequenceID],[MessageNumber]

12

レスポンスでのWebサービス側WS-RM 1.2機能終了時※2

0xA4BB

次のどちらかが出力されます。

[SequenceID],[MessageNumber]

異常終了の場合は例外名

13

レスポンスでのWebサービスクライアント側WS-RM 1.2機能開始時

0xA4BC

[SequenceID],[MessageNumber]

14

レスポンスでのWebサービスクライアント側WS-RM 1.2機能終了時

0xA4BD

次のどちらかが出力されます。

[SequenceID]

異常終了の場合は例外名

注※1

重複したメッセージを受信した場合は出力されません。

注※2

重複したメッセージを受信した場合に，HTTPステータスコード202を返すときは出力されません。

WS-RM 1.2機能のAckメッセージの性能解析トレースのトレース取得ポイントを次の図に示します。

図39‒13　Ackメッセージのトレース取得ポイント

各トレース取得ポイントとイベントIDの対応を次の表に示します。

表39‒25　詳細レベルでのトレース取得ポイントと出力される情報（WS-RM 1.2機能のAckメッセージ）

図中の番号

取得ポイント

出力される情報

イベントID

オプション情報

15

Webサービスクライアント側WS-RM 1.2機能開始時

0xA4BE

[SequenceID]

16

Webサービス側WS-RM 1.2機能開始時

0xA4C0

[SequenceID]

17

Webサービス側WS-RM 1.2機能終了時

0xA4C1

次のどちらかが出力されます。

[SequenceID]

異常終了の場合は例外名

18

Webサービスクライアント側WS-RM 1.2機能終了時

0xA4BF

次のどちらかが出力されます。

[SequenceID]

異常終了の場合は例外名

(d)　RESTful Webサービス呼び出し時のトレース取得ポイント

RESTful Webサービス（Webサービス）呼び出し時のトレース取得ポイントを，リソース側，クライアント側に分けてそれぞれ次の図に示します。

リソース側

図39‒14　RESTful Webサービス呼び出し時のトレース取得ポイント（リソース側）

各トレース取得ポイントとイベントIDの対応を次の表に示します。

表39‒26　標準レベルでのトレース取得ポイントと出力される情報（JAX-RS機能・RESTful Webサービス）

図中の番号

取得ポイント

出力される情報

イベントID

オプション情報

1

JAX-RSエンジンのサーブレット開始時

0xA4A0

−

2

Webリソース呼び出し前

0xA4A2

次のどれかが出力されます。

JResponseOutInvoker

ObjectOutInvoker

ResponseOutInvoker

TypeOutInvoker

VoidOutInvoker

VoidVoidMethodInvoker

HttpReqResDispatcher

3

アンマーシャル前

0xA4A6

−

4

アンマーシャル後

0xA4A7

例外発生の場合は例外名

5

Webリソース呼び出し後

0xA4A3

次のどれかが出力されます。

JResponseOutInvoker

ObjectOutInvoker

ResponseOutInvoker

TypeOutInvoker

VoidOutInvoker

VoidVoidMethodInvoker

HttpReqResDispatcher

6

マーシャル前

0xA4A8

−

7

マーシャル後

0xA4A9

例外発生の場合は例外名

8

JAX-RSエンジンのHTTPメッセージ送信前

0xA4A1

例外発生の場合は例外名

（凡例）

−：オプション情報はありません。

表39‒27　詳細レベルでのトレース取得ポイントと出力される情報（JAX-RS機能・RESTful Webサービス）

図中の番号

取得ポイント

出力される情報

イベントID

オプション情報

9

HTTPリクエストとリソースのマッチング処理実行時

0xA4AC

次のどれかが出力されます。

accept root resource classes

forwarding view to JSP page

accept implicit view

match path

accept sub-resource methods

accept resource methods

matched sub-resource method

matched resource method

accept resource message in ResourceClassRule

accept resource message in ResourceOjectRule

accept right hand path redirect

accept right hand path

accept sub-resource locator

accept termination

matched message body reader

matched exception mapper

mapped exception to response

matched message body writer

クライアント側

「11.4.1　Webリソースクライアントのユースケース」で説明したユースケースごとに説明します。

図39‒15　RESTful Webサービス呼び出し時のトレース取得ポイント（クライアント側）

各トレース取得ポイントとイベントIDの対応を次の表に示します。

表39‒28　標準レベルでのトレース取得ポイントと出力される情報（JAX-RS機能・RESTful Webサービス用クライアントAPI）

図中の番号

取得ポイント

出力される情報

イベントID

オプション情報

1

HTTPメソッド呼び出しの開始時

0xA4A4

エンドポイントURL

2

マーシャル前

0xA4A8

−

3

マーシャル後

0xA4A9

−

4

HTTPメソッド呼び出しの終了時

0xA4A5

例外発生の場合は例外名

5

アンマーシャル前

0xA4A6

−

6

アンマーシャル後

0xA4A7

例外発生の場合は例外名

（凡例）

−：オプション情報はありません。

39.4.3　性能解析トレースによる性能解析方法

性能解析トレースファイルとは，性能解析トレースをCSV形式で出力したテキストファイルを指します。

(1)　Webサービスの場合

性能解析トレースファイルを使用して，JAX-WSエンジンを含むWebサービス全体のレスポンスタイムと，Webサービス（UP）のレスポンスタイムを解析する方法を説明します。なお，ここではWebサービス実装クラスで開発したWebサービスと，スタブベースのWebサービスクライアントの例を説明します。そのほかの形態のWebサービスおよびWebサービスクライアントの場合はイベントIDが異なることがあるので，必要に応じて読み替えてください。

イベントID「0xA408」，「0xA40C」，「0xA410」，および「0xA414」をキーにして，性能解析トレースファイルをフィルタリングします。各イベントIDに対するトレース取得ポイントを次の表に示します。

表39‒29　フィルタリングするイベントIDに対応するトレース取得ポイント

項番

イベントID

トレース取得ポイント

1

0xA408

JAX-WSエンジンのサーブレット開始時

2

0xA40C

Webサービス呼び出し前

3

0xA410

Webサービス呼び出し後

4

0xA414

JAX-WSエンジンのSOAPメッセージ送信前

リクエストを2回送信した場合に，イベントID「0xA408」，「0xA40C」，「0xA410」および「0xA414」をキーにして，性能解析トレースファイルをフィルタリングした例を次の図に示します。

図39‒16　性能解析トレースをフィルタリングした例

クライアントアプリケーション情報から，リクエストの処理状況を確認できます。同じリクエストを処理している場合，同じクライアントアプリケーション情報が出力されます。

同一クライアントアプリケーション情報の中のイベントID「0xA408」および「0xA414」のトレース取得時刻から，JAX-WSエンジンを含めたWebサービス全体のレスポンスタイムを解析できます。また，「0xA40C」および「0xA410」のトレース取得時刻から，Webサービス（UP）のレスポンスタイムを解析できます。

(2)　Webリソースの場合

性能解析トレースファイルを使用して，JAX-RSエンジンを含むWebリソース全体のレスポンスタイムと，Webリソース（UP）のレスポンスタイムを解析する方法を説明します。

イベントID「0xA4A0」，「0xA4A2」，「0xA4A3」および「0xA4A1」をキーにして，性能解析トレースファイルをフィルタリングします。各イベントIDに対するトレース取得ポイントを次の表に示します。

表39‒30　フィルタリングするイベントIDに対応するトレース取得ポイント

項番

イベントID

トレース取得ポイント

1

0xA4A0

JAX-RSエンジンのサーブレット開始時

2

0xA4A2

Webリソース呼び出し前

3

0xA4A3

Webリソース呼び出し後

4

0xA4A1

JAX-RSエンジンのHTTPメッセージ送信前

リクエストを2回送信した場合に，イベントID「0xA4A0」，「0xA4A2」，「0xA4A3」および「0xA4A1」をキーにして，性能解析トレースファイルをフィルタリングした例を次の図に示します。

図39‒17　性能解析トレースをフィルタリングした例

クライアントアプリケーション情報から，リクエストの処理状況を確認できます。同じリクエストを処理している場合，同じクライアントアプリケーション情報が出力されます。

同一クライアントアプリケーション情報の中のイベントID「0xA4A0」および「0xA4A1」のトレース取得時刻から，JAX-RSエンジンを含めたWebリソース全体のレスポンスタイムを解析できます。また，「0xA4A2」および「0xA4A3」のトレース取得時刻から，Webリソース（UP）のレスポンスタイムを解析できます。

付録

付録A　旧バージョンからの移行

旧バージョンの機能であるSOAPアプリケーション開発支援機能，およびSOAP通信基盤を利用して開発したSOAPアプリケーションの移行について，およびJAX-WSエンジンを利用したApplication Serverを08-00〜08-70から09-00以降にバージョンアップする場合の注意事項について説明します。

SOAPアプリケーション開発支援機能／SOAP通信基盤で開発したSOAPアプリケーションおよびSOAPクライアントは，バージョンアップインストールして同じ環境で利用できます。この場合，特に設定は不要です。

SOAPアプリケーション開発支援機能／SOAP通信基盤で開発したSOAPアプリケーション，およびSOAPクライアントをJAX-WSエンジン上で利用する場合，バージョンアップインストールしたあとに，JAX-WSエンジンの環境に切り替えます。また，JAX-WS 2.2仕様およびApplication ServerのJAX-WS機能のサポート範囲に従って，改めてWebサービスおよびWebサービスクライアントを作成し直す必要があります。

付録A.1　バージョンアップインストール

SOAPアプリケーション開発支援機能／SOAP通信基盤，JAX-WS機能，およびJAX-RS機能は，Application Serverのインストール時に同時にインストールされます。

ここでは，旧バージョンがインストールされているマシンに対して，バージョンアップインストールする場合の手順および注意事項について説明します。

(1)　J2EEサーバの移行

Application Serverをバージョンアップインストールする場合，マニュアル「アプリケーションサーバ 機能解説 保守／移行編」の「10.2.2　更新インストールの場合」に記載されている移行手順に従ってインストールしてください。

バージョンアップインストールすると，SOAPアプリケーション開発支援機能およびSOAP通信基盤を利用するように設定されます。

(2)　Webサービスのアンデプロイ

Webサービス（またはSOAPアプリケーション）を移行する場合，あらかじめJ2EEサーバにデプロイされているWebサービス（またはSOAPアプリケーション）をアンデプロイしてください。

(3)　動作環境の切り替え

SOAPアプリケーション開発支援機能／SOAP通信基盤，JAX-WSエンジン，およびJAX-RSエンジンの切り替えは，J2EEサーバ用オプション定義ファイルで定義します。ここでは，J2EEサーバ用オプション定義ファイルの指定内容，および指定方法について説明します。

J2EEサーバ用オプション定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「2.2.2　usrconf.cfg（J2EEサーバ用オプション定義ファイル）」を参照してください。

JAX-WSエンジンおよびJAX-RSエンジンを利用する場合

JAX-WSエンジンおよびJAX-RSエンジンを利用する場合，J2EEサーバ用オプション定義ファイルのadd.class.pathの「cjjaxws.jar」と「cjjaxrs.jar」の行を有効にし，「hitsaaj.jar」の行を無効にします。次の例に従って定義してください。

...
#add.class.path=<cosminexus.home>¥c4web¥lib¥hitsaaj.jar
add.class.path=<cosminexus.home>¥jaxws¥lib¥cjjaxws.jar
add.class.path=<cosminexus.home>¥jaxrs¥lib¥cjjaxrs.jar
...

SOAPアプリケーション開発支援機能／SOAP通信基盤を利用する場合

SOAPアプリケーション開発支援機能／SOAP通信基盤を利用する場合，J2EEサーバ用オプション定義ファイルのadd.class.pathの「hitsaaj.jar」の行を有効にし，「cjjaxws.jar」の行を無効にします。次の例に従って定義してください。

...
add.class.path=<cosminexus.home>¥c4web¥lib¥hitsaaj.jar
#add.class.path=<cosminexus.home>¥jaxws¥lib¥cjjaxws.jar
...

注意事項

有効，無効にする行に矛盾がないように設定してください。例えば，「hitsaaj.jar」，「cjjaxws.jar」，および「cjjaxrs.jar」すべての行を無効にした場合，またはすべての行を有効にした場合の動作は保証されません。

J2EEサーバ用オプション定義ファイルの編集方法を説明します。

ここで説明するどの方法でも，J2EEサーバ用オプション定義ファイルを編集（保存）したあとに，J2EEサーバを再起動してください。J2EEサーバを再起動しない場合は，編集内容が反映されません。

(a)　直接編集する場合

直接編集する場合，次の場所に格納されたJ2EEサーバ用オプション定義ファイルをテキストエディタで開き，内容を変更します。

<Application Serverのインストールディレクトリ>/CC/server/usrconf/ejb/<J2EEサーバ名>/usrconf.cfg

(b)　Management Serverの運用管理ポータルを利用する場合

Management Serverの運用管理ポータルを利用する場合，［J2EEコンテナの設定］画面の「拡張パラメタ」で設定します。

JAX-WSエンジンおよびJAX-RSエンジンを利用する場合の設定例を次に示します。

図A‒1　運用管理ポータルによるJAX-WSエンジンおよびJAX-RSエンジンの設定例

SOAPアプリケーション開発支援機能およびSOAP通信基盤を利用する場合の設定例を次に示します。

図A‒2　運用管理ポータルによるSOAPアプリケーション開発支援機能／SOAP通信基盤の設定例

運用管理ポータルの［J2EEコンテナの設定］画面については，マニュアル「アプリケーションサーバ 運用管理ポータル操作ガイド」の「10.8.2　J2EEコンテナの設定」を参照してください。

(c)　Smart Composer機能を利用する場合

Smart Composer機能を利用する場合は，簡易構築定義ファイルに，J2EEの拡張パラメタとして追加します。Smart Composer機能については，マニュアル「アプリケーションサーバ システム構築・運用ガイド」を参照してください。簡易構築定義ファイルについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「4.　Smart Composer機能で使用するファイル」を参照してください。

JAX-WSエンジンおよびJAX-RSエンジンを利用する場合の設定例を次に示します。

<param>
 <param-name>add.class.path</param-name>
 <param-value>&lt;cosminexus.home&gt;¥jaxws¥lib¥cjjaxws.jar</param-value>
</param>
<param>
 <param-name>add.class.path</param-name>
 <param-value>&lt;cosminexus.home&gt;¥jaxrs¥lib¥cjjaxrs.jar</param-value>
</param>

SOAPアプリケーション開発支援機能およびSOAP通信基盤を利用する場合の設定例を次に示します。

<param>
 <param-name>add.class.path</param-name>
 <param-value>&lt;cosminexus.home&gt;¥c4web¥lib¥hitsaaj.jar</param-value>
</param>

付録A.2　旧バージョンで作成したWSDLの互換性

旧バージョンで作成したWSDLをJAX-WSエンジン上で使用できます。ただし，WSDLに記述されたXML Schemaには制限があります。データ型，制約ファセット，および出現回数の制限について示します。

データ型の制限を次の表に示します。

表A‒1　XML Schemaのデータ型の制限

項番

データ型

最大値

最大桁数

1

duration型

（形式：PnYnMnDTnHnMnS）

nY（年）

2147483647

−

2

nM（月）

3

nD（日）

4

nH（時）

5

nM（分）

6

nS（秒）

1秒以上

7

1秒未満

8

date型

（形式：CCYY-MM-DD）

CCYY※1

9

gYearMonth型

（形式：CCYY-MM）

CCYY※1

10

gYear型

（形式：CCYY）

CCYY※1

11

dateTime型

（形式：CCYY-MM-DDThh:mm:ss）

CCYY※1

1秒未満※2

12

dateTime型

（形式：CCYY-MM-DDThh:mm:ss）

1秒未満※2

13

time型（形式：hh:mm:ss）

規定はありません。

14

base64Binary型

メモリに依存します。

15

hexBinary型

16

decimal型

17

integer型

18

nonPositiveInteger型

19

nonNegativeInteger型

20

negativeInteger型

21

positiveInteger型

（凡例）

−：該当しないことを示します。

注※1

"9999"を超える場合，桁数を追加できます。

注※2

"ss"に続く小数点以下に，1秒未満の値を指定できます。

制約ファセットに関する制限を次の表に示します。

表A‒2　XML Schemaの制約ファセットに関する制限

項番

制約ファセット

最大値

最大桁数

1

length

2147483647

−

2

minLength

3

maxLength

4

totalDigits

5

fractionDigits

6

maxInclusive

規定はありません。

メモリに依存します。

7

maxExclusive

8

minInclusive

9

minExclusive

（凡例）

−：該当しないことを示します。

出現回数の指定の制限を次の表に示します。

表A‒3　XML Schemaの出現回数の指定に関する制限

項番

出現回数の指定

最大値

最大桁数

1

minOccurs

2147483647

−

2

maxOccurs

（凡例）

−：該当しないことを示します。

付録A.3　JAX-WSエンジンを利用したApplication Serverを08-00〜08-70から09-00〜09-70にバージョンアップする場合

ここでは，JAX-WSエンジンを利用したApplication Serverを08-00〜08-70から09-00〜09-70にバージョンアップインストールする場合の注意事項を説明します。

(1)　SSL接続におけるホスト名検証

SSL接続におけるホスト名検証（Hostname Verification）は08-00〜08-70と09-00以降とで動作が異なります。

08-00〜08-70

WebサービスクライアントからSSLプロトコルに対応したWebサービスに接続する場合，エンドポイントアドレスに含まれるホスト名と，証明書のホスト名が一致しているかどうかは検証されません。

09-00以降

WebサービスクライアントからSSLプロトコルに対応したWebサービスに接続する場合，エンドポイントアドレスに含まれるホスト名と，証明書のホスト名が一致しているかどうかが検証されます。使用されるHostnameVerifierはJDKのデフォルトの実装です。JDKのデフォルトのHostnameVerifierの動作についてはJDKのドキュメントを参照してください。

09-00以降で08-00〜08-70と同様にSSL接続におけるホスト名検証が行われないようにするには，com.cosminexus.xml.ws.client.http.HostnameVerificationPropertyプロパティに"true"を設定してください。

(2)　フォルトから例外クラスへのマッピング

cjwsimportコマンドを実行すると，WSDLのフォルトは，JAX-WS 2.2仕様に従ってJava型にマッピングされます。このとき，ラッパ例外クラスが生成される条件は，08-00〜08-70と09-00以降とで異なります。

08-00〜08-70

wsdl:portType要素とwsdl:binding要素の孫要素に，対応関係にあるwsdl:fault要素が定義されている場合，ラッパ例外クラスが生成されます。どちらか一方だけに定義されている場合は生成されません。

09-00以降

wsdl:portType要素の孫要素にwsdl:fault要素が定義されている場合，ラッパ例外クラスが生成されます。wsdl:binding要素の孫要素として，対応関係にあるwsdl:fault要素が定義されている必要はありません。

(3)　javax.activation.DataHandlerオブジェクトの動作

javax.activation.DataHandlerオブジェクトは，08-00〜08-70と09-00以降とで動作が異なります。

08-00〜08-70

wsi:swaRef形式またはMTOM/XOP仕様形式の添付ファイルで受信したデータがjavax.activation.DataHandlerオブジェクトの場合，入力ストリームからすべてのデータを読み込みます。

09-00以降

wsi:swaRef形式またはMTOM/XOP仕様形式の添付ファイルで受信したデータがjavax.activation.DataHandlerオブジェクトの場合，入力ストリームから順次読み込みます。

wsi:swaRef形式またはMTOM/XOP仕様形式の添付ファイルの受信側では，javax.activation.DataHandlerオブジェクトが持つ入力ストリームからすべてのデータを読み込まないと受信処理が完了しないため，送信側の送信処理は受信側の受信処理が完了するまで待ち状態が続きます。

この状態を解消するためには，javax.activation.DataHandlerオブジェクトが持つjava.io.InputStreamオブジェクトからすべてのデータを読み込むか，javax.activation.DataHandlerクラスのwriteTo(java.io.OutputStream)メソッドを使用して入力ストリームのデータを出力ストリームに書き込む必要があります。

(4)　javax.xml.transform.Sourceオブジェクトの動作

javax.xml.transform.Sourceオブジェクトは，08-00〜08-70と09-00以降とで動作が異なります。

08-00〜08-70

MTOM/XOP仕様形式の添付ファイルで受信したデータがjavax.xml.transform.Sourceオブジェクトの場合，入力ストリームからすべてのデータを読み込みます。

09-00以降

MTOM/XOP仕様形式の添付ファイルで受信したデータがjavax.xml.transform.Sourceオブジェクトの場合，入力ストリームから順次読み込みます。javax.xml.transform.Sourceオブジェクトは，JAXBがjavax.xml.transform.stream.StreamSourceオブジェクトに変換します。

MTOM/XOP仕様形式の添付ファイルの受信側では，javax.xml.transform.stream.StreamSourceオブジェクトが持つ入力ストリームからすべてのデータを読み込まないと受信処理が完了しないため，送信側の送信処理は受信側の受信処理が完了するまで待ち状態が続きます。

この状態を解消するためには，javax.xml.transform.stream.StreamSourceオブジェクトが持つjava.io.Readerオブジェクトからすべてのデータを読み込む必要があります。

(5)　アドレッシング機能を使用している場合のサービス側ランタイムの動作の違い

アドレッシング機能を使用していて，次の条件がすべて重なった場合，サービス側ランタイムの動作が08-50〜08-70と09-00以降とで異なります。

SOAP 1.1仕様のメッセージである。

リクエストメッセージのアドレッシングヘッダにwsa:ReplyTo要素が存在しない。

リクエストメッセージのアドレッシングヘッダにwsa:FaultTo要素が存在し，WebサービスのURIを設定している。

サービス側でエラーが発生し，SOAPフォルトを返信する。

08-50〜08-70

HTTPステータスコード：202を返します。

09-00以降

HTTPステータスコード：500を返します。

(6)　MIME Multipart/Related構造のSOAPメッセージ受信時の動作の違い

1048576バイト以上のサイズのMIMEボディを含むMIME Multipart/Related構造のSOAPメッセージを受信した場合，JAX-WSエンジンの動作が08-00〜08-70と09-00以降とで異なります。

08-00〜08-70

1048576バイト以上のサイズのMIMEボディを含むMIME Multipart/Related構造のSOAPメッセージを受信した場合，JAX-WSエンジンはSOAPメッセージに含まれるMIMEボディを一時ファイルに出力しないで，Javaヒープに展開します。

09-00以降

1048576バイト以上のサイズのMIMEボディを含むMIME Multipart/Related構造のSOAPメッセージを受信した場合，JAX-WSエンジンはSOAPメッセージに含まれるMIMEボディを一時ファイルに出力します。

添付ファイルパートのMIMEボディに対応する一時ファイルは，com.sun.xml.ws.developer.StreamingDataHandler#close()メソッドで添付ファイルをクローズするときに削除されます。

詳細については，「10.24　MIME Multipart/Related構造のSOAPメッセージの受信」を参照してください。

(7)　MIME Multipart/Related構造のSOAPメッセージ送信時の動作の違い

MTOM/XOP仕様形式の添付ファイル機能を使用してMIME Multipart/Related構造のSOAPメッセージを送信する場合，JAX-WSエンジンの動作が08-70と09-00以降とで異なります。

08-70

レスポンスメッセージは，常にMIME Multipart/Related構造のSOAPメッセージです。

09-00以降

Webサービス側で次の条件をすべて満たすリクエストメッセージを受信した場合，レスポンスメッセージに含まれるバイナリデータがBase64形式のデータになります。

リクエストメッセージのHTTPヘッダにあるAcceptフィールドにapplication/xop+xmlがない。

リクエストメッセージのルートパートにあるContent-Typeにapplication/xop+xmlがない。

付録A.4　JAX-WSエンジンを利用したApplication Serverを09-70以前から09-87以降にバージョンアップする場合

ここでは，JAX-WSエンジンを利用したApplication Serverを09-70以前から09-87以降にバージョンアップインストールする場合の注意事項を説明します。

(1)　cjaptコマンドの廃止

JAX-WS機能のcjaptコマンドは使用できません。JAX-WS 2.2仕様に対応したWebサービス実装クラスをコンパイルする場合，javacコマンドを使用してください。javacコマンドについては，JDKのドキュメントを参照してください。

(2)　cjwsgenコマンドの廃止およびhwsgenコマンドの追加

JAX-WS機能のcjwsgenコマンドは使用できません。コンパイルしたWebサービス実装クラスに対して事前にエラーチェックをする場合，hwsgenコマンドを使用してください。hwsgenコマンドに指定できるオプションは09-70のcjwsgenコマンドと同じです。ただし，cjwsgenコマンドの-soapオプションおよび-soap12bindingオプションは使用できません。また，動作定義ファイルに設定するcjwsgenコマンドの定義はhwsgenコマンドでは無効となり，hwsgenコマンドではログを出力しません。hwsgenコマンドについては，「14.1.2　hwsgenコマンド」を参照してください。

(3)　java.activationモジュールを使用するアプリケーションのコンパイル

Java SEが提供していたjava.activationモジュールに含まれるAPIを使用するアプリケーションをコンパイルする場合は，次のライブラリをクラスパスに追加してコンパイルしてください。

<Cosminexusインストールディレクトリ>¥jdk¥lib¥hcompatlib¥hjdk.act.jar

このライブラリは，コンパイル以外の用途では使用しないでください。

付録B　POJOのWebサービスからEJBのWebサービスへの移行

付録B.1　移行方法の詳細

POJOで開発されたWebサービスを，EJBのWebサービスとして動作させることで，EJBの機能を利用できます。ここでは，POJOのWebサービスをEJBのWebサービスに移行する方法について説明します。なお，POJOのWebサービスで十分な場合，EJBへの移行は不要です。

POJOのWebサービスをEJBのWebサービスに移行する方法を次の表に示します。

表B‒1　EJBのWebサービスに移行する方法

項番

POJOのWebサービスの構成物

EJBのWebサービスへの移行方法

1

Webサービス実装クラス

ソースコードにjavax.ejb.Statelessアノテーションを追加し，コンパイルします。

2

項番1以外のJavaクラス（SEI，JavaBeansクラス（スタブ）など）

EJBのWebサービスへの移行後もクラスファイルをそのまま使用できます。

3

WSDL

POJOのWebサービスの場合とEJBのWebサービスの場合とではWebサービスとして公開するURLが異なるため，soap:address要素のlocation属性などのURLに関する値を変更して使用します。EJBのURLについては，「10.2.2(1)　ディスカバリ」を参照してください。

4

cosminexus-jaxws.xml，web.xml，application.xmlなどのDD

POJOのWebサービス用に作成されたDDは，EJBのWebサービスではそのまま使用できません。EJBのWebサービス用に新たにDDを作成してください。

POJOのWebサービスをEJBのWebサービスに移行する場合，Webサービス実装クラスのソースコードの修正が必要です。ここでは，POJOのWebサービスの実行に必要なクラスファイルと，Webサービス実装クラスのソースコードがあることを前提に説明します。

移行手順の流れを次に示します。

(1)　EJBのWebサービス実装クラスを作成する

POJOのWebサービス実装クラスのソースコードにjavax.ejb.Statelessアノテーションでアノテートします。アノテートしたソースコードをコンパイルしてクラスファイルを作成します。

(2)　Webサービス実行に必要なクラスファイルおよびWSDLを流用する

POJOのWebサービスを実行するために必要なSEI，JavaBeansクラス（スタブ）などのクラスファイルは，EJBのWebサービスとして実行する場合にも使用できます。

POJOのWebサービスを実行するために使用していたWSDLがある場合は，EJBのWebサービスとして実行する場合にも使用できます。ただし，POJOのWebサービスをEJBのWebサービスとして実行した場合に，Webサービスとして公開するURLが異なるため，WSDLのsoap:address要素のlocation属性などのURLに関する値を変更して使用します。EJBのWebサービスのURLについては，「10.2.2(1)　ディスカバリ」を参照してください。

(3)　EJB JARファイルを作成する

(1)(2)のクラスファイルおよびWSDLをEJB JARファイルに格納します。EJB JARファイルの構成については，「3.5.2　EJB JARファイルの構成」を参照してください。

(4)　デプロイメントディスクリプタを作成する

(3)で作成したEJB JARファイルを指定するapplication.xmlを作成します。application.xmlの例を次に示します。「statelessjava.jar」には(3)で作成したEJB JARファイルの名前を指定します。

<?xml version="1.0" encoding="UTF-8"?>
<application version="6" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">

  <description>Sample application &quot;statelessjava_dynamic_generate&quot;</description>
  <display-name>Sample_application_statelessjava_dynamic_generate</display-name>
  <module>
    <ejb>statelessjava_dynamic_generate.jar</ejb>
  </module>
</application>

バージョン5のapplication.xmlを作成する場合は，application要素のversion属性を"5"に，xsd:schemaLocation属性の二つ目のロケーション情報を"http://java.sun.com/xml/ns/javaee/application_5.xsd"にしてください。

EJBのWebサービスの動作には，web.xmlは必須ではありません。EJBのWebサービスで，サーブレットフィルタなどの設定をweb.xmlに加える場合にweb.xmlを作成します。詳細については，「3.5.4　EJBのWebサービスの設定用WARファイルの作成」を参照してください。また，cosminexus-jaxws.xmlはEJBのWebサービスには適用されません。

(5)　EARファイルを作成する

(3)(4)で作成したEJB JARファイルとapplication.xmlを含むEARファイルを作成します。EARファイルの構成については，「3.5.3　EARファイルの作成」を参照してください。

付録C　JAX-WSエンジンのメモリ使用量の算出

Javaヒープ領域でのJAX-WSエンジンのメモリ使用量（Webサービス実行側）を次の場合を用いて説明します。

アプリケーション起動時のメモリ使用量

1リクエスト当たりのメモリ使用量

添付ファイル使用時の1リクエスト当たりのメモリ使用量

単位時間当たりのメモリ使用量

なお，JAX-WSエンジンに関する設定は，すべてデフォルト値とします。以降で説明するメモリ使用量には，JAX-WSエンジンの内部クラスで使用するメモリ使用量，内部クラスが呼び出すJava APIのメモリ使用量，およびJavaVMの内部実装クラスで使用するメモリ量も含みます。

また，以降で説明するJAX-WSエンジン固有のメモリ使用量は目安であり，実際のシステムでは若干異なる場合があります。

付録C.1　アプリケーション起動時のメモリ使用量

Webサービスを含むアプリケーション起動時のメモリ使用量について説明します。アプリケーション起動時とは，cjstartappコマンド実行時，またはManagement ServerからJ2EEアプリケーションを起動した直後のことを指します。

アプリケーション起動時には，JAX-WSエンジンの実行に必要なクラスの初期化などが行われます。初期化に必要なメモリ量は，Webサービス実装クラスの処理に関係なく，約21.2MBとなります。また，Javaヒープ内のMetaspace領域でのメモリ使用量は，J2EEサーバにロードされるクラスファイルの合計サイズです。JAX-WSエンジンのコンテナ拡張ライブラリで指定するcjjaxws.jarのクラスファイルの総和は約7MBになります。

付録C.2　1リクエスト当たりのメモリ使用量

1リクエスト当たりの処理に必要なメモリ使用量について説明します。1リクエストとは，Webサービスクライアントからリクエストを受け付け，処理をし，レスポンスを返すまでのことを指します。

初回リクエスト時と2回目以降のリクエスト時では，使用されるJAX-WSエンジン固有のメモリ使用量が異なります。

初回リクエスト時のメモリ使用量を示します。

1リクエスト当たりのメモリ使用量（初回）＝
   Webサービス実装クラスが使用するメモリ使用量＋JAX-WSエンジン固有のメモリ使用量(2.43MB)

2回目以降のリクエスト時のメモリ使用量を示します。

1リクエスト当たりのメモリ使用量（2回目以降）＝
   Webサービス実装クラスが使用するメモリ使用量＋JAX-WSエンジン固有のメモリ使用量(119.9KB)

また，単位時間当たりに複数のリクエストが到着する場合のメモリ使用量の算出式は，次のとおりです。

単位時間当たりのメモリ使用量＝
   1リクエスト当たりのメモリ使用量（初回）+{1リクエスト当たりのメモリ使用量（2回目以降）×（単位時間当たりのリクエスト処理数−1）}

付録C.3　添付ファイル使用時の1リクエスト当たりのメモリ使用量

添付ファイルを使用するWebサービスのアプリケーションで，1リクエスト当たりの処理に必要なメモリ使用量について説明します。1リクエストとは，Webサービスクライアントからリクエストを受け付け，処理をし，レスポンスを返すまでのことを指します。

ここで説明する算出方法では，Webサービスクライアントから添付ファイルを受け付け，添付ファイルをそのままWebサービスクライアントに返す処理をするWebサービスを想定しています。

(1)　添付ファイルサイズが10KBの場合

初回リクエスト時のメモリ使用量を示します。

1リクエスト当たりのメモリ使用量（初回）＝
   Webサービス実装クラスが使用するメモリ使用量＋JAX-WSエンジン固有のメモリ使用量（2.68MB）

2回目以降のリクエスト時のメモリ使用量を示します。

1リクエスト当たりのメモリ使用量（2回目以降）＝
   Webサービス実装クラスが使用するメモリ使用量＋JAX-WSエンジン固有のメモリ使用量（193KB）

(2)　添付ファイルサイズが100KBの場合

初回リクエスト時のメモリ使用量を示します。

1リクエスト当たりのメモリ使用量（初回）＝
   Webサービス実装クラスが使用するメモリ使用量＋JAX-WSエンジン固有のメモリ使用量（2.73MB）

2回目以降のリクエスト時のメモリ使用量を示します。

1リクエスト当たりのメモリ使用量（2回目以降）＝
   Webサービス実装クラスが使用するメモリ使用量＋JAX-WSエンジン固有のメモリ使用量（411KB）

(3)　添付ファイルサイズが1MBの場合

初回リクエスト時のメモリ使用量を示します。

1リクエスト当たりのメモリ使用量（初回）＝
   Webサービス実装クラスが使用するメモリ使用量＋JAX-WSエンジン固有のメモリ使用量（4.54MB）

2回目以降のリクエスト時のメモリ使用量を示します。

1リクエスト当たりのメモリ使用量（2回目以降）＝
   Webサービス実装クラスが使用するメモリ使用量＋JAX-WSエンジン固有のメモリ使用量（2.24MB）

付録C.4　単位時間当たりのメモリ使用量の算出

単位時間当たりに複数のリクエストが到着する場合のメモリ使用量の算出式は，次のとおりです。

単位時間当たりのメモリ使用量 ＝
   1リクエスト当たりのメモリ使用量（初回）+{1リクエスト当たりのメモリ使用量（2回目以降）×（単位時間当たりのリクエスト処理数−1）}

ここでは例として，1分間に60リクエストが到着し，平均約10KBの添付ファイルを扱うシステムの1時間当たりのメモリ使用量を算出します。このシステムでは，Webサービス実装クラスが使用するメモリ使用量が，1リクエスト当たり100KBとします。

この場合，初回時の1リクエスト当たりのメモリ使用量は次のとおりとなります。

100KB＋2.68MB＝2.78MB

また，2回目以降の1リクエスト当たりのメモリ使用量は次のとおりとなります。

100KB＋193KB＝293KB

この結果から，1時間当たりのメモリ使用量は，次のように算出できます。

2.78MB＋{293KB×（60×60−1)}＝1,033MB

1時間当たりのメモリ使用量に，アプリケーション起動時のメモリ量を加えると，このアプリケーションが起動してから1時間で使用するJavaヒープのメモリ量がわかります。

21.2MB＋1,033MB＝1,054.2MB

付録D　用語解説

マニュアルで使用する用語について

マニュアル「アプリケーションサーバ & BPM/ESB基盤 用語解説」を参照してください。

索引

数字

1リクエスト当たりのメモリ使用量[1]

1リクエスト当たりのメモリ使用量（添付ファイル使用時）[1]

A

Actionアノテーション指定時の動作[1]

action要素（javax.jws.WebMethod）[1]

AddressingFeature[1]

AddressingFeatureクラスと匿名URI[1]

Addressingアノテーション指定時の動作[1]

APIのサポート範囲[1]、[2]

application.xmlを作成する（RESTFul Webサービス）[1]

application.xmlを作成する（SEI起点）[1]

application.xmlを作成する（SEI起点・EJBのWebサービス）[1]

application.xmlを作成する（SEI起点・hwsgenコマンド）[1]

application.xmlを作成する（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

application.xmlを作成する（SEI起点・wsi:swaRef形式の添付ファイル）[1]

application.xmlを作成する（SEI起点・アドレッシング）[1]

application.xmlを作成する（SEI起点・カスタマイズ）[1]

application.xmlを作成する（SEI起点・ストリーミング）[1]

application.xmlを作成する（WSDL起点）[1]

application.xmlを作成する（WSDL起点・WS-RM 1.2）[1]

application.xmlを作成する（プロバイダ起点・SAAJ）[1]

AttachmentPartクラス[1]

B

binding属性（wsdl:port要素）[1]

byte[]を使用する方法（java.lang.Stringオブジェクトを送信する場合）[1]

byte[]を使用する方法（XMLファイルを送信する場合）[1]

byte[]を使用する方法（イメージファイルを送信する場合）[1]

byte[]を使用する方法（テキストファイルを送信する場合）[1]

C

childElementName属性（jaxws:bindings要素）[1]

CID URLスキームの形式[1]

cjwsimportコマンド[1]

cjwsimportコマンドのオプション一覧[1]

cjwsimportコマンドの指定形式[1]

cjwsimportコマンドの終了コード[1]

cjwsimportコマンドの生成ファイル一覧[1]

className要素（javax.xml.ws.FaultAction）[1]

className要素（javax.xml.ws.RequestWrapper）[1]

className要素（javax.xml.ws.ResponseWrapper）[1]

ClientHandlerExceptionクラスのメソッド仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

ClientRequest.Builderクラスのメソッド仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

ClientRequestクラスとWebリソースクラスに含まれる情報[1]

ClientRequestクラスのメソッド仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

ClientResponse.Statusクラスの列挙型定数とメソッドの仕様〔RESTful Webサービス用クライアントAPI〕[1]

ClientResponseクラスのメソッド仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

Clientクラスのメソッド仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

closeメソッドの処理[1]

com.cosminexus.jaxws.http.proxyPassword[1]

com.cosminexus.jaxws.http.proxyUser[1]

com.cosminexus.jaxws.https.proxyPassword[1]

com.cosminexus.jaxws.https.proxyUser[1]

com.sun.xml.ws.Closeableクラス[1]

com.sun.xml.ws.developer.StreamingAttachmentFeatureクラス[1]

com.sun.xml.ws.developer.StreamingAttachmentアノテーション[1]

com.sun.xml.ws.developer.StreamingDataHandlerクラス[1]

Conformanceへの対応[1]

Cookieクラス[1]

cosminexus-jaxws.xml使用時の設定例[1]

cosminexus-jaxws.xmlによるカスタマイズ[1]

cosminexus-jaxws.xmlの書式[1]

cosminexus-jaxws.xmlのファイル名と格納先[1]

D

DefaultClientConfigクラスの定数およびメソッドの仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

Detailインタフェース[1]

Document BareスタイルでのMTOM/XOP仕様形式の添付ファイル[1]

E

EARファイル[1]、[2]

EARファイルの作成[1]、[2]

EARファイルを作成する（RESTFul Webサービス）[1]

EARファイルを作成する（SEI起点）[1]

EARファイルを作成する（SEI起点・EJBのWebサービス）[1]

EARファイルを作成する（SEI起点・hwsgenコマンド）[1]

EARファイルを作成する（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

EARファイルを作成する（SEI起点・wsi:swaRef形式の添付ファイル）[1]

EARファイルを作成する（SEI起点・アドレッシング）[1]

EARファイルを作成する（SEI起点・カスタマイズ）[1]

EARファイルを作成する（SEI起点・ストリーミング）[1]

EARファイルを作成する（WSDL起点）[1]

EARファイルを作成する（WSDL起点・WS-RM 1.2）[1]

EARファイルを作成する（プロバイダ起点・SAAJ）[1]

EARファイルをデプロイする（RESTFul Webサービス）[1]

EARファイルをデプロイする（SEI起点）[1]

EARファイルをデプロイする（SEI起点・EJBのWebサービス）[1]

EARファイルをデプロイする（SEI起点・hwsgenコマンド）[1]

EARファイルをデプロイする（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

EARファイルをデプロイする（SEI起点・wsi:swaRef形式の添付ファイル）[1]

EARファイルをデプロイする（SEI起点・アドレッシング）[1]

EARファイルをデプロイする（SEI起点・カスタマイズ）[1]

EARファイルをデプロイする（SEI起点・ストリーミング）[1]

EARファイルをデプロイする（WSDL起点）[1]

EARファイルをデプロイする（WSDL起点・WS-RM 1.2）[1]

EARファイルをデプロイする（プロバイダ起点・SAAJ）[1]

EJB JARファイル[1]

EJB JARファイルの構成[1]

EJBのWebサービスに適用する場合の注意事項[1]

EJBのWebサービスの設定用WARファイルの作成[1]

EJBのWebサービス呼び出し[1]

element属性（wsdl:part要素）[1]

enabled要素（javax.xml.ws.soap.Addressing）[1]

enabled要素（javax.xml.ws.soap.MTOM）[1]

endpointInterface要素（javax.jws.WebService）[1]

endpointInterface要素の利用（javax.jws.WebServiceアノテーション）[1]

EntityTagクラス[1]

er:catalog要素[1]

er:public要素[1]

er:system要素[1]

exclude要素（javax.jws.WebMethod）[1]

F

faultBean要素（javax.xml.ws.WebFault）[1]

fault要素（javax.xml.ws.Action）[1]

file要素（javax.jws.HandlerChain）[1]

G

GenericTypeクラスのコンストラクタおよびメソッド仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

H

handleFaultメソッドの処理[1]

handleMessageメソッドの処理[1]

header要素（javax.jws.WebParam）[1]

header要素（javax.jws.WebResult）[1]

http.nonProxyHosts[1]

http.proxyHost[1]

http.proxyPort[1]

HttpHeadersインタフェース[1]

https.proxyHost[1]

https.proxyPort[1]

HTTPSPropertiesクラスの定数，コンストラクタおよびメソッドの仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

HTTPステータスコード[1]、[2]、[3]

HTTPステータスコード（例外をフォルトにバインディングする場合）[1]

HTTPヘッダ[1]、[2]

HTTPヘッダ（添付ファイルからSOAPメッセージ・MTOM/XOP）[1]

HTTPヘッダ（添付ファイルからSOAPメッセージ・wsi:swaRef形式）[1]

HTTPヘッダとHTTPボディの境界文字列（添付ファイルからSOAPメッセージ・wsi:swaRef形式）[1]

HTTPヘッダの設定〔RESTful Webサービス用クライアントAPI〕[1]

HTTPボディ（添付ファイルからSOAPメッセージ・MTOM/XOP）[1]

HTTPボディ（添付ファイルからSOAPメッセージ・wsi:swaRef形式）[1]

HTTPリクエストのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ[1]

HTTPリクエストボディのgzip圧縮[1]

HTTPレスポンス圧縮機能との連携[1]

HTTPレスポンスのエンティティに使用できるJavaの型とMIMEメディアタイプの組み合わせ[1]

hwsgenコマンド[1]

hwsgenコマンドによるエラーチェック（ラッパbeanの動的生成機能）[1]

hwsgenコマンドのオプション一覧[1]

hwsgenコマンドの指定形式[1]

hwsgenコマンドの終了コード[1]

I

implementation属性（cosminexus-jaxws.xml）[1]

input要素（javax.xml.ws.Action）[1]

J

J2EEサーバの移行[1]

J2EEサーバへの例外のスロー[1]

java.awt.Imageを使用する方法（イメージファイルを送信する場合）[1]

java.lang.Stringオブジェクトを送信する場合（MTOM/XOP形式）[1]

java.util.Listオブジェクト[1]

java.util.Mapクラス[1]

javaee:handler要素[1]

javaee:handler-chains要素[1]

javaee:handler-chain要素[1]

javaee:handler-class要素[1]

javaee:handler-name要素[1]

javaee:soap-header要素[1]

javaee:soap-role要素[1]

JavaVMのプロパティ[1]

javax.activation.DataHandlerオブジェクト取得時の注意事項（MTOM/XOP形式）[1]

javax.activation.DataHandlerオブジェクト取得時の注意事項（wsi:swaRef形式）[1]

javax.activation.DataHandlerオブジェクト生成時の注意事項[1]

javax.activation.DataHandlerオブジェクト生成時の注意事項（MTOM/XOP形式）[1]

javax.activation.DataHandler型に指定できる添付ファイル[1]

javax.activation.DataHandlerを使用する方法（java.lang.Stringオブジェクトを送信する場合）[1]

javax.activation.DataHandlerを使用する方法（XMLファイルを送信する場合）[1]

javax.activation.DataHandlerを使用する方法（イメージファイルを送信する場合）[1]

javax.activation.DataHandlerを使用する方法（テキストファイルを送信する場合）[1]

javax.annotation.Resourceアノテーションの指定〔Webサービスコンテキストのインジェクション〕[1]

javax.jws.HandlerChainアノテーション[1]

javax.jws.Onewayアノテーション[1]

javax.jws.soap.SOAPBindingアノテーション[1]

javax.jws.WebMethodアノテーション[1]

javax.jws.WebParamアノテーション[1]

javax.jws.WebResultアノテーション[1]

javax.jws.WebServiceアノテーション[1]

javax.servlet.http.HttpServletRequest[1]

javax.servlet.http.HttpServletResponse[1]

javax.servlet.ServletConfig[1]

javax.servlet.ServletContext[1]

javax.ws.rs.core.ext.Providers[1]

javax.ws.rs.core.HttpHeaders[1]

javax.ws.rs.core.Request[1]

javax.ws.rs.core.SecurityContext[1]

javax.ws.rs.core.UriInfo[1]

javax.xml.bind.annotation.XmlElementアノテーション[1]

javax.xml.bind.annotation.XmlMimeTypeアノテーション[1]

javax.xml.bind.annotation.XmlTypeアノテーション[1]

javax.xml.transform.Sourceオブジェクト取得時の注意事項（MTOM/XOP形式）[1]

javax.xml.transform.Sourceを使用する方法（XMLファイルを送信する場合）[1]

javax.xml.ws.Actionアノテーション[1]

javax.xml.ws.BindingProviderインタフェース[1]

javax.xml.ws.BindingTypeアノテーション[1]

javax.xml.ws.Bindingインタフェース[1]

javax.xml.ws.Dispatchインタフェース[1]

javax.xml.ws.EndpointReferenceクラス[1]

javax.xml.ws.FaultActionアノテーション[1]

javax.xml.ws.handler.Handler<C extends MessageContext>インタフェース[1]

javax.xml.ws.handler.HandlerResolverインタフェース[1]

javax.xml.ws.handler.LogicalMessageContextインタフェース[1]

javax.xml.ws.handler.MessageContextインタフェース[1]

javax.xml.ws.handler.PortInfoインタフェース[1]

javax.xml.ws.handler.soap.SOAPHandler<T extends SOAPMessageContext>インタフェース[1]

javax.xml.ws.handler.soap.SOAPMessageContextインタフェース[1]

javax.xml.ws.Holder<T>クラス[1]

javax.xml.ws.LogicalMessageインタフェース[1]

javax.xml.ws.ProtocolExceptionクラス[1]

javax.xml.ws.Providerインタフェース[1]

javax.xml.ws.RequestWrapperアノテーション[1]

javax.xml.ws.ResponseWrapperアノテーション[1]

javax.xml.ws.ServiceModeアノテーション[1]

javax.xml.ws.Serviceクラス[1]

javax.xml.ws.soap.AddressingFeatureクラス[1]

javax.xml.ws.soap.Addressingアノテーション[1]

javax.xml.ws.soap.MTOMFeatureクラス[1]

javax.xml.ws.soap.MTOMアノテーション[1]

javax.xml.ws.soap.SOAPBindingインタフェース[1]

javax.xml.ws.soap.SOAPFaultExceptionクラス[1]

javax.xml.ws.soap.SOAPFaultExceptionのバインディング[1]

javax.xml.ws.WebFaultアノテーション[1]

javax.xml.ws.WebServiceContextインタフェース[1]

javax.xml.ws.WebServiceExceptionクラス[1]

javax.xml.ws.WebServiceExceptionのバインディング[1]

javax.xml.ws.WebServiceProviderアノテーション[1]

javax.xml.ws.WebServiceRefアノテーション[1]

javax.xml.ws.WebServiceRefアノテーションの指定例〔サービスクラスおよびポートのインジェクション〕[1]

javax.xml.ws.wsaddressing.W3CEndpointReferenceBuilderクラス[1]

javax.xml.ws.wsaddressing.W3CEndpointReferenceクラス[1]

Javaアプリケーション用オプション定義ファイルを作成する（RESTful Webサービス）[1]

Javaアプリケーション用オプション定義ファイルを作成する（SEI起点）[1]

Javaアプリケーション用オプション定義ファイルを作成する（SEI起点・EJBのWebサービス）[1]

Javaアプリケーション用オプション定義ファイルを作成する（SEI起点・hwsgenコマンド）[1]

Javaアプリケーション用オプション定義ファイルを作成する（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

Javaアプリケーション用オプション定義ファイルを作成する（SEI起点・wsi:swaRef形式の添付ファイル）[1]

Javaアプリケーション用オプション定義ファイルを作成する（SEI起点・アドレッシング）[1]

Javaアプリケーション用オプション定義ファイルを作成する（SEI起点・カスタマイズ）[1]

Javaアプリケーション用オプション定義ファイルを作成する（SEI起点・ストリーミング）[1]

Javaアプリケーション用オプション定義ファイルを作成する（WSDL起点）[1]

Javaアプリケーション用オプション定義ファイルを作成する（WSDL起点・WS-RM 1.2）[1]

Javaアプリケーション用オプション定義ファイルを作成する（プロバイダ起点・SAAJ）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（RESTFul Webサービス）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（SEI起点）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（SEI起点・EJBのWebサービス）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（SEI起点・hwsgenコマンド）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（SEI起点・wsi:swaRef形式の添付ファイル）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（SEI起点・アドレッシング）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（SEI起点・カスタマイズ）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（SEI起点・ストリーミング）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（WSDL起点）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（WSDL起点・WS-RM 1.2）[1]

Javaアプリケーション用ユーザプロパティファイルを作成する（プロバイダ起点・SAAJ）[1]

Java型を指定してHTTPリクエストおよびHTTPレスポンスを送受信する〔Webリソースクライアントのユースケース〕[1]

Java型を指定してHTTPリクエストを送信し，汎用型（ClientResponse）でHTTPレスポンスを受信する〔Webリソースクライアントのユースケース〕[1]

JavaからWSDLへのデフォルトマッピング[1]

JavaからWSDLへのマッピング[1]

JavaからWSDLへのマッピングに関する注意事項[1]

JavaからWSDLへのマッピングのカスタマイズ[1]

JavaソースからWSDLへのマッピング一覧[1]

JavaソースからWSDLへのマッピング例[1]

Javaソースをコンパイルする（RESTFul Webサービス）[1]

Javaソースを生成する（SEI起点・hwsgenコマンド）[1]

Javaソースを生成する（プロバイダ起点・SAAJ）[1]

Javaのパッケージ名に記述できる文字列[1]

Javaのラッパ例外クラスからフォルトへのマッピング[1]

Javaメソッドのオーバーロード[1]

Javaメソッドのパラメタの条件[1]

Java例外の伝搬[1]

JAXBアノテーションのサポート[1]、[2]

JAX-RS 1.1仕様のサポート範囲[1]

jaxws:bindings要素に指定できる値[1]

jaxws:bindings要素の指定（埋め込みによるバインディング宣言）[1]

jaxws:bindings要素の指定（外部バインディングファイル）[1]

jaxws:bindings要素の属性の指定可否[1]

jaxws:enableAsyncMapping要素（jaxws:bindings要素）[1]

jaxws:enableWrapperStyle要素（jaxws:bindings要素）[1]

jaxws:enableWrapperStyle要素の優先順位[1]

jaxws:javadoc要素（jaxws:bindings要素）[1]

jaxws:parameter要素でinoutパラメタ名をカスタマイズする場合の注意事項[1]

jaxws:provider要素（jax:bindings要素）[1]

jaxws:provider要素を記述した場合の動作[1]

jaxwsdd:endpoints要素（cosminexus-jaxws.xml）[1]

jaxwsdd:endpoint要素（cosminexus-jaxws.xml）[1]

JAX-WS・JAX-RS仕様の対応バージョン，プレフィクスおよび名前空間URI[1]

JAX-RSエンジン[1]

JAX-RSエンジン〔Webリソース側〕[1]

JAX-RSエンジン〔Webリソースクライアント側〕[1]

JAX-RSエンジンの動作[1]

JAX-RS機能の設定と動作[1]

JAX-RS仕様のサポート範囲[1]

JAX-WS 2.2仕様のサポート範囲[1]

JAX-WS API[1]

JAX-WS APIのインタフェースおよびクラスの種類[1]

JAX-WS APIを使用する場合の実装例[1]

JAX-WSエンジン[1]

JAX-WSエンジンとJAX-RSエンジンの設定[1]

JAX-WSエンジンのサポート範囲（Webサービス側）[1]

JAX-WSエンジンの動作[1]

JAX-WSエンジンの動作（MTOM/XOP）[1]

JAX-WSエンジンの動作とサポート範囲[1]

JAX-WSエンジンの動作とサポート範囲（Webサービスクライアント側）[1]

JAX-WSエンジンのメモリ使用量の算出[1]

JAX-WS機能の設定と動作[1]

JAX-WS機能のログの見積もり方法[1]

JAX-WS仕様のサポート範囲[1]

JSON POJOマッピング[1]

JSON POJOマッピングの設定[1]

JSONからPOJOへのマッピング[1]

L

localName要素（javax.xml.ws.RequestWrapper）[1]

localName要素（javax.xml.ws.ResponseWrapper）[1]

location属性（soap:address要素）[1]

location属性（soap12:address要素）[1]

location属性（wsdl:import要素）[1]、[2]

M

MediaTypeクラス[1]

MessageFactoryクラス[1]

messageName要素（javax.xml.ws.WebFault）[1]

message属性（soap:header要素）[1]

message属性（soap12:header要素）[1]

message属性（wsdl:fault要素）[1]

message属性（wsdl:input要素）[1]

message属性（wsdl:output要素）[1]

MimeHeadersクラス[1]

MimeHeaderクラス[1]

MIME Multipart/Related構造のSOAPメッセージの受信[1]、[2]、[3]

MIMEパートの記述順序（MTOM/XOP）[1]

MIMEパートの記述順序（wsi:swaRef形式）[1]

MIMEパートの終端文字列（添付ファイルからSOAPメッセージ・wsi:swaRef形式）[1]

MIMEバインディング[1]

mode要素（javax.jws.WebParam）[1]

MTOM/XOP仕様形式の添付ファイルで使用するアノテーション[1]

MTOM/XOP仕様形式の添付ファイルのSOAPメッセージ[1]

MTOM/XOP仕様形式の添付ファイルの使用方法[1]

MTOM/XOP仕様形式の添付ファイルの対象[1]

MTOM/XOP仕様形式の添付ファイルのデータサイズによるマッピング方法[1]

MTOMFeature[1]

MultivaluedMapImplクラスのコンストラクタおよびメソッド仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

N

namespace属性（wsdl:import要素）[1]、[2]

namespace要素（javax.xml.bind.annotation.XmlElement）[1]

namespace要素（javax.xml.bind.annotation.XmlType）[1]

name属性（cosminexus-jaxws.xml）[1]

name属性（jaxws:bindings要素）[1]

name属性（portType要素）[1]

name属性（soap:fault要素）[1]

name属性（soap12:fault要素）[1]

name属性（wsdl:binding要素）[1]

name属性（wsdl:definitions要素）[1]

name属性（wsdl:fault要素）[1]、[2]

name属性（wsdl:input要素）[1]、[2]

name属性（wsdl:message要素）[1]

name属性（wsdl:operation要素）[1]、[2]

name属性（wsdl:output要素）[1]、[2]

name属性（wsdl:part要素）[1]

name属性（wsdl:port要素）[1]

name属性（wsdl:service要素）[1]

name要素（javax.jws.WebParam）[1]

name要素（javax.jws.WebResult）[1]

name要素（javax.jws.WebService）[1]

name要素（javax.xml.bind.annotation.XmlElement）[1]

name要素（javax.xml.bind.annotation.XmlType）[1]

name要素（javax.xml.ws.WebFault）[1]

NewCookieクラス[1]

nillable要素（javax.xml.bind.annotation.XmlElement）[1]

Nodeインタフェース[1]

node属性の記述形式（jaxws:bindings要素）[1]

non-wrapperスタイルでのMTOM/XOP仕様形式の添付ファイル（MTOM/XOP）[1]

O

one-wayオペレーション[1]

one-wayオペレーションの注意事項[1]

operationName要素（javax.jws.WebMethod）[1]

org.jvnet.mimepull.MIMEConfigクラス[1]

output要素（javax.xml.ws.Action）[1]

P

parameterStyle要素（javax.jws.soap.SOAPBinding）[1]

parseEagerlyによる変化[1]

partName要素（javax.jws.WebParam）[1]

partName要素（javax.jws.WebResult）[1]

partName要素（javax.xml.ws.RequestWrapper）[1]

partName要素（javax.xml.ws.ResponseWrapper）[1]

parts属性（soap:body要素）[1]

parts属性（soap12:body要素）[1]

part属性（jaxws:bindings要素）[1]

part属性（soap:header要素）[1]

part属性（soap12:header要素）[1]

PathSegmentインタフェース[1]

POJOからJSONへのマッピング[1]

POJOのWebサービスからEJBのWebサービスへの移行[1]

portName要素（javax.jws.WebService）[1]

portName要素（javax.xml.ws.WebServiceProvider）[1]

port属性（cosminexus-jaxws.xml）[1]

PRFデーモンの起動[1]

propOrder要素（javax.xml.bind.annotation.XmlType）[1]

Providerアノテーション[1]

publicId属性[1]

R

Requestインタフェース[1]

required要素（javax.xml.bind.annotation.XmlElement）[1]

required要素（javax.xml.ws.soap.Addressing）[1]

Response.ResponsBuilderクラス[1]

responses要素（javax.xml.ws.soap.Addressing）[1]

Responseクラス[1]

RESTful Webサービス開発のポイント[1]

RESTful Webサービス開発の例[1]

RESTful Webサービスの開発の概要[1]

RESTful Webサービスの開発の流れ[1]

RESTful Webサービスの機能[1]

RESTful Webサービス用クライアント API[1]

RESTful Webサービス用クライアントAPIとJDKの関係[1]

RESTful Webサービス用クライアントAPIとユーザプログラムの関係[1]

RESTful Webサービス用クライアントAPIのサポート範囲[1]

RESTful Webサービス用クライアントAPIの仕組み[1]

RESTful Webサービス用クライアントAPIのスレッドセーフ性[1]

RESTful Webサービス用クライアントAPIを使用するクライアントの実装[1]

RMD[1]

RMS[1]

S

SAAJ 1.3仕様のサポート範囲[1]

SAAJResultクラス[1]

SAAJ仕様のサポート範囲[1]

SecurityContextインタフェース[1]

SEIからバインディングへのマッピング[1]

SEIからバインディングへのマッピング規則[1]

SEIの取得に関する注意事項[1]

SEIの条件[1]

SEIのメソッド名からオペレーションへのマッピング[1]

SEIのメソッド名からオペレーションへのマッピング規則[1]

SEI名およびクラス名の衝突時のマッピング[1]

SEI名からポートタイプへのマッピング[1]

SEI名に記述できる文字列[1]

SEI名の条件[1]

SEI名をjaxws:class要素でカスタマイズした場合のスケルトンクラス名[1]

SEI名をカスタマイズする場合の注意事項[1]

SEIを起点とした開発の流れ[1]

SEIを起点とした開発の流れ（hwsgenコマンドを使用する場合）[1]

SEIを起点とした開発の例[1]

SEIを起点とした開発の例（EJBのWebサービスの場合）[1]

SEIを起点とした開発の例（hwsgenコマンドを使用する場合）[1]

SEIを起点とした開発の例（MTOM/XOP仕様形式の添付ファイル使用時）[1]

SEIを起点とした開発の例（wsi:swaRef形式の添付ファイル使用時）[1]

SEIを起点とした開発の例（アドレッシング機能使用時）[1]

SEIを起点とした開発の例（カスタマイズする場合）[1]

SEIを起点とした開発の例（ストリーミング使用時）[1]

SEIを生成する（WSDL起点）[1]

SEIを生成する（WSDL起点・WS-RM 1.2）[1]

serviceName要素（javax.jws.WebService）[1]

serviceName要素（javax.xml.ws.WebServiceProvider）[1]

servlet-mapping要素の記述例[1]、[2]、[3]

soap:address要素[1]

soap:binding要素[1]

soap:body要素[1]

soap:fault要素[1]

soap:header要素[1]

soap:mustUnderstand属性の設定（Webサービス側）[1]

soap:mustUnderstand属性の設定（Webサービスクライアント側）[1]

soap:operation要素[1]

soap12:address要素[1]

soap12:binding要素[1]

soap12:body要素[1]

soap12:fault要素[1]

soap12:header要素[1]

soap12:operation要素[1]

soapAction属性（soap:operation要素）[1]

soapAction属性（soap12:operation要素）[1]

SOAPActionヘッダに関連するメッセージコンテキストプロパティ[1]

SOAPBodyインタフェース[1]

SOAPElementインタフェース[1]

SOAPEnvelopeインタフェース[1]

SOAPFactoryクラス[1]

SOAPFaultインタフェース[1]

SOAPHeaderElementインタフェース[1]

SOAPHeaderインタフェース[1]

SOAPMessageクラス[1]

SOAPPartクラス[1]

SOAP Webサービス開発の流れ[1]

SOAP Webサービス開発のポイント[1]

SOAP Webサービスの開発の概要[1]

SOAP Webサービスの機能[1]

SOAPトランスポートと転送バインディング[1]

SOAPのバージョン選択[1]

SOAPのバージョン選択（Webサービス開発時）[1]

SOAPのバージョン選択（Webサービスクライアント開発時）[1]

SOAPのバージョン選択（実行時）[1]

SOAPバインディング[1]

SOAPハンドラ[1]

SOAPヘッダが含まれる場合のハンドラの動作（Webサービス側）[1]

SOAPヘッダが含まれる場合のハンドラの動作（Webサービスクライアント側）[1]

SOAPヘッダの設定方法[1]

SOAPメッセージから添付ファイルへのマッピング（MTOM/XOP）[1]

SOAPメッセージから添付ファイルへのマッピング（wsi:swaRef形式）[1]

SOAPロールとアクタの設定（Webサービス側）[1]

SOAPロールとアクタの設定（Webサービスクライアント側）[1]

SSLプロトコルによる接続[1]、[2]

style属性（soap:binding要素）[1]

style属性（soap:operation要素）[1]

style属性（soap12:binding要素）[1]

style属性（soap12:operation要素）[1]

style要素（javax.jws.soap.SOAPBinding）[1]

sun.net.www.http.HttpClientによるリクエスト再送抑止[1]

systemId属性[1]

T

targetNamespace属性（wsdl:definitions要素）[1]

targetNamespace要素（javax.jws.WebParam）[1]

targetNamespace要素（javax.jws.WebResult）[1]

targetNamespace要素（javax.jws.WebService）[1]

targetNamespace要素（javax.xml.ws.RequestWrapper）[1]

targetNamespace要素（javax.xml.ws.ResponseWrapper）[1]

targetNamespace要素（javax.xml.ws.WebFault）[1]

targetNamespace要素（javax.xml.ws.WebServiceProvider）[1]

threshold要素（javax.xml.ws.soap.MTOM）[1]

transport属性（soap:binding要素）[1]

transport属性（soap12:binding要素）[1]

type属性（wsdl:binding要素）[1]

U

UAC（ユーザアカウント制御）[1]

UACが有効なWindowsでコマンドラインインタフェースを使用する場合の注意事項[1]

UniformInterfaceExceptionクラスのメソッド仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

UriBuilderクラス[1]

UriInfoインタフェース[1]

uri属性（er:public要素）[1]

uri属性（er:system要素）[1]

URIテンプレート[1]

URLデコードの無効化[1]

url-pattern属性（cosminexus-jaxws.xml）[1]

use属性（soap:body要素）[1]

use属性（soap:fault要素）[1]

use属性（soap:header要素）[1]

use属性（soap12:body要素）[1]

use属性（soap12:fault要素）[1]

use属性（soap12:header要素）[1]

use要素（javax.jws.soap.SOAPBinding）[1]

V

value要素（javax.xml.bind.annotation.XmlMimeType）[1]

value要素（javax.xml.ws.BindingType）[1]

value要素（javax.xml.ws.FaultAction）[1]

value要素（javax.xml.ws.ServiceMode）[1]

value要素（javax.xml.ws.WebServiceRef）[1]

version属性の記述形式（jaxws:bindings要素）[1]

W

WARファイル[1]、[2]

WARファイルの構成[1]、[2]

web.xmlの作成[1]、[2]

web.xmlの例[1]、[2]

web.xmlをWARファイルに含めない場合の動作[1]

web.xmlを作成する（RESTFul Webサービス）[1]

web.xmlを作成する（SEI起点）[1]

web.xmlを作成する（SEI起点・hwsgenコマンド）[1]

web.xmlを作成する（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

web.xmlを作成する（SEI起点・wsi:swaRef形式の添付ファイル）[1]

web.xmlを作成する（SEI起点・アドレッシング）[1]

web.xmlを作成する（SEI起点・カスタマイズ）[1]

web.xmlを作成する（SEI起点・ストリーミング）[1]

web.xmlを作成する（WSDL起点）[1]

web.xmlを作成する（WSDL起点・WS-RM 1.2）[1]

web.xmlを作成する（プロバイダ起点・SAAJ）[1]

WebResource.Builderクラスのメソッド仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

WebResourceクラスのメソッド仕様と注意事項〔RESTful Webサービス用クライアントAPI〕[1]

Webサービス側JAX-WSエンジンの動作（MTOM/XOP）[1]

Webサービス側のJAX-WSエンジンの動作（アドレッシング機能使用時）[1]

Webサービス側のフォルトおよび例外の処理[1]

Webサービスクライアント開発の流れ[1]

Webサービスクライアント側JAX-WSエンジンの動作（MTOM/XOP）[1]

Webサービスクライアント側のJAX-WSエンジンの動作（アドレッシング機能使用時）[1]

Webサービスクライアント側のフォルトの処理[1]

Webサービスクライアントでストリーミングを使用する[1]

WebサービスクライアントでのHANDLERスコープのメッセージコンテキストプロパティ[1]

Webサービスクライアントのインスタンス生成〔サービスクラスおよびポートのインジェクション〕[1]

Webサービスクライアントの開発例（SEI起点）[1]

Webサービスクライアントの開発例（SEI起点・EJBのWebサービス）[1]

Webサービスクライアントの開発例（SEI起点・hwsgenコマンド）[1]

Webサービスクライアントの開発例（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

Webサービスクライアントの開発例（SEI起点・wsi:swaRef形式の添付ファイル）[1]

Webサービスクライアントの開発例（SEI起点・アドレッシング）[1]

Webサービスクライアントの開発例（SEI起点・カスタマイズ）[1]

Webサービスクライアントの開発例（SEI起点・ストリーミング）[1]

Webサービスクライアントの開発例（WSDL起点）[1]

Webサービスクライアントの開発例（WSDL起点・WS-RM 1.2）[1]

Webサービスクライアントの開発例（プロバイダ起点・SAAJ）[1]

Webサービスクライアントの実装[1]

Webサービスクライアントの実装クラスにシーケンス終了処理を追加する（WSDL起点・WS-RM 1.2）[1]

Webサービスクライアントの実装クラスをコンパイルする（SEI起点）[1]

Webサービスクライアントの実装クラスをコンパイルする（SEI起点・EJBのWebサービス）[1]

Webサービスクライアントの実装クラスをコンパイルする（SEI起点・hwsgenコマンド）[1]

Webサービスクライアントの実装クラスをコンパイルする（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

Webサービスクライアントの実装クラスをコンパイルする（SEI起点・wsi:swaRef形式の添付ファイル）[1]

Webサービスクライアントの実装クラスをコンパイルする（SEI起点・アドレッシング）[1]

Webサービスクライアントの実装クラスをコンパイルする（SEI起点・カスタマイズ）[1]

Webサービスクライアントの実装クラスをコンパイルする（SEI起点・ストリーミング）[1]

Webサービスクライアントの実装クラスをコンパイルする（WSDL起点）[1]

Webサービスクライアントの実装クラスをコンパイルする（WSDL起点・WS-RM 1.2）[1]

Webサービスクライアントの実装クラスをコンパイルする（プロバイダ起点・SAAJ）[1]

Webサービスクライアントの実装クラスを作成する（SEI起点）[1]

Webサービスクライアントの実装クラスを作成する（SEI起点・EJBのWebサービス）[1]

Webサービスクライアントの実装クラスを作成する（SEI起点・hwsgenコマンド）[1]

Webサービスクライアントの実装クラスを作成する（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

Webサービスクライアントの実装クラスを作成する（SEI起点・wsi:swaRef形式の添付ファイル）[1]

Webサービスクライアントの実装クラスを作成する（SEI起点・アドレッシング）[1]

Webサービスクライアントの実装クラスを作成する（SEI起点・カスタマイズ）[1]

Webサービスクライアントの実装クラスを作成する（SEI起点・ストリーミング）[1]

Webサービスクライアントの実装クラスを作成する（WSDL起点）[1]

Webサービスクライアントの実装クラスを作成する（WSDL起点・WS-RM 1.2）[1]

Webサービスクライアントの実装クラスを作成する（プロバイダ起点・SAAJ）[1]

Webサービスクライアントの実装例（JAX-WS APIを使用）[1]

Webサービスクライアントの実装例（ディスパッチベース）[1]

Webサービスクライアントを実行する（SEI起点）[1]

Webサービスクライアントを実行する（SEI起点・EJBのWebサービス）[1]

Webサービスクライアントを実行する（SEI起点・hwsgenコマンド）[1]

Webサービスクライアントを実行する（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

Webサービスクライアントを実行する（SEI起点・wsi:swaRef形式の添付ファイル）[1]

Webサービスクライアントを実行する（SEI起点・アドレッシング）[1]

Webサービスクライアントを実行する（SEI起点・カスタマイズ）[1]

Webサービスクライアントを実行する（SEI起点・ストリーミング）[1]

Webサービスクライアントを実行する（WSDL起点）[1]

Webサービスクライアントを実行する（WSDL起点・WS-RM 1.2）[1]

Webサービスクライアントを実行する（プロバイダ起点・SAAJ）[1]

Webサービスコンテキストのインジェクション[1]

Webサービス実装クラスおよびプロバイダ実装クラスの作成[1]

Webサービス実装クラスからSEIへのマッピング[1]

Webサービス実装クラスからサービスおよびポートへのマッピング[1]

Webサービス実装クラスからサービスおよびポートへのマッピング規則[1]

Webサービス実装クラスの条件[1]

Webサービス実装クラス名に記述できる文字列[1]

Webサービス実装クラス名の条件[1]

Webサービス実装クラスをコンパイルする（SEI起点）[1]

Webサービス実装クラスをコンパイルする（SEI起点・EJBのWebサービス）[1]

Webサービス実装クラスをコンパイルする（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

Webサービス実装クラスをコンパイルする（SEI起点・wsi:swaRef形式の添付ファイル）[1]

Webサービス実装クラスをコンパイルする（SEI起点・アドレッシング）[1]

Webサービス実装クラスをコンパイルする（SEI起点・カスタマイズ）[1]

Webサービス実装クラスをコンパイルする（SEI起点・ストリーミング）[1]

Webサービス実装クラスをコンパイルする（WSDL起点）[1]

Webサービス実装クラスをコンパイルする（WSDL起点・WS-RM 1.2）[1]

Webサービス実装クラスを作成する（SEI起点）[1]

Webサービス実装クラスを作成する（SEI起点・EJBのWebサービス）[1]

Webサービス実装クラスを作成する（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

Webサービス実装クラスを作成する（SEI起点・wsi:swaRef形式の添付ファイル）[1]

Webサービス実装クラスを作成する（SEI起点・アドレッシング）[1]

Webサービス実装クラスを作成する（SEI起点・カスタマイズ）[1]

Webサービス実装クラスを作成する（SEI起点・ストリーミング）[1]

Webサービス実装クラスを作成する（WSDL起点）[1]

Webサービス実装クラスを作成する（WSDL起点・WS-RM 1.2）[1]

Webサービスセキュリティ機能を使用する場合の注意事項[1]

Webサービスセキュリティハンドラ[1]

Webサービスでストリーミングを使用する[1]

Webサービスとクライアントの形態[1]

Webサービスのアンデプロイ[1]

Webサービスの開発および実行の前提条件[1]

Webサービスの開発時および実行時に使用する機能[1]

Webサービスの開発の概要[1]

Webサービスの開発例（SEI起点）[1]

Webサービスの開発例（SEI起点・EJBのWebサービス）[1]

Webサービスの開発例（SEI起点・hwsgenコマンド）[1]

Webサービスの開発例（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

Webサービスの開発例（SEI起点・wsi:swaRef形式の添付ファイル）[1]

Webサービスの開発例（SEI起点・アドレッシング）[1]

Webサービスの開発例（SEI起点・カスタマイズ）[1]

Webサービスの開発例（SEI起点・ストリーミング）[1]

Webサービスの開発例（WSDL起点）[1]

Webサービスの開発例（WSDL起点・WS-RM 1.2）[1]

Webサービスの開発例（プロバイダ起点・SAAJ）[1]

Webサービスの形態[1]

Webサービスの実行例（SEI起点）[1]

Webサービスの実行例（SEI起点・EJBのWebサービス）[1]

Webサービスの実行例（SEI起点・hwsgenコマンド）[1]

Webサービスの実行例（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

Webサービスの実行例（SEI起点・wsi:swaRef形式の添付ファイル）[1]

Webサービスの実行例（SEI起点・アドレッシング）[1]

Webサービスの実行例（SEI起点・カスタマイズ）[1]

Webサービスの実行例（SEI起点・ストリーミング）[1]

Webサービスの実行例（WSDL起点）[1]

Webサービスの実行例（WSDL起点・WS-RM 1.2）[1]

Webサービスの実行例（プロバイダ起点・SAAJ）[1]

Webサービスの情報表示[1]

Webサービスの初期化[1]

Webサービスの初期化と破棄[1]

Webサービスの破棄[1]

Webサービスを開始する（RESTFul Webサービス）[1]

Webサービスを開始する（SEI起点）[1]

Webサービスを開始する（SEI起点・EJBのWebサービス）[1]

Webサービスを開始する（SEI起点・hwsgenコマンド）[1]

Webサービスを開始する（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

Webサービスを開始する（SEI起点・wsi:swaRef形式の添付ファイル）[1]

Webサービスを開始する（SEI起点・アドレッシング）[1]

Webサービスを開始する（SEI起点・カスタマイズ）[1]

Webサービスを開始する（SEI起点・ストリーミング）[1]

Webサービスを開始する（WSDL起点）[1]

Webサービスを開始する（WSDL起点・WS-RM 1.2）[1]

Webサービスを開始する（プロバイダ起点・SAAJ）[1]

Webリソースクライアント実装時の注意事項〔RESTful Webサービス用クライアントAPI〕[1]

Webリソースクライアントの実装クラスを作成する（java.net.HttpURLConnectionを利用する）〔RESTFul Webサービス〕[1]

Webリソースクライアントの実装クラスを作成する（クライアントAPIを利用する）〔RESTFul Webサービス〕[1]

Webリソースクライアントのユースケース[1]

Webリソース初期化時の構文チェック（KDJJ20003-WとKDJJ10006-E）[1]

Webリソースとプロバイダ[1]

Webリソースの開発例（RESTFul Webサービス）[1]

Webリソースの呼び出し例（RESTFul Webサービス）[1]

Webリソースクライアントの開発例〔RESTFul Webサービス〕[1]

Webリソースクライアントの実装クラスをコンパイルする〔RESTFul Webサービス〕[1]

Webリソースクライアントを実行する（RESTFul Webサービス）[1]

wrapper子要素名に記述できる文字列（wrapperスタイル）[1]

wrapperスタイルの条件[1]

wsa:Action要素指定時の動作[1]

wsa:Action要素の注意事項[1]

wsa:MessageID要素を指定していない場合の動作[1]

wsaw:Action属性およびwsam:Action属性の注意事項[1]

wsaw:Anonymous要素指定時の動作[1]

wsdl:binding要素[1]

wsdl:definitions要素[1]

wsdl:documentation要素[1]

wsdl:fault要素（wsdl:binding要素の孫要素の場合）[1]

wsdl:fault要素（wsdl:portType要素の孫要素の場合）[1]

wsdl:import要素[1]

wsdl:import要素の書式[1]

wsdl:input要素（wsdl:binding要素の孫要素の場合）[1]

wsdl:input要素（wsdl:portType要素の孫要素の場合）[1]

wsdl:message要素[1]

wsdl:operation要素（wsdl:binding要素の子要素の場合）[1]

wsdl:operation要素（wsdl:portType要素の子要素の場合）[1]

wsdl:output要素（wsdl:binding要素の孫要素の場合）[1]

wsdl:output要素（wsdl:portType要素の孫要素の場合）[1]

wsdl:part要素[1]

wsdl:portType要素[1]

wsdl:port要素[1]

wsdl:service要素[1]

wsdl:types要素[1]

WSDL 1.1仕様のサポート範囲[1]

wsdlLocation属性の記述形式（jaxws:bindings要素）[1]

wsdlLocation要素（javax.jws.WebService）[1]

wsdlLocation要素（javax.xml.ws.WebServiceProvider）[1]

wsdlLocation要素（javax.xml.ws.WebServiceRef）[1]

WSDLインポート機能[1]、[2]

WSDLオペレーションの名前に関連するメッセージコンテキストプロパティ[1]

WSDLからJavaソースへのマッピング一覧[1]

WSDLからJavaソースへのマッピング例[1]

WSDLからJavaへのデフォルトマッピング[1]

WSDLからJavaへのマッピング[1]

WSDLからJavaへのマッピングに関する注意事項[1]

WSDLからJavaへのマッピングのカスタマイズ[1]

WSDLから添付ファイルのJava型へのマッピング（wsi:swaRef形式）[1]

WSDL作成時の注意事項[1]

WSDL仕様のサポート範囲[1]

WSDL定義の階層的なインポート[1]

WSDL定義の再帰的なインポート[1]

WSDLとJavaソースのマッピング[1]

WSDLに関連するメッセージコンテキストプロパティ[1]

WSDLのsoap12:binding要素のtransport属性についての注意[1]

WSDLの拡張属性[1]

WSDLの拡張要素[1]

WSDLの拡張要素と拡張属性[1]

WSDLの作成[1]

WSDLファイルにWS-RM Policyを追加する（WSDL起点・WS-RM 1.2）[1]

WSDLファイルを作成する（SEI起点）[1]

WSDLファイルを作成する（SEI起点・EJBのWebサービス）[1]

WSDLファイルを作成する（WSDL起点）[1]

WSDLファイルを作成する（WSDL起点・WS-RM 1.2）[1]

WSDLを起点とした開発の流れ[1]

WSDLを起点とした開発の例[1]

WSDLを起点とした開発の例（WS-RM 1.2機能使用時）[1]

WSIMPORT_OPTS環境変数[1]

WS-Policyによる設定[1]

WS-RM 1.2機能[1]、[2]

WS-RM 1.2機能の送達保証[1]

WS-RM 1.2機能を使用したメッセージの流れ[1]

WS-RM 1.2機能を使用する場合のサービスエンドポイントのアドレスの指定[1]

WS-RM 1.2仕様のサポート範囲[1]

WS-RM Policy 1.2仕様のサポート範囲[1]

WS-RM Policyの追加方法[1]

WS-RM仕様のサポート範囲[1]

X

XML Catalogs 1.1仕様のサポート範囲の一覧[1]

XML Catalogs 1.1仕様のサポート範囲の詳細[1]

XML Catalogs 1.1のサポート範囲[1]

XML Schemaの出現回数の指定に関する制限[1]

XML Schemaの制約ファセットに関する制限[1]

XML Schemaのデータ型の制限[1]

XOP情報セットの形式[1]

xsd:schema要素[1]

あ

アーカイブの作成[1]、[2]

アウトバウンド[1]

アドレッシング機能[1]、[2]

アドレッシング機能で使用するアノテーションの注意事項[1]

アドレッシング機能を使用したWebサービスにアクセスする場合の注意事項[1]

アノテーション（JAX-RS）[1]

アノテーション一覧[1]

アノテーションの継承[1]

アノテーションのサポート範囲[1]

アプリケーション起動時のメモリ使用量[1]

アプリケーションのクライアントの実行[1]

アンマーシャル[1]

い

異常終了時の対処（cjwsimportコマンド）[1]

異常終了時の対処（hwsgenコマンド）[1]

一時ファイル（ストリーミング）[1]

インジェクション[1]

インジェクション用アノテーション（JAX-RS）[1]

インタフェースおよびクラスの一覧（JAX-WS）[1]

インタフェースおよびクラスの一覧表[1]

インタフェースおよびクラスのサポート範囲[1]

インタフェースおよびクラスの種類[1]

インタフェースの透過性[1]

インバウンド[1]

インポート／インクルードしている場合の注意[1]

インポート対象のWSDL定義の条件[1]

インポートできるWSDL定義[1]

う

埋め込みによるバインディング宣言[1]

埋め込みによるバインディング宣言と外部バインディングファイルの同時指定[1]

え

エラーページ[1]

エラーページをカスタマイズする場合の注意事項[1]

エンティティパラメタ[1]

エンティティプロバイダ[1]

お

オーバーロードによる名前衝突[1]

オプションの指定有無とファイルの出力先[1]

オペレーションからメソッド名へのマッピング[1]

オペレーションとその子要素の記述個数[1]

オペレーション名に記述できる文字列[1]

オペレーション名の条件[1]

か

開発例の構成（RESTFul Webサービス）[1]

開発例の構成（SEI起点）[1]

開発例の構成（SEI起点・EJBのWebサービス）[1]

開発例の構成（SEI起点・hwsgenコマンド）[1]

開発例の構成（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

開発例の構成（SEI起点・wsi:swaRef形式の添付ファイル）[1]

開発例の構成（SEI起点・アドレッシング）[1]

開発例の構成（SEI起点・カスタマイズ）[1]

開発例の構成（SEI起点・ストリーミング）[1]

開発例の構成（WSDL起点）[1]

開発例の構成（WSDL起点・WS-RM 1.2）[1]

開発例の構成（プロバイダ起点・SAAJ）[1]

開発例の流れ（RESTFul Webサービス）[1]

開発例の流れ（SEI起点）[1]

開発例の流れ（SEI起点・EJBのWebサービス）[1]

開発例の流れ（SEI起点・hwsgenコマンド）[1]

開発例の流れ（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

開発例の流れ（SEI起点・wsi:swaRef形式の添付ファイル）[1]

開発例の流れ（SEI起点・アドレッシング）[1]

開発例の流れ（SEI起点・カスタマイズ）[1]

開発例の流れ（SEI起点・ストリーミング）[1]

開発例の流れ（WSDL起点）[1]

開発例の流れ（WSDL起点・WS-RM 1.2）[1]

開発例の流れ（プロバイダ起点・SAAJ）[1]

外部バインディングファイルによるカスタマイズ[1]

各MIMEパート間の境界文字列（添付ファイルからSOAPメッセージ・wsi:swaRef形式）[1]

カスタマイズ対象となった要素の値[1]

カタログ機能[1]、[2]

カタログ機能とは[1]

カタログ機能の性能[1]

カタログ機能の利用（Webサービスクライアントの開発時）[1]

カタログ機能の利用（Webサービスクライアントの実行時）[1]

カタログ機能利用時の注意事項[1]

カタログファイル[1]

カタログファイルの記述例[1]

カタログファイルの構文[1]

カタログファイルの配置[1]

稼働ログ[1]

き

期待した性能が出ない[1]

旧バージョンからの移行[1]

旧バージョンで作成したWSDLの互換性[1]

共通定義ファイル[1]、[2]

共通定義ファイルの設定項目[1]

共通定義ファイルの設定項目（JAX-RS）[1]

く

クライアントAPI[1]、[2]

クライアントAPIのインタフェースおよびクラスのサポート範囲[1]

クライアントAPIの使用時に発生する例外（KDJJ18888-E）[1]

クライアントアプリケーション情報とルートアプリケーション情報の有効範囲[1]

クライアント側のハンドラで操作しても意味のないメッセージコンテキストプロパティ[1]

クライアントの形態[1]

クラスベースのマッピング[1]

こ

コアAPI[1]、[2]

コマンド[1]、[2]

コマンドラインの実行[1]

コマンドライン利用時の設定[1]

コマンドライン利用時の注意事項[1]

コマンドラインを利用したクライアントアプリケーションの実行[1]

コンテキスト（JAX-RS）[1]

コンパイル済みのクラスファイルを保存する（SEI起点・hwsgenコマンド）[1]

さ

サービスAPI[1]、[2]

サービスおよびポートからサービスクラスへのマッピング[1]

サービスクラスおよびポートのインジェクション[1]

サービスクラスへのハンドラチェインの設定[1]

サービスクラスを生成する（SEI起点）[1]

サービスクラスを生成する（SEI起点・EJBのWebサービス）[1]

サービスクラスを生成する（SEI起点・hwsgenコマンド）[1]

サービスクラスを生成する（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

サービスクラスを生成する（SEI起点・wsi:swaRef形式の添付ファイル）[1]

サービスクラスを生成する（SEI起点・アドレッシング）[1]

サービスクラスを生成する（SEI起点・カスタマイズ）[1]

サービスクラスを生成する（SEI起点・ストリーミング）[1]

サービスクラスを生成する（WSDL起点）[1]

サービスクラスを生成する（WSDL起点・WS-RM 1.2）[1]

サービス固有例外の処理[1]

サービス名およびポート名に記述できる文字列[1]

サービス名およびポート名の条件[1]

サブリソースクラス[1]

サポートしていないサブサブコード[1]

サポートするプロパティとフィーチャ[1]

し

シーケンスライフサイクルメッセージ[1]

ジェネリクス型の制限[1]

ジェネリクスの型削除[1]

ジェネリクスを使用したクラスまたはインタフェースの使用について[1]

指定できるデータ型〔JSONからPOJOへのマッピング〕[1]

指定できるデータ型〔POJOからJSONへのマッピング〕[1]

自動生成クラス[1]

受信したHTTPリクエストの処理で検出されるエラー[1]

受信したデータの取得方法（MTOM/XOP形式）[1]

障害対策[1]

障害の種類と対策[1]

障害発生時に取得する資料[1]

使用できるHTTPメソッド[1]

使用できるバインディング宣言（埋め込みによるバインディング宣言）[1]

使用できるバインディング宣言（外部バインディングファイル）[1]

す

スキーマ型からJava型へのマッピング[1]

スケルトンクラスへのマッピング[1]

スタブベースのWebサービスクライアントの開発の流れ[1]

スタブベースの実装例[1]

ストリーミング[1]、[2]

ストリーミングされた添付ファイルの操作[1]

ストリーミングの使用方法[1]

せ

生成されるラッパ例外クラス[1]

性能解析トレース（PRF）[1]

性能解析トレースによる性能解析方法[1]

性能解析トレースの取得レベル[1]

性能解析トレースのトレース出力情報[1]

性能解析トレースのトレース取得ポイント[1]

前提条件[1]

前提となる構成ソフトウェア[1]

そ

送信するデータごとのJavaオブジェクトの生成方法（MTOM/XOP形式）[1]

送達保証の種類[1]

存在するXMLファイルを送信する場合（MTOM/XOP形式）[1]

存在するイメージファイルを送信する場合（MTOM/XOP形式）[1]

存在するテキストファイルを送信する場合（MTOM/XOP形式）[1]

た

対応付け〔カタログ機能〕[1]

単位時間当たりのメモリ使用量の算出[1]

ち

注意事項[1]

注意事項（MTOM/XOP）[1]

つ

通信ログ[1]

通信ログに出力されるHTTPヘッダ名[1]

通信ログの文字エンコーディング[1]

て

ディスカバリ[1]、[2]、[3]、[4]

ディスカバリとディスパッチ（JAX-RS）[1]

ディスカバリとディスパッチ（JAX-WS）[1]

ディスパッチ[1]、[2]、[3]

ディスパッチベースのWebサービスクライアントの開発の流れ[1]

ディスパッチベースの実装例[1]

デプロイと開始の例（RESTFul Webサービス）[1]

デプロイと開始の例（SEI起点）[1]

デプロイと開始の例（SEI起点・EJBのWebサービス）[1]

デプロイと開始の例（SEI起点・hwsgenコマンド）[1]

デプロイと開始の例（SEI起点・MTOM/XOP仕様形式の添付ファイル）[1]

デプロイと開始の例（SEI起点・wsi:swaRef形式の添付ファイル）[1]

デプロイと開始の例（SEI起点・アドレッシング）[1]

デプロイと開始の例（SEI起点・カスタマイズ）[1]

デプロイと開始の例（SEI起点・ストリーミング）[1]

デプロイと開始の例（WSDL起点）[1]

デプロイと開始の例（WSDL起点・WS-RM 1.2）[1]

デプロイと開始の例（プロバイダ起点・SAAJ）[1]

添付ファイルからSOAPメッセージへのマッピング（MTOM/XOP）[1]

添付ファイルからSOAPメッセージへのマッピング（wsi:swaRef形式）[1]

添付ファイルからSOAPメッセージへのマッピングの注意事項（MTOM/XOP）[1]

添付ファイルからSOAPメッセージへのマッピングの注意事項（wsi:swaRef形式）[1]

添付ファイル機能（MTOM/XOP）[1]、[2]

添付ファイル機能（wsi:swaRef）[1]

添付ファイル機能（wsi:swaRef形式）[1]

添付ファイル使用時のWSDLの記述（wsi:swaRef形式）[1]

添付ファイル付きSOAPメッセージ[1]

添付ファイル付きSOAPメッセージ（wsi:swaRef形式）[1]

添付ファイル付きSOAPメッセージの構造[1]

添付ファイルデータを取得する方法（wsi:swaRef形式）[1]

添付ファイルで使用できるJava型と送受信できるデータ（MTOM/XOP形式）[1]

添付ファイルに使用できるJava型[1]

添付ファイルのJavaインスタンスの生成と取得（wsi:swaRef形式）[1]

添付ファイルのJavaインタフェース（MTOM/XOP）[1]

添付ファイルのJavaインタフェース（wsi:swaRef形式）[1]

添付ファイルのJava型とWSDLのマッピング（wsi:swaRef形式）[1]

添付ファイルのWSDL（MTOM/XOP）[1]

添付ファイルのWSDL（wsi:swaRef形式）[1]

添付ファイルのインスタンスを生成する方法（wsi:swaRef形式）[1]

添付ファイルの拡張子とMIMEタイプのマッピング[1]

添付ファイルのデータサイズ[1]

添付ファイルパートのMIMEヘッダ（添付ファイルからSOAPメッセージ・MTOM/XOP）[1]

添付ファイルパートのMIMEヘッダ（添付ファイルからSOAPメッセージ・wsi:swaRef形式）[1]

添付ファイルパートのMIMEヘッダとMIMEボディの境界文字列（添付ファイルからSOAPメッセージ・wsi:swaRef形式）[1]

添付ファイルパートのMIMEボディ（添付ファイルからSOAPメッセージ・wsi:swaRef形式）[1]

添付ファイルを指定できる個所[1]

添付ファイルを使用する場合のサポート範囲（SAAJ）[1]

と

同期通信[1]

動作環境の切り替え[1]

動作定義の優先度[1]

動作定義ファイル（JAX-RS）[1]

動作定義ファイル（JAX-WS）[1]

動作定義ファイルの記述規則[1]

動作定義ファイルの記述規則（JAX-RS）[1]

トラブルシュート[1]

な

名前空間からパッケージ名へのマッピング[1]

名前空間に記述できる文字列[1]

名前空間の記述形式[1]

名前空間の条件[1]

名前衝突時の対応[1]

名前衝突時の動作（wrapperスタイル）[1]

名前衝突時のマッピング[1]

名前衝突の優先順位と解決方法[1]

は

バージョンアップインストール[1]

パートの種類とJavaソースへのマッピングの関係（non-wrapperスタイル）[1]

パートの種類とJavaソースへのマッピングの関係（wrapperスタイル）[1]

パート名に記述できる文字列（non-wrapperスタイル）[1]

配列[1]

バインディング拡張要素からパラメタへのマッピング[1]

パス指定用アノテーション[1]

パス情報[1]

パッケージ名から名前空間へのマッピング[1]

パッケージ名のカスタマイズ[1]

パッケージ名の条件[1]

パラメタおよび戻り値からメッセージのパートへのマッピング（non-wrapperスタイルの場合）[1]

パラメタおよび戻り値からメッセージのパートへのマッピング（wrapperスタイルの場合）[1]

パラメタ型[1]

パラメタと戻り値の組み合わせ（non-wrapperスタイル）[1]

パラメタと戻り値の組み合わせ（wrapperスタイル）[1]

パラメタに指定できるJava型（non-wrapperスタイル）[1]

パラメタに指定できるJava型（wrapperスタイル）[1]

ハンドラチェイン設定ファイルの構文[1]

ハンドラチェイン設定ファイルのサポート範囲[1]

ハンドラチェイン設定ファイルの配置[1]

ハンドラチェインの設定（Webサービス側）[1]

ハンドラチェインの設定（Webサービスクライアント側）[1]

ハンドラチェインの編成[1]

ハンドラチェインを設定するコードの追加[1]

ハンドラの型[1]

ハンドラの初期化と破棄[1]

ハンドラの配置[1]

ハンドラフレームワーク[1]、[2]

ハンドラフレームワークの使用〔サービスクラスおよびポートのインジェクション〕[1]

ハンドラリゾルバの例[1]

汎用型でHTTPリクエストおよびHTTPレスポンスを送受信する〔Webリソースクライアントのユースケース〕[1]

ひ

非同期通信[1]

ビルトイン要求メソッド識別子（JAX-RS）[1]

ふ

フィーチャの有効化〔サービスクラスおよびポートのインジェクション〕[1]

フォルトbeanへのマッピング[1]

フォルトから参照されるメッセージのパートの個数[1]

フォルトから例外クラスへのマッピング[1]

フォルトと例外の処理[1]

フォルト名に記述できる文字列[1]

フォルト名の条件[1]

フォルトメッセージ[1]

フォルトメッセージの注意事項[1]

複数のWSDL定義のインポート[1]

プロキシサーバ経由の接続[1]、[2]

プログラムが意図したとおりに動作しない[1]

プログラムの実行中に異常終了する[1]

プロセス別の定義ファイル[1]、[2]

プロセス別の定義ファイルの設定[1]

プロセス別の定義ファイルの設定[1]

プロトコルハンドラ[1]

プロバイダ[1]

プロバイダ実装クラスを作成する[1]

プロバイダを起点とした開発の流れ[1]

プロバイダを起点とした開発の例（SAAJを利用した場合）[1]

プロパティとフィーチャの設定〔RESTful Webサービス用クライアントAPI〕[1]

へ

ベーシック認証による接続[1]、[2]

ほ

ポートタイプからSEI名へのマッピング[1]

ポートタイプに記述できる文字列[1]

ポートタイプの記述個数[1]

ポートタイプ名の条件[1]

ポートへのハンドラチェインの設定[1]

保守ログ[1]

ま

マーシャル[1]

マッピング（wrapperスタイル）[1]

マッピング中に発生する例外〔JSON POJOマッピング〕[1]

マッピング要件〔JSONからPOJOへのマッピング〕[1]

マッピング要件〔POJOからJSONへのマッピング〕[1]

め

メソッドのパラメタおよび戻り値からメッセージのパートへのマッピング規則[1]

メソッド名およびパラメタ名の衝突時のマッピング[1]

メソッド名に記述できる文字列[1]

メソッド名の条件[1]

メタデータの発行[1]

メタデータの発行（JAX-RS）[1]

メタデータの発行条件[1]、[2]

メタデータ発行の有効／無効[1]

メッセージコンテキスト使用時の注意事項[1]

メッセージコンテキストの使用[1]

メッセージコンテキストのプロパティのサポート範囲[1]

メッセージ送受信時の動作[1]

メッセージのパートからパラメタおよび戻り値へのマッピング（non-wrapperスタイルの場合）[1]

メッセージのパートからパラメタおよび戻り値へのマッピング（wrapperスタイルの場合）[1]

メディアタイプ宣言（RESTFul Webサービス）[1]

メディアタイプ宣言用アノテーション[1]

ゆ

ユーザ定義メッセージコンテキストプロパティ追加時の注意事項〔Webサービスコンテキストのインジェクション〕[1]

よ

要求コンテキストのプロパティ変更〔サービスクラスおよびポートのインジェクション〕[1]

ら

ラッパbeanの動的生成機能[1]

ラッパ例外クラスからフォルトへのマッピング規則[1]

ラッパ例外クラスの条件[1]

ラッパ例外クラス名に記述できる文字列[1]

ラッパ例外クラス名の条件[1]

ランタイム例外のバインディング[1]

り

リクエストメッセージ受信時の動作[1]

リソースクラス[1]

リソースメソッドの戻り値[1]

る

ルートパートから添付ファイルへのマッピング（MTOM/XOP）[1]

ルートパートから添付ファイルへのマッピング（wsi:swaRef形式）[1]

ルートパートのMIMEヘッダ（添付ファイルからSOAPメッセージ・MTOM/XOP）[1]

ルートパートのMIMEヘッダ（添付ファイルからSOAPメッセージ・wsi:swaRef形式）[1]

ルートパートのMIMEヘッダとMIMEボディの境界文字列（添付ファイルからSOAPメッセージ・wsi:swaRef形式）[1]

ルートパートのMIMEボディ（添付ファイルからSOAPメッセージ・MTOM/XOP）[1]

ルートパートのMIMEボディ（添付ファイルからSOAPメッセージ・wsi:swaRef形式）[1]

ルートリソースクラス[1]

ルートリソースクラスの作成[1]

ルートリソースクラスを作成する（RESTFul Webサービス）[1]

れ

例外のマッピング[1]

例外ハンドリング[1]

例外ハンドリング〔JSONからPOJOへのマッピング〕[1]

例外ハンドリング〔POJOからJSONへのマッピング〕[1]

例外マッピングプロバイダ[1]

例外マッピングプロバイダで処理できる例外[1]

例外ログ[1]

レスポンスメッセージ[1]

ろ

ログ[1]

ログの重要度[1]

ログの重要度と出力条件[1]

ログの出力先[1]

ログの出力先（J2EEサーバ上で動作するWebサービスやWebサービスクライアントの場合）[1]

ログの出力先（J2EEサーバ上で動作するWebリソースやWebリソースクライアントの場合）[1]

ログの出力先（コマンドラインインタフェースでWebサービスクライアントを利用する場合）[1]

ログの出力先（コマンドラインインタフェースでWebリソースクライアントを利用する場合）[1]

ログの出力先（コマンドを実行する場合）[1]

ログの出力条件（稼働ログ／例外ログ／保守ログ）[1]

ログの出力条件（通信ログ）[1]

ログの種類[1]

ログの設定方法[1]

ログのフォーマット[1]

ログのフォーマット（稼働ログ／保守ログ）[1]

ログのフォーマット（例外ログ／通信ログ）[1]

ログの見積もり[1]

ログファイルのローテーション[1]

論理ハンドラ[1]