WebServices - Axis

Axis インストール方法

目次

はじめに

このドキュメントでは Apache Axis のインストール方法を解説します。Java コードの書き方を既に知っていて、XML を恐れない人を対象としています。また、既にアプリケーションサーバかサーブレットエンジンを持っていて、その操作と配備に慣れている人を対象としています。もしアプリケーションサーバが必要であれば、Jakarta Tomcat [英語] をお勧めします。[ もし Tomcat をインストールするのであれば、最新の 4.1.x 版で、かつ、Java 1.4 対応の LE 版ではなく(LE 版は XML パーサである Xerces を省略するので)、完全版を取得してください ]。その他のサーブレットエンジンも、バージョン 2.2 以上のサーブレット API を実装しているのであれば対応しています。Axis クライアントと Axis サーバは Java 1.3 以降を必要としていることに注意してください。

Axis に関する詳しい情報はユーザガイドをご覧下さい。

事前知識

Java 、サーバサイド Java 、SOAPに初めて触れる人たちの多くは、Axis の様々な問題に直面しています。 Axis クライアントと Axis サーバのコードを書いていけば SOAP について学ぶことはできますが、配列とは何か、といった Java の基本概念、サーブレットがどのようにして動くのか、といったアプリケーションサーバの基本概念、そして HTTP プロトコルの基本を学ぶにはふさわしい時機ではありません。

Web サービスのコードを書くのに必要な事前知識は以下の通りです :

  1. 基本的な、Java のデータ型、クラス、プログラミング概念。
  2. スレッド、競合状態、スレッドセーフ、同期化。
  3. クラスローダ、階層クラスローダ、"ClassNotFoundException" の一般的な原因。
  4. 例外トレースから問題の突き止め方、 NullPointerException (NPE) やその他の一般的な例外と、その修正方法。
  5. Webアプリケーション、サーブレット。Webアプリケーションにおけるクラス、ライブラリとデータの配置場所。
  6. アプリケーションサーバの起動方法と、Webアプリケーションの配備方法。
  7. ネットワーク、IP プロトコル群とソケット API の中心的な概念。特に TCP/IP。
  8. HTTP、中心的なプロトコルとエラーコード、HTTP ヘッダと(できたら)基本認証の詳細。
  9. XML。パース方法等は必要ではなく、well-formed XML (整形式の XML 文書)と valid XML (妥当な XML 文書)の構成要素。

Axis と SOAP はこれらの詳細に依存しています。もしこれらを知らないのであれば、Axis (あるいはその他のWebサービスミドルウェア)は学ぶには危険な場所です。遅かれ早かれこれらの詳細を知る必要性がでてきます。Axis よりも学びやすい場所があります。

もし Java を全く知らないのであれば、Axis に取り組めるほどの十分な基礎を身に付けるために、Sun のウェブサイトにある The Java Tutorial のようなところか、Thinking in Java [英語] のような古典から始めるのをお勧めします。簡単なWebアプリケーションを作ってみるのも良いかもしれません。これにより HTTP がどのようにして動いているのか、 Java アプリケーションサーバがどのようにして HTTP と統合しているのかといった知識を身につけることができます。この点については Mastering the World Wide Web [英語] にある講義ノートが(Axis は講義28でのみ紹介されているにも関わらず)参考になるでしょう。

Axis と SOAP を効果的に使うには上記で挙げたもの以上に学ぶべきことがあることに注意しましょう。その他の大きな領域としては "インターネット規模の分散アプリケーションを作る方法" があります。現在のところ誰もその方法を知らないので、実際に自分でやってみて知識を得る必要があります。

ステップ 0: 概念

Apache Axis はオープンソースの SOAP サーバとSOAP クライアントです。SOAP はインターネットを通した、任意の言語で書かれたシステム間の相互アプリケーション通信のための機構です。SOAP は一般的に HTTP 上でメッセージを交換します : クライアントが SOAP リクエストを POST で送り、HTTP サクセスコードと SOAP レスポンス、あるいは HTTP エラーコードのいずれかを受け取ります。オープンソースとは、ソースを得ることができるが問題に直面したときに助けてくれる正式なサポート機関がないことを意味します。

SOAP メッセージは XML メッセージです。これらのメッセージにより SOAP システム間で構造化情報を交換します。メッセージはエンベロープの中の1つ以上の SOAP 要素から構成されています。SOAP 要素とはヘッダとSOAP 本体です。これら要素中のデータを表現するのに SOAP は2つの文法を持っています。1つ目は5節で扱う XML RPC システムの明快な派生物です。2つ目は新しい(そして一般的に優れている)システムである XML スキーマです。Axis は Java オブジェクトをネットワークに送るときと結果を受け取るときに、Java オブジェクトを SOAP データに変換する機構を持っています。何か問題が起きると、サーバは SOAP フォルトを送り、Axis はそれを Java の例外に変換します。

