Apache Muse を使用して HTTP サーバー用の WSDM インターフェースを作成する

Web サービス標準を使って一般的製品の管理機能を公開する方法

Apache Muse を使用して管理可能リソース用 WS-DistributedManagement (WSDM) 準拠インターフェースを作成する方法を学びましょう。このチュートリアルでは、リソース用の Web サービス・インターフェースを設計する方法、実装用コードを生成する方法、そしてそのコードを Web アプリケーションとしてデプロイする方法を学習します。このチュートリアルで取り扱う管理可能リソースは、一般に「httpd」と呼ばれる広く普及した Apache HTTP Server です。このチュートリアルを修了した時点で、WSDM 準拠の管理クライアントで httpd リソースを操作することができる、Muse ベースのアプリケーション が完成します。

Dan Jemiolo, Advisory Software Engineer, IBM

Dan JemioloDan Jemiolo は、ノースカロライナ州リサーチ・トライアングル・パークにある IBM Autonomic Computing チームの Advisory Software Engineer です。彼は Apache Muse 2.0 の設計および開発を指揮し、現在も引き続きこのプロジェクトに取り組んでいます。また、Dan は WS-RF TC に WS-ResourceMetadata 仕様のエディターとして参加しており、Web サービス標準の採用を促進する IBM の戦略に携わっています。彼はわずか 2 年前に、Rensselaer Polytechnic Institute で Computer Science を専攻し理学修士の学位を取得した後、IBM に入社しました。



2006年 11月 21日

セクション 1. 始める前に

まず、このチュートリアルの内容と最も効果的な活用方法について説明します。

このチュートリアルについて

このチュートリアルでは、単純な例を挙げるだけでなく、ソフトウェア製品用の WS-DistributedManagement (WSDM) インターフェース (今日の IT システムにおいて極めて一般的なもの) を構築する方法について説明します。Apache Muse プロジェクトのツールとフレームワークを使用して、Apache HTTP Server (一般に「httpd」と呼ばれます) 用の WSDM インターフェースを設計、実装し、デプロイします。これまで Muse を使用したことがない場合は、まず Muse プロジェクトの文書に含まれる入門チュートリアル (「参考文献」を参照) を修了しておかなければ、このチュートリアルを十分に理解するのは難しいかもしれません。

目標

このチュートリアルでは、既存の管理可能リソース用の Web サービス・インターフェースを設計するうえでの詳細なポイントを学びながら、httpd 用 Web サービス・インターフェースを定義する Service Definition Language (WSDL) 文書を作成していきます。次に、Muse の付属ツールを使用して、このインターフェースに準拠した、Java™ Platform, Enterprise Edition (Java EE) Web アプリケーションとしてデプロイすることのできるコードと成果物を生成します。WSDM 互換の管理クライアントで httpd を操作することができるようなアプリケーションを完成していく過程で、WSDM の概念を製品の既存の管理 API にマップする方法を学ぶことができるでしょう。

前提条件

このチュートリアルは、中級レベルのスキルと経験を有する Java プログラマーを対象としています。また、WS-ResourceFramework (WSRF) と WSDM 標準で定義されている概念および XML スキーマについても、しっかりと理解しておく必要があります。さらに、Muse 2.0 ディストリビューションに付属する入門チュートリアル (リンクは「参考文献」を参照) を試し、サンプル・アプリケーションを正しく実行できるようにしておくことも期待されます。

システム要件

このチュートリアルで構築するアプリケーションを実行するためには、システムに Apache Tomcatのインストールが必要です。Tomcat 5.5 には Java Platform, Standard Edition (Java SE) 1.5 が必須なので、Java SE 1.4 をご使用の場合は Tomcat 4.1 または 5.0 が必要となります。作業には Microsoft Windows コンソールを使用しますが、UNIX® や Linux® をお使いの場合でも、本チュートリアルはご利用いただけます。


セクション 2. Apache HTTP Server のインストールと理解

このセクションではhttpd のインストールと動作確認について説明し、このチュートリアルに関係するファイルを調べます。既に httpd について熟知していて、システムへのインストールが完了している場合には、このセクションを省略してもかまいません。

httpd 用の Web サービス管理機能インターフェースを構築するには、まずこの製品がシステム上にあることを確認しなければなりません。最新バージョンは Apache の Web サイトから入手できます。Microsoft® Windows® ユーザーの場合は MSI インストーラーが最も使いやすいでしょう。

ディストリビューションの内容を解凍した後、インストール・ディレクトリー内の /bin/httpd アプリケーションを実行すると、サーバーが起動します。サーバーが起動したら、動作状態は Web ブラウザーで確認できます。http://localhost に移動すると、「It works!」というシンプルなメッセージが表示されます。現時点で必要なのは、インストール済み環境のファイルに目を通し、目的を把握することです。

httpd を開始するための別の方法

Windows ユーザーは、別の方法でサーバーを開始することもできます。「スタート」メニューから、「Apache HTTP Server」 > 「Control Apache Server」 > 「Start Apache in Console」の順に選択してください。サーバーが起動すると、コンソールは何も表示されない状態になります。

httpd インストール済み環境の /bin ディレクトリーには、アプリケーション自体に加えて、数多くのスクリプトが含まれています。これらのスクリプトはパフォーマンス・テスト、ログ保守、キャッシュ管理などを提供するものですが、すべてのスクリプトに、管理クライアントに対して公開することができる関連オプションやタスクが定義されています。このチュートリアルでは httpd アプリケーション自体に焦点を当てていますが、この実行可能ファイルの操作を理解しておくと、他の実行可能ファイルにアクセスしてアプリケーションに機能を追加する方法がわかるようになります。

