Axis リファレンスガイド
バージョン 1.2
フィードバック: axis-dev@ws.apache.org
目次
ツールリファレンス
WSDL2Java リファレンス
使い方: java org.apache.axis.wsdl.WSDL2Java [オプション] WSDL-URI
オプション:
-h, --help
このメッセージを出力して終了します
-v, --verbose
詳細なメッセージを出力します
-n, --noImports
インポートされた WSDL ドキュメントを除いた WSDL ドキュメントを対象としたコード
を生成します
-O, --timeout <引数>
タイムアウト秒を指定します (デフォルトは45、無効にするには -1 を指定します)
-D, --Debug
デバッグ情報を出力します
-W, --noWrapped
"wrapped" document/literal サポートを止めます
-s, --server-side
Webサービスのためのサーバサイドバインディングを生成します
-S, --skeletonDeploy <引数>
deploy.wsdd にスケルトン(true)、あるいは実装(false)を配備します
デフォルトは false です。--server-side を前提とします
-N, --NStoPkg <引数>=<値>
名前空間をパッケージにマッピングします
-f, --fileNStoPkg <引数>
NStoPkg マッピングのファイルを指定します (デフォルトは NStoPkg.properties)
-p, --package <引数>
全ての名前空間をパッケージマッピングで上書きし、代わりにこのパッケージ名を使い
ます
-o, --output <引数>
生成されるファイルの出力ディレクトリを指定します
-d, --deployScope <引数>
deploy.xml にスコープを追加します : "Application", "Request", "Session"
-t, --testCase
Webサービスのための junit テストケースクラスを生成します
-a, --all
全ての要素(参照していない要素を含む)のコードを生成します
-T, --typeMappingVersion
1.1、あるいは 1.2 を指し示します。デフォルトは 1.1 です (SOAP 1.1 JAX-RPC 準拠
。1.2 は SOAP 1.1 エンコードを指し示します)。
-F, --factory <引数>
GeneratorFactory インターフェースを実装する(Java の生成関数を拡張するための)カ
スタムクラスの名前を指定します
-i, --nsInclude <名前空間>
生成されたコードに明確に含める名前空間(-x オプションで明確に除外しない限り、デ
フォルトでは全ての名前空間になります)
-x, --nsExclude <名前空間>
生成されたコードに明確に含めない名前空間(-i オプションで最初の名前空間を含めな
い限り、デフォルトでは除外されなくなります)
-p, --property <名前>=<値>
カスタムの GeneratorFactory が利用するプロパティの名前と値
-H, --helperGen
メタデータのための、別のヘルパークラスを生成します
-U, --user <引数>
WSDL-URI にアクセスするためのユーザ名を指定します
-P, --password <引数>
WSDL-URI にアクセスするためのパスワードを指定します
-c, --implementationClassName <引数>
引数を実装クラスとして利用します。
- -h, --help
- 使用例を出力して終了します
- -v, --verbose
- ツールが生成している際に、何を生成しているのか表示します
- -n, --noImports
- コマンドラインに現れる WSDL ドキュメントのコードのみ生成します。デフォルトでは、全ての WSDL ドキュメント、つまりインポートされた WSDL ドキュメントを除いた WSDL ドキュメントと、インポートした全ての WSDL ドキュメントのファイルを生成します。
- -O, --timeout
- タイムアウト秒を指定します。デフォルトは45です。無効にするには -1 を指定します。
- -D, --Debug
- デバッグ情報を出力します。デバッグ情報は現在のところ WSDL2Java のシンボルテーブルです。デバッグ情報はシンボルテーブルが完成した後、つまり WSDL が無事にパースされた後にのみ出力されることに注意してください。
- -W, --noWrapped
- いわゆる "wrapped" document/literal スタイルの操作の、特別な扱いを止めます。デフォルトでは WSDL2Java は以下の条件を認識します。
- もし入力メッセージが単一部分であり、
- その部分が一つの要素で、
- その要素が操作と同じ名前を持ち、
- その要素の複合型が属性を持たない。
もしこの条件を満たしたら、WSDL2Java はトップレベルの要素を 'unwrap' し、その要素の各コンポーネントを操作の引数として扱います。WSDL のこの型は、RPC
スタイルの引数をこのトップレベルスキーマ要素に wrap する Microsoft .NET のWebサービスのデフォルトです。
- -s, --server-side
- Webサービスのためのサーバサイドバインディングを生成します。
- <バインディング名>Skeleton という名前のスケルトンクラス。これは生成されるかもしれないしされないかもしれない (-S、--skeletonDeploy をご覧ください)。
- <バインディング名>Impl という名前の実装テンプレートクラス。すでにこのクラスが存在していれば、これは生成されないことに注意してください。
- deploy.wsdd
- undeploy.wsdd
- -S, --skeletonDeploy <引数>
- deploy.wsdd にスケルトン(true)、あるいは実装(false)を配備します。つまり、"true" の場合 deploy.wsdd ファイル中の service 節は次のようになります。
<service name="AddressBook" provider="java:RPC">
<parameter name="className" value="samples.addr.AddressBookSOAPBindingSkeleton"/>
...
</service>
また、"false" の場合は次のようになります。
<service name="AddressBook" provider="java:RPC">
<parameter name="className" value="samples.addr.AddressBookSOAPBindingImpl"/>
...
</service>
このオプションのデフォルトは false です。このオプションを使用する際、--server-side オプションを前提とするので明示的に --server-side を指定する必要はありません。
- -N, --NStoPkg <引数>=<値>
- デフォルトでは、パッケージ名は WSDL ドキュメント中の名前空間文字列から巧妙なやり方 (通常、もし名前空間が "http://x.y.com" か "urn:x.y.com" であれば、対応するパッケージは "com.y.x" になります) で生成されます。あなたのやりたいことがこのやり方ではない場合、--NStoPkg 引数を使ってオリジナルのマッピングを提供することができます。この方法は必要な回数だけ繰り返すことができ、また各固有の名前空間マッピングに対して一度だけ行うことができます。例えば "urn:AddressFetcher2" を呼ぶ名前空間が WSDL ドキュメントにあったとして、この名前空間にあるオブジェクトが samples.addr パッケージに属するファイルを生成したい場合、以下のオプションを WSDL2Java に与えます。
--NStoPkg urn:AddressFetcher2=samples.addr
(もし短いオプションタグ "-N" を使った場合、"-N" と名前空間の間にスペースを入れてはいけないことに注意してください。)
- -f, --fileNStoPkg <引数>
- もし WSDL ドキュメントの中に多くの名前空間があった場合、それらに対するマッピングを全てリストアップするのは冗長です。コマンドラインを簡潔にするために、WSDL2Java はプロパティファイルの中のマッピングも探します。デフォルトではこのプロパティファイルは "NStoPkg.properties" という名前で、デフォルトパッケージ(つまりパッケージ無し)の中になければなりません。しかし、--fileNStoPkg オプションを使ってオリジナルのファイルを明示的に与えることができます。
このファイルの中身は --NStoPkg コマンドラインオプションの引数と同じ形式です。例えば、上記のコマンドラインオプションを与える代わりに、同じ情報を NStoPkg.properties に与えることができます。
urn\:AddressFetcher2=samples.addr
(プロパティファイルの中のコロンはエスケープされないといけないことに注意してください)
与えられたマッピングがコマンドラインとプロパティファイルの両方にあった場合、コマンドラインの方が優先されます。
- -p, --package <引数>
- これは WSDL ドキュメントの中の全ての名前空間を同じ Java パッケージ名にマッピングするための簡便なオプションです。これはとても便利かもしれませんが、危険です。これを実行した際の影響について把握しておく必要があります。例えば違う名前空間で同じ名前を持った複数の型があるかもしれません。同時に --NStoPkg スイッチと --package を使うとエラーとなります。
- -o, --output <引数>
- 生成される全てのファイルのルートディレクトリを指定します。
- -d, --deployScope <引数>
- deploy.wsdd にスコープ "Application"、"Request"、"Session"を追加する。このオプションがなければ deploy.wsdd にはスコープタグは現れません。その場合 Axis ランタイムは "Request" をデフォルトとします。
- -t, --testCase
- クライアントサイドの JUnit テストケースを生成します。このテストケースは単体で動きますが、実際はデフォルト値(オブジェクトの場合は null、プリミティブ型の場合は false)を渡す以外のことは何もしません。生成された実装ファイルのように、生成されたテストケースはあなたが埋め込むためのテンプレートと考えることができます。
- -a, --all
- 全ての要素(参照していない要素を含む)のコードを生成します。デフォルトでは WSDL2Java は WSDL ファイルの中の参照されている要素のコードしか生成しません。
"参照されている"の意味について説明します。単純に、サービスから始めて、そのサービスから参照される全ての binding を生成し、その参照されている binding によって参照されている portType を生成し、、、と呼び出すことはできません。もし portType、message、types のみから成る WSDL ファイルからコードを生成する場合はどうなるでしょう。もし WSDL2Java が service としてアンカーを使用していて、ファイルに service がない場合、何も生成されません。ですからアンカーは WSDL ファイルの中で存在する、次に示す順序において最低の要素です。
- types
- portTypes
- bindings
- services
例えば、もし WSDL ファイルに type のみが含まれる場合、その全ての type が生成されます。しかしもし WSDL ファイルに type と portType が含まれる場合、portType と、portType によって参照されている type のみが生成されます。
アンカーは、コマンドラインに現れた WSDL ファイルの中のもの検索され、インポートされた WSDL ファイルの中のものは検索されないことに注意してください。これにより、ある WSDL ファイルから他の WSDL ファイルで定義された構成をインポートする際に、インポートされた WSDL ファイルの構成が全て生成されるということに悩まされずにすみます。
- -T, --typeMappingVersion <引数>
- 1.1 か 1.2 を指定します。デフォルトは 1.2 (SOAP 1.2 JAX-RPC 準拠) です。
- -F, --factory <引数>
- WSDL2Java 生成器の機能を拡張するために使われます。引数は JavaWriterFactory を拡張するクラス名です。
- -H, --helperGen
- メタデータのための、別のヘルパークラスを生成します。
- -U, --user <引数>
- このユーザ名は WSDL2Java の入力として与えられた WSDL-URI を解決するために使われます。もし URI がユーザ名を含んでいる場合、これはコマンドラインスイッチを上書きします。ユーザ名とパスワードが入った URL の例は次の通りです。http://user:password@hostname:port/path/to/service?WSDL
- -P, --password <引数>
- このパスワードは WSDL2Java の入力として与えられた WSDL-URI を解決するために使われます。もし URI がパスワードを含んでいる場合、これはコマンドラインスイッチを上書きします。
- -c, --implementationClassName <引数>
- 実装クラスの名前を設定します。特に、java2wsdl に続き wsdl2java を利用して既存のクラスをWebサービスとしてエクスポートする際に便利です。もしスケルトンデプロイオプションを使っている場合、生成の後、実装クラスが wsdl2java によって生成されたポート型名インターフェースを実装しているか必ず確認してください。また、エクスポートしたメソッドが全て java.lang.RemoteException を throw するかも確認してください。
Java2WSDL リファレンス
以下に現在のツールで生成されたヘルプメッセージを示します
Java2WSDL 生成器
使い方: java org.apache.axis.wsdl.Java2WSDL [オプション] class-of-portType
オプション:
-h, --help
メッセージを表示して終了します
-I, --input <引数>
入力する WSDL ファイルのファイル名を指定します
-o, --output <引数>
出力する WSDL ファイルのファイル名を指定します
-l, --location <引数>
サービスロケーションの URL を指定します
-P, --portTypeName <引数>
portType 名を指定します (もし指定されなかった場合は class-of-portType から得ま
す)
-b, --bindingName <引数>
binding 名を指定します (もし指定されなかった場合は --servicePortName の値 +
"SOAPBinding" となります)
-S, --serviceElementName <引数>
service 要素名を指定します (デフォルトは --servicePortName の値 + "Service")
-s, --servicePortName <引数>
service port 名を指定します (もし指定されなかった場合は --location から得ます)
-n, --namespace <引数>
対象とする名前空間を指定します。
-p, --PkgtoNS <引数>=<値>
パッケージ=名前空間、のような名前と値のペアを指定します。
-m, --methods <引数>
スペースかコンマで区切られた、エクスポートするメソッドのリストを指定します。
-a, --all
継承したクラスにある許可されたメソッドを探します。
-w, --outputWsdlMode <引数>
WSDL 出力モードを指定します : All、Interface、Implementation
-L, --locationImport <引数>
wsdl インターフェースの場所を指定します。
-N, --namespaceImpl <引数>
wsdl 実装の対象とする名前空間を指定します。
-O, --outputImpl <引数>
出力する実装 WSDL ファイルのファイル名を指定します。このオプションを指定すると
--outputWsdlMode オプションが無視されます。
-i, --implClass <引数>
class-of-portType のメソッドの実装を含むオプションのクラスを指定します。このク
ラスの中のデバッグ情報は、メソッドパラメータ名を得るのに使われます。
このメソッドパラメータ名は WSDL part 名を設定するのに使われます。
-x, --exclude <引数>
スペースかコンマで区切られた、エクスポートしないメソッドのリストを指定します。
-c, --stopClasses <引数>
--all スイッチが与えられると継承検索をしないクラス名の、スペースかコンマで区切
られたリストを指定します。
-T, --typeMappingVersion <引数>
1.1、あるいは 1.2 を指し示します。デフォルトは 1.1 です (SOAP 1.1 JAX-RPC 準拠
。1.2 は SOAP 1.1 エンコードを指し示します)。
-A, --soapAction <引数>
operation 要素の soapAction 属性の値を指定します。値は DEFAULT、OPERATION、
NONE のいずれかです。OPERATION は operation の名前を soapAction にします。
DEFAULT は operation のメタデータ(普通は "")に従って soapAction を設定します。
NONE は "" を soapAction にします。デフォルトは DEFAULT です。
-y, --style <引数>
WSDL での binding の style を指定します。DOCUMENT、RPC、WRAPPED のいずれかです
。
-u, --use <引数>
binding の中の item の使い方を指定します。LITERAL か ENCODED のいずれかです。
-e, --extraClasses <引数>
types 要素に追加するクラス名の、スペースかコンマで区切られたリストを指定します
。
-C, --importSchema
生成された WSDL に物理的にインポートされるべき XML Schema のファイルや URL
-X, --classpath
追加のクラスパス要素
詳細:
portType 要素名= <--portTypeName 値> または <class-of-portType 値>
binding 要素名= <--bindingName 値> または <--servicePortName 値>
Soap Binding
service 要素名= <--serviceElementName 値> または <--portTypeName 値>
Service
port 要素名= <--servicePortName 値>
address ロケーション= <--location 値>
- -h , --help
- ヘルプメッセージを表示します。
- -I, --input <WSDL ファイル>
- 入力する wsdl ファイルの名前を指定するオプションのパラメータです。出力される wsdl ファイルは、入力された wsdl ファイルからくる全てのものと、新しい構成を含んでいます。もし新しい構成がすでに入力された wsdl ファイルに現れていたらその新しい構成は追加されません。このオプションを、複数の port、binding、portTypes から成る wsdl ファイルを構築する際に便利です。
- -o, --output <WSDL ファイル>
- 出力する WSDL ファイルのファイル名を指定します。もし指定しなければ、現在のディレクトリに適切なデフォルトの WSDL ファイルが出力されます。
- -l, --location <ロケーション>
- service の location の url を指定します。最後のスラッシュあるいはバックスラッシュの後の名前は、その service の名前です(-s オプションで上書きされていない限り)。service 要素の中の port 要素の中の address 要素の location 属性に指定した値が割り当てられます。
- -P, --portTypeName <名前>
- portType 要素に使う名前を指定します。指定しなければ class-of-portType の名前が使われます。
- -b, --bindingName <名前>
- binding 要素に使う名前を指定します。指定しなければ --servicePortName + "SoapBinding" の名前が使われます。
- -S, --serviceElementName <名前>
- service 要素の名前を指定します。指定しなければ <portTypeName>Service が service 要素になります。
- -s, --servicePortName <名前>
- service port の名前を指定します。指定しなければ service port 名は --location の値から生成されます。
- -n, --namespace <対象名前空間>
- WSDL の対象の名前空間の名前を指定します。
- -p, --PkgToNS <package> <名前空間>
- パッケージから名前空間へのマッピングを指定します。もし名前空間を持たないパッケージがあれば、Java2WSDL 生成器は適切な名前空間の名前を生成します。このオプションは複数回指定できます。
- -m, --methods <arguments>
- もしこのオプションを指定したら、インターフェースの指定されたメソッドのみが WSDL ファイルに出力されます。メソッドのリストはコンマで区切られていなければなりません。指定しなければ、インターフェースで宣言された全てのメソッドが WSDL ファイルにエクスポートされます。
- -a, --all
- もしこのオプションが指定したら、Java2WSDL パーサは継承したクラスを見にいき、WSDL ファイルにエクスポートするメソッドのリストを決めます。
- -w, --outputWSDLMode <mode>
- 生成する WSDL の種類を指定します。有効な値は以下の通りです。
- All --- (デフォルト) WSDL 構成のインターフェースと実装の両方を含む wsdl を生成します。
- Interface --- 構成のインターフェース(service 要素なし)を含む WSDL を生成します。
- Implementation -- 実装を含む WSDL を生成します。WSDL インターフェースは -L オプションを介してインポートされます。
- -L, --locationImport <url>
- 実装 WSDL を生成する際に、インターフェース WSDL のロケーションを指定するのに使われます。
- -N, --namespaceImpl <名前空間>
- 実装 WSDL の名前空間を指定します。
- -O, --outputImpl <WSDL file>
- 出力する実装 WSDL ファイルのファイル名を指定するのにこのオプションを使います。もし指定したのなら、Java2WSDL はインターフェース WSDL ファイルと実装 WSDL ファイルを生成します。もしこのオプションを使用したら、-w オプションは無視されます。
- -i, --implClass <実装クラス>
- 実装クラスファイルでは時々余分な情報が手に入ります。実装クラスを指定するのにこのオプションを使用します。
- -x, --exclude <リスト>
- wsdl ファイルから除外されたくないメソッドのリストを指定します。
- -c, --stopClasses <リスト>
- Java2WSDL の継承検索をしないクラスのリストを指定します。
- -T, --typeMappingVersion <バージョン>
- 使用する型マッピングレジストリを選びます。1.1 か 1.2 です。
- -A, --soapAction <引数>
- operation 要素の soapAction 属性の値を指定します。値は DEFAULT、OPERATION、NONE のいずれかです。OPERATION は operation の名前を soapAction にします。DEFAULT は operation のメタデータ(普通は "")に従って soapAction を設定します。NONE は "" を soapAction にします。デフォルトは DEFAULT です。
- -y, --style <引数>
- WSDL ドキュメントの style を指定します。RPC、DOCUMENT、WRAPPED のいずれかです。デフォルトは RPC です。もし RPC が指定されると rpc wsdl が生成されます。もし DOCUMENT が指定されると、document wsdl が生成されます。WRAPPED が指定されると wrapped アプローチによる document/literal wsdl が生成されます。wrapped style は use 属性を literal に強制します。
- -u, --use <引数>
- WSDL ドキュメントの use を指定します。LITERAL か ENCODED のいずれかです。もし LITERAL が指定されると、XML Schema はリクエストに対する XML の表現を定義します。もし ENCODED が指定されると、生成された WSDL の中で SOAP エンコーディングが指定されます。
- -e, --extraClasses <引数>
- WSDL ドキュメントの types 節に含まれるべきクラス名の、スペースかコンマで区切られたリストを指定します。service インターフェースが基礎のクラスを参照していて、WSDL がこれらの他のクラスの XML Schema 型定義を含ませたいような場合、このオプションは便利です。--extraClasses オプションは複数回指定できます。それぞれの指定ごとに、リストにクラスが追加されます。
- -C, --importSchema
- 生成された WSDL に物理的にインポートされるべき XML Schema のファイルや URL
- -X, --classpath
- 追加のクラスパス要素
デプロイ(WSDD)リファレンス
注意 : この節で参照されている全ての要素は WSDD 名前空間、すなわち "http://xml.apache.org/axis/wsdd/" の中にあります。
- <deployment>
- これが deployment であると Axis エンジンに伝える、配備ドキュメントのルート要素です。配備ドキュメントは、完全なエンジン設定、あるいは、実行中のエンジンに配備するコンポーネントの集合、を表します。
- <GlobalConfiguration>
- この要素は Axis のエンジンにまたがる設定を制御するのに利用されます。いくつかの下位要素を含んでいます。
-
<parameter> : これは Axis エンジンにオプションを設定するのに利用されます。詳細については後述の グローバル Axis 設定 節をご覧下さい。<parameter> 要素はいくつあってもかまいません。
-
<role> : これはエンジンが認識する SOAP アクタ/ロール URI を設定するのに利用されます。これによりそのロールに向けられた SOAP ヘッダは無事にエンジンによって処理されます。<role> 要素はいくつあってもかまいません。
-
<requestFlow> : これは、各リクエストの実際のサービスの前に呼ばれる、グローバルリクエストハンドラを設定するのに利用されます。<requestFlow> 内に <handler> または <chain> 要素(下記参照)はいくつあってもかまいませんが、<requestFlow> は1つだけです。
-
<responseFlow> : これは、各リクエストの実際のサービスの後に呼ばれる、グローバルレスポンスハンドラを設定するのに利用されます。<responseFlow> 内に <handler> または <chain> 要素(下記参照)はいくつあってもかまいませんが、<responseFlow> は1つだけです。
- <undeployment>
- これが undeployment であると Axis に伝える、配備ドキュメントのルート要素です。
- <handler [name="名前"] type="型"/>
-
<deployment>、<undeployment> の中のトップレベル、あるいは<chain>、<requestFlow>、<responseFlow>の中にあります。handler を定義し、handler の型を指定します。"type" は既に定義したほかの handler の名前、あるいは "java:class.name" 形式の QName です。オプションの "name" 属性によって、配備の他の部分からこの handler の定義を参照することができます。任意の数の <parameter name="名前" value="値"> 要素を持つことができ、それぞれが、配備した handler にオプションを提供します。
- <service name="名前" provider="プロバイダ" >
- Axis Service を配備/アンデプロイします。これは最も複雑な WSDD タグなので、これに少し時間をかけて説明します。
オプション は以下のように指定します。<parameter name="名前" value="値"/>。そして一般的なものは以下のものを含みます。
-
className : バックエンドの実装クラスを指定します。
-
allowedMethods : それぞれのプロバイダはどのメソッドがWebサービスとしての公開が許されるか決めることができます。
Axis が提供するプロバイダを要約すると次のようになります。
Java RPC Provider (provider="java:RPC") デフォルトでは、className オプションの中のクラスで指定された全ての public メソッド(全ての継承したメソッドも含む)はWebサービスとして利用できます。
Java Provider に関する詳細は WHERE??? をご覧下さい。
Java MsgProvder (provider="java:MSG")
上記のメソッドにさらに制限を加えるには、Webサービスとして許可するメソッドのみの名前の、スペースで区切られたリストを指定して allowedMethods オプションを使います。このオプションに、機能的にオプションを全く指定しないのと同じである、値 "*" を指定することも可能です。operation 要素は提供されたメソッドをさらに定義するために使えますが、どのメソッドが利用可能になるかには影響を与えない、ということを言及することにも価値があります。
上記は Axis が提供するプロバイダについてのことですが、それぞれの個別のプロバイダは実装依存となります。このオプションに対応しているか、どのように対応しているかについてはプロバイダのドキュメントを見直してください。
どのようなWebサービスを公開するにしても、セキュリティとの係わり合いがあることに注意してください。
ベストプラクティスが導くように、安全でない環境でWebサービスを提供する際は、許可するメソッドを提供されているサービスを必要とする人たちのみに制限することを強くお勧めします。そして利用可能となった人たちは、それらの機能と、あなたのシステム資源にどのようにアクセスし、公開するか、完全に理解する必要があります。
-
allowedRoles : このサービスにアクセスが許可されたロールの、コンマで区切られたリストを指定します(SOAP ロールとは対照的に、これらはセキュリティロールであることに注意してください。セキュリティロールはアクセスを制御し、SOAP ロールはどの SOAP ヘッダを処理するかを制御します。)。
-
extraClasses : WSDL ドキュメントの types 節に含めるべきクラス名の、スペースやコンマで区切られたリストを指定します。これは、サービスインターフェースが基底クラスを参照し、これらの他のクラスに対して XML Schema 型定義を WSDL に含ませたい場合に便利です。
サービスのプロバイダの前、あるいは後に呼び出したい handler を定義したいのであれば、下位要素である <requestFlow> と <responseFlow> を使ってできます。いずれの要素も <service> 要素の中で指定でき、またそれらのセマンティックスは、以降で説明されている <chain> 要素と同一です。つまり、それらは <handler> 要素と <chain> 要素を含むことができ、指定された順で呼び出されます。
あなたのサービスハンドラによって認識される ロール を制御するには、サービス宣言内で任意の数の <role> 要素を指定します。
例。
<service name="test">
<parameter name="className" value="test.Implementation"/>
<parameter name="allowedMethods" value="*"/>
<namespace>http://testservice/</namespace>
<role>http://testservice/MyRole</role>
<requestFlow> <!-- リクエストを処理する前にこれらを起動する -->
<handler type="java:MyHandlerClass"/>
<handler type="somethingIDefinedPreviously"/>
</requestFlow>
</service>
メタデータは、service の中で <operation> タグを使って、service の特定の operation について指定することができます。これにより、あるメソッドの java のパラメータ名を特定の XML 名にマッピングできたり、パラメータに対してパラメータモードを指定することができます。
<operation name="メソッド">
</operation>
- <chain name="名前"> <下位要素/>... </chain>
- chain を定義します。chain が呼び出されるとリスト中のそれぞれの handler (すなわち配備された handler 名) が順番に呼び出されます。これにより、共通的に利用される機能である "モジュール" を作り上げることができます。chain の中にある下位要素は <handler> か <chain> です。<chain> の中にある <handler> は次のように、その Java クラスによって定義されるか、
<chain name="myChain">
<handler type="java:org.apache.axis.handlers.LogHandler"/>
</chain>
あるいは次にように、以前に定義された <handlers> を参照することによって定義されます。この場合、handler の "type" は他の handler 定義の名前を参照します。
<handler name="logger" type="java:org.apache.axis.handlers.LogHandler"/>
<chain name="myChain"/>
<handler type="logger"/>
</chain>
- <transport name="名前">
- サーバサイドの transport を定義します。サーバの transport は、入ってくるリクエストが到着すると呼び出されます。サーバの transport は <requestFlow> 要素 と/あるいは <responseFlow> 要素 で定義され、これらの要素は、処理のリクエスト (すなわち入ってくるメッセージ) 部分、あるいは処理のレスポンス (すなわち出ていくメッセージ) 部分で呼び出す handler や chain を指定します (この機能は上記の <service> 要素とまったく同じように働きます)。通常、transport のリクエスト/レスポンスフローの中の handler は、プロトコルヘッダーをパースする等といった transport 特有の機能を実装します。
どのような種類の transport (といっても普通は HTTP transport に関連しますが)に対しても、Axis サーブレットに特定のクエリー文字列が渡されたときに、Axis サーブレットに任意のアクション ("プラグイン" を用いる) を実行させることができます (この意味とプラグインの使い方の詳細についてはAxis 開発者ガイドの中にあるAxis サーブレットクエリー文字列プラグインをご覧下さい)。クエリー文字列 handler クラスの名前を知っていれば、Axis サーバ設定の <transport> 要素の中に、適切な <parameter> 要素を加えることによって可能です。設定例は以下のとおりです。
<transport name="http">
<parameter name="useDefaultQueryStrings" value="false" />
<parameter name="qs.name" value="class.name" />
</transport>
この例では、Axis サーブレットが応答しなくてはいけないクエリー文字列は ?name で、このクエリー文字列に出会ったら呼び出さなくてはいけないクラスの名前は class.name です。<parameter> 要素の name 属性は、この <parameter> 要素がクエリー文字列 handler を定義していることを指し示すために、"qs." という文字列から始めなければなりません。value 属性は org.apache.axis.transport.http.QSHandler インターフェースを実装しているクラスの名前を指し示さなくてはいけません。Axis はデフォルトで3つの Axis サーブレットクエリー文字列 handler (?list, ?method, and ?wsdl) を提供しています。これらの定義については Axis サーバ設定ファイルをご覧下さい。もし (上記の例のように) これらのデフォルトのクエリー文字列 handler を使用したくないのであれば、<parameter> 要素の name 属性を "useDefaultQueryStrings"、value 属性を false にします。デフォルトでは true に設定されていて、もしデフォルトの動きをさせたいのであればこの要素は必要ありません。
- <transport name="名前" pivot="ハンドラ型">
- SOAP メッセージを送信する際に呼び出される、クライアントサイドの transport を定義します。"pivot" 属性は、この transport の実際の送信者となる handler を指定します(例えば HTTPSender)。サーバサイドの transport と同様に、リクエスト (すなわち出ていくメッセージ) 時、あるいはレスポンス (すなわち入ってくるメッセージ) 時に処理をするリクエストフロー、あるいはレスポンスフローも指定できます。
- <typeMapping qname="ns:ローカル名" classname="クラス名" serializer="クラス名" deserializer="クラス名"/>
- それぞれの typeMapping は、指定された Serializer と Deserializer を使って、 XML の修飾名を Java クラスに、あるいは Java クラスから XML の修飾名にマッピングします。
- <beanMapping qname="ns:ローカル名" classname="クラス名">
- JavaBeans をエンコード/デコードするのにあらかじめ定義された serializer/deserializer を使用する、簡略化した型マッピングを指定します。"クラス名" で指定されたクラスは get/set アクセサといった JavaBean 標準パターンに従う必要があります。
- <documentation>
-
<service>、<operation>、あるいは操作 <parameter> 内で利用することができます。要素の内容は任意のテキストで、生成された wsdl の wsdl:document 要素内に入れられます。
例:
<operation name="echoString" >
<documentation>この操作は文字列をエコーします</documentation>
<parameter name="param">
<documentation>文字列</documentation>
</parameter>
</operation>
グローバル Axis 設定
サーバは (デフォルトでは) server-config.wsdd ファイルの中の値によって設定されますが、熱心な Axis ユーザは自分専用の設定 handler を書き、LDAP サーバ、データベース、リモートのWebサービスなどに設定データを保存することができます。これを行う方法についてはソースをご覧下さい。web.xml ファイルにオプションを追加して、自動的にそれらを取り出すこともできます。設定事項を一箇所に集めておくことはお勧めしません。
server-config ファイルにはグローバル設定部があり、入れ子の要素として名前/値ペアのパラメータを持つことができます。ここに下で説明しているオプションの例を挙げますが、オプションはもっとあります (いつものようにソースをご覧下さい)。
<globalConfiguration>
<parameter name="adminPassword" value="admin"/>
<parameter name="attachments.Directory" value="c:\temp\attachments"/>
<parameter name="sendMultiRefs" value="true"/>
<parameter name="sendXsiTypes" value="true"/>
<parameter name="attachments.implementation"
value="org.apache.axis.attachments.AttachmentsImpl"/>
<parameter name="sendXMLDeclaration" value="true"/>
<parameter name="enable2DArrayEncoding" value="true"/>
</globalConfiguration>
adminPassword |
AdminService で使われる管理者のパスワードを指定します。 |
attachments.Directory |
添付が行き着くディレクトリを指定します。対象のプラットフォームに適した文法を用いる必要があります。 |
attachments.implementation |
添付サポートを実装するクラスの名前を指定します。デフォルトはorg.apache.axis.attachments.AttachmentsImplです。 |
axis.enableListQuery |
"list the WSDD" 機能を有効にするフラグです。現在のシステム設定をリストアップすることで、広く入手可能にさせたくない情報 (adminservice のパスワード等) を公開することになるので、デフォルトでは false に設定されています。 |
axis.disableServiceList |
サービス一覧機能を無効にする際にフラグを立てます。デフォルトでは false に設定されています。これにより、サーブレットルートに対して GET リクエストが実行されたときに、AxisServlet がサービスを一覧にすることができます。 |
axis.servicesPath |
Axis サーブレットへのパスです。これは web.xml で定義されているサービスのサーブレットマッピングと同じである必要があります。サービスの一覧表示の際に利用されます。デフォルトは "/services/" です。 |
axis.Compiler |
JWS コンパイルのためのコンパイラアダプタクラス名を指定します。デフォルトは org.apache.axis.components.compiler.Javac です。代わりに jikes を呼び出すには org.apache.axis.components.compiler.Jikes に変更してください。 |
axis.development.system |
システムを production (false) から development (true) に切り替えます。development システムは、production が提供すべきでないスタックトレースやその他の情報を出力します。 |
axis.xmlEncoding |
XML メッセージに使うエンコーディングを指定します。UTF-8 (デフォルト) か UTF-16 のいずれかです。 |
axis.engineConfigClass |
Axis 設定を提供するクラスの名前を指定します。別の設定メカニズムを使用するには EngineConfiguration を実装した新しいクラスを実装し、ここでその名前を指定します。 |
axis.jws.servletClassDir |
コンパイル済みの JWS ページが置かれるパスを指定します。 |
axis.sendMinimizedElements |
.Net1.0 が、処理すべき [英語] XML を正しく処理できない場合に有効にするフラグです。デフォルトでは true になっています。もしある .NET クライアントが、他のオブジェクトに入っている空の配列を返すWebサービスの処理に失敗する場合はこのフラグを false に設定してください。 |
enable2DArrayEncoding |
2次元配列エンコーディングを有効にするにはこれを "true" に設定してください。このエンコーディングは .NET 1.0 と互換性がありません。デフォルトは "false" です。 |
sendMultiRefs |
multiref 要素が送られるか送られないかを制御する true か false のフラグです。 |
sendXMLDeclaration |
メッセージの中で <?xml?> 宣言が送られるかどうかを制御する true か false のフラグです。 |
sendXsiTypes |
インターネット上に送られる全ての値の型の送信を有効/無効にする true/false のフラグです。デフォルトは true です。 |
SingleSOAPVersion |
"1.1" か "1.2" に設定されると、Axis エンジンは指定された SOAP のバージョンのみ受け付けるように設定されます。異なるバージョンで Axis エンジンにアクセスすると失敗に終わります。 |
use-servlet-security |
サーブレットコンテナの認証を無効にするにはこのフラグを設定してください。 |
個別のサービス設定
TODO
ここに利用可能な各サービス設定オプションを挙げます。これらはサービスをデプロイする wsdd ファイルに設定でき、そこから値が取得されます。
ここに挙げたもの以外もあります。
style |
RPC:enc あるいは doc/lit エンコーディングを使用するか設定します。 |
SingleSOAPVersion |
"1.1" か "1.2" に設定されると、Axis エンジンは指定された SOAP のバージョンのみ受け付けるように設定されます。異なるバージョンで Axis エンジンにアクセスすると失敗に終わります。 |
wsdlFile |
WSDL ファイルへのパスを設定します。このパスは絶対パス、あるいは axis.jar がロードできるリソースになります。自分専用の WSDL ファイルをエクスポートする際に便利です。リソースへのパスを指定するときは、クラスパスの先頭をスラッシュで始めます (例えば "/org/someone/res/mywsdl.wsdl")。Axis はどのようにしてファイルを返すのか、あるいはリソースを返すのかを知るのでしょうか。Axis はまずファイルを探し、もしなければリソースを返します。 |
Axis ロギング設定
Axis は Jakarta プロジェクトの commons-logging API [英語] を使用します。この API は、コードの至るところでのロギングを実装する commons-logging.jar で実装されています。普通このライブラリはロギングに対して Log4j ライブラリを使用します。この際、log4j の実装はサーバあるいはクライアントのクラスパスに設定されています。commons-logging API は Avalon、System.out、Java1.4 logger を使用することもできます。このライブラリの JavaDocs はロガーの選択方法を説明していて、システムプロパティやクラスパスにあるプロパティファイルによって選択が可能です。
Log4J はクラスパスにある log4j.properties ファイルを使用して設定することができ、後のバージョンでは XML 設定もサポートしています。Axis は axis.jar の中に、あらかじめ設定された log4j.properties ファイルを含んでいます。一般ユーザはこれで十分ですが、複雑なプロジェクトでは log4j.properties ファイルを自分で設定したいでしょう。ここにそのやり方を挙げます。
- zip ファイルビューアで axis.jar を開き、log4j.properties を取り除きます。
- もしくは、自分の axis.jar をビルドする際、JAR にプロパティファイルを入れないように、Ant プロパティ exclude.log4j.configuration を設定します。
- 自分用の log4J.properties ファイルを作成し、(サーバサイドの) WEB-INF/classes の中と、クライアントサイドのメインアプリケーションの JAR ファイルに入れます。
- この log4J プロパティファイルを自分の好きなように編集します。サーバサイドにおいて、定期的なログをしゃれた html 出力に設定すると便利ですが、バックエンドサーバをクラスタリングし始めると便利でなくなってきます。'chainsaw' のような Log4J のパワーツールがあることはここでは秘密です。
ログのカテゴリ
ログ情報を出力する Axis のクラスは、各クラスごとに自分用のログを作成し、それぞれ違うレベルの情報を出力することが可能です。例えば、メインの入り口であるサーブレットは org.apache.axis.transport.http.AxisServlet、Axis エンジンは org.apache.axis.AxisEngine と呼ばれるログなどがあります。また、特別なカテゴリ用に特別なログもあります。
org.apache.axis.TIME |
このログは、入ってくるメッセージを実行し、preamble に分割し、呼び出し、ポストして送る時間を記録します。これらは debug レベルでのみログが取られます。 |
org.apache.axis.EXCEPTIONS |
インターネットを介して送り返される例外です。普通は '健全な' 操作で作成される AxisFault は、debug レベルでログが取られます。その他のログは info レベルでログが取られます。というのもそれらはサーバサイドのトラブルをより示唆しているからです。 |
org.apache.axis.enterprise |
"エンタープライズ" レベルのログ、つまり一般的には、(Axis ビルドのような) 単純な環境では邪魔であるが、エンタープライズ製品であるならば追跡したいログです。 |
あらかじめ設定された Axis コンポーネントリファレンス
サーバ側
- SimpleSessionHandler
- 簡単なセッション管理を行うために SOAP ヘッダを使用します
- LogHandler
- LogHandler が呼び出されると、LogHandler は単にロガーにメッセージをログします。
- SoapMonitorHandler
- SoapMonitor ユーティリティに SOAP リクエストメッセージとレスポンスメッセージを送信するメッセージパイプラインにフックを提供します。
- DebugHandler
- soap ヘッダ要素の値に基づいて動的にデバッグレベルを設定するデモを行うハンドラの見本です。
- ErrorHandler
- リクエスト/レスポンスフロー処理を停止するために AxisFault を投げるハンドラの見本です。
- EchoHandler
- EchoHandler はリクエストメッセージをレスポンスメッセージにコピーします。
- HTTPAuth
- HTTPAuthHandler は HTTP 特有の認証情報 (現在のところ、基本認証のみ) を受け取り、ユーザ名とパスワードを一般的な MessageContext プロパティに変換します
- SimpleAuthenticationHandler
- SimpleAuthentication ハンドラは SecurityProvider が求めているあらゆる情報 (現在のところ、ユーザ名とパスワードのみ) を使ってユーザを認証するために、MessageContext を SecurityProvider (org.apache.axis.security をご覧下さい) に渡します。
- SimpleAuthorizationHandler
- たいてい SimpleAuthenticationHandler と一緒にデプロイされる (この組み合わせのために "authChecks" と呼ばれる chain があらかじめ定義されています) このハンドラは、現在認証されているユーザが対象のサービスの許可されたロールの一人かどうか確認します。アクセスが拒否されると Fault が投げられます。
- MD5AttachHandler
- 添付情報の MD5 ハッシュを生成し、soap ボディの中に属性として値を追加する、ドキュメントがなく、不必要な、テストされていないハンドラです。
- URLMapper
- HTTP 特有のハンドラである URLMapper は、普通 (デフォルトでデプロイされている) HTTP トランスポート chain に基づいています。URLMapper は URL に基づくサービス処理を提供します。例えば、 http://localhost:8080/axis/services/MyService?wsdl のような URL が機能するのはこのハンドラのおかげです。
- RPCProvider
- RPCProvider は全ての RPC サービスの pivot ポイントです。RPCProvider は以下のオプションを受け付けます。
className = 呼び出すバックエンドオブジェクトのクラスを指定します。
methodName = スペースで区切られた、Webサービスとしてエクスポートされるメソッドのリストを指定します。特別な値 "*" はそのクラスの全ての public メソッドにマッチします。
- MsgProvider
- MsgProvider は全てのメッセージングサービスの pivot ポイントです。MsgProvider は以下のオプションを受け付けます。
className = 呼び出すバックエンドオブジェクトのクラスを指定します。
methodName = スペースで区切られた、Webサービスとしてエクスポートされるメソッドのリストを指定します。特別な値 "*" はそのクラスの全ての public メソッドにマッチします。
- JWSHandler
- ドロップインデプロイを実行します。
- JAXRPCHandler
- Axis エンジンに Axis ハンドラインタフェースを公開する、JAX-RPC 準拠のハンドラのラッパです。
- LocalResponder
- LocalResponder はローカル呼び出しから返ってきたレスポンスメッセージを String にシリアライズするハンドラです。LocalResponder はデフォルトではサーバのローカルトランスポートレスポンスチェインにあり、メッセージを String 形式にシリアライズする処理がサーバの型マッピングのコンテキストで行われることを保障します。
クライアント側
- SimpleSessionHandler
- 簡単なセッション管理を行うために SOAP ヘッダを使用します
- JAXRPCHandler
- Axis エンジンに Axis ハンドラインタフェースを公開する、JAX-RPC 準拠のハンドラのラッパです。
- HTTPSender
- HTTP を介してリクエストメッセージをリモートサーバに送り、レスポンスメッセージを受け取るハンドラです。
- LocalSender
- リクエストメッセージを "ローカルの" AxisServer に送るハンドラです。"ローカルの" AxisServer はそれを処理してレスポンスメッセージを返します。これはテスト時に大変便利で、デフォルトでは "local:" トランスポートにマッピングされています。ですから例えば AdminClient のテストはこのようにして行えます。
% java org.apache.axis.client.AdminClient -llocal:// list