SOAP は異なるシステムを連携させることを目的としています。同じチームによって書かれた Java プログラムを密に連携させるための機構ではありません。SOAP は Java プログラム同士を連携させることができますが、RMI や Corba ほど密には連携できません。RMI なら喜んで直列化していた Java オブジェクトを送ろうとすると、Axis は失敗し、あなたは失望するでしょう。意図的にこのようにしています : もし Axis が RMI を真似て Java オブジェクトをバイトストリームに直列化したら、あらゆるところにおいて Java の特定バージョンに依存することになります。

Axis は、 Java サービスをプログラミングする上で標準的な方法の一つである JAX-RPC API を実装しています。Sun のウェブサイトにある仕様書やチュートリアルを見れば API を理解できます。JAX-RPC API に従ってコードを書けば、Sun や BEA の実装のような、JAX-RPC API の他の実装と連携できます。さらに、Axis は JAX-RPC API をさまざまに拡張する拡張性を提供します。これにより、よりよいプログラムを書くことができますが、Axis の実装とだけしか連携できません。しかし Axis は無料でかつソースを取得できるので、問題にはならないでしょう。

Axis は JAR ファイル axis.jar にコンパイルされていて、JAR ファイル jaxrpc.jarsaaj.jar に宣言されている JAX-RPC API を実装しています。axis.jar はロギング、WSDL プロセッシング、イントロスペクションのための多様なヘルパーライブラリを必要としています。これらの全てのファイルはWebアプリケーション axis.war にパッケージ化し、サーブレットコンテナに配備することができます。Axis にはいくつかのSOAP サービスのサンプルがついてきます。新しくコンパイルしたクラスを Axis の webapp に追加して登録すれば、自分用の SOAP サービスを追加することができます。

その前に、Axis をインストールして動かさなくてはいけません。

ステップ 1: webapp を準備する

ここでは、ウェブサーバが localhost のポート 8080 で起動していていることを仮定します。もしお使いのサーバが違うポートで起動しているのであれば、このドキュメントの 8080 をあなたのポート番号に読み替えてください。

お使いのアプリケーションサーバのどのディレクトリにWebアプリケーション("webapps")を配備すればいいのか、調べておく必要があります。このディレクトリに、ダウンロードした xml-axis の中の webapps/axis ディレクトリをコピーします。このディレクトリに好きな名前を付けることができますが、その名前が、クライアントがアクセスするサービスの URL の基礎となることに注意してください。このドキュメントの残りの部分ではデフォルトの webapp 名を "axis" と仮定しますので、もし必要であれば適切に読み替えてください。

ステップ 2: ライブラリの設定

Axis のディレクトリ中に WEB-INF というサブディレクトリがあります。このディレクトリにはいくつかの基本的な設定情報が入っていますが、あなたが配備したい依存関係やWebサービスを入れる際にも使います。

Axis は XML パーサを探し出せる必要があります。もしアプリケーションサーバか Java ランタイムが、ウェブアプリケーションから XML パーサを見えないようにしているのであれば、XML パーサをダウンロードしてウェブアプリケーションに追加する必要があります。Java 1.4 は Crimson パーサを含んでいるのでこの段階を省略することができますが、Axis チームは Xerces を使うことをお勧めします。

XML パーサを追加するには、JAXP 1.1 XML 準拠のお好みのパーサを手に入れてください。他のパーサでもほとんど動きますが、xml-xerces distribution [英語] にある Xerces のjar 一式 をお勧めします。お使いの JRE やアプリケーションサーバに独自の特定要件がない限り、パーサのライブラリを axis/WEB-INF/lib に入れてください。このドキュメントの例では Xerces を使います。このドキュメントでは Axis からパーサが見えるように AXISCLASSPATH に xml-apis.jar と xercesImpl.jar を追加しています (下をご覧下さい)

もし Xerces や DOM に関する ClassNotFound エラーが出るのであれば、XML パーサがインストールされていないか CLASSPATH (あるいは AXISCLASSPATH) が正しく設定されていません。

Tomcat 4.x と Java 1.4