/conf ディレクトリーには、httpd 用の構成ファイルがあります。最も重要なファイルは httpd.conf です。これには基本的な TCP/IP、スレッド化、アクセス権などの設定を始め、数多くの設定が含まれています。これらの設定は単純な「名前と値」の対として記述されており、Java のプロパティー・ファイルと非常によく似ています。このファイルの最上部には、ファイル内の値を変更する際には適切な判断が必要であるということを警告するコメントが記述されています。そのため、サーバーの動作に影響する httpd.conf の値は一切変更しない予定です。代わりに、httpd 用 WS-ResourceProperties の実装の一環として、このファイルから値を読み取ることにします。


セクション 3. WSDL の設計 (パート 1): リソース・プロパティー

ここまでは httpd の基本について説明しました。次は、httpd の概念を WSRF 仕様と WSDM 仕様の概念に置き換える方法を見ていきましょう。WSRF をベースとする WSDL の最初のパートは、状態モデル、つまり「リソース・プロパティー文書」です。

さまざまなタイプのプロパティー

WSRF をベースとするすべての Web サービスには、WS-ResourceProperties 仕様での定義に沿ったリソース・プロパティー文書が必要です。WSRF と WSDM にはいずれも、管理対象リソースの開発者にとって有用な多数の標準プロパティー (その多くはオプション) が定義されています。また、httpd インストール済み環境には、管理クライアントにとって有用な情報として、HTTP サーバー特有のものも数多く提供されています。本書では、まず自由に使用できる標準プロパティーをいくつか説明したあとで、httpd 特有のプロパティーを取り上げます。

WS-* プロパティー

WSRF と WSDM で定義されるプロパティーをすべてこのセクションで取り上げることは不可能なため (この情報については、「参考文献」に示された OASIS 標準のリンクを参照してください)、その代わりに、最も重要なプロパティーのいくつかに注目し、httpd インターフェースでどのように使用すればよいのかを明らかにします。

  • ResourceId:WSDM Management Using Web Services (MUWS) の識別機能の一部。これは、リソース・タイプの各インスタンスに固有な ID です。例えば、1 つの httpd リソースに 3 つのインスタンスを定義する場合もありますが、各インスタンスには、区別のために別々の ResourceId 値が与えられます。
  • ManageabilityCapability:WSDM MUWS の ManageabilityCharacteristics 機能の一部。この一連の URI は、Web サービスがサポートする管理機能をリモート・クライアントに伝えるものです。つまり、管理クライアントに「これが私にできることだ」と伝えるのです。
  • CaptionDescription、および Version:WSDM MUWS の Description 機能の一部。これらの値は、管理クライアントがリソースをより明確に分類・表示するのに役立つ、人間が読めるテキストを提供します。
  • OperationalStatus:WSDM MUWS の OperationalStatus 機能の一部。これは単純な列挙型であり、リソースのサービス要求能力を概要レベルで報告します。有効な値としては、AvailablePartiallyAvailableUnavailableUnknown があります。

これらのプロパティーはすべて、識別と記述という共通のテーマで展開されます。このアプリケーションでは、プロパティーの値は httpd に固有のものですが、プロパティーの定義と意味体系は標準に準拠しています。先頭の 2 つのプロパティーは URI で、末尾の 2 つは単純なストリングです。コードの実装段階に入った時点で、これらに適切な値を割り当てることができます。

HTTP プロパティー

Apache HTTP Server には管理クライアントにとって有用な構成データが多数用意されており、そのすべてが httpd.conf ファイルに記載されています。もちろん、このファイルには Web サービス経由で公開したくない情報も多く含まれているため、httpd.conf ファイル内のすべてのプロパティーがリソース・プロパティーであるとは言えません。そのため、このファイルから単純な値をいくつか選び、それらを WSRP を使ってリソース・プロパティーとしてモデル化する方法を示します。そうすれば、他の管理関連の値を公開する方法を理解することができるでしょう。

