Hitachi

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


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ソースを修正し,コンパイルし直す必要があります。