Java 1.4 で java.* と javax.* から始まるパッケージのロード方法のルールが変わりました。具体的に言うと、それらのパッケージは endorsed ディレクトリからのみロードされます。 jaxrpc.jar と saaj.jar は javax パッケージを含んでいるので、それらはロードされません。もし happyaxis.jsp (下をご覧下さい) から該当するパッケージが見えない場合、それらを axis/WEB-INF/lib から CATALINA_HOME/common/lib にコピーし、Tomcat を再起動してください。

WebLogic 8.1

WebLogic 8.1 には webservices.jar が含まれていますが、これは Axis の saaj.jar と衝突し、Axis 1.2 をそのまま使うことができなくなります。この衝突が起こる理由は、WebLogic が Java Web Services Developer Pack [英語] Version 1.0 の javax.xml.soap.* パッケージにある古い定義を利用する一方、Axis は J2EE 1.4 の新しい改訂版を利用するからです。

しかしながら、Axis 基盤のWebサービスを Weblogic 8.1 で実行することを可能にする2つの設定変更があります。

  • Axis を含む webapp 内の、 WEB-INF/weblogic.xml の <prefer-web-inf-classes> 要素を true に設定します。以下に weblogic.xml の例を示します。
    <weblogic-web-app>
      <container-descriptor>
        <prefer-web-inf-classes>true</prefer-web-inf-classes>
      </container-descriptor>
    </weblogic-web-app>

    もし true に設定すれば、<prefer-web-inf-classes> 要素は WebLogic のクラスローダに対して、アプリケーションクラスやシステムクラスよりも優先して WEB-INF ディレクトリ内にあるクラスをロードするように強制させます。この方法は単一のWebモジュールにしか影響を与えないのでお勧めします。

  • WebLogic サーバを起動するスクリプト内で、CLASSPATH プロパティを修正して、WebLogic の webservices.jar の前に Axis の saaj.jar ライブラリが来るようにします。
    注意: この方法は特定の WebLogic インスタンスにデプロイされた全てのアプリケーションに影響を与えます。これらのアプリケーションは WebLogic の webservices が利用できなくなるかもしれません。

WebLogic のクラスローダの仕組みの詳細については、WebLogic Server Application Classloading [英語] をご覧下さい。

ステップ 3: ウェブサーバの起動方法

ウェブサーバの起動方法は製品ごとに異なります。たいていの場合、単純にスタートアップアイコンをダブルクリックするか、コマンドラインからコマンドを起動するだけです。

ステップ 4: インストールを確認する

Webアプリケーションと依存関係をインストールしたら、サーバがWebアプリケーションを起動しているか確認しましょう。

スタートページを探す

webapp のスタートページを見てみましょう。たいていの場合、http://127.0.0.1:8080/axis/ ですが、もちろんポート番号によって変わります。

これで Apache-Axis のスタートページが見えるはずです。もしスタートページが見えないのであれば、webapp が実際にはインストールされていない、あるいはアプリケーションサーバが起動していません。

happyaxis によって Axis を確認する

リンク Validate the local installation's configuration をたどってください。
リンクをたどると、必須ライブラリとオプションライブラリがあるか確認するテストーページ happyaxis.jsp に行きます。このページの URL はhttp://localhost:8080/axis/happyaxis.jsp のようになります。

もし必須ライブラリのうち一つでも足りなければ、Axis は動きません。
全ての必須ライブラリが見つかり、この確認ページが happy になるまで先に進んではいけません。
オプションコンポーネントはオプションです。必要性がでてきたらインストールしてください。もし internal server error と例外のトレースしか見えない場合、おそらく複数の XML パーサが CLASSPATH (あるいは AXISCLASSPATH) にあり、これがバージョン不整合の原因となっています。余分のパーサを取り除き、アプリケーションサーバを再起動してもう一度試してください。

いくつかのサービスを見てみる

スタートページで View the list of deployed Web services を選んでください。ここでは、サーブレットで表示しないように設定されていない限り、登録されたWebサービスを全て表示します。このページにある、配備されたそれぞれのWebサービスの (wsdl) をクリックすることで、そのWebサービスが立ち上がっていて動いているか確認することができます。

Axis がサポートしている 'インスタント' JWS Webサービスは、ここへ表示されないことに注意してください。このトピックに関してはインストールガイドで詳しく取り扱っています。

SOAP エンドポイントをテストする

そろそろサービスをテストしてもいい頃でしょう。SOAP 1.1 はエンドポイントに XML リクエストを出す際に HTTP POST を使いますが、Axis はテストに便利な生の HTTP GET アクセス機構もサポートしています。まずは getVersion メソッドを呼んでバージョンエンドポイントから Axis のバージョンを取得してみましょう :