httpd.conf ファイルを開いて、ファイルの内容に目を通してください。次のようなプロパティーが確認できるはずです。

  • ThreadsPerChild:各 httpd プロセスの要求処理スレッドの数。デフォルトは 250 です。
  • Listen:サーバーが listen するポート番号。デフォルトは 80 です。
  • ServerName:サーバーが自身を識別するために使用する、完全ホスト名とポート。これはオプションですが、説明用として有用です。この行のコメントを外し (# を削除)、正しい値を指定してください。このチュートリアルでは http://localhost と指定するだけで十分です。

他にも多くのプロパティーがありますが、このチュートリアルでは上記の 3 つを中心に取り上げます。これらのプロパティーに共通する優れた特性の 1 つは、HTTP サーバーに対して汎用性があることです。つまり、プロパティーやその値に関して httpd 固有のものは存在しません。これは、WSRF と WSDM を最大限に活用するための重要なポイントです。なぜなら、これらの仕様は複雑さを排除するように設計されたものですが、製品固有の管理 API は主な複雑さの 1 つだからです。この Web サービス・インターフェースは別の HTTP サーバー製品から再利用できますが、それをサポートするために管理クライアントがロジックを変更する必要はありません。

プロパティー用の XML スキーマを作成できるように、後でこれらのプロパティーにネームスペースを追加する予定です。ThreadsPerChildListenServerName プロパティーの型は、それぞれ integer、integer、URI です。Muse ベースの正しいコードと成果物を生成する際に使用できる WSDL を作成するには、ここまでの説明内容を理解していれば十分です。


セクション 4. WSDL の設計 (パート 2): リソース・オペレーション

Web サービス・インターフェースに含めるべきオペレーションを選択するには、WSRF 仕様と WSDM 仕様に加えて、httpd の /bin ディレクトリーに入っている実行可能ファイルについても理解しておく必要があります。これらの標準をできる限り再利用できるように、まず WSRF と WSDM に注目しましょう。

WS-* オペレーション

WSRF ベースのリソースを作成する以上は、リソース・プロパティー文書だけでなく、その文書を操作するための WSRP オペレーションも必要です。WSRF で最小限必要となるオペレーションは 1 つだけ、すなわち GetResourceProperty だけです。WSDM から選択したリソース・プロパティーはオペレーションの定義を行わない機能の一部なので、GetResourceProperty だけが必要となります。WSRF のその他の部分 (WS-ResourceLifetime や WS-ServiceGroup など) は、この例には適用されません。

WSRP では実際に 3 つの「get」オペレーションが定義されていますが、これらは同時に要求できる情報の数が異なるだけで、非常によく似ています。そのため Muse 2.0 では、3 つのオペレーション (GetResourcePropertyGetResourcePropertyDocumentGetMultipleResourceProperties) すべてが 1 つのコンポーネント (機能) として実装されています。これについては、Muse の文書に含まれる入門チュートリアルで詳しく説明されています。ここでは、他の 2 つの「get」オペレーションを WSDL に追加するのはどのような理由からなのかを説明するだけにとどめます。これらのオペレーションを実行するコードを含める予定があり、オペレーションがアプリケーションに余分な負荷をかけない場合には、リモート・クライアントに公開しておくと便利でしょう。

Muse のすべてのサンプル・アプリケーションで使用されている、もう 1 つの非常に有用なオペレーションとして、WS-MetadataExchange (WSX) 仕様の GetMetadata があります。このオペレーションは、クライアントにとって、リソースの WSDL 文書を解決するための極めて堅固な手段となります。Web ブラウザーで使用される ?wsdl 規則は SOAP に準拠しておらず、仮想パスを考慮に入れていません。そのため、WSDL のすべての部分をクライアントが解決できるように、可能な限りこのオペレーションをサポートするとよいでしょう。

つまり最終的に WSDL に含める WS-* オペレーションは、GetResourcePropertyGetResourcePropertyDocumentGetMultipleResourceProperties、および GetMetadata となります。

HTTP オペレーション

httpd オペレーションの保護

サーバーの起動時や停止時にこのような重要オペレーションを開放する場合は、当然ながら、セキュリティーが問題となります。これらのアクションの認証と許可はこのチュートリアルの対象範囲外ですが、Web サービスのセキュリティーについて学ぶための情報は「参考文献」セクションに記載されています。

「/bin には複数の実行可能ファイルやタスクが入っているが、管理クライアントから呼び出すことのできる新規オペレーションを定義する際には httpd アプリケーションに焦点を当てる」ということは、既に述べました。リソース・プロパティーと同様にオペレーションについても、httpd 自体ではなく、HTTP サーバー全般に共通するものに焦点を当てることにします。そこで明白な候補となるのが StartStop の 2 つです。可用性の維持と最適化を担当している場合、管理クライアントは必ずサーバーの可用性を制御しなければなりません。Start オペレーションと Stop オペレーションはそれぞれ、httpd アプリケーションの実行と終了にマップすることが可能です。

この単純なシナリオでは、Start オペレーションにも Stop オペレーションにもパラメーター・リストは指定されません。WSDL メッセージ用のスキーマは、リソース・プロパティー文書と同じネームスペースに作成します。これらのオペレーションが WSRP オペレーションやリソース・プロパティー文書と組み合わさって、リソースのポート・タイプが形成されます。ポート・タイプは 1 つのまとまったインターフェースとして機能するものであり、クライアントはこれを使用して HTTP サーバー・リソースの推論と操作を行います。


セクション 5. WSDL の設計 (パート 3): XML の作成

このセクションでは、httpd リソース用の実際の WSDL 文書を作成することによって、最後の 2 つのセクションの設計判断を開始します。Muse SDK で提供される テンプレート WSDL を修正し、必要な WS-* 定義が含まれるようにします。

Muse SDK には、WSRF 仕様と WSDM 仕様で定義されているプロパティーとオペレーションをすべて含むテンプレート、WSDL が付属しています。このテンプレートは、不要な定義にコメント・マーカーを追加してカスタムのプロパティーとオペレーションを追加すれば、修正することができます。この WSDL は、入門チュートリアルの学習時に使用したものと同じです。テンプレートは Muse SDK の /docs/2.0.0/tutorial/artifacts ディレクトリーにありますが、ここからもダウンロード可能です。

http-management という名前のディレクトリーを作成し、そこにテンプレート・ファイルのコピーを保存してください。入門チュートリアルと同様に、テンプレートから参照されるすべての WS-* WSDL ファイルと XSD ファイルもコピーする必要があります。その後、以下のステップを実行してカスタマイズを行ってください。

  1. WSDL ファイルに「http-server.wsdl」のような意味のある名前を付けます。
  2. テキスト・エディターを使用して、現在のターゲット・ネームスペース (http://ws.apache.org/muse/test/wsrf) を検索・置換します。ネームスペースを http://www.example.com/http-server に変更してください。
  3. テキスト・エディターを使用して、現在の WSDL 名 (WsResource) を検索・置換します。WSDL 名を HttpServer に変更してください。
  4. WSDL の下部で、<wsdl-soap:address/> 要素の location 属性を http://localhost:8080/http-management/services/http-server に変更します。
  5. httpd リソースで使用しないリソース・プロパティーを、すべて削除します。これには、CurrentTimeTerminationTimeQueryExpressionDialect、および 4 つのトピック関連プロパティーが含まれます。
  6. httpd リソースで使用しない <wsdl:message/> 要素と <wsdl:operation/> 要素を、すべて削除します。これには、 QueryResourcePropertiesSetResourcePropertiesSubscribe、および GetCurrentMessage が含まれます。

これで、テンプレート WSDL が httpd リソース用にカスタマイズされました。WSDM で定義された 5 つのプロパティーと、4 つのオペレーション (GetResourcePropertyGetResourcePropertyDocumentGetMultipleResourcePropertiesGetMetadata) が指定された状態になっています。残りはすべて、HTTP サーバー特有のプロパティーとオペレーションを追加するものです。


セクション 6. WSDL の設計 (パート 4): HTTP の追加

WSDL 作成に関するこの最終セクションでは、カスタマイズ済みの WSDL ファイルに httpd 固有のリソース・プロパティーとオペレーションを追加します。その後、コード生成に進み、Muse のコマンド行ツールを使ってこの WSDL からアプリケーションを作成します。

HTTP リソース・プロパティー

httpd 固有のリソース・プロパティーを追加するには、専用の XML スキーマ定義を作成し、それらへの参照をリソース・プロパティー文書に挿入しなければなりません。リソース・プロパティーは、ThreadsPerChildListenServerName. の 3 つです。明確にするため、ListenPortNumber にリネームし、Web サービス・クライアントが httpd 固有の構成データを知る必要がないようにしてください。

リソース・プロパティー文書は、http://www.example.com/http-server にバインドされた <xsd:schema/> 要素下の <wsdl:types/> セクションに定義されています。これはリスト 1 に示すようなコードです。

リスト 1. リソース・プロパティー文書の定義
<xsd:schema elementFormDefault="qualified" 
      targetNamespace="http://www.example.com/http-server">

   <xsd:element name="HttpServerProperties">
       <xsd:complexType>
        
            ...
            
</xsd:schema>

このスキーマに、リスト 2 に示された 3 つのプロパティー定義を追加する必要があります。追加する場所は HttpServerProperties 要素の上でも下でもかまいません。

リスト 2. 3 つのプロパティー定義
<xsd:element name="ServerName" type="xsd:anyURI"/>
<xsd:element name="PortNumber" type="xsd:integer"/>
<xsd:element name="ThreadsPerChild" type="xsd:integer"/>

この 3 行はプロパティーの型を定義していますが、リソース・プロパティー文書にプロパティーの「インスタンス」を追加するものではありません。それを行うには、リスト 3 に示すように、HttpServerProperties 要素に追加する必要があります。

リスト 3. HttpServerProperties 要素への追加
<xsd:element name="HttpServerProperties">
    <xsd:complexType>
        <xsd:sequence>
            <xsd:element ref="tns:ServerName"/>
            <xsd:element ref="tns:PortNumber"/>
            <xsd:element ref="tns:ThreadsPerChild"/>
            
            ...
            
        </xsd:sequence>
    </xsd:complexType>
</xsd:element>

ref 属性が使われていることに注目してください。これは、リソース・プロパティー文書内にある他のスキーマ型を参照する場合の最も一般的な方法です。ここで示されているのは、リソース・プロパティー文書の各インスタンスには 3 つの型のインスタンスがそれぞれ 1 つ存在すべきだということです。つまり、これらのプロパティーの 1 つに対する GetResourceProperty 呼び出しはすべて、1 つの値を返す必要があります。

HTTP リソース・オペレーション

次は、リソース・プロパティーの定義を追加した <xsd:schema/> 要素に、Start オペレーションと Stop オペレーションのためのメッセージ型を追加します。これらのオペレーションにはパラメーターがないため、作業はとても簡単です。

リスト 4. メッセージ型の追加
<xsd:element name="Start"/>
<xsd:element name="StartResponse"/>

<xsd:element name="Stop"/>
<xsd:element name="StopResponse"/>

<xsd:element name="StartFailedFault">
    <xsd:complexType>
        <xsd:complexContent>
            <xsd:extension base="wsrf-bf:BaseFaultType" />
        </xsd:complexContent>
    </xsd:complexType>
</xsd:element>

<xsd:element name="StopFailedFault">
    <xsd:complexType>
        <xsd:complexContent>
            <xsd:extension base="wsrf-bf:BaseFaultType" />
        </xsd:complexContent>
    </xsd:complexType>
</xsd:element>

型なしとオープン・コンテンツとの違い

「型がないこと」 (Java では「void」) と「オープン・コンテンツを許可すること」を混同しないでください。後者の場合は、xsd:anyType という型が必要です。Muse のコード生成ツールは、xsd:anyType のパラメーターを JDK の org.w3c.dom.Element 型にマップし、Java メソッドでの処理用として未加工の XML コンテンツを提供します。この例ではパラメーターは不要なので、型はブランクのままにしておいてください。

メッセージ要素は空 (void) なので、type 属性はありません。また、HTTP サーバーのライフ・サイクル特有のエラーをレポートすることができるように、障害の型を 2 つ (各オペレーションに 1 つ) 追加しています。WSRF の BaseFault を拡張したこれらのフィールドを使用すれば、その型のタイム・スタンプ、メッセージ、発信元などを伝達できます。

ここで、これらのオペレーション用に <wsdl:message/> 要素と <wsdl:operation/> 要素を定義し、ポート・タイプに含められるようにする必要があります。ほとんどの WSDL エディターでは、<wsdl:message/> 要素を追加すると自動的に <wsdl:operation/> 要素が追加されますが、通常のテキスト・エディターを使用している人のために、リスト 5 に XML を示します。<wsdl:message/> 要素は、現在の <wsdl:message/> 要素リストの末尾に追加できます。WSDL のポート・タイプ下にある <wsdl:operation/> 要素についても同じです。

リスト 5. XML サンプル
<wsdl:message name="StartRequest">
    <wsdl:part name="StartRequest" element="tns:Start" />
</wsdl:message>
<wsdl:message name="StartResponse">
    <wsdl:part name="StartResponse"/>
</wsdl:message>
<wsdl:message name="StartFailedFault">
    <wsdl:part name="StartFailedFault" element="tns:StartFailedFault" />
</wsdl:message>
<wsdl:message name="StopRequest">
    <wsdl:part name="StopRequest" element="tns:Stop" />
</wsdl:message>
<wsdl:message name="StopResponse">
    <wsdl:part name="StopResponse" />
</wsdl:message>
<wsdl:message name="StopFailedFault">
    <wsdl:part name="StopFailedFault" element="tns:StopFailedFault" />
</wsdl:message>

<wsdl:portType name="HttpServerPortType" 
               wsrf-rp:ResourceProperties="tns:HttpServerProperties">
               
    ...
    
    <wsdl:operation name="Start">
      <wsdl:input  wsa:Action="http://www.example.com/http-server/Start" 
                   name="StartRequest" message="tns:StartRequest" />
      <wsdl:output wsa:Action="http://www.example.com/http-server/StartResponse" 
                   name="StartResponse" message="tns:StartResponse" />
      <wsdl:fault name="StartFailedFault" message="tns:StartFailedFault"/>
      <wsdl:fault name="ResourceUnknownFault" message="tns:ResourceUnknownFault"/>
      <wsdl:fault name="ResourceUnavailableFault" 
                   message="tns:ResourceUnavailableFault"/>
  </wsdl:operation>
  <wsdl:operation name="Stop">
      <wsdl:input  wsa:Action="http://www.example.com/http-server/Stop" 
                   name="StopRequest" message="tns:StopRequest" />
      <wsdl:output wsa:Action="http://www.example.com/http-server/StopResponse" 
                   name="StopResponse" message="tns:StopResponse" />
      <wsdl:fault name="StopFailedFault" message="tns:StopFailedFault"/>
      <wsdl:fault name="ResourceUnknownFault" message="tns:ResourceUnknownFault"/>
      <wsdl:fault name="ResourceUnavailableFault" 
                   message="tns:ResourceUnavailableFault"/>
    </wsdl:operation>
               
</wsdl:portType>

これで WSDL は完成です。WSRF、WSDM、WSX、および独自のカスタム定義に沿ったプロパティーとオペレーションを含む、HTTP サーバー用の WSDM インターフェースができました。次は Muse のコード生成ツール、WSDL2Java を利用して、このインターフェースを httpd 固有のコマンドおよび設定にマップしましょう。


セクション 7. WSDL2Java によるコード生成

ここでは、WSDL2Java ツールを使用し、Muse ベースのアプリケーション用にスケルトンの Java コードと XML 成果物を生成します。コード生成が完了したら、プロパティーとオペレーションを httpd インストール済み環境にマップする方法を説明します。

この時点で、http-management という名前のディレクトリー内に http-server.wsdl ファイル (およびそれが依存する WS-* ファイル) があるはずです。コマンド行を使用し、http-management ディレクトリーに切り替えて以下のコマンドを実行してください。

wsdl2java -wsdl http-server.wsdl

カスタム機能はネームスペースによって定義される

カスタム機能の定義はすべて XML ネームスペースによって分離されるということを覚えておきましょう。WSDL2Java は、WSDL を分析する際、ポート・タイプで参照されている新規の各スキーマに対して、新規のカスタム機能 (パッケージ、インターフェース、実装クラス) を作成します。そのため、いくつかのスキーマを結合したポート・タイプを持つ大規模プロジェクトの場合は、作成する実装クラスが複数存在することになります。これにより、「特定の機能の動作をデバッグするだけなのに巨大な集積 Java クラスを調べなければならない」という事態がなくなります。

このツールは 3 つの ディレクトリー (JavaSource、WebContent、src) と 1 つのビルド・ファイル (Apache Ant) を生成します。JavaSource ディレクトリーには、httpd 固有の機能のスケルトン・ソース・コードが入っています。WebContent ディレクトリーには、Apache Axis2 (SOAP エンジン)、Muse のライブラリー、WSDL のファイル、および Muse のデプロイメント記述子が入っています。WebContent ディレクトリーに入っているものを修正する必要はありませんが、Muse SDK のサンプル・プロジェクトに含まれるものと似ているはずです。src ディレクトリーには、リモート・クライアント用の完全なソース・コードがあります。このコードを使用すると、XML 「配管」コードを多数書かなくても、WSDM インターフェースと通信できます。

JavaSource のパッケージ・ディレクトリーを詳しく調べて、Java のソース・ファイルを見つけてください。ファイル名は IMyCapability.java と MyCapability.java になっているはずです。デフォルトでは、WSDL2Java は、生成済みアプリケーションを構成して WS-* 機能の Muse による実装を使用できるようにした後、HTTP サーバー定義を含むすべてのカスタム機能に対する Java コードを作成します。したがって、WSRF、WSDM、または WSX の構成体に対するコードは生成されません。これらの構成体は、WebContent/WEB-INF/lib 内にある Muse のライブラリーによって処理されます。ここにあるソース・コードは、Java EE の WAR ファイルが作成される前に、ビルド・ファイルによってコンパイルされて 1 つの JAR ファイルにまとめられ、WebContent/WEB-INF/lib に追加されます。

IMyCapability.java ファイルを開くと Java インターフェースを確認できますが、このインターフェースには、3 つの httpd プロパティーすべてに対する getter メソッドと setter メソッドに加えて、start メソッドと stop メソッドも定義されています。また、機能の XML ネームスペースに対する定数も指定されています。これは Muse の org.apache.muse.ws.resource.WsrfCapability インターフェースを拡張したものであり、WSRF ベースの全機能の基盤であるということも、覚えておいてください。コードはちょうどリスト 6 のようになります。

リスト 6. Java インターフェースのコード
package com.example.www.http_server;

import javax.xml.namespace.QName;

public interface IMyCapability
{
    String PREFIX = "tns";

    String NAMESPACE_URI = "http://www.example.com/http-server";

    public int getThreadsPerChild();

    public void setThreadsPerChild(int param0);

    public String getServerName();

    public void setServerName(String param0);

    public int getPortNumber();

    public void setPortNumber(int param0);

    public void start() throws StartFault;

    public void stop() throws StopFault;
}

MyCapability.java の内容を見れば、インターフェースの全メソッドに対するメソッド・スタブが定義された実装クラスが確認できます。次のセクションでは、これらのメソッドを埋めていき、WSDM インターフェースが実際に機能するようにします。


セクション 8. HTTP Server オペレーションの実装

このセクションでは、httpd アプリケーションを使用して start メソッドと stop メソッドを実装します。stop の実装は Windows 固有のものですが、このセクションの説明を読めば、UNIX ベース・システム用として機能させることも簡単であるとわかるでしょう。

start メソッドと stop メソッドはいずれも、シェル・コマンドを実行するために Java の java.lang.Runtime クラスを使用する必要があります。どちらのメソッドも、適切なコマンド行フラグを指定して httpd アプリケーションを実行するだけなので、極めて単純です。リスト 7 のコードは、httpd が /apache-2.2 (Windows ユーザーの場合は C:\apache-2.2) にインストールされているということを前提としています。これを MyCapability.java ファイルにコピー・アンド・ペーストしてください。

リスト 7. MyCapability.java ファイルにコピー・アンド・ペースト
 public void start() 
  throws Exception
 {
  try
  {
   Runtime.getRuntime().exec("/apache-2.2/bin/httpd -k start");
   getLog().info("The httpd process was started successfully.");
  }
  
  catch (IOException error)
  {
   throw new Exception("The httpd process failed to start.");   
  }
 }

 public void stop() 
  throws Exception
 {
  try
  {
   // Unix users: use ps and kill to do the same task
   Runtime.getRuntime().exec("/apache-2.2/bin/httpd -k stop");
   getLog().info("The httpd process was stopped successfully.");
  }
  
  catch (IOException error)
  {
   throw new Exception("The httpd process failed to stop.");   
  }
 }

Runtime.exec() が呼び出されるたびに、オペレーションが正常に実行されたことを確認するメッセージが Muse ログ・ファイルに出力されます。このログ・ファイルは、WEB-INF/services/muse/log ディレクトリー下のデプロイ済み WAR ファイルにあります。

この時点で、どのようにして汎用 Web サービス・オペレーションを取得し、実際の IT リソース (httpd) にマップしたかがわかるはずです。この実装を、インターフェース (クライアント側から見れば動作) を変更することなく別の HTTP サーバー製品用に変更する方法も、容易に想像できるでしょう。


セクション 9. HTTP Server オペレーションの実装

このセクションでは、httpd.conf ファイルを使用して、リソース・プロパティー・フィールドの値を埋めていきます。実装では、WS-Security 認証を導入する必要がないように、リモート・クライアントに対して 3 つの プロパティーが読み取り専用として定義されています。また、これらのプロパティーを読み取り専用のままにしておけば、httpd プロセス実行中の変更を防止するためのチェックも、回避することができます。

プロパティーは起動後に変化することがないため、初期化中に httpd.conf からプロパティーを読み込んでおき、WSDL2Java が MyCapability クラスに作成したフィールドに、それらのプロパティーを保持することも可能です。この実装コードを MyCapability ファイルにコピー・アンド・ペーストしてください。

リスト 8. 実装コード
    public void initialize()
        throws SoapFault
    {
        super.initialize();
        
        Map configParams = null;
	        
	try
	{
	    configParams = readConfigFile("/apache-2.2/conf/httpd.conf");
	}

	catch (IOException error)
	{
	    throw new SoapFault("Error while reading httpd.conf.", error);
	}

	_ServerName = (String)configParams.get("ServerName");
	
	String portString = (String)configParams.get("Listen");
	String threadsString = (String)configParams.get("ThreadsPerChild");
	
	_PortNumber = Integer.valueOf(portString);
        _ThreadsPerChild = Integer.valueOf(threadsString);
    }
    
    protected Map readConfigFile(String filePath)
        throws IOException
    {
        BufferedReader reader = new BufferedReader(new FileReader(filePath));
        String nextLine = null;
        
        Map configParams = new HashMap();
        
        while ((nextLine = reader.readLine()) != null)
        {
            nextLine = nextLine.trim();
            
            // ignore comments and blank lines
            if (nextLine.length() == 0 || 
                nextLine.charAt(0) == '#' || 
                nextLine.charAt(0) == '<')
                continue;
            
            int space = nextLine.indexOf(' ');
            String name = nextLine.substring(0, space);
            String value = nextLine.substring(space + 1);
            configParams.put(name, value);
        }
        
        return configParams;
    }

可変のリソース・プロパティーを許可する

動的なプロパティーの場合は、フィールドの値を削除して、代わりに各 getter メソッドで httpd.conf からプロパティーの値を読み取ることになるでしょう。このアプリケーションを拡張してプロパティーを可変にした場合、getter メソッドと setter メソッドはどちらも、要求時に java.io パッケージを使用して httpd.conf ファイルを読み込むように実装されます。

最初のメソッドは、基本クラスの initialize メソッド (すべての自己完結型開始タスクを機能が実行できるメソッド) をオーバーライドしています。このメソッドは、httpd.conf ファイル内にある「名前と値」の対を単純に java.util.Map に読み込んだ後、見つけた値を使ってクラスのフィールドを設定します。initialize メソッドが呼び出されるのは、Muse アプリケーションがいずれかの SOAP 要求にサービスを提供する前です。

2 番目のメソッドは、ファイルを解析して java.util.Map に渡し、入力データからコメント行とブランク行を入念に削除するという、実際のタスクを実行します。最後に、getter メソッドはそのままにしておく必要があります。これらの getter メソッドは、Muse の GetResourceProperty 実装から呼び出されたときに、httpd.conf から読み込まれた値を返します。


セクション 10. 実装をより構成可能なものにする

これで実装はほぼ完成ですが、アプリケーションをビルドしてデプロイする前に対処すべき問題がもう 1 つあります。ハードコーディングされた httpd のインストール・パスです。

startstopinitialize メソッドでは、httpd インストール済み環境内にあるファイルを参照すると、/apache-2.2 ディレクトリーが参照されます。これはハッキングであり、他のマシン上でこの WSDM 管理機能インターフェースを httpd の他のインスタンスのために再利用することはできなくなります。インストール・ディレクトリーを Muse アプリケーションの初期化パラメーターにすれば、新規マシンごとにアプリケーションを再コンパイル/再ビルドする必要がありません。

Muse のデプロイメント記述子では、リソース・タイプの各機能に対して初期化パラメーター (単純な「名前と値」の対) を指定することも可能です。WebContent/WEB-INF/services/muse/muse.xml という名前のファイルを開いて、リスト 9 に示す XML のフラグメントを探してください。

リスト 9. XML フラグメント
<capability>
  <capability-uri>http://www.example.com/http-server</capability-uri>
  <java-capability-class>com.example.www.http_server.MyCapability</java-capability-class>
</capability>

このフラグメントは、Muse ランタイムに対して HTTP サーバーの機能を説明しています。ここに、httpd のインストール・パスを格納する初期化パラメーターを追加することができます。このアプリケーションを別のマシン (異なるパスに異なる httpd インストール済み環境を持つマシン) に移動する場合は、再コンパイルと再ビルドではなく、muse.xml ファイルに新しいパスを指定すればよいだけです。リスト 10 は、muse.xml に追加する構文を示しています。

リスト 10. muse.xml に追加する構文
<capability>
  <capability-uri>http://www.example.com/http-server</capability-uri>
  <java-capability-class>com.example.www.http_server.MyCapability</java-capability-class>
<init-param>
      <param-name>httpd-install-dir</param-name>
      <param-value>C:\apache-2.2</param-value>
  </init-param>
</capability>

次は、この値が読み込まれてハードコーディング済みパスの代わりに使用されるように、Java コードを変更する必要があります。幸い、この重労働はすべて Muse ランタイムによって実施されるため、必要なのは getInitializationParameter()メソッドを呼び出すことだけです。現在のコードを修正し、リスト 11 の太字の行を含めたものにしてください。

リスト 11. getInitializationParameter() メソッドの呼び出し
 public void initialize()
  throws SoapFault
 {
  super.initialize();
  
String installDir = getInitializationParameter("httpd-install-dir");
  
  Map configParams = null;
	  
	try
	{
	 configParams = readConfigFile(installDir + "/conf/httpd.conf");
	}

	catch (IOException error)
	{
	 throw new SoapFault("Error while reading httpd.conf.", error);
	}

	_ServerName = (String)configParams.get("ServerName");
	
	String portString = (String)configParams.get("Listen");
	String threadsString = (String)configParams.get("ThreadsPerChild");
	
	_PortNumber = Integer.valueOf(portString);
  _ThreadsPerChild = Integer.valueOf(threadsString);
 }
 
 ...
 
 public void start() 
  throws Exception
 {
  try
  {
String installDir = getInitializationParameter("httpd-install-dir");
  
   Runtime.getRuntime().exec(installDir + "/bin/httpd -k start");
   getLog().info("The httpd process was started successfully.");
  }

  catch (IOException error)
  {
   throw new Exception("The httpd process failed to start.");   
  }
 }
 
 public void stop() 
  throws Exception
 {
  try
  {
String installDir = getInitializationParameter("httpd-install-dir");
  
   Runtime.getRuntime().exec(installDir + "/bin/httpd -k stop");
   getLog().info("The httpd process was stopped successfully.");
  }

  catch (IOException error)
  {
   throw new Exception("The httpd process failed to start.");   
  }
 }

これで、httpd 用の WSDM エンドポイントをコンパイル、ビルド、デプロイする準備が整いました。


セクション 11. WSDM エンドポイントのビルドとデプロイ

WSDL2Java を実行したのと同じコマンド行から、今度は Ant を使用し、Apache Tomcat にデプロイされる Java EE WAR ファイルをビルドしましょう。コマンド行から ant を実行するだけで build.xml ファイル内の命令が実行され、最終的には、http-management.war という名前のファイルが作成されます。

WAR ファイルが作成されたら、このファイルを Apache Tomcat インストール済み環境の /webapps ディレクトリーにコピーする必要があります。Tomcat サーバーを起動すると、WAR ファイルが展開され、デプロイされます。これで次の最終セクションに進むことができます。最終セクションでは、WSDM エンドポイントに対するテスト・クライアントを実行して、その動作を確認します。


セクション 12. WSDM エンドポイントのテスト

httpd 用 WSDM エンドポイントのビルドとデプロイが完了し、Tomcat サーバーが起動したら、テスト・クライアントを実行し、実際の動作を確認することができます。WSDL2Java によって生成されたリモート・クライアントを覚えていますか。これには、すべてのリソース・プロパティーに対する getter メソッドと メソッド、およびすべてのオペレーションに対するメソッドが定義されています。リスト 12 のコードでは、このクライアントを使って Start オペレーションと Stop オペレーションを呼び出し、すべてのリソース・プロパティー値 (GetResourceProperty) を読み取っています。このコードを HttpProxy.java ファイルにコピー・アンド・ペースし、コンパイルして実行してください。

リスト 12. Start オペレーションと Stop オペレーションの呼び出し
    public static void main(String[] args)
    {
        //
        // create EPR for test resource
        //
        URI address = URI.create("http://localhost:8080/http-management/services/http");
        EndpointReference epr = new EndpointReference(address);

        //
        // create proxy - uncomment setTrace() to see SOAP messages
        //
        HttpProxy http = new HttpProxy(epr);
        // http.setTrace(true);

        try
        {

            //
            // start server
            //
            http.start();

            //
            // read/print some property values
            //
            System.out.println("Name: " + http.getServerName());
            System.out.println("Port: " + http.getPortNumber());
            System.out.println("Threads: " + http.getThreadsPerChild());
        }

        catch (Throwable error)
        {
            error.printStackTrace();
        }

        try
        {
            //
            // stop server
            //
            http.stop();
        }

        catch (Throwable error)
        {
            error.printStackTrace();
        }
    }

このテスト・クライアントの出力は、以下のようになります。

Name: http://localhost
Port: 80
Threads: 250

http.setTrace(true); 呼び出しのコメントを外すと、テスト・クライアントによって送受信される SOAP メッセージをすべて確認することができます。この方法は、新規の WSDM エンドポイントをデバッグする際に極めて有用です。現時点でこの行のコメントを外すと、1 つの Start 呼び出し、3 つの GetResourceProperty 呼び出し、そして 1 つの Stop 呼び出しが確認できます。

最後に、Tomcat のコンソールまたは Muse のログ・ファイル (WEB-INF/services/muse/log/muse.log) に目を通すと、start メソッドと stop メソッドで出力したメッセージを確認できます。オペレーションが動作していることを確認するもう 1 つの方法は、テスト・クライアントから stop 呼び出しを削除してから Web ブラウザーで http://localhost を調べるという方法です。「It works!」というメッセージが再び表示されていれば、httpd プロセスが実際にアクティブであることがわかります。


セクション 13. まとめ

このチュートリアルでは、単純なチュートリアルの範囲を超えて、Apache Muse と実際の IT 製品との統合に着手する方法を説明してきました。実際に動作する Apache HTTP Server 用 WSDM インターフェースを構築し、独自のテスト・クライアントと Web ブラウザーを使って検証を行いました。さらに、「WSRF や WSDM における抽象的概念」を「ソフトウェア製品における具体的概念」にマップする方法についても、Muse のプログラミング・モデルを使って説明しました。これらの考え方は、WSDM で他の製品を扱う際の基礎として役立つでしょう。

参考文献

学ぶために

  • OASIS 標準: Apache Muse の Web サイトでは、このプロジェクトがサポートするすべての OASIS 標準が提供されています。
  • WS-Security support のサポート: Apache Axis2 は、このチュートリアルで構築したアプリケーションに認証を追加する際に使用できる、WS-Security をサポートしています。
  • Apache Muse - チュートリアル: Muse の使用経験がない場合は、このチュートリアルに挑戦する前に、Muse パッケージに含まれる入門チュートリアルを修了しておいてください。
  • developerWorks の「Autonomic computing」ゾーンには、記事、チュートリアル、標準・仕様に加えて、ダウンロード可能なツール (Build to Manage Toolkit for Problem Determination など) へのリンクも用意されています。
  • SOA サービスと Web サービス: developerWorks の「SOA and Web services」ゾーンでは、WS 標準とその影響 (テクノロジーに及ぼす影響) について、さらに詳しいリソースが提供されています。

製品や技術を入手するために

  • Apache Muse 2.0.0.: Muse をダウンロードして、このチュートリアルで使用される SDK を入手してください。
  • Apache HTTP Server: Apache HTTP Server をダウンロードして、このチュートリアルで構築したアプリケーションを実行できるようにしてください。

議論するために

コメント

developerWorks: サイン・イン

必須フィールドは(*)で示されます。


IBM ID が必要ですか?
IBM IDをお忘れですか?


パスワードをお忘れですか?
パスワードの変更

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


お客様が developerWorks に初めてサインインすると、お客様のプロフィールが作成されます。会社名を非表示とする選択を行わない限り、プロフィール内の情報(名前、国/地域や会社名)は公開され、投稿するコンテンツと一緒に表示されますが、いつでもこれらの情報を更新できます。

送信されたすべての情報は安全です。

ディスプレイ・ネームを選択してください



developerWorks に初めてサインインするとプロフィールが作成されますので、その際にディスプレイ・ネームを選択する必要があります。ディスプレイ・ネームは、お客様が developerWorks に投稿するコンテンツと一緒に表示されます。

ディスプレイ・ネームは、3文字から31文字の範囲で指定し、かつ developerWorks コミュニティーでユニークである必要があります。また、プライバシー上の理由でお客様の電子メール・アドレスは使用しないでください。

必須フィールドは(*)で示されます。

3文字から31文字の範囲で指定し

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


送信されたすべての情報は安全です。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Tivoli (service management), SOA and web services
ArticleID=252230
ArticleTitle=Apache Muse を使用して HTTP サーバー用の WSDM インターフェースを作成する
publish-date=11212006