http://localhost:8080/axis/services/Version?method=getVersion

次のようなものを返すでしょう :

<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <getVersionResponse
     soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <getVersionReturn
       xsi:type="xsd:string">
         Apache Axis version: 1.1 Built on Apr 04, 2003 (01:30:37 PST)
      </getVersionReturn>
    </getVersionResponse>
  </soapenv:Body>
</soapenv:Envelope>

もちろん Axis のバージョンとビルド日時はあなたの結果とは異なっているでしょう。

JWS エンドポイントのテスト

それでは JWS Webサービスをテストしてみましょう。Axis の JWS Webサービスは Axis の webapp の WEB-INF ツリーに入れた、拡張子 .jws の java ファイルです。URL でその .jws ファイルを要求すると、そのファイルはコンパイルされ、そして実行されます。JWS ページについてはユーザガイドで詳しく取り上げています。

JWS サービスをテストするには、用意されている例、 EchoHeaders.jws (これについては axis/ ディレクトリをご覧下さい) に対してリクエストを投げます。

ブラウザで http://localhost:8080/axis/EchoHeaders.jws?method=list にアクセスしてください。

以下のような、アプリケーションヘッダの XML リストが返って来るでしょう。

<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <listResponse
     soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <listReturn xsi:type="soapenc:Array"
       soapenc:arrayType="xsd:string[6]"
       xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
        <item>accept:image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*</item>
        <item>accept-language:en-us</item>
        <item>accept-encoding:gzip, deflate</item>
        <item>user-agent:Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)</item>
        <item>host:localhost:8080</item>
        <item>connection:Keep-Alive</item>
      </listReturn>
    </listResponse>
  </soapenv:Body>
</soapenv:Envelope>

繰り返しになりますが、正確な戻り値はこれとは異なるでしょうし、正しいホスト名、ポート番号、webapp 名の URL に直す必要があります。

ステップ 5: 新しいWebサービスのインストール

これまでの過程で Axis をインストールし、動かしてきました。次は自分のWebサービスを追加します。

ここでのプロセスを要約すると、(1) 新しいサービスのクラスとライブラリを Axis WAR ディレクトリツリーに入れる、そして (2) それらの新しいファイルを Axis エンジンに認識させる、ということになります。(2) は、Admin ウェブサービスを介して XML デプロイメントディスクリプタを新しいサービスにサブミットすることにより行われます。通常これは AdminClient プログラム、あるいは Ant タスク <axis-admin> により行われます。これら両方とも同じことを行います : Axis SOAP クライアントを起動して、それ自体 SOAP サービスである Axis administration サービスと通信します。Axis administration サービスはある1点について特別な SOAP サービスでもあります。それは、(リモートアクセスではなく)ローカル呼び出しのみに制限されていて、また、あなたのサービスを誰でも管理できるようにさせないためにパスワードで制限されています。クライアントが知っているデフォルトのパスワードがあり、もしそれを変更したら新しいパスワードをクライアントに渡さなければなりません。

最初のステップとして、あなたが書いたコードをサーバに追加します。

WEB-INF ディレクトリの中の "classes" ディレクトリ (つまり axis/WEB-INF/classes ) を探して (あるいは作って) ください。このディレクトリにインストールしたい コンパイル済みの Java クラス を、Java パッケージのディレクトリ構造を壊さないように注意しながらコピーしてください。

もしインストールしたいサービスがすでに JAR ファイルにパッケージ化されているのなら、単に WEB-INF/lib ディレクトリに入れるだけです。依存しているサードパーティ製のライブラリがあれば、同じディレクトリに入れてください。

Axis の webapp に新しいクラスやライブラリを追加したら webapp を再起動してください。これはアプリケーションサーバを再起動するか、あるいは特定の webapp を再起動するサーバ特有の仕組みを利用することによって行います。

注意 : もしあなたのWebサービスが xml-axis の提供する簡単な認証ハンドラを利用している(これは製品版利用を目的としているというよりは、ハンドラの書き方の説明であるため実際はお勧めしません)のであれば 、対応する users.lst ファイルを WEB-INF ディレクトリにコピーする必要があります。

ステップ 6: Webサービスを配備

これまで設定した様々なクラスや JAR が新しいWebサービスを実行します。残っている作業は、このWebサービスを公開する方法を Axis に伝えることです。このサービスが何か、どのメソッドを公開するのか、そして SOAP エンドポイントとしてのその他の側面を XML で表現するWebサービスデプロイメントディスクリプタ (WSDD) を、Axis は受け取ります。

これらの WSDD ファイルについてはユーザガイドとリファレンスガイドで扱います。ここでは Axis サンプルにある株価サービスの WSDD ファイルを使います。

クラスパスの設定

これらのサンプルを動かすために、axis.jar、commons-discovery.jar、commons-logging.jar、jaxrpc.jar、saaj.jar、log4j-1.2.8.jar (あるいはお好みのロギング実装)、そして XML パーサの jar ファイル (例えば xerces.jar) が Java から見えてないといけません。これらのサンプルでは、これらのファイルを AXISCLASSPATH に追加し、サンプル実行時に AXISCLASSPATH を指定しています。また、xml-apis.jar と xercesImpl.jar ファイルを AXIS_LIB ディレクトリにコピーしました。代わりに、XML パーサの jar ファイルを AXISCLASSPATH 変数に追加するか、これら全てのファイルを CLASSPATH 変数に追加してもかまいません。

Windows では、今まで説明したことは次のようにすればよいでしょう。このドキュメントでは Axis を C:\axis にインストールしたと仮定します。この情報を WinNT/2000/XP で恒久的に格納するには、"マイコンピュータ" を右クリックして "プロパティ" を選択します。"詳細" タブをクリックして新しい環境変数を作成します。変数文字列をワードパッドで作成してから該当するテキストフィールドにコピーした方が良いでしょう。

set AXIS_HOME=c:\axis
set AXIS_LIB=%AXIS_HOME%\lib
set AXISCLASSPATH=%AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery.jar;
  %AXIS_LIB%\commons-logging.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;
  %AXIS_LIB%\log4j-1.2.8.jar;%AXIS_LIB%\xml-apis.jar;%AXIS_LIB%\xercesImpl.jar

Unix を使っている方も同じようなことをします。これ以降では、Axis を /usr/axis にインストールしていて、bash シェルを利用していることを想定しています。もし違うシェルを使っている場合は、違いについてシェルのドキュメントをご覧下さい。変数をシェルに行き渡らせるためには、シェルのスタートアップ(ドット)ファイルに変数を追加する必要があります。もう一度シェルドキュメントをご覧下さい。

set AXIS_HOME=/usr/axis
set AXIS_LIB=$AXIS_HOME/lib
set AXISCLASSPATH=$AXIS_LIB/axis.jar:$AXIS_LIB/commons-discovery.jar:
  $AXIS_LIB/commons-logging.jar:$AXIS_LIB/jaxrpc.jar:$AXIS_LIB/saaj.jar:
  $AXIS_LIB/log4j-1.2.8.jar:$AXIS_LIB/xml-apis.jar:$AXIS_LIB/xercesImpl.jar
export AXIS_HOME; export AXIS_LIB; export AXISCLASSPATH

Axis のクライアントコードを利用するには、Java を呼ぶ際に AXISCLASSPATH を選びます。お使いのプラットフォームにより

java -cp %AXISCLASSPATH% ...

と入力するか、あるいは

java -cp "$AXISCLASSPATH" ...

と入力します。CLASSPATH にスペースを含まないのであればクオートを省略してもかまいません。

AXISCLASSPATH 変数を CLASSPATH 変数に追加してもよいでしょう。これによってこのガイドにある例題を起動する際に AXISCLASSPATH を追加する必要がなくなります。このドキュメントでは CLASSPATH 変数に追加しなかったことを想定しています。

デプロイメントディスクリプタを探す

axis/samples/stock の中を見て deploy.wsdd ファイルを探してください。これが Axis に伝えたいデプロイメントディスクリプタです。デプロイメントディスクリプタは Axis 特有の XML ファイルであり、Webサービスの配備(アンデプロイ)方法、Axis 自身の設定方法を Axis に伝えます。Axis Administration Webサービスにより、 AdminClient プログラムと、対応する Ant タスクが解釈のために新しい WSDD ファイルをサブミットすることができます。Axis 'エンジン' はその設定を更新し、その状態を保存します。

Axis はデフォルトではその状態をグローバル設定ファイルである axis/WEB-INF/server-config.wsdd に保存します。ときどき、そのようなファイルがありませんという警告メッセージを見かけるかもしれませんが、心配する必要はありません。Axis に何かを配備した後、Axis は server-config.wsdd ファイルを自動生成するからです。webapp の中を確認してこのファイルの中身を見てもかまいませんし、さらには、同じ設定を行いたい他のシステムにコピーすることもできます。Axis は、展開済みのWebアプリケーション WEB-INF ディレクトリへ状態を保存するために WEB-INF ディレクトリの書き込み許可を必要とします。

Admin クライアントの実行

samples/stock ディレクトリで以下のコマンドを実行してください。もしこのディレクトリにいなければ、"java.io.FileNotFoundException: deploy.wsdd (システムは指定されたファイルを見つけることができませんでした。)" 例外が発生します。

Windows では
java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient
     -lhttp://localhost:8080/axis/services/AdminService deploy.wsdd
UNIX では
java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient
     -lhttp://localhost:8080/axis/services/AdminService deploy.wsdd

もし java クライアントエラー (ClassNotFoundException) が発生したら、AXISCLASSPATH (または CLASSPATH) 変数を正しく設定していない、クラス名を間違えた、あるいはその他の基本的なミスをしたことが考えられます。そのような問題を突き止めるのは 基本的な Java 開発スキルです。もしこれらのやり方を知らないのであれば、今すぐ勉強しましょう。

注意 : localhost をあなたのホスト名、8080 をあなたのWebサーバが使っているポート番号に置き換えてください。もしWebアプリケーションを "axis" 以外に置き換えたのであれば、それに従って URL を変えてください。

もし AxisFault のリストを受け取ったら、クライアントは動いていますが、配備が失敗しています。ここからは TCP のソケット API と、Webサービスの配備に必要な HTTP の基本についての知識を必要とします。もし接続拒否といったソケットエラーを受け取ったら、相手のコンピュータがあなたと通信していないので、原因を探して直してください。もし HTTP エラーコードを受け取ったら、そのエラーの意味を知り、問題を解決してください。これらのスキルはWebサービスを利用する上で基本的なことです。

ユーザガイド は AdminClient について詳細に取り扱っています。また、Ant ビルドスクリプトにおいて Axis の利用を自動化する Ant タスク [英語] もあります。

ステップ 7: テスト

このステップはオプションですが、非常にお勧めです。説明上、すでに株価サンプルをインストールして配備していることを仮定しています。

  • xml-axis のディレクトリに移動して以下のコマンドを実行してください:
    Windows では
    java -cp .;%AXISCLASSPATH% samples.stock.GetQuote
         -lhttp://localhost:8080/axis/servlet/AxisServlet
         -uuser1 -wpass1 XXX
    UNIX では
    java -cp $AXISCLASSPATH samples.stock.GetQuote
         -lhttp://localhost:8080/axis/servlet/AxisServlet
         -uuser1 -wpass1 XXX
  • 結果として "55.25" が返ってくるはずです。

注意 : 前回と同様に、localhost をあなたのホスト名、8080 をあなたのWebサーバが使っているポート番号に置き換えてください。もしWebアプリケーションを "axis" 以外に置き換えたのであれば、それに従って URL を変えてください。

高度なインストール : 自分の Webapp に Axis を追加する

もしあなたがWebアプリケーションの配備の経験が豊かで、特に、既存の、あるいは複雑な webapp にWebサービスを追加したいのであれば、Axis を起動する別のアプローチを取ることができます。Axis の webapp にあなたのクラスを追加する代わりに、あなたのアプリケーションに Axis を追加することができます。

中心となる概念は次の通りです。

  1. あなたの WAR ファイルに axis.jar、wsdl.jar、saaj.jar、jaxrpc.jar、そしてその他の依存しているライブラリを追加します。
  2. axis/WEB-INF/web.xml からすべての Axis サーブレット宣言とマッピングをコピーして、あなたの web.xml に追加します。
  3. あなたの webapp をビルドして配備します。
  4. あなたの webapp の URL に変えることにより、Axis の代わりにあなたの webapp に対して Axis AdminClient を起動します。

このプロセスは PDF ファイル [英語] でダウンロードできる Java Development with Ant [英語] の15章で取り扱っています。

もし動かなかったら

Axis はインストールするには複雑なシステムです。なぜなら、あなたのアプリケーションサーバに内在する機能に依存していて、極めて複雑な設定があり、そして全ての分散アプリケーションのようにネットワークに依存するからです。

これまで多くの人がそれぞれの問題を axis-user メーリングリストに投稿し、Axis 開発者だけでなく Axis ユーザも、可能であれば最大限の助けをしてきました。ただ、自分の問題をメーリングリストにあせって投稿する前に、一言注意があります。

Axis はフリーです。つまりお金が支払われているサポート人員はいません。コミュニティから得られる助けは全てボランティアであり、彼らの心からの親切心から来るものです。彼らは、以前助けが欲しかった同じハードルを越える助けをしたい他のユーザかもしれないし、開発者自身かもしれない。しかしそれは皆ボランティアであり、あまり期待しないでください。

  1. 開発者メーリングリストではなく、ユーザメーリングリストに投稿してください。開発者メーリングリストの方がより質の高い答えが返ってきやすいと思うかもしれません。しかし開発者は、スキルを持ったその他大勢のユーザと共に、ユーザメーリングリストにも入っています。ですからより多くの人があなたの質問に答えることができるでしょう。また、検索可能なメーリングリストアーカイブを作る際に、ユーザに関する全ての問題が一つのメーリングリストにある方が都合がいいのです。
  2. Axis に関連しない質問はしないでください。このメーリングリストは Axis や SOAP に関連しない問題について質問する場所ではありません。MS Soap ツールキットや .NET クライアントサイドの質問ですら積極的な回答を受け取れないでしょう。私達はこれらを避けます。これは、Axis が入っている Sun Java Web Services Developer Pack や Jboss.net にもあてはまります。
  3. soapbuilders メーリングリストにも邪魔しないでください。このメーリングリストは SOAP ツールキットを開発する人のためのものであって、使う人のものではありません。話題からずれたメッセージはあてつけがましく無視されます。
  4. 誰かがあなたの問題を解決してくれるという保障はありません。そのような状況の一般的な反応は沈黙です。それにはちゃんとした理由があります。もし質問の答えを知らない皆が "私は知りません" と言ったら、メーリングリストは雑音でいっぱいになってしまうからです。沈黙を直接に受け取らないで下さい。
  5. 迅速な返答を期待しないで下さい。たとえ誰かが答えを知っていても、その人がメールを読むまで1日2日かかる場合もあります。ですから1、2時間で回答を得られなかったときに、パニックを起こして再送しないでください。辛抱強くなってください。待っている間は自分自身で問題を解決していてください。
  6. まずは自分の宿題をかたづけてください。このドキュメントは理解すべき基本的な材料をリストアップしています。返答を受け取るのに1日かかる場合もあると警告もしました。SOAP 呼び出しで HTTP エラー '404' が返ってきたときを想像してください。'助けて' リクエストをあわてて送信するべきでしょうか。それとも HTTP エラーコードが何か、404 番が普通何を意味しているか、Java デバッガをどう使うか、を調べるべきでしょうか。私達はデバッグを簡単にする情報源を提供したはずです。
  7. 意味のある件名にして投稿しましょう。自分のメッセージは読まれずに捨てられるのではなく、読んでほしいはずです。'Axis の問題'、'Axis について助けて' などといった件名は無意味であり、多くの読者を得ることはできないでしょう。
  8. まずはメーリングリストアーカイブ [英語] を検索して、誰かが同じ問題を抱えていなかったか調べましょう。このリストは検索可能であり、問題に対する回答をより早く手に入れることができます。
  9. jira [英語] データベースを使って Axis バグ (公開、非公開両方とも) を検索してください。
  10. よく聞かれる質問 (FAQ)、インストールメモ、相互運用性に関する問題、そしてその他の役に立つ情報はAxis Wiki をご覧下さい。
  11. 助けを求める際、その人を知っている場合を除き、直接ある人にメールをしないでください。失礼かつ生意気です。メーリングリストに投稿されたメッセージは全てのコミュニティ(投稿した人とメーリングリストを検索した人両方)に利益をもたらします。個人的なメッセージは受け手の時間を消費するだけで歓迎されません。普通、個人的なリクエストの受け手は、完全に無視をしなかった場合でも、'メーリングリストに聞いてください'という返事をするだけです。
  12. 設定問題を再現するのは難しいので、助けるのも難しいということを理解してください。あなたに代わって診断を自動化する happyaxis.jsp のデモを行いましたが、これでも、特にあいまいなプラットフォームでは、助けを得るのは難しいでしょう。
  13. 最新版、さらには将来リリースされるベータ版の Axis を使ってください。あなたの問題が、最新版ではすでに知られていて直されたバグであるのは嫌でしょう。どんな質問に対しても返ってくる一般的な返答はたいてい '最新リリースを試しましたか' です。
  14. ソースを勉強して使ってください、そして欠陥を見つけたら直してください。このドキュメントですらもし欠陥を見つけたら直してください。品質を上げるには Axis ユーザメーリングリストの参加を通じてのみ可能です。

これを読んで Axis ユーザメーリングリストの参加を思いとどまりましたか。そうでないことを望みます。このメーリングリストは Axis を使う人のものであるため、あなたのプロジェクトが進むにつれて仲間となるでしょう。私達はあなたに、このメーリングリストがサーバサイド Java 開発の初心者のための年中無休のサポートラインではなく、この領域についてある程度自分でできる必要があるということを知っておいてほしかったのです。これは銀の弾丸ではありません。しかしメーリングリストを効果的に使う方法を知っておくことが、Axis のよりよい開発の手助けとなるでしょう。

まとめ

Axis は単に自分の webapp に追加できる SOAPの実装であり、自分のWebサービスをホストできる webapp です。Axis のインストールは、特に Java 1.4 の厳しい要求が与えられると、少し手間がかかります。順にテストし、happyaxis と同梱のテストサービスを使うといった秩序だったプロセスに従えば、Axis で始めるのが簡単であることがわかります。

付録: SOAP モニタを有効にする

SOAP モニタにより、ウェブブラウザ(Java plug-in 1.3 以上を用いる)を介して SOAP リクエストとレスポンスを監視することができます。利用方法の詳細な解説についてはユーザガイドのSOAP モニタを利用するをご覧下さい。

SOAP モニタはデフォルトでは無効です。有効にする基本的なステップは、SOAP モニタ Java アプレットをコンパイルし、SOAP モニタWebサービスをデプロイし、各監視Webサービスに対してリクエストとレスポンスのフロー定義を追加します。以下に詳細を記します。

  1. $AXIS_HOME/webapps/axis (あるいは %AXIS_HOME%\webapps\axis) に行き、SOAPMonitorApplet.java をコンパイルします。
    Windows では
    javac -classpath %AXIS_HOME%\lib\axis.jar SOAPMonitorApplet.java
    Unix では
    javac -classpath $AXIS_HOME/lib/axis.jar SOAPMonitorApplet.java

    生成された全てのクラスファイル (つまり SOAPMonitorApplet*.class) を、SOAP モニタを利用するWebアプリケーションのルートディレクトリ (例えば .../tomcat/webapps/axis) にコピーします。

  2. admin client と deploy-monitor.wsdd ファイル(以下に示しています)を利用して SOAPMonitorService をデプロイします。

    deploy-monitor.wsdd があるディレクトリに行き、以下のコマンドを実行します。このコマンドは、/axis が意図するWebアプリケーションで、ポート 8080 でアクセスすることができることを仮定しています。

    Windows では
    java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient 
         -lhttp://localhost:8080/axis/services/AdminService deploy-monitor.wsdd
    UNIX では
    java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient
         -lhttp://localhost:8080/axis/services/AdminService deploy-monitor.wsdd
    SOAPMonitorService Deployment Descriptor (deploy-monitor.wsdd)
    <deployment xmlns="http://xml.apache.org/axis/wsdd/" 
                xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"> 
      <handler name="soapmonitor" 
               type="java:org.apache.axis.handlers.SOAPMonitorHandler"> 
        <parameter name="wsdlURL" 
                   value="/axis/SOAPMonitorService-impl.wsdl"/> 
        <parameter name="namespace" 
                   value="http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl"/> 
        <parameter name="serviceName" value="SOAPMonitorService"/> 
        <parameter name="portName" value="Demo"/> 
      </handler> 
      <service name="SOAPMonitorService" provider="java:RPC"> 
        <parameter name="allowedMethods" value="publishMessage"/> 
        <parameter name="className" 
                   value="org.apache.axis.monitor.SOAPMonitorService"/> 
        <parameter name="scope" value="Application"/> 
      </service>
    </deployment>
  3. 監視するそれぞれのサービスに対して、リクエストとレスポンスのフロー定義を、サービスのデプロイメントディスクリプタに追加し、サービスをデプロイ(あるいは再デプロイ)します。requestFlowresponseFlow 定義は <service> 要素の最初のタグになります。サービスが既にデプロイされているのであれば、それをアンデプロイして修正したデプロイメントディスクリプタでデプロイします。以下に例を示します。
    ... 
       <service name="xmltoday-delayed-quotes" provider="java:RPC"> 
         <requestFlow> 
           <handler type="soapmonitor"/> 
         </requestFlow> 
         <responseFlow> 
           <handler type="soapmonitor"/> 
         </responseFlow> 
           ...
  4. ウェブブラウザで http[s]://host[:port][/webapp]/SOAPMonitor (あなたのWebアプリケーションに適した値に書き換えてください。例えば http://localhost:8080/axis/SOAPMonitor) に行きます。ここではサービスのリクエストとレスポンスが監視できる SOAP モニタアプレットが表示されます。正しく設定され、デプロイされたサービスへのリクエストは全てこのアプレットに表示されるはずです。