IPv4 Edge Components プログラミング・ガイド

WebSphere Application Server
Edge Components プログラミング・ガイド

バージョン 7.0

資料番号 GD88-6860-00

第 1 刷 (2008 年 6 月)

この版は、以下のプログラムに適用されます。

WebSphere Application Server、バージョン 7.0

また、新しい版で明記されていない限り、以降のすべてのリリースおよびモディフィケーションに適用されます。

資料を注文する場合は、IBM 担当者または最寄りの IBM 営業所にご連絡ください。

(C) Copyright International Business Machines Corporation 2008. All rights reserved.


目次


本書について

  • 本書の対象読者
  • 前提知識
  • 本書で使用されている規則と用語
  • アクセシビリティー
  • 関連資料および Web サイト
  • ご意見の送付方法
  • Edge Components のカスタマイズの概要

  • Caching Proxy のカスタマイズ
  • Load Balancer のカスタマイズ
  • サンプル・コードの検索
  • Caching Proxy API

  • Caching Proxy API の概要
  • API プログラム作成の一般手順
  • サーバー・プロセス・ステップ
  • ガイドライン
  • プラグイン関数
  • 事前定義関数およびマクロ
  • API ステップの Caching Proxy 構成ディレクティブ
  • 他の API との互換性
  • CGI プログラムの移植
  • Caching Proxy API の参照情報
  • 変数
  • 認証および許可
  • バリアント・キャッシュ
  • API の例
  • カスタム advisor

  • advisor によるロード・バランシング情報の提供
  • 標準 advisor 機能
  • カスタム advisor の作成
  • 通常モードと置換モード
  • advisor 命名規則
  • コンパイル
  • カスタム advisor の実行
  • 必須なルーチン
  • 検索順序
  • 命名およびファイル・パス
  • カスタム advisor メソッドおよび関数呼び出し
  • 標準 advisor
  • サイド・ストリーム advisor
  • 2 つのポート advisor
  • WebSphere Application Server advisor
  • advisor から戻されるデータの使用
  • 索引


    1. プロキシー・サーバー・プロセスにおけるステップのフローチャート
    2. HTTP_ および PROXY_ 変数接頭部
    3. プロキシー・サーバーの認証および許可のプロセス

    本書について

    このセクションでは、本書「WebSphere(R) Application Server Edge Components プログラミング・ガイド」の目的、編成、および規則について説明します。


    本書の対象読者

    本書では、WebSphere Application Server バージョン 7.0. の Edge Components をカスタマイズするために使用できるアプリケーション・プログラミング・インターフェース (API) について説明します。 この情報は、プラグイン・アプリケーションを作成したり、その他のカスタマイズを行う プログラマーを対象としています。 ネットワーク設計者およびシステム管理者にとっても、この情報は可能なカスタマイズ・タイプの指示として役立つ場合があります。


    前提知識

    本書をご利用の際には、使用予定の API に応じて、Java(TM) または C プログラミング言語を使用した プログラミング手順を理解している必要があります。 公開された各インターフェースで使用可能なメソッドおよび構造について文書化していますが、独自のアプリケーションの構成方法、ユーザー・システム用のコンパイル方法、および検査方法を知っている必要があります。一部のインターフェースには サンプル・コードが提供されていますが、このサンプルは独自のアプリケーションを 構成するための例としてのみ提供されています。


    本書で使用されている規則と用語

    本書では、以下のような書体およびキー操作の規則を使用しています。

    表 1. 本書で使用されている規則

    規則 意味
    太字 グラフィカル・ユーザー・インターフェース (GUI) に関しては、太字は、メニュー、メニュー項目、 ラベル、ボタン、アイコン、およびフォルダーを示します。 また、太字にしないと周りのテキストと混同される恐れがあるコマンド名を強調するためにも 使用されます。
    モノスペース コマンド・プロンプトから入力する必要のあるテキストを示します。 また、モノスペースは、画面上のテキスト、コード例、およびファイルからの引用も示します。
    イタリック 指定する必要のある可変値を示します (例: fileName に ファイルの名前を指定します)。 イタリックは、強調表示および書名の表示にも使用されます。
    Ctrl-x x がキーの名前である場合、制御文字のシーケンスを示します。例えば、 Ctrl-c は、Ctrl キーを押しながら c キーを押すという意味になります。
    Return Return、Enter または左矢印が表示されているキーを指します。
    % root 権限を必要としないコマンド用の Linux および UNIX(R) コマンド・シェル・プロンプトを示します。
    # root 権限を必要とするコマンド用の Linux および UNIX コマンド・シェル・プロンプトを示します。
    C:¥ Windows のコマンド・プロンプトを示します。
    コマンド入力 コマンドを「入力」または「発行」するよう指示されたときは、コマンドを入力してから Return を押します。 例えば、「ls コマンドを入力してください」という指示が出された場合には、コマンド・プロンプトに ls と入力してから Return を押すという意味になります。
    [ ] 構文記述内のオプション項目を囲みます。
    { } 構文記述内の、項目を選択する必要があるリストを囲みます。
    | 構文記述の中で { } (中括弧) で囲まれた選択項目リストにある項目を区切るために使用されます。
    ... 構文記述内の省略記号は、前の項目を 1 回以上繰り返すことができることを示します。 例にある省略記号は、簡潔にするために例から情報が省略されていることを示します。

    アクセシビリティー

    アクセシビリティー機能は、運動障害または視覚障害など身体に障害を持つユーザーがソフトウェア・プロダクトを快適に使用できるようにサポートします。 WebSphere Application Server バージョン 7.0 の主なアクセシビリティー機能は次のとおりです。


    関連資料および Web サイト


    ご意見の送付方法

    IBM にお客様のご意見をお寄せください。本書または WebSphere Application Server の Edge Components に関するその他の資料についてお気付きの点がありましたら、次のようにしてください。


    Edge Components のカスタマイズの概要

    本書では、WebSphere Application Server の Edge Components のために提供されるアプリケーション・プログラム・インターフェース (API) について説明します。 (WebSphere Application Server の Edge Components には、Caching Proxy と Load Balancer が含まれます。) 管理者は提供されるいくつかのインターフェースを使用して 環境をカスタマイズしたり、Edge Components 相互間の対話方法を変更したり、 他のソフトウェア・システムと対話できるようにしたりすることができます。

    重要: Caching Proxy は、すべての Edge Components 環境で使用可能です。ただし、以下の例外があります。

    本書の API はいくつかのカテゴリーを扱っています。


    Caching Proxy のカスタマイズ

    Caching Proxy の処理シーケンスにはいくつかのインターフェースが書き込まれていて、カスタム処理を追加したり標準処理の代わりに使用したりできます。実行できるカスタマイズには、以下のようなタスクの変更および拡大が含まれます。

    カスタム・アプリケーション・プログラムは、Caching Proxy プラグインとも呼ばれ、プロキシー・サーバーの処理シーケンス中の、事前に定義されたポイントで呼び出されます。

    Caching Proxy API は、特定のシステム機能を実装するために使用されています。 例えば、プロキシー・サーバーの LDAP サポートはプラグインとして実装されます。

    Caching Proxy API では、インターフェースについて詳しく説明します。これには、プラグイン・プログラムを使用するようにプロキシー・サーバーを構成するためのステップが含まれます。


    Load Balancer のカスタマイズ

    ユーザー独自の advisor を作成することによって、Load Balancer をカスタマイズできます。 advisor はサーバー上で実際のロード測定を実行します。 カスタム advisor があれば、ロードを測定するためのシステムに 関連する、自分で用意したメソッドを使用することができます。 これは特に、カスタマイズ済みまたは所有 Web サーバー・システムがある場合に重要です。

    カスタム advisor では、カスタム advisor の作成および使用の詳細について説明します。 これには、advisor のサンプル・コードも含まれます。


    サンプル・コードの検索

    上記の API のサンプル・コードは、Edge Components CD-ROM の samples ディレクトリーに入っています。 追加のコード・サンプルを WebSphere Application Server Web サイト www.ibm.com/software/webservers/appserv/ から入手できます。


    Caching Proxy API

    このセクションでは、Caching Proxy アプリケーション・プログラミング・インターフェース (API) の概念、 利点、および仕組みについて説明します。

    重要: Caching Proxy は、すべての Edge Components 環境で使用可能です。ただし、以下の例外があります。


    Caching Proxy API の概要

    この API は Caching Proxy へのインターフェースであり、これを使用してプロキシー・サーバーの基本機能を拡張することができます。 拡張機能またはプラグインを作成し、次の例を含むカスタマイズされた処理を実行できます。

    Caching Proxy API には、以下の利点があります。


    API プログラム作成の一般手順

    Caching Proxy プラグイン・プログラムを作成する前に、プロキシー・サーバーがどのように機能するのかを理解しておく必要があります。 プロキシー・サーバーの振る舞いは、いくつかの別個の処理ステップに分けることができます。 これらのそれぞれのステップで、API を使用して独自にカスタマイズした機能を使用することが可能です。 例えば、 ある処理をクライアント要求の読み取り後、他の処理を行う前に行う、あるいは特殊ルーチンを認証時に実行してから、 要求ファイルの送信後に再度行うなどを決めます。

    事前定義機能のライブラリーには API が備わっています。 ご使用のプラグイン・プログラムは、プロキシー・サーバー・プロセス (例えば、要求の操作、要求ヘッダーの読み取りまたは書き込み、あるいはプロキシー・サーバーのログへの書き込みなど) と対話するために事前定義 API 関数を呼び出すことができます。 これらの関数を、ご自分で作成したプラグイン関数と混同しないでください。プラグイン関数は、プロキシー・サーバーによって呼び出されます。 事前定義関数については、事前定義関数およびマクロで説明しています。

    サーバー構成ファイル内の対応する Caching Proxy API ディレクティブを使用して 適切なステップでプラグイン関数を呼び出すように、プロキシー・サーバーに対して指示します。 これらのディレクティブについては、API ステップの Caching Proxy 構成ディレクティブで説明します。

    本書には、次の内容が含まれています。

    以下のコンポーネントと手順を使用して独自の Caching Proxy プラグイン・プログラムを作成することができます。

    サーバー・プロセス・ステップ

    プロキシー・サーバーの基本操作は、そのフェーズでサーバーが実行する処理のタイプに基づいて、いくつかのステップに分けることができます。 各ステップには、プログラムの指定された部分を実行できる接続点があります。Caching Proxy 構成ファイル (ibmproxy.conf) に API ディレクティブを追加することによって、特定のステップで呼び出すプラグイン関数を指定します。 そのステップに複数のディレクティブを組み込むことによって、特定のプロセス・ステップで 複数のプラグイン関数を呼び出すことができます。

    いくつかのステップはサーバー要求プロセスの一部です。 つまり、プロキシー・サーバーは、要求を処理するたびにこれらのステップを実行します。 その他のステップは要求処理とは無関係に実行されます。 つまり、要求が処理されているかどうかにかかわらず、 サーバーはこれらのステップを実行します。

    コンパイルされたプログラムは、オペレーティング・システムに応じて、 いずれかの共用オブジェクト (例えば、DLL または .so ファイル) に入っています。 サーバーは、その要求プロセス・ステップを進めながら、いずれかの関数が要求の 処理を終えたことを示すまでは、各ステップに関連付けられたプラグイン関数を呼び出します。 特定のステップのプラグイン関数が複数ある場合は、これらの関数は構成ファイル内に あるディレクティブの順序で呼び出されます。

    要求がプラグイン関数によって処理されない (そのステップに関する Caching Proxy API ディレクティブを 組み込まなかったか、そのステップのプラグイン関数が HTTP_NOACTION を戻した) 場合には、サーバーはそのステップのためのデフォルト・アクションを実行します。

    注 : これは、Service ステップを除くすべてのステップにあてはまります。Service ステップにはデフォルト・アクションはありません。

    図 1 は、プロキシー・サーバー・プロセスのステップを表し、要求処理に関連するステップの処理順序を定義しています。

    図 1. プロキシー・サーバー・プロセスにおけるステップのフローチャート



    この図の中の 4 つのステップは、クライアント要求の処理とは無関係に実行されます。 これらのステップは、プロキシー・サーバーの実行および保守に関連しています。 これらのステップには以下が含まれます。

    以下のリストは、図 1 に示した各ステップの目的を示しています。必ずしもすべてのステップが特定の要求で呼び出されるわけではありません。

    Server Initialization
    プロキシー・サーバーが始動されたときに、クライアント要求が受け入れられる前に初期化を実行します。

    Midnight
    夜間にプラグインを実行します。 要求コンテキストはありません。 このステップは要求プロセスの一部ではないため、図では別個に表示されています。 つまり、このステップの実行はどの要求からも独立しています。

    GC Advisor
    キャッシュ内のファイルに関するガーベッジ・コレクションの決定に影響を与えます。 このステップは要求プロセスの一部ではないため、図では別個に表示されています。 つまり、このステップの実行はどの要求からも独立しています。 ガーベッジ・コレクションは、キャッシュ・サイズが最大値に達したときに行われます。 (キャッシュ・ガーベッジ・コレクションの構成については、「WebSphere Application Server Caching Proxy 管理ガイド」に記載されています。)

    PreExit

    要求が読み込まれた後、まだ何も実行されないうちに処理を実行します。

    このステップで要求が処理されたことを示す標識 (HTTP_OK) が戻された場合には、 サーバーは要求プロセスの他のステップをバイパスし、Transmogrifier、Log、および PostExit ステップだけを実行します。

    Name Translation
    仮想パスを (URL から) 物理パスに変換します。

    Authorization

    保管されたセキュリティー・トークンを使用して保護、ACL、およびその他のアクセス制御用の 物理パスを検査し、基本認証に必要な WWW 認証ヘッダーを生成します。 独自のプラグイン関数を作成してこのステップを置き換える場合は、これらのヘッダーを 自分で生成しなければなりません。

    詳しくは、認証および許可を参照してください。

    Authentication

    セキュリティー・トークンのデコード、検査、および保管を行います。

    詳しくは、認証および許可を参照してください。

    Object Type
    パスが示すファイル・システム・オブジェクトを探します。

    Post Authorization

    許可およびオブジェクト検索後に (ただし要求が満たされる前に) 処理を実行します。

    このステップで要求が処理されたことを示す標識 (HTTP_OK) が戻された場合には、 サーバーは要求プロセスの他のステップをバイパスし、Transmogrifier、Log、および PostExit ステップだけを実行します。

    Service
    ファイルの送信、CGI の実行などによって要求を満たします。

    Proxy Advisor
    プロキシーとキャッシングの決定に影響を与えます。

    Transmogrifier
    クライアントに送信される応答のデータ部分に書き込みアクセス権限を与えます。

    Log
    カスタマイズされたトランザクション・ロギングを使用可能にします。

    Error
    エラー条件に対して、カスタマイズされた応答を使用可能にします。

    PostExit
    要求処理に割り振られたリソースをクリーンアップします。

    Server Termination
    正常シャットダウンが行われたときにクリーンアップ処理を実行します。

    ガイドライン

    プラグイン関数

    定義済み要求処理ステップ用に独自のプログラム関数を作成する場合は、プラグイン関数プロトタイプに示した構文に従ってください。

    各ユーザー関数では、実行されたアクションを示す値が 戻りコード・パラメーターに使用される必要があります。

    プラグイン関数プロトタイプ

    Caching Proxy ステップごとの関数プロトタイプは、使用する形式を示し、それらが実行できる処理のタイプを記述します。 関数名は事前定義されないので、注意してください。関数には固有の名前を指定する必要がありますが、 命名規則は自由に決めることができます。 わかりやすくするため、本書では、サーバーの処理ステップに関連する名前を使用しています。

    各プラグイン関数で、特定の事前定義 API 関数が有効です。 すべてのステップで無効な事前定義関数もあります。 以下の事前定義 API 関数は、これらのどのプラグイン関数からでも呼び出すことができます。

    その他の有効または無効な API 関数については、関数のプロトタイプの説明に 示されています。

    関数に送られる handle パラメーターの値は、 最初の引数として事前定義関数に渡すことができます。 事前定義された API 関数については、事前定義関数およびマクロで説明しています。

    Server Initialization

    void HTTPD_LINKAGE ServerInitFunction (
         unsigned char *handle, 
         unsigned long *major_version,
         unsigned long *minor_version, 
         long *return_code
         )
    

    このステップに定義された関数は、サーバー初期化の間のモジュールのロード時に一度呼び出されます。初期化を行うことができるのはいずれかの要求が受け入れられる前です。

    すべてのサーバー初期化関数が呼び出されますが、このステップの関数から エラー戻りコードが戻されると、サーバーはエラー・コードを戻した関数と 同じモジュールで構成された他のすべての関数を無視します。 (つまり、エラーを戻した関数と同じ共用オブジェクトに入っている 関数はどれも呼び出されません。)

    バージョン・パラメーターにはプロキシー・サーバーのバージョン番号が含まれます。バージョン・パラメーターは Caching Proxy によって提供されます。

    PreExit

    void  HTTPD_LINKAGE  PreExitFunction (
             unsigned char *handle, 
             long *return_code
             )
    

    このステップに定義された関数は、要求が読み取られた後、処理が行われる前に それぞれの要求ごとに呼び出されます。 このステップのプラグインを使用することにより、クライアントの要求が Caching Proxy によって処理される前に、この要求にアクセスできます。

    preExit 関数の有効な戻りコードは次のとおりです。

    その他の戻りコードは使用しないでください。

    この関数が HTTP_OK を戻した場合、プロキシー・サーバーは、その要求が処理されたものと想定します。 それ以降のすべての要求処理ステップはバイパスされ、応答ステップ (Transmogrifier、 Log、および PostExit) のみが実行されます。

    このステップ中は、事前定義 API 関数はすべて有効です。

    Midnight

    void  HTTPD_LINKAGE  MidnightFunction (
             unsigned char *handle, 
             long *return_code
             )
    

    このステップで定義された関数は毎日、真夜中に実行されます。要求コンテキストは含まれていません。 例えば、この関数はログを分析する子プロセスを起動するために使用できます。 (このステップで処理が長引くと、ロギングの妨げになる可能性があることに注意してください。)

    Authentication

    void  HTTPD_LINKAGE  AuthenticationFunction (
             unsigned char *handle, 
             long *return_code
             )
    

    このステップで定義された関数は、要求の認証方式に基づいて要求ごとに呼び出されます。 この関数は、要求とともに送信されるセキュリティー・トークンの検査を カスタマイズするために使用できます。

    Name Translation

    void  HTTPD_LINKAGE  NameTransFunction (
             unsigned char *handle, 
             long *return_code
             )
    

    このステップで定義された関数は、要求ごとに呼び出されます。 テンプレートと一致する要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 Name Translation ステップは要求が処理される前に実行され、URL を ファイル名などのオブジェクトにマッピングするためのメカニズムを提供します。

    Authorization

    void  HTTPD_LINKAGE  AuthorizationFunction (
             unsigned char *handle, 
             long *return_code
             )
    

    このステップで定義された関数は、要求ごとに呼び出されます。 テンプレートと一致する要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 Authorization ステップは要求が処理される前に実行され、 識別されたオブジェクトをクライアントに戻すことができるかどうかを 検査するために使用できます。基本認証を行う場合は、必要な WWW 認証ヘッダーを生成しなければなりません。

    Object Type

    void  HTTPD_LINKAGE  ObjTypeFunction (
             unsigned char *handle, 
             long *return_code
             )
     
    

    このステップで定義された関数は、要求ごとに呼び出されます。 テンプレートと一致する要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 Object Type ステップは要求が処理される前に実行され、 オブジェクトが存在するかどうかを調べてオブジェクトの型定義を行うために使用できます。

    PostAuthorization

    void  HTTPD_LINKAGE  PostAuthFunction (
             unsigned char *handle, 
             long *return_code
             )
    

    このステップで定義された関数は、要求を許可してから処理が起こるまえに呼び出されます。 この関数が HTTP_OK を戻した場合、プロキシー・サーバーは、その要求が処理されたものと想定します。 それ以降のすべての要求ステップはバイパスされ、応答ステップ (Transmogrifier、 Log、および PostExit) のみが実行されます。

    このステップ中は、サーバー事前定義関数はすべて有効です。

    Service

    void  HTTPD_LINKAGE  ServiceFunction (
             unsigned char *handle, 
             long *return_code 
             )
    

    このステップで定義された関数は、要求ごとに呼び出されます。 テンプレートと一致する要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 Service ステップは、要求が PreExit または PostAuthorization ステップで 満たされなかった場合に、この要求を満たします。

    このステップ中は、サーバー事前定義関数はすべて有効です。

    URL ではなく HTTP メソッドに基づいて実行する Service 関数を構成するための情報については、「WebSphere Application Server Caching Proxy 管理ガイド」の Enable ディレクティブの項を参照してください。

    Transmogrifier
    このプロセス・ステップで呼び出される関数は、応答データをストリームとしてフィルターに掛けるために使用できます。このステップの 4 つのプラグイン関数は順番に呼び出され、 それぞれがデータが流れるパイプのセグメントとして動作します。 つまり、指定した openwriteclose、および error 関数が 応答ごとにこの順番で呼び出されます。 それぞれの関数は、順番に同じデータ・ストリームを処理します。

    このステップには、以下の 4 つの関数をインプリメントしなければなりません。 (使用する関数名は、以下で使用されているものと同じでなくてもかまいません。)

    注 :

    GC Advisor

    void  HTTPD_LINKAGE  GCAdvisorFunction (
             unsigned char *handle, 
             long *return_code
             )
    

    このステップで定義された関数は、ガーベッジ・コレクションの際、キャッシュ内のファイルごとに呼び出されます。この関数によって、保持するファイルと廃棄するファイルの決定に 影響を与えることができます。 詳細については、GC_* 変数を参照してください。

    Proxy Advisor

    void  HTTPD_LINKAGE  ProxyAdvisorFunction (
             unsigned char *handle, 
             long *return_code
             )
    

    このステップで定義された関数は、各プロキシー要求のサービス時に呼び出されます。 例えば、USE_PROXY 変数を設定するために使用することができます。

    Log

    void  HTTPD_LINKAGE  LogFunction (
             unsigned char *handle,
             long *return_code
             )
    

    このステップで定義された関数は、要求が処理され、クライアントへの通信が クローズされた後で、それぞれの要求ごとに呼び出されます。 テンプレートと一致する要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 この関数は、要求処理の成否に関係なく呼び出されます。 ログ・プラグインにデフォルトのログ・メカニズムを変更させたくない場合は、戻りコードを HTTP_OK ではなく HTTP_NOACTION に設定します。

    Error

    void  HTTPD_LINKAGE  ErrorFunction (
             unsigned char *handle, 
             long *return_code
             )
    

    このステップで定義された関数は、失敗した要求ごとに呼び出されます。 テンプレートと一致する、失敗した要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 Error ステップを使用して、エラー応答をカスタマイズできます。

    PostExit

    void  HTTPD_LINKAGE  PostExitFunction (
             unsigned char *handle, 
             long *return_code
             )
    

    このステップで定義された関数は、要求の成否に関係なく、 要求ごとに呼び出されます。 このステップを使用して、要求を処理するプラグインによって割り振られたリソースに対して クリーンアップ・タスクを行うことができます。

    Server Termination

    void  HTTPD_LINKAGE  ServerTermFunction (
             unsigned char *handle, 
             long *return_code
             )
    

    このステップで定義された関数は、サーバーが正常にシャットダウンしたときに呼び出されます。 これにより、サーバー初期化ステップの際に割り振られたリソースをクリーンアップすることができます。このステップでは、いずれの HTTP_* 関数も呼び出さないでください (呼び出しの結果は保証できません)。構成ファイルに Server Termination 用の複数の Caching Proxy API ディレクティブがある場合は、それらがすべて呼び出されます。

    注:
    ibmproxy -stop コマンドを使用して Solaris プラットフォーム上の Caching Proxy をシャットダウンした場合、Solaris コードの現行の制限のため、Server Termination プラグイン・ステップは実行されません。Caching Proxy の開始および停止に関しては、「WebSphere Application Server Caching Proxy 管理ガイド」を参照してください。

    HTTP 戻りコードおよび値

    これらの戻りコードは、World Wide Web Consortium によって公開されている HTTP 1.1 仕様書 (www.w3.org/pub/WWW/Protocols/) の RFC 2616 に準拠しています。 プラグイン関数は、以下のいずれかの値を戻す必要があります。

    表 2. Caching Proxy API 関数の HTTP 戻りコード

    戻りコード
    0 HTTP_NOACTION
    100 HTTP_CONTINUE
    101 HTTP_SWITCHING_PROTOCOLS
    200 HTTP_OK
    201 HTTP_CREATED
    202 HTTP_ACCEPTED
    203 HTTP_NON_AUTHORITATIVE
    204 HTTP_NO_CONTENT
    205 HTTP_RESET_CONTENT
    206 HTTP_PARTIAL_CONTENT
    300 HTTP_MULTIPLE_CHOICES
    301 HTTP_MOVED_PERMANENTLY
    302 HTTP_MOVED_TEMPORARILY
    302 HTTP_FOUND
    303 HTTP_SEE_OTHER
    304 HTTP_NOT_MODIFIED
    305 HTTP_USE_PROXY
    307 HTTP_TEMPORARY_REDIRECT
    400 HTTP_BAD_REQUEST
    401 HTTP_UNAUTHORIZED
    403 HTTP_FORBIDDEN
    404 HTTP_NOT_FOUND
    405 HTTP_METHOD_NOT_ALLOWED
    406 HTTP_NOT_ACCEPTABLE
    407 HTTP_PROXY_UNAUTHORIZED
    408 HTTP_REQUEST_TIMEOUT
    409 HTTP_CONFLICT
    410 HTTP_GONE
    411 HTTP_LENGTH_REQUIRED
    412 HTTP_PRECONDITION_FAILED
    413 HTTP_ENTITY_TOO_LARGE
    414 HTTP_URI_TOO_LONG
    415 HTTP_BAD_MEDIA_TYPE
    416 HTTP_BAD_RANGE
    417 HTTP_EXPECTATION_FAILED
    500 HTTP_SERVER_ERROR
    501 HTTP_NOT_IMPLEMENTED
    502 HTTP_BAD_GATEWAY
    503 HTTP_SERVICE_UNAVAILABLE
    504 HTTP_GATEWAY_TIMEOUT
    505 HTTP_BAD_VERSION

    事前定義関数およびマクロ

    ユーザー独自のプラグイン関数から、サーバーの事前定義関数およびマクロを呼び出すことができます。 その事前定義された名前を使用し、以下の形式に従う必要があります。パラメーターの説明で、 i は入力パラメーターを示し、o は出力パラメーターを示し、 i/o はパラメーターが入力と出力の両方であることを示しています。

    これらの関数は、要求の結果に応じて、いずれかの HTTPD 戻りコードを戻します。これらのコードは、事前定義関数およびマクロからの戻りコードで説明されています。

    これらの関数を呼び出すときは、プラグインへ提供されたハンドルを最初のパラメーターとして使用します。最初の パラメーターとして使用しない場合、関数は HTTPD_PARAMETER_ERROR エラー・コードを戻します。 NULL は、有効なハンドルとしては受け入れられません。

    HTTPD_authenticate()
    ユーザー ID またはパスワード、あるいはその両方を認証します。 PreExit、Authentication、Authorization、および PostAuthorization ステップでのみ有効です。

    void  HTTPD_LINKAGE  HTTPD_authenticate (
             unsigned char *handle,      /* i; handle */
             long *return_code           /* o; return code */
             )
    

    HTTPD_cacheable_url()
    Caching Proxy の標準に従って指定の URL コンテンツをキャッシュできるかどうかを戻します。

    void HTTPD_LINKAGE  HTTPD_cacheable_url ( 
            unsigned char *handle,      /* i; handle */
            unsigned char *url,         /* i; URL to check */
            unsigned char *req_method,  /* i; request method for the URL */
            long *retval                /* o; return code */
            )
    

    戻り値 HTTPD_SUCCESS は、URL コンテンツがキャッシュできることを示します。HTTPD_FAILURE はコンテンツがキャッシュできないことを示します。また、HTTPD_INTERNAL_ERROR もこの関数の可能な戻りコードです。

    HTTPD_close()
    (Transmogrifier ステップでのみ有効です。) ストリーム・スタック内の次の close ルーチンに制御権を移動します。この関数は、 必要な処理が済んだ後に、Transmogrifier の open、write、close のいずれかの関数から呼び出してください。 この関数は、応答が処理されて、Transmogrifier ステップが完了したことをプロキシー・サーバーに通知します。

    void  HTTPD_LINKAGE  HTTPD_close (
             unsigned char *handle,       /* i; handle */
             long *return_code            /* o; return code */ 
             )
    

    HTTPD_exec()
    この要求を満たすために、スクリプトを実行します。PreExit、Service、 PostAuthorization、および Error ステップで有効です。

    void  HTTPD_LINKAGE  HTTPD_exec (
             unsigned char *handle,         /* i; handle */
             unsigned char *name,           /* i; name of script to run */
             unsigned long *name_length,    /* i; length of the name */
             long *return_code              /* o; return code */
             )
    

    HTTPD_extract()
    この要求に関連する変数の値を抽出しま す。name パラメーターで有効な変数は、CGI で使用されるものと同じです。 詳しくは、変数を参照してください。この関数はすべてのステップで有効です。 ただし、すべての変数がすべてのステップで有効であるとは限りません。

    void  HTTPD_LINKAGE  HTTPD_extract (
          unsigned char *handle,       /* i; handle */
          unsigned char *name,         /* i; name of variable to extract */
          unsigned long *name_length,  /* i; length of the name */
          unsigned char *value,        /* o; buffer in which to put 
                                             the value */
          unsigned long *value_length, /* i/o; buffer size */
          long *return_code            /* o; return code */
          )
    

    この関数が HTTPD_BUFFER_TOO_SMALL コードを戻した場合、要求したバッファー・サイズは、抽出された値を入れるのに十分な大きさではありませんでした。この場合、 この関数はバッファーを使用せず、この値を正常に抽出するために必要な バッファー・サイズで value_length パラメーターを更新します。 少なくとも、戻された value_length と同じ大きさのバッファーを使用して抽出を再試行します。

    注:
    抽出される変数が HTTP ヘッダー用である場合、 要求に同じ名前の複数のヘッダーが含まれていても、HTTPD_extract() 関数は 最初に一致するオカレンスのみを抽出します。 httpd_getvar() 関数を HTTPD_extract() の代わりに使用することができます。 httpd_getvar() 関数を使用した場合、その他の利点もあります。 詳しくは、httpd_getvar() を参照してください。

    HTTPD_file()
    この要求を満たすために、ファイルを送信します。 PreExit、Service、 Error、PostAuthorization、および Transmogrifier ステップでのみ有効です。

    void  HTTPD_LINKAGE  HTTPD_file (
             unsigned char *handle,          /* i; handle */
             unsigned char *name,            /* i; name of file to send */
             unsigned long *name_length,     /* i; length of the name */
             long *return_code               /* o; return code */
             )
    

    httpd_getvar()
    HTTPD_extract() と同じですが、引数の長さを指定する必要がないので、簡単に使用できます。

    const  unsigned char *          /* o; value of variable */
    HTTPD_LINKAGE
    httpd_getvar(
       unsigned char *handle,       /* i; handle */
       unsigned char *name,         /* i; variable name */
       unsigned long *n             /* i; index number for the array 
                                          containing the header */
       )
    

    ヘッダーが入っている配列の指標は 0 から始まります。配列で最初の項目を得るには、n に値 0 を使用します。5 番目の項目を得るには、n には値 4 を使用します。

    注:
    戻り値の内容を廃棄したり変更したりしないでください。戻されたストリングは、ヌル文字で終了しています。

    HTTPD_log_access()
    サーバーのアクセス・ログにストリング を書き込みます。

    void  HTTPD_LINKAGE  HTTPD_log_access (
             unsigned char *handle,           /* i; handle */
             unsigned char *value,            /* i; data to write */
             unsigned long *value_length,     /* i; length of the data */
             long *return_code                /* o; return code */
             ) 
    

    サーバー・アクセス・ログにパーセント記号 (%) を書き込むときに、 エスケープ記号は必要がない ことに注意してください。

    HTTPD_log_error()
    サーバーのエラー・ログにストリングを書き込みます。

    void  HTTPD_LINKAGE  HTTPD_log_error (
             unsigned char *handle,          /* i; handle */
             unsigned char *value,           /* i; data to write */
             unsigned long *value_length,    /* i; length of the data */
             long *return_code               /* o; return code */
             )
    

    サーバー・エラー・ログにパーセント記号 (%) を書き込むときに、 エスケープ記号は必要がない ことに注意してください。

    HTTPD_log_event()
    サーバーのイベント・ログにストリングを書き込みます。

    void  HTTPD_LINKAGE  HTTPD_log_event (
             unsigned char *handle,          /* i; handle */
             unsigned char *value,           /* i; data to write */
             unsigned long *value_length,    /* i; length of the data */
             long *return_code               /* o; return code */
             )
    

    サーバー・イベント・ログにパーセント記号 (%) を書き込むときに、 エスケープ記号は必要がない ことに注意してください。

    HTTPD_log_trace()
    サーバーのトレース・ログにストリングを書き込みます。

    void  HTTPD_LINKAGE  HTTPD_log_trace (
             unsigned char *handle,          /* i; handle */
             unsigned char *value,           /* i; data to write */
             unsigned long *value_length,    /* i; length of the data */
             long *return_code               /* o; return code */
             )
    

    サーバー・トレース・ログにパーセント記号 (%) を書き込むときに、 エスケープ記号は必要がない ことに注意してください。

    HTTPD_open()
    (Transmogrifier ステップでのみ有効です。) ストリーム・スタック内の次のルーチンに制御権を移動します。 必要なヘッダーを設定して、write ルーチンを開始する準備ができたら、 Transmogrifier の open、write、close のいずれかの関数からこれを呼び出してください。

    void  HTTPD_LINKAGE  HTTPD_open (
             unsigned char *handle,      /* i; handle */
             long *return_code           /* o; return code */ 
             )	
    

    HTTPD_proxy()
    プロキシー要求を行います。PreExit、Service、および PostAuthorization ステップでのみ有効です。
    注:
    これは完了関数です。 要求は、この関数の後に完了します。

    void  HTTPD_LINKAGE  HTTPD_proxy (
             unsigned char *handle,        /* i; handle */
             unsigned char *url_name,      /* i; URL for the 
                                                 proxy request */
             unsigned long *name_length,   /* i; length of URL */
             void *request_body,           /* i; body of request */
             unsigned long *body_length,   /* i; length of body */
             long *return_code             /* o; return code */
             ) 
    

    HTTPD_read()
    クライアントの要求の本体を読み取ります。ヘッダーの読み取りには HTTPD_extract() を 使用してください。PreExit、Authorization、 PostAuthorization、および Service ステップでのみ有効であり、PUT または POST 要求が実行された場合にだけ使用できます。この関数は、HTTPD_EOF が戻されるまでループの中で呼び出してください。 この要求に本体がない場合、この関数は失敗します。

    void  HTTPD_LINKAGE  HTTPD_read (
             unsigned char *handle,          /* i; handle */
             unsigned char *value,           /* i; buffer for data */
             unsigned long *value_length,    /* i/o; buffer size 
                                                     (data length) */
             long *return_code               /* o; return code */
             )
    

    HTTPD_restart()
    すべてのアクティブ状態の要求を処理した後で、サーバーを再始動します。 Server Initialization、 Server Termination、および Transmogrifier を除くすべてのステップで有効です。

    void  HTTPD_LINKAGE  HTTPD_restart ( 
             long *return_code    /* o; return code */
             )
    

    HTTPD_set()
    この要求に関連する変数の値を設定します。name パラメーターで 有効な変数は、CGI で使用されるものと同じです。 詳しくは、変数を参照してください。

    この関数で変数を作成することもできますので注意してください。作成する変数は、 変数で説明されている、 接頭部 HTTP_ および PROXY_ の規則に準拠します。 HTTP_ で始まる変数を作成した場合、この変数は、接頭部 HTTP_ なしで、 クライアントへの応答でヘッダーとして送信されます。 例えば、Location ヘッダーを設定するには、変数名 HTTP_LOCATION で HTTPD_set() を使用します。 接頭部 PROXY_ を付けて作成した変数は、コンテンツ・サーバーへの要求でヘッダーとして送信されます。 接頭部 CGI_ を付けて作成した変数は CGI プログラムに渡されます。

    この関数はすべてのステップで有効です。 ただし、すべての変数がすべてのステップで有効であるとは限りません。

    void  HTTPD_LINKAGE  HTTPD_set (
             unsigned char *handle,        /* i; handle */
             unsigned char *name,          /* i; name of value to set */
             unsigned long *name_length,   /* i; length of the name */
             unsigned char *value,         /* i; buffer with value */
             unsigned long *value_length,  /* i; length of value */
             long *return_code             /* o; return code */
             ) 
    
    注:
    httpd_setvar() 関数を使用して、バッファーおよび長さを指定せずに変数値を 設定することができます。 詳しくは、httpd_setvar() を参照してください。

    httpd_setvar()
    HTTPD_set() と同じですが、引数の長さを指定する必要がないので、簡単に使用できます。

    long             /* o; return code */
    HTTPD_LINKAGE   httpd_setvar (
           unsigned char *handle,       /* i; handle */
           unsigned char *name,         /* i; variable name */
           unsigned char *value,        /* i; new value */ 
           unsigned long *addHdr        /* i; add header or replace it */
           )
    

    addHdr パラメーターには、以下の 4 つの値を使用できます。

    これらの値は HTAPI.h で定義されます。

    httpd_variant_insert()
    バリアントをキャッシュに挿入します。

    void  HTTPD_LINKAGE  httpd_variant_insert (
             unsigned char *handle,    /* i; handle */
             unsigned char *URI,       /* i; URI of this object */
             unsigned char *dimension, /* i; dimension of variation */
             unsigned char *variant,   /* i; value of the variant */
             unsigned char *filename,  /* i; file containing the object */
             long *return_code         /* o; return code */
             )
    

    注 :

    1. dimension 引数は、このオブジェクトが URI と異なる点となっているヘッダーを参照します。 例えば、上記の例で、dimension 値を User-Agent にすることができます。
    2. variant 引数は、dimension 引数で指定されたヘッダーの値を参照します。 これは URI とは異なります。例えば、上記の例で、variant 引数を次の値にすることができます。
      Mozilla 4.0 (compatible; BatBrowser 94.1.2; Bat OS)
    3. filename 引数は、ユーザーが変更済みコンテンツを保管したファイル名の ヌル終了コピーを指す必要があります。 ユーザーには、ファイルを除去する責任があります。 このアクションは、この関数から戻った後で行うのが安全です。 このファイルには、ヘッダーのない本体だけが入っています。
    4. バリアントをキャッシュする場合、サーバーはコンテンツ長ヘッダーを更新して、Warning: 214 (警告 : 214) ヘッダーを追加します。ストロング・エンティティー・タグは除去されます。

    httpd_variant_lookup()
    キャッシュ内の指定のバリアントの有無を判別します。

    void  HTTPD_LINKAGE  httpd_variant_lookup (
        unsigned char *handle,             /* i; handle */
        unsigned char *URI,                /* URI of this object */
        unsigned char *dimension,          /* i; dimension of variation */
        unsigned char *variant,            /* i; value of the variant */
                 long *return_code);       /* o; return code */ 
    

    HTTPD_write()
    応答の本文を書き込みます。この関数は、PreExit、Service、Error、および Transmogrifier ステップで有効です。

    初めてこの関数を呼び出す前にコンテンツ・タイプを設定しなかった場合、 サーバーは、CGI データ・ストリームが送信されるものと想定します。

    void  HTTPD_LINKAGE  HTTPD_write (
        unsigned char *handle,             /* i; handle */
        unsigned char *value,              /* i; data to send */
        unsigned char *value_length,       /* i; length of the data */
                 long *return_code);       /* o; return code */      
    注:
    応答ヘッダーを設定するには、HTTPD_set() を参照してください。
    注:
    HTTPD_* 関数が戻った後で、それと一緒に渡したメモリーを解放しておくと安全です。

    事前定義関数およびマクロからの戻りコード

    サーバーは、要求が成功したかどうかに応じて、以下のいずれかの値に戻りコード・パラメーターを設定します。

    表 3. 戻りコード

    状況コード 説明
    -1 HTTPD_UNSUPPORTED この関数はサポートされていません。
    0 HTTPD_SUCCESS この関数は正常に実行され、出力フィールドが有効です。
    1 HTTPD_FAILURE 関数は失敗しました。
    2 HTTPD_INTERNAL_ERROR 内部エラーを検出し、 この要求の処理を続行できません。
    3 HTTPD_PARAMETER_ERROR 1 つまたは複数の無効なパラメーターが渡されました。
    4 HTTPD_STATE_CHECK この関数はこのプロセス・ステップでは無効です。
    5 HTTPD_READ_ONLY (これを戻すのは HTTPD_set と httpd_setvar だけです。) 変数は読み取り専用であり、プラグインによって設定できません。
    6 HTTPD_BUFFER_TOO_SMALL (これを戻すのは HTTPD_set、 httpd_setvar、および HTTPD_read だけです。)指定のバッファーが小さすぎます。
    7 HTTPD_AUTHENTICATE_FAILED (これを戻すのは HTTPD_authenticate だけです。) 認証は失敗しました。 詳細については、HTTP_RESPONSE および HTTP_REASON 変数を調べてください。
    8 HTTPD_EOF (これを戻すのは HTTPD_read だけです。) 要求本文の終わりを示します。
    9 HTTPD_ABORT_REQUEST クライアントが要求が指定する条件と一致しないエンティティー・タグを指定したために、 要求は打ち切られました。
    10 HTTPD_REQUEST_SERVICED (これを戻すのは HTTPD_proxy だけです。) 呼び出した関数は この要求の応答を完了しました。
    11 HTTPD_RESPONSE_ALREADY_COMPLETED その要求の応答はすでに完了しているので、 この関数は失敗しました。
    12 HTTPD_WRITE_ONLY 変数は書き込み専用であり、プラグインによって読み取ることはできません。

    API ステップの Caching Proxy 構成ディレクティブ

    要求プロセスの各ステップには構成ディレクティブがあり、これを使用して、そのステップの間に呼び出して実行したいプラグイン関数を示すことができます。 サーバーの構成ファイル (ibmproxy.conf) にそれらのディレクティブを追加するには、サーバーの構成ファイルを手操作で編集して更新するか、または Caching Proxy の「構成および管理」フォームの中の 「API 要求処理」フォームを使用します。

    API 使用上の注意

    API ディレクティブおよび構文

    これらの構成ファイル・ディレクティブは、ここに明確に指定されたものを除いてスペースを入れずに、ibmproxy.conf ファイル中に 1 行で記述しなければなりません。構文例の一部では 読みやすさのために改行していますが、実際のディレクティブではそこにスペースを入れないでください。

    表 4. Caching Proxy プラグインの API ディレクティブ

    ServerInit

    /path/file:function_name init_string
    PreExit

    /path/file:function_name
    Authentication
    type /path/file:function_name
    NameTrans
    /URL /path/file:function_name
    Authorization
    /URL /path/file:function_name
    ObjectType
    /URL /path/file:function_name
    PostAuth

    /path/file:function_name
    Service
    /URL /path/file:function_name
    Midnight

    /path/file:function_name
    Transmogrifier

    /path/file:open_function_name: write_function_name: close_function_name:error_function



    Log
    /URL /path/file:function_name
    Error
    /URL /path/file:function_name
    PostExit

    /path/file:function_name
    ServerTerm

    /path/file:function_name
    ProxyAdvisor

    /path/file:function_name
    GCAdvisor

    /path/file:function_name

    API ディレクティブ変数

    これらのディレクティブの変数には、以下の意味があります。

    type
    プラグイン関数が呼び出されるかどうかを指定するために Authentication ディレクティブでのみ 使用されます。 有効な値は次のとおりです。

    URL
    プラグイン関数が呼び出される要求を指定します。 このテンプレートに一致する URL を持つ要求によって、プラグイン関数が使用されます。 これらのディレクティブの URL 指定は、仮想 (プロトコルを組み込んでいない) ですが、前にスラッシュ (/) が付いています。例えば、 /www.ics.raleigh.ibm.com は正しい形ですが、http://www.ics.raleigh.ibm.com は正しくありません。この値は、特定の URL またはテンプレートとして指定することができます。

    path/file
    コンパイル済みプログラムの完全修飾ファイル名。

    function_name
    プログラム内でプラグイン関数に指定した名前。

    パス情報にアクセスする場合、Service ディレクティブには、関数名の後に アスタリスク (*) が必要です。

    init_string
    ServerInit ディレクティブのこのオプション部分には、プラグイン関数に渡したい テキストを入れることができます。 httpd_getvar() を使用して INIT_STRING 変数からテキストを抽出します。

    これらのディレクティブの構文など、詳細については、「WebSphere Application Server Caching Proxy 管理ガイド」を参照してください。


    他の API との互換性

    Caching Proxy API は、バージョン 4.6.1 までの ICAPI および GWAPI と下位互換性があります。

    CGI プログラムの移植

    Caching Proxy API を使用するために、C で作成された CGI アプリケーションを移植する場合、以下のガイドラインに従います。


    Caching Proxy API の参照情報

    変数

    API プログラムの作成に際しては、リモート・クライアントおよびサーバー・システムに関する情報を提供する Caching Proxy 変数を使用することができます。

    注 :

    変数定義

    注:
    HTTP_ または PROXY_ 接頭部が付いていない ヘッダー変数はあいまいです。 あいまいさを避けるために、 ヘッダーの変数名とともに常に HTTP_ または PROXY_ 接頭部を使用してください。

    ACCEPT_RANGES
    Accept-Ranges 応答ヘッダーの値が入ります。 これは、コンテンツ・サーバーが範囲要求に 応答できるかどうかを指定します。 PROXY_ACCEPT_RANGES を使用して、 コンテンツ・サーバーからプロキシーに送信される ヘッダー値を抽出してください。 HTTP_ACCEPT_RANGES を使用して、 プロキシーからクライアントに送信される ヘッダー値を設定してください。
    注:
    ACCEPT_RANGES はあいまいです。あいまいさを 排除するには、代わりに HTTP_ACCEPT_RANGES および PROXY_ACCEPT_RANGES を 使用してください。

    ALL_VARIABLES
    読み取り専用。すべての CGI 変数が入ります。 以下に例を示します。
              ACCEPT_RANGES BYTES
         CLIENT_ADDR 9.67.84.3

    AUTH_STRING
    読み取り専用。サーバーがクライアント認証をサポートする場合は、このストリングには、クライアントを認証するのに使用される、デコードされていないクリデンシャルが入ります。

    AUTH_TYPE
    読み取り専用。サーバーがクライアント認証をサポートし、スクリプトが保護されている場合は、この変数にはクライアントの認証に使用される方式が入ります。例えば Basic です。

    CACHE_HIT
    読み取り専用。キャッシュ内にプロキシー要求が見つかったかどうかを示します。以下の値が戻されます。

    CACHE_MISS
    書き込み専用。キャッシュ・ミスを強制するかどうかを定義します。 有効な値は次のとおりです。

    CACHE_TASK
    読み取り専用。キャッシュが使用されたかどうかを識別します。 以下の値が戻されます。

    この変数は、PostAuthorization、PostExit、ProxyAdvisor、または Log ステップで使用できます。

    CACHE_UPDATE
    読み取り専用。プロキシー要求がキャッシュを更新したかどうかを示します。以下の値が戻されます。

    CLIENT_ADDR または CLIENTADDR
    REMOTE_ADDR と同じ。

    CLIENTMETHOD
    REQUEST_METHOD と同じ。

    CLIENT_NAME または CLIENTNAME
    REMOTE_HOST と同じ。

    CLIENT_PROTOCOL または CLIENTPROTOCOL
    クライアントが要求を出すために使用するプロトコルの名前とバージョンが入ります。 例えば HTTP/1.1 です。

    CLIENT_RESPONSE_HEADERS
    読み取り専用。サーバーがクライアントに送信するヘッダーを含むバッファーを戻します。

    CONNECTIONS
    読み取り専用。使用されている接続の数またはアクティブな要求の数が入ります。 例えば 15 です。

    CONTENT_CHARSET
    text/* 用の応答の文字セットです。例えば US ASCII です。この変数の抽出は、クライアントからのコンテンツ文字セットのヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるコンテンツ文字セットのヘッダーが影響を受けます。

    CONTENT_ENCODING
    文書で使用されるエンコードを指定します。例えば x-gzip です。この変数の抽出は、クライアントからのコンテンツ・エンコードのヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるコンテンツ文字セットのヘッダーが影響を受けます。

    CONTENT_LENGTH
    この変数の抽出は、クライアントの要求から得られるヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるヘッダーの値が影響を受けます。

    注:
    CONTENT_LENGTH はあいまいです。あいまいさを排除する場合は、HTTP_CONTENT_LENGTH および PROXY_CONTENT_LENGTH を使用してください。

    CONTENT_TYPE
    この変数の抽出は、クライアントの要求から得られるヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるヘッダーの値が影響を受けます。

    注:
    CONTENT_TYPE はあいまいです。あいまいさを排除する場合は、HTTP_CONTENT_TYPE および PROXY_CONTENT_TYPE を使用してください。

    CONTENT_TYPE_PARAMETERS
    その他の MIME 属性が入りますが、 文字セットは入りません。 この変数の抽出は、クライアント要求から得られるヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるヘッダーの値が影響を受けます。

    DOCUMENT_URL
    URL (Uniform Request Locator) が入ります。 以下に例を示します。
    http://www.anynet.com/~userk/main.htm
    

    DOCUMENT_URI
    DOCUMENT_URL と同じ。

    DOCUMENT_ROOT
    読み取り専用。パス・ルールによる定義のとおりの文書ルート・パスが入ります。

    ERRORINFO
    エラー・ページを判別するエラー・コードを指定します。例えば blocked です。

    EXPIRES
    プロキシーのキャッシュに保管された文書の有効期限が切れる時期を定義します。この変数の抽出は、クライアント要求から得られるヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるヘッダーの値が影響を受けます。以下に例を示します。
    Mon, 01 Mar 2002 19:41:17 GMT
    

    GATEWAY_INTERFACE
    読み取り専用。サーバーが使用している API のバージョンが入ります。 例えば ICSAPI/2.0 です。

    GC_BIAS
    書き込み専用。この浮動小数点値は、 ガーベッジ・コレクションを考慮されている ファイルのガーベッジ・コレクションについての決定に影響します。 入力される値には、ランキングを判別するために、そのファイル・タイプ用の Caching Proxy の品質設定値が掛けられます。 品質設定値は 0.0 から 0.1 の範囲の値であり、 プロキシー構成ファイル (ibmproxy.conf) 内の AddType ディレクティブによって 定義されます。

    GC_EVALUATION
    書き込み専用。この浮動小数点値によって、 ガーベッジ・コレクションを考慮されている ファイルの除去 (0.0) と保持 (1.0) のどちらを行うかを判別します。 0.0 と 1.0 の間の値はランクによって順位を付けられます。 つまり、GC_EVALUATION 値 0.1 を持つ ファイルは、GC_EVALUATION 値 0.9 を持つファイルよりも 除去される可能性が高くなります。

    GC_EXPIRES
    読み取り専用。考慮中のファイルがキャッシュ内で有効期限切れとなるまでの残り秒数を示します。この変数を抽出できるのは、GC Advisor プラグインのみです。

    GC_FILENAME
    読み取り専用。ガーベッジ・コレクション用に考慮されているファイルを示します。この変数を抽出できるのは、GC Advisor プラグインのみです。

    GC_FILESIZE
    読み取り専用。ガーベッジ・コレクション用に考慮されているファイルのサイズを示します。この変数を抽出できるのは、GC Advisor プラグインのみです。

    GC_LAST_ACCESS
    読み取り専用。ファイルが最後にアクセスされた時期を示します。この変数を抽出できるのは、GC Advisor プラグインのみです。

    GC_LAST_CHECKED
    読み取り専用。ファイルが最後に検査された時期を示します。この変数を抽出できるのは、GC Advisor プラグインのみです。

    GC_LOAD_DELAY
    読み取り専用。ファイルの検索に掛かる時間を示します。この変数を抽出できるのは、GC Advisor プラグインのみです。

    HTTP_COOKIE
    この変数には、読み取り時に、クライアントによって 設定された Set-Cookie ヘッダーの値が入ります。 これは、応答ストリーム (プロキシーとクライアントの間) での 新しい cookie の設定に使用することもできます。 この変数を設定すると、重複するヘッダーの有無に関係なく、文書要求ストリームの中に新しい Set-Cookie ヘッダーが作成されます。

    HTTP_HEADERS
    読み取り専用。すべてのクライアント要求ヘッダーの抽出に使用されます。

    HTTP_REASON
    この変数を設定すると、HTTP 応答内の理由ストリングが影響を受けます。 また、この設定により、 クライアントに対するプロキシーの応答に含まれる理由ストリングも影響を受けます。 この変数を抽出すると、コンテンツ・サーバーから プロキシーへの応答で理由ストリングが戻されます。

    HTTP_RESPONSE
    この変数を設定すると、HTTP 応答内の応答コードが影響を受けます。 また、この設定により、クライアントに対するプロキシーの応答に含まれる状況コードも影響を受けます。この変数を抽出すると、 コンテンツ・サーバーからプロキシーへの応答で状況コードが戻されます。

    HTTP_STATUS
    HTTP 応答コードおよび理由ストリングが入ります。例えば 200 OK です。

    HTTP_USER_AGENT
    User-Agent 要求ヘッダーの値が入ります。 これは、クライアント Web ブラウザーの名前 (例えば Netscape Navigator / V2.02) です。 この変数を設定すると、クライアントに対するプロキシーの応答に含まれるヘッダーが 影響を受けます。この変数の抽出は、クライアントの要求から得られるヘッダーに適用されます。

    INIT_STRING
    読み取り専用。このストリングは、ServerInit ディレクティブで定義されます。この変数は、Server Initialization ステップでのみ読み取ることができます。

    LAST_MODIFIED
    この変数の抽出は、クライアント要求から得られるヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるヘッダーの値が影響を受けます。 以下に例を示します。
    Mon, 01 Mar 1998 19:41:17 GMT

    LOCAL_VARIABLES
    読み取り専用。全ユーザー定義変数。

    MAXACTIVETHREADS
    読み取り専用。アクティブ・スレッドの最大数。

    NOTMODIFIED_TO_OK
    クライアントへの完全応答を強制します。 PreExit および ProxyAdvisor ステップで有効です。

    ORIGINAL_HOST
    読み取り専用。要求のホスト名または宛先 IP アドレスを戻します。

    ORIGINAL_URL
    読み取り専用。クライアント要求で送信された元の URL を戻します。

    OVERRIDE_HTTP_NOTRANSFORM
    Cache-Control: no-transform ヘッダーがある場合にデータを変更できるようにします。この変数を設定すると、クライアントへの応答ヘッダーが影響を受けます。

    OVERRIDE_PROXY_NOTRANSFORM
    Cache-Control: no-transform ヘッダーがある場合にデータを変更できるようにします。この変数を設定すると、コンテンツ・サーバーへの要求が影響を受けます。

    PASSWORD
    基本認証の場合は、デコードされたパスワードが入ります。例えば password です。

    PATH
    完全変換パスが入ります。

    PATH_INFO
    Web ブラウザーが送信したものと同様の追加パス情報が入ります。例えば /foo です。

    PATH_TRANSLATED
    PATH_INFO に入っているパス情報のデコード・バージョンまたは変換バージョンが入ります。以下に例を示します。
    d:¥wwwhome¥foo
    
    /wwwhome/foo
    

    PPATH
    部分変換パスが入ります。 これは、Name Translation ステップで使用してください。

    PROXIED_CONTENT_LENGTH
    読み取り専用。プロキシー・サーバーを介して実際に転送される応答データの長さを戻します。

    PROXY_ACCESS
    要求がプロキシー要求であるかどうかを定義します。 例えば NO です。

    PROXY_CONTENT_TYPE
    HTTPD_proxy() を介して出されたプロキシー要求の Content-Type ヘッダーが入ります。 情報が POST のメソッドで送信される場合、この変数には組み込まれたデータのタイプが入ります。プロキシー・サーバー構成ファイル内に独自のコンテンツ・タイプを作成し、このコンテンツ・タイプをビューアーにマップすることができます。この変数の抽出は、コンテンツ・サーバーの応答から得られるヘッダー値に適用されます。この変数を設定すると、コンテンツ・サーバーへの要求のヘッダーが影響を受けます。以下に例を示します。
    application/x-www-form-urlencoded
    

    PROXY_CONTENT_LENGTH
    HTTPD_proxy() を介して出されたプロキシー要求の Content-Length ヘッダー。 情報が POST のメソッドで送信される場合、この変数にはデータの文字数が入ります。一般に、サーバーは、標準入力を用いて情報を転送するときは、 ファイルの終わりフラグを送信しません。必要な場合は、 CONTENT_LENGTH 値を使用すると、入力ストリングの終わりを判別することができます。この変数の抽出は、コンテンツ・サーバーの応答から得られるヘッダー値に適用されます。この変数を設定すると、コンテンツ・サーバーへの要求のヘッダーが影響を受けます。以下に例を示します。
    7034

    PROXY_COOKIE
    この変数には、読み取り時に、 起点サーバーによって設定された Set-Cookie ヘッダーの値が入ります。 これは、要求ストリームでの新しい cookie の設定に使用することもできます。 この変数を設定すると、重複するヘッダーの有無に関係なく、文書要求ストリームの中に新しい Set-Cookie ヘッダーが作成されます。

    PROXY_HEADERS
    読み取り専用。プロキシー・ヘッダーの抽出に使用されます。

    PROXY_METHOD
    HTTPD_proxy() を介して作成された要求のメソッドを示します。この変数の抽出は、コンテンツ・サーバーの応答から得られるヘッダー値に適用されます。この変数を設定すると、コンテンツ・サーバーへの要求のヘッダーが影響を受けます。

    QUERY_STRING
    情報が GET メソッドを使用して送信される場合、 この変数には照会内の疑問符 (?) に続く情報が入ります。 この情報は CGI プログラムによってデコードしなければなりません。以下に例を示します。
    NAME=Eugene+T%2E+Fox&ADDR=etfox%7Cibm.net&INTEREST=xyz
    

    RCA_OWNER
    読み取り専用。要求されたオブジェクトを所有していたノードを示す数値を戻します。この変数は、PostExit、ProxyAdvisor、 または Log ステップで使用することが可能であり、 サーバーがリモート・キャッシュ・アクセス (RCA) を使用するキャッシュ配列の一部であるときにのみ意味があります。

    RCA_TIMEOUTS
    読み取り専用。すべてのピアへの RCA 要求で発生したタイムアウトの合計回数を示す数値を戻します。この変数は、どのステップでも使用することができます。

    REDIRECT_*
    読み取り専用。変数名 (例えば REDIRECT_URL) に対応する、 エラー・コードのリダイレクト・ストリングが入ります。 考えられる REDIRECT_ 変数のリストは、Apache Web サーバーについての オンライン文書に示されています (http://httpd.apache.org/docs-2.0/custom-error.html)。

    REFERRER_URL
    読み取り専用。ブラウザーの最後の URL ロケーションが入ります。 この変数により、クライアントは、Request-URL の入手元であるリソースのアドレス (URL) を (サーバーに役立つように) 指定できます。以下に例を示します。
    http://www.company.com/homepage
    

    REMOTE_ADDR
    Web ブラウザーの IP アドレスが入ります (使用可能な場合)。例えば 45.23.06.8 です。

    REMOTE_HOST
    Web ブラウザーのホスト名が入ります (使用可能な場合)。例えば www.raleigh.ibm.com です。

    REMOTE_USER
    サーバーがクライアント認証をサポートし、スクリプトが保護されている場合は、この変数は、認証のために渡されたユーザー名が入ります。例えば joeuser です。

    REQHDR
    読み取り専用。クライアントによって送信された ヘッダーのリストが入ります。

    REQUEST_CONTENT_TYPE
    読み取り専用。要求本文のコンテンツ・タイプを戻します。 以下に例を示します。
    application/x-www-form-urlencoded
    

    REQUEST_CONTENT_LENGTH
    読み取り専用。情報が POST のメソッドで送信される場合、この変数にはデータの文字数が入ります。一般に、サーバーは、標準入力を用いて情報を転送するときは、ファイルの終わりフラグを送信しません。必要な場合は、 CONTENT_LENGTH 値を使用すると、入力ストリングの終わりを判別することができます。例えば 7034 です。

    REQUEST_METHOD
    読み取り専用。要求の送信に使用されるメソッド (HTML フォームの METHOD 属性によって指定されたとおりの) が入ります。例えば GET または POST です。

    REQUEST_PORT
    読み取り専用。URL に指定されたポート番号またはプロトコルに基づいたデフォルト・ポートを戻します。

    RESPONSE_CONTENT_TYPE
    読み取り専用。情報が POST のメソッドで送信される場合、この変数には組み込まれたデータのタイプが入ります。プロキシー・サーバー構成ファイル内に独自のコンテンツ・タイプを作成し、このコンテンツ・タイプをビューアーにマップすることができます。例えば text/html です。

    RESPONSE_CONTENT_LENGTH
    読み取り専用。情報が POST のメソッドで送信される場合、この変数にはデータの文字数が入ります。一般に、サーバーは、標準入力を用いて情報を転送するときは、ファイルの終わりフラグを送信しません。必要な場合は、 CONTENT_LENGTH 値を使用すると、入力ストリングの終わりを判別することができます。例えば 7034 です。

    RULE_FILE_PATH
    読み取り専用。構成ファイルの完全修飾ファイル・システム・パスおよびファイル名が入ります。

    SSL_SESSIONID
    読み取り専用。現在の要求が SSL 接続上で受信されたものである場合は、SSL セッション ID を戻します。現在の要求が SSL 接続上で受信されたものでない場合は NULL を戻します。

    SCRIPT_NAME
    要求の URL が入ります。

    SERVER_ADDR
    読み取り専用。プロキシー・サーバーのローカル IP アドレスが入ります。

    SERVER_NAME
    読み取り専用。この要求に関するコンテンツ・サーバーのプロキシー・サーバー・ホスト名または IP アドレスが入ります。例えば www.ibm.com です。

    SERVER_PORT
    読み取り専用。クライアント要求が送信されたプロキシー・サーバーのポート番号が入ります。例えば 80 です。

    SERVER_PROTOCOL
    読み取り専用。要求を行うときに使用されるプロトコルの名前とバージョンが入ります。例えば HTTP/1.1 です。

    SERVER_ROOT
    読み取り専用。プロキシー・サーバー・プログラムがインストールされているディレクトリーが入ります。

    SERVER_SOFTWARE
    読み取り専用。プロキシー・サーバーの名前とバージョンが入ります。

    STATUS
    HTTP 応答コードおよび理由ストリングが入ります。例えば 200 OK です。

    TRACE
    情報をトレースする程度を判別します。戻り値は、以下のとおりです。

    URI
    読み取り/書き込み。DOCUMENT_URL と同じ。

    URI_PATH
    読み取り専用。 URL のパス部分だけが戻されます。

    URL
    読み取り/書き込み。DOCUMENT_URL と同じ。

    URL_MD4
    読み取り専用。現行要求の潜在的なキャッシュ・ファイルのファイル名を戻します。

    USE_PROXY
    現行要求について、 チェーニング対象のプロキシーを識別します。 URL を指定します。例えば http://myproxy:8080 です。

    USERID
    REMOTE_USER と同じ。

    USERNAME
    REMOTE_USER と同じ。

    認証および許可

    まず、用語を簡単に説明します。

    認証
    要求側の ID を確認するための、この要求に関連するセキュリティー・トークンの検証。

    許可
    要求側がリソースに対するアクセス権を所有しているかどうかを、セキュリティー・トークンを使用して判別するプロセス。

    図 3 は、プロキシー・サーバーによる認証および許可プロセスを表しています。

    図 3. プロキシー・サーバーの認証および許可プロセス

    認証および許可プロセスのダイアグラム

    図 3 に示したように、サーバーの許可および認証のプロセスの最初のステップは、許可プロセスの開始です。

    Caching Proxy において、認証は許可プロセスの一部であり、認証が行われるのは、許可が必要な場合に限られます。

    許可および認証プロセス

    プロキシー・サーバーは、許可を必要とする要求を処理するときに以下のステップに従います。

    1. 最初に、プロキシー・サーバーはその構成ファイルを検査し、許可ディレクティブがあるかどうかを判別します。
    2. プロキシー・サーバーは、クライアント要求の中に HTTP_authenticate ヘッダーが存在するかどうかを検査することにより、認証プロセスを開始します。
    3. プロキシー・サーバーは、プロキシー構成ファイルの中に認証ディレクティブが存在するかどうかを検査します。

    Caching Proxy プラグインが独自の許可プロセスを備えている場合、そのプロセスがデフォルトのサーバーの許可および認証を上書き します。 したがって、構成ファイルに許可ディレクティブがある場合には、 それらに関連するプラグイン関数は、必要な認証を処理する必要もあります。 これに使用するために、事前定義 HTTPD_authenticate() 関数が用意されています。

    許可プラグインに認証を備えるには、次の 3 つの方法があります。

    Caching Proxy プラグインが独自の許可プロセスを備えていない場合でも、次の方法を使用して、カスタマイズされた認証を用意することができます。

    Authorization ステップを実行すると、それがデフォルトのサーバー許可を実行し、 次にその許可が認証プラグイン関数を呼び出します。

    以下の点に注意してください。

    バリアント・キャッシュ

    元の文書 (URI) が変更されたデータをキャッシュする場合は、バリアント・キャッシュを使用します。Caching Proxy は、API によって生成されたバリアントを処理します。バリアントとは、 基本文書の別バージョンです。

    一般に、起点サーバーはバリアントを送信するときに、それらがバリアントであることを識別できません。Caching Proxy は、プラグインによって作成されたバリアント (例えばコード・ページ変換) のみをサポートします。プラグインが HTTP ヘッダーに入っていない基準に基づいてバリアントを作成する場合は、プラグインに PreExit または PostAuthorization ステップ関数を組み込んで疑似ヘッダーを作成して、Caching Proxy が既存のバリアントを正しく識別できるようにしなければなりません。

    例えば、ブラウザーが送信する User-Agent ヘッダーの値に基づいて ユーザーが要求したデータを変更するには、Transmogrifier API プログラムを使用します。 close 関数で、変更された内容をファイルに保管するか、 またはバッファー長を指定してデータ引数としてバッファーを渡します。 その後で、バリアント・キャッシュ関数 httpd_variant_insert() および httpd_variant_lookup() を使用して、コンテンツをキャッシュに入れます。

    API の例

    Edge Components のインストール CD-ROM の samples ディレクトリーに提供されているサンプル・プログラムを参照して、独自の Caching Proxy API 関数の作成に役立ててください。 WebSphere Application Server Web サイト www.ibm.com/software/webservers/appserv/ に追加情報が記載されています。


    カスタム advisor

    このセクションでは、Load Balancer 用のカスタム advisor の作成について説明します。


    advisor によるロード・バランシング情報の提供

    advisor は、指定サーバー上のロードに関する情報を提供するために Load Balancer 内部で働くソフトウェア・エージェントです。 各標準プロトコル (HTTP、SSL、その他) ごとに異なる advisor が存在します。定期的に、Load Balancer 基本コードが advisor サイクルを実行します。このサイクルで、構成内のすべてのサーバーの状況が個別に評価されます。

    Load Balancer 用の独自の advisor を作成することによって、サーバー・マシンのロードを判別する方法をカスタマイズできます。

    標準 advisor 機能

    一般に、advisor は、以下のようにロード・バランシングを可能にするために働きます。

    1. 定期的に、advisor は各サーバーとの接続をオープンし、サーバーに要求メッセージを送ります。メッセージの内容はサーバーで実行しているプロトコルに固有です。例えば、HTTP advisor はサーバーに HEAD 要求を送ります。
    2. advisor はサーバーからの応答を listen します。応答を取得した後、advisor はそのサーバーのロード値を計算して報告します。advisor が異なればロード値を計算する方法も異なりますが、たいていの標準 advisor はサーバーが応答に要する時間を測定し、その値をロードとしてミリ秒単位で報告します。
    3. advisor は Load Balancer のマネージャー機能にロードを報告します。ロードはマネージャー報告書の「ポート」欄に表示されます。マネージャーは advisor の報告したロードを管理者が設定した重みとともに使用して、サーバーへの着信要求のロード・バランシング方法を決定します。
    4. サーバーが応答しない場合、 advisor はそのロードに対して負の値 (-1) を戻します。マネージャーはこの情報を使用して、特定のサーバーについてサービスを延期する時期を決定します。

    Load Balancer に提供されている標準 advisor には、以下の機能のための advisor が含まれます。 これらの advisor に関する詳細情報は「WebSphere Application Server Load Balancer 管理ガイド」に記載されています。

    標準 advisor が提供されていない所有プロトコルをサポートするには、カスタム advisor を作成しなければなりません。


    カスタム advisor の作成

    カスタム advisor はクラス・ファイルとして提供される小さな Java コードであり、サーバー上のロードを判別するために Load Balancer 基本コードによって呼び出されます。 基本コードは、カスタム advisor のインスタンスの開始と停止、状況および報告書の提供、ヒストリー情報のログ・ファイルへの記録、さらに advisor 結果のマネージャー・コンポーネントへの報告など、必要なすべての管理サービスを提供します。

    Load Balancer 基本コードがカスタム advisor を呼び出すと、以下のステップが実行されます。

    1. Load Balancer 基本コードがサーバー・マシンとの接続をオープンします。
    2. ソケットがオープンすると、基本コードは指定された advisor の GetLoad 関数を呼び出します。
    3. advisor の GetLoad 関数は、ユーザーがサーバーの状況を評価するために定義した ステップ (サーバーからの応答を待つなど) を実行します。 この関数は、応答が受け取られると実行を終了します。
    4. Load Balancer 基本コードはサーバーとのソケットをクローズして、ロード情報をマネージャーに報告します。 カスタム advisor が通常モードで作動するか置換モードで作動するかによって、基本コードは GetLoad 関数の終了後に追加の計算を行う場合があります。

    通常モードと置換モード

    カスタム advisor は、Load Balancer と通常 モードまたは置換 モードで対話するように設計することができます。

    操作モードの選択は、カスタム advisor ファイルで、コンストラクター・メソッドのパラメーターとして指定されます。(各 advisor は設計に基づいて、上記のモードのいずれかでのみ稼動します。)

    通常モードでは、カスタム advisor がサーバーとデータを交換し、基本 advisor コードが交換の時間を測定して、ロード値を計算します。その後、基本コードがこのロード値をマネージャーに報告します。成功を示す場合は値ゼロが、 またはエラーを示す場合は -1 がカスタム advisor から戻されます。

    通常モードを指定するには、コンストラクター内の replace フラグを false に設定してください。

    置換モードでは、基本コードはいかなる時間測定も行いません。カスタム advisor はその固有の要件に基づいて、指定された操作をすべて実行し、その後、実際のロード値を戻します。基本コードはそのロード値を受け入れ、それをそのままマネージャーに報告します。最良の結果を得るには、高速サーバーを表す 10 と低速サーバーを表す 1000 によって、ロード値を 10 から 1000 の間で正規化してください。

    置換モードを指定するには、コンストラクター内の replace フラグを true に設定してください。

    advisor 命名規則

    カスタム advisor ファイル名は ADV_name.java という形式に従わなければなりません。 ここで name は advisor のために選択する名前です。 完全な名前は大文字の接頭部 ADV_ で始まり、後続の文字がすべての小文字でなければなりません。ここで小文字を使用することにより、 advisor を実行するためのコマンドでの大/小文字の区別が不要になります。

    Java の規則に従って、ファイル内で定義されるクラスの名前はファイルの名前と一致しなければなりません。

    コンパイル

    Java 言語でカスタム advisor を作成し、それを Load Balancer コードと同じレベルの Java コンパイラーでコンパイルする必要があります。ご使用のシステムにおける Java のバージョンを検査するには、install_path/java/bin ディレクトリーから以下のコマンドを実行してください。

    java -fullversion
    

    現行ディレクトリーがお客様のパスの一部ではない場合、正しいバージョン情報が確実に得られるようにするために、現行ディレクトリーから Java を実行するように指定する必要があります。 その場合、install_path/java/bin ディレクトリーから以下のコマンドを実行してください。

    ./java -fullversion
    

    コンパイル時には、以下のファイルが参照されます。

    コンパイル時には、クラスパス環境変数がカスタム advisor ファイルと基本クラス・ファイルの 両方を指していなければなりません。 Microsoft Windows システムの場合、サンプル・コンパイル・コマンドは次のような書式です。

     install_path/java/bin/javac -classpath /opt/ibm/edge/lb/servers/lib/ibmlb.jar ADV_name.java
    

    ただし、

    コンパイルの出力は ADV_name.class などのクラス・ファイルです。advisor を開始する前に、 クラス・ファイルを install_path/servers/lib/CustomAdvisors/ ディレクトリーに コピーしてください。

    注:
    カスタム advisor は、コンパイルした時のオペレーティング・システムとは別のオペレーティング・システムで実行することができます。例えば、作成したadvisor を Windows システムでコンパイルし、その結果として得られるクラス・ファイルを (バイナリー形式で) Linux マシンにコピーして、そこでカスタム advisor を実行することができます。 AIX、HP-UX、Linux、および Solaris オペレーティング・システムでは、構文は類似しています。

    カスタム advisor の実行

    カスタム advisor を実行するには、最初に advisor のクラス・ファイルを Load Balancer マシン上の lib/CustomAdvisors サブディレクトリーにコピーする必要があります。 例えば、myping というカスタム advisor の場合、ファイル・パスは、 install_path/servers/lib/CustomAdvisors/ADV_myping.class

    になります。Load Balancer を構成し、そのマネージャー機能を開始し、カスタム advisor を開始するコマンドを発行します。 カスタム advisor は、次のように、その名前から ADV_ 接頭部とファイル拡張子を除いたものによって指定されます。

    dscontrol advisor start myping port_number
    

    コマンドに指定するポート番号は、advisor がターゲット・サーバーとの接続をオープンするポートです。

    必須なルーチン

    すべてのadvisor と同様に、カスタム advisor は、ADV_Base と呼ばれる advisor 基本クラスの機能性を拡張 します。 advisor ベースは、マネージャーの重みアルゴリズムで使用するためにロードをマネージャーに報告するなど、advisor の関数の大部分を実行します。advisor ベースはまた、ソケット接続およびクローズ操作を実行し、advisor が使用する送信および受信メソッドを提供します。advisor は、調査中のサーバー用に指定されたポートでデータを送信および受信するためだけに使用されます。advisor ベース内の TCP メソッドは、ロードを計算するために時間測閧ウれます。advisor ベースのコンストラクター内のフラグが、既存のロードを advisor から戻された新しいロードで上書きするかどうかを示します。

    注:
    コンストラクターで設定された値に基づき、advisor ベースは指定された間隔でロードを重みアルゴリズムに提供します。 advisor が処理を完了せず、有効なロードを戻せない場合には、 advisor ベースは前に報告されたロードを使用します。

    advisor には、以下の基本クラス・メソッドがあります。

    これらの必須ルーチンに関する詳細は、このセクションで後述します。

    検索順序

    カスタム advisor は、ネイティブ advisor または標準 advisor を検索した後に呼び出されます。 Load Balancer は、指定の advisor を標準 advisor のリストから見つけられない場合、カスタム advisor のリストを調べます。 advisor の使用に関する追加情報は「WebSphere Application Server Load Balancer 管理ガイド」に記載されています。

    命名およびファイル・パス

    カスタム advisor の名前およびパスについては、以下の要件を忘れないでください。

    カスタム advisor メソッドおよび関数呼び出し

    コンストラクター (advisor 基本によって提供される)

    public <advisor_name> (
            String sName;
            String sVersion;
            int iDefaultPort;
            int iInterval;
            String sDefaultLogFileName;
            boolean replace
    )
    
    sName
    カスタム advisor の名前。
    sVersion
    カスタム advisor のバージョン。
    iDefaultPort
    サーバーへの接続を行うポート番号 (ポート番号が呼び出しに指定されていない場合)。
    iInterval
    advisor がサーバーを照会する間隔。
    sDefaultLogFileName
    このパラメーターは必須ですが、使用されません。許容値はヌル・ストリングである ""
    です。replace
    この advisor が置換 モードで機能するかどうかを示します。可能な値は、以下のとおりです。

    ADV_AdvisorInitialize()

    void  ADV_AdvisorInitialize()

    このメソッドは、カスタム advisor に必要な初期化を実行するために提供されます。このメソッドが呼び出されるのは advisor 基本モジュールを開始した後です。

    標準 advisor を含む多くの場合においてこのメソッドは使用されず、 そのコードを構成するのは return ステートメントだけです。 このメソッドは suppressBaseOpeningSocket メソッドを呼び出すために使用できます。 suppressBaseOpeningSocket メソッドが有効であるのは上記のメソッド内から呼び出された場合のみです。

    getLoad()

    int getLoad(
            int iConnectTime;
            ADV_Thread *caller
    )
    
    iConnectTime
    接続の完了に要した時間 (ミリ秒)。このロード測定は advisor 基本コードによって実行されてカスタム advisor コードに渡されます。ロード値を戻すときには、測定を使用することもまたは無視することもできます。接続が失敗すると、この値が -1 に設定されます。
    caller
    advisor 基本メソッドを提供する advisor 基本クラスのインスタンス。

    カスタム advisor で使用可能な関数呼び出し

    以下のセクションで説明するメソッドまたは関数は、カスタム advisor から呼び出せます。これらのメソッドは advisor 基本コードによってサポートされています。

    一部の関数呼び出し (例えば function_name () など) は直接に作成できますが、その他は接頭部 caller を必要とします。caller は基本 advisor インスタンスを示し、これは実行されるカスタム advisor をサポートします。

    ADVLOG()

    ADVLOG 関数により、カスタム advisor はテキスト・メッセージを advisor 基本ログ・ファイルに書き込むことができます。形式は次のとおりです。

    void  ADVLOG  (int logLevel, String message)
    
    logLevel
    メッセージがログ・ファイルに書き込まれる状況レベル。 advisor ログ・ファイルはステージで編成されます。最も緊急のメッセージには状況レベル 0 を指定し、緊急の度合いがそれより低いメッセージには大きい数値を指定します。メッセージの最も詳細なタイプには状況レベル 5 が指定されます。 これらのレベルは、リアルタイムでユーザーが受け取るメッセージのタイプを制御するために 使用されます (詳細の度合いを設定するには dscontrol コマンドが 使用されます)。 致命的なエラーは常にレベル 0 で記録する必要があります。
    message
    ログ・ファイルに書き込むメッセージ。このパラメーターの値は標準 Java ストリングです。

    getAdvisorName()

    getAdvisorName 関数は、カスタム advisor 名の接尾部部分の Java ストリングを戻します。 例えば、ADV_cdload.java という名前の advisor では、この関数は値 cdload を戻します。

    この関数にはパラメーターを使用しません。

    この値は advisor のインスタンス化中に変更できないことに注意してください。

    getAdviseOnPort()

    getAdviseOnPort 関数は、呼び出しカスタム advisor を実行するポート番号を戻します。戻り値は Java 整数 (int) であり、この関数ではパラメーターは使用されません。

    この値は advisor のインスタンス化中に変更できないことに注意してください。

    caller.getCurrentServerId()

    getCurrentServerId 関数は、現行サーバーを一意的に表わす Java ストリングを戻します。

    advisor 基本コードがすべてのサーバー・マシンを連続して照会するため、通常はカスタム advisor を呼び出すたびにこの値が変更されます。

    この関数にはパラメーターを使用しません。

    caller.getCurrentClusterId()

    getCurrentClusterId 関数呼び出しは、現行クラスターを一意的に表わす Java ストリングを戻します。

    advisor 基本コードがすべてのクラスターを連続して照会するため、通常はカスタム advisor を呼び出すたびにこの値が変更されます。

    この関数にはパラメーターを使用しません。

    caller.getSocket()

    getSocket 関数呼び出しは、通信のために現行サーバーに対してオープンされているソケットを表す、Java ソケットを戻します。

    この関数にはパラメーターを使用しません。

    getInterval()

    getInterval 関数は、advisor サイクル間の秒数である advisor 間隔を戻します。この値は、 dscontrol コマンドを使用して実行時に変更しない限り、 カスタム advisor のコンストラクターに設定されたデフォルト値と同じです。

    戻り値は Java 整数 (int) です。この関数にはパラメーターを使用しません。

    caller.getLatestLoad()

    getLatestLoad 関数により、カスタム advisor は指定サーバー・オブジェクトの最新ロード値を獲得できます。 ロード値は、advisor 基本コードおよびマネージャー・デーモンによって内部テーブルで保守されています。

    int caller.getLatestLoad (String clusterId, int port, String serverId)
    

    3 つの引数は 1 つのサーバー・オブジェクトをともに定義します。

    clusterId
    現行ロード値を入手する対象となるサーバー・オブジェクトのクラスター ID。この引数は、Java ストリングでなければなりません。
    port
    現行ロード値を入手するサーバー・オブジェクトのポート番号。
    serverId
    現行ロード値を入手する対象となるサーバー・オブジェクトのサーバー ID。この引数は、Java ストリングでなければなりません。

    戻り値は整数です。

    この関数呼び出しは、あるプロトコルまたはポートの動作を別のものの動作に依存させる場合に役立ちます。例えば、同一マシン上の Telnet サーバーが使用不可である場合に、特定アプリケーション・サーバーを使用不可にするカスタム advisor でこの関数呼び出しを使用する場合などです。

    caller.receive()

    receive 関数は、ソケット接続から情報を入手します。

    caller.receive(StringBuffer *response)
    

    パラメーター response は、検索されたデータが置かれるストリング・バッファーです。さらに、この関数は以下の重要度のある整数値を戻します。

    caller.send()

    send 関数は、指定ポートを使用してデータのパケットをサーバーに送信するために確立したソケット接続を使用します。

    caller.send(String command)
    

    パラメーター command は、サーバーに送信するデータが入っているストリングです。この関数は、以下の重要度のある整数値を戻します。

    suppressBaseOpeningSocket()

    suppressBaseOpeningSocket 関数呼び出しにより、カスタム advisor の代わりに 基本 advisor コードがサーバーへの TCP ソケットをオープンするかどうかを カスタム advisor が指定できます。 advisor が状況を判別するためにサーバーとの直接通信を使用しない場合は、このソケットをオープンする必要はありません。

    この関数呼び出しを出せるのは一度だけであり、ADV_AdvisorInitialize ルーチンから出さなければなりません。

    この関数にはパラメーターを使用しません。


    以下の例は、カスタム advisor をインプリメントできる方法を示します。

    標準 advisor

    このサンプル・ソース・コードは、標準 Load Balancer HTTP advisor に類似しています。 以下のように機能します。

    1. 送信要求 "HEAD/HTTP" コマンドが出されます。
    2. 応答を受け取ります。情報は解析されませんが、応答により getLoad メソッドが終了します。
    3. getLoad メソッドは成功を示す 0 または失敗を示す -1 を戻します。

    この advisor は通常モードで操作するので、ロード測定はソケット・オープン、送信、受信、およびクローズ操作を実行するために必要な経過時間 (ミリ秒) に基づきます。

    package CustomAdvisors;
    import com.ibm.internet.lb.advisors.*;
    public class ADV_sample extends ADV_Base implements ADV_MethodInterface {
      static final String ADV_NAME ="Sample";
      static final int ADV_DEF_ADV_ON_PORT = 80;
      static final int ADV_DEF_INTERVAL = 7;
      static final String ADV_SEND_REQUEST = 
        "HEAD / HTTP/1.0¥r¥nAccept: */*¥r¥nUser-Agent: " +
        "IBM_Load_Balancer_HTTP_Advisor¥r¥n¥r¥n";
     
    //--------
    // Constructor
     
      public ADV_sample() {
        super(ADV_NAME, "3.0.0.0-03.31.00", 
              ADV_DEF_ADV_ON_PORT, ADV_DEF_INTERVAL, "",
              false);
        super.setAdvisor( this );
      }
     
    //--------
    // ADV_AdvisorInitialize
     
      public void ADV_AdvisorInitialize() {
        return;                                  // usually an empty routine
      }
     
    //--------
    // getLoad
     
      public int getLoad(int iConnectTime, ADV_Thread caller) {
        int iRc;
        int iLoad = ADV_HOST_INACCESSIBLE;       // initialize to inaccessible
     
        iRc = caller.send(ADV_SEND_REQUEST);     // send the HTTP request to 
                                                 // the server
        if (0 <= iRc) {                          // if the send is successful
          StringBuffer sbReceiveData = new StringBuffer("");   // allocate a buffer 
                                                               // for the response
          iRc = caller.receive(sbReceiveData);   // receive the result
     
          // parse the result here if you need to
     
          if (0 <= iRc) {          // if the receive is successful
            iLoad = 0;             // return 0 for success 
          }                        // (advisor's load value is ignored by
        }                          //  base in normal mode)
        return iLoad;
      }
    }
    

    サイド・ストリーム advisor

    このサンプルでは、advisor ベースによる標準ソケットのオープンの抑制を例示しています。その代わりに、この advisor は、サイド・ストリーム Java ソケットをオープンしてサーバーを照会します。 このプロシージャーは、通常のクライアント・トラフィックと異なるポートを使用して advisor 照会を listen するサーバーのために役立ちます。

    この例では、サーバーはポート 11999 上で listen していて、 照会されたときに 16 進 int "4" でロード値を戻します。 このサンプルは置換モードで実行されます。 つまり、advisor コンストラクターの最終パラメーターが true に設定されて、 advisor 基本コードは経過時間ではなく戻されたロード値を使用します。

    初期化ルーチンでの supressBaseOpeningSocket() に対する呼び出しに注意してください。データが送信されないときの基本ソケットの抑制は不要です。例えば、advisor がサーバーに接続できることを確認するためにソケットをオープンする場合などです。 この選択を行う前には、アプリケーションの必要性を注意深く調べてください。

    package CustomAdvisors;
    import java.io.*;
    import java.net.*;
    import java.util.*;
    import java.util.Date;
    import com.ibm.internet.lb.advisors.*;
    import com.ibm.internet.lb.common.*;
    import com.ibm.internet.lb.server.SRV_ConfigServer;
     
    public class ADV_sidea extends ADV_Base implements ADV_MethodInterface {
      static final String ADV_NAME = "sidea";
      static final int ADV_DEF_ADV_ON_PORT = 12345;
      static final int ADV_DEF_INTERVAL = 7;
     
      // create an array of bytes with the load request message
      static final byte[] abHealth = {(byte)0x00, (byte)0x00, (byte)0x00, 
                                      (byte)0x04};
     
      public ADV_sidea() {
        super(ADV_NAME, "3.0.0.0-03.31.00", ADV_DEF_ADV_ON_PORT,
              ADV_DEF_INTERVAL, "", 
              true);         // replace mode parameter is true
        super.setAdvisor( this );
      }
     
    //--------
    // ADV_AdvisorInitialize
     
      public void ADV_AdvisorInitialize()
      { 
        suppressBaseOpeningSocket();   // tell base code not to open the 
                                       // standard socket 
            return;
      }
     
    //--------
    // getLoad
     
      public int getLoad(int iConnectTime, ADV_Thread caller) {
        int iRc; 
        int iLoad = ADV_HOST_INACCESSIBLE;    // -1
        int iControlPort = 11999;   // port on which to communicate with the server
     
        String sServer = caller.getCurrentServerId();   // address of server to query 
        try { 
          socket soServer = new Socket(sServer, iControlPort);  // open socket to 
                                                                // server
          DataInputStream disServer = new DataInputStream(
                                          soServer.getInputStream());
          DataOutputStream dosServer = new DataOutputStream(
                                           soServer.getOutputStream());
     
          int iRecvTimeout = 10000;  // set timeout (in milliseconds)
                                     // for receiving data 
          soServer.setSoTimeout(iRecvTimeout);
     
          dosServer.writeInt(4);     // send a message to the server
          dosServer.flush();
     
          iLoad = disServer.readByte();   // receive the response from the server
     
        } catch (exception e) {
          system.out.println("Caught exception " + e);
        }
        return iLoad;    // return the load reported from the server 
      }
    }
     
    

    2 つのポート advisor

    このカスタム advisor サンプルは、サーバーの 1 つのポートに対する失敗を検出する機能を説明しています。 これは、そのポートの状況と、同一サーバー・マシン上にある別のポート上で実行されている 異なるサーバー・デーモンの状況の両方に基づいています。 例えば、ポート 80 の HTTP デーモンが応答を停止する場合には、ポート 443 の SSL デーモンへのルーティング・トラフィックも停止することができます。

    この advisor は、応答を送信しないサーバーは機能を停止したと見なして、ダウンのマークを付けるので、 標準 advisor よりも積極的です。標準 advisor は応答のないサーバーを非常に低速であると見なします。この advisor は HTTP ポートおよび SSL ポートのいずれかの応答がないと、両方のポートがダウンしたことを示す マークをサーバーに付けます。

    このカスタム advisor を使用するには、advisor の HTTP ポート上にある インスタンスと SSL ポート上にあるインスタンスを管理者が開始します。 advisor は HTTP 用と SSL 用の 2 つの静的グローバル・ハッシュ・テーブルを検証します。各 advisor は そのサーバー・デーモンとの通信を試行し、そのハッシュ・テーブルにこのイベントの結果を保管します。 各 advisor が基本 advisor クラスに戻す値は、 その固有のサーバー・デーモンと通信する能力およびそのデーモンと通信するパートナー advisor の能力によって異なります。

    以下のカスタム・メソッドが使用されます。

    次のエラー条件が検出されます。

    このサンプルは HTTP 用のポート 80 および SSL 用の 443 をリンクするように書かれていますが、ポートの組み合わせは任意に調整できます。

    package CustomAdvisors;
    import java.io.*;
    import java.net.*;
    import java.util.*;
    import java.util.Date;
    import com.ibm.internet.lb.advisors.*;
    import com.ibm.internet.lb.common.*;
    import com.ibm.internet.lb.manager.*;
    import com.ibm.internet.lb.server.SRV_ConfigServer;
     
    //--------
    // Define the table element for the hash tables used in this custom advisor
     
    class ADV_nte implements Cloneable {
      private String  sCluster;
      private int     iPort;
      private String  sServer;
      private int     iLoad;
      private Date    dTimestamp;
     
    //--------
    // constructor
     
      public ADV_nte(String sClusterIn, int iPortIn, String sServerIn, 
                     int iLoadIn) {
        sCluster = sClusterIn;
        iPort = iPortIn;
        sServer = sServerIn;
        iLoad = iLoadIn;
        dTimestamp = new Date();
      }
     
    //--------
    // check whether this element is current or expired
      public boolean isCurrent(ADV_twop oThis) {
        boolean bCurrent;
        int iLifetimeMs = 3 * 1000 * oThis.getInterval();   // set lifetime as 
                                                            // 3 advisor cycles
        Date dNow = new Date();
        Date dExpires = new Date(dTimestamp.getTime() + iLifetimeMs);
     
        if (dNow.after(dExpires)) {
          bCurrent = false;
        } else {
          bCurrent = true;
        }
        return bCurrent;
      }
     
    //--------
    // value accessor(s)
     
      public int getLoadValue() { return iLoad; }
     
    //--------
    // clone (avoids corruption between threads)
     
      public synchronized Object Clone() {
        try { 
          return super.clone();
        } catch (cloneNotSupportedException e) {
          return null;
        }
      }
     
    }
     
    //--------
    // define the custom advisor
     
    public class ADV_twop extends ADV_Base 
       implements ADV_MethodInterface, ADV_AdvisorVersionInterface {
     
      static final int ADV_TWOP_PORT_HTTP = 80;
      static final int ADV_TWOP_PORT_SSL = 443;
     
      //--------
      // define tables to hold port-specific history information
     
      static HashTable htTwopHTTP = new Hashtable();
      static HashTable htTwopSSL = new Hashtable();
     
      static final String ADV_TWOP_NAME = "twop";
      static final int ADV_TWOP_DEF_ADV_ON_PORT = 80;
      static final int ADV_TWOP_DEF_INTERVAL = 7;
      static final String ADV_HTTP_REQUEST_STRING = 
        "HEAD / HTTP/1.0¥r¥nAccept: */*¥r¥nUser-Agent: " +
        "IBM_LB_Custom_Advisor¥r¥n¥r¥n";
     
      //--------
      // create byte array with SSL client hello message
     
      public static final byte[] abClientHello = {
        (byte)0x80, (byte)0x1c,
        (byte)0x01,               // client hello
        (byte)0x03, (byte)0x00,   // SSL version
        (byte)0x00, (byte)0x03,   // cipher spec len (bytes)
        (byte)0x00, (byte)0x00,   // session ID len (bytes)
        (byte)0x00, (byte)0x10,   // challenge data len (bytes)
        (byte)0x00, (byte)0x00, (byte)0x03,   // cipher spec
        (byte)0x1A, (byte)0xFC, (byte)0xE5, (byte)Ox20,  // challenge data
        (byte)0xFD, (byte)0x3A, (byte)0x3C, (byte)0x18, 
        (byte)0xAB, (byte)0x67, (byte)0xB0, (byte)0x52, 
        (byte)0xB1, (byte)0x1D, (byte)0x55, (byte)0x44, (byte)0x0D, (byte)0x0A };
     
      //--------
      // constructor
     
      public ADV_twop() {
        super(ADV_TWOP_NAME, VERSION, ADV_TWOP_DEF_ADV_ON_PORT, 
              ADV_TWOP_DEF_INTERVAL, "", 
              false);    // false = load balancer times the response
        setAdvisor ( this );
      }
     
      //--------
      // ADV_AdvisorInitialize
     
      public void ADV_AdvisorInitialize() {
            return;
      }
     
      //--------
      // synchronized PUT and GET access routines for the hash tables
     
      synchronized ADV_nte getNte(Hashtable ht, String sName, String sHashKey) {
        ADV_nte nte = (ADV_nte)(ht.get(sHashKey));
        if (null != nte) {
          nte = (ADV_nte)nte.clone();
        }
        return nte;
      }
     synchronized void putNte(Hashtable ht, String sName, String sHashKey, 
                              ADV_nte nte) {
       ht.put(sHashKey,nte);
       return;
     }
     
      //--------
      // getLoadHTTP - determine HTTP load based on server response
     
      int getLoadHTTP(int iConnectTime, ADV_Thread caller) {
        int iLoad = ADV_HOST_INACCESSIBLE;
     
        int iRc = caller.send(ADV_HTTP_REQUEST_STRING);  // send request message 
                                                         // to server 
        if (0 <= iRc) {           // did the request return a failure? 
          StringBuffer sbReceiveData = new StringBuffer("")    // allocate a buffer 
                                                               // for the response
          iRc = caller.receive(sbReceiveData);    // get response from server
     
          if (0 <= iRc) {             // did the receive return a failure? 
            if (0 < sbReceiveData.length()) {      // is data there? 
              iLoad = SUCCESS;        // ignore retrieved data and 
                                      // return success code
            }
          }
        }
        return iLoad;
      }
     
      //--------
      // getLoadSSL() - determine SSL load based on server response
     
      int getLoadSSL(int iConnectTime, ASV_Thread caller) {
        int iLoad = ADV_HOST_INACCESSIBLE;
        int iRc;
     
        CMNByteArrayWrapper cbawClientHello = new CMNByteArrayWrapper(
                                                      abClientHello);
        Socket socket = caller.getSocket();
     
        try {
            socket.getOutputStream().write(abClientHello);
            // Perform a receive.
            socket.getInputStream().read();
            // If receive is successful, return load of 0.  We are not concerned with
            // data's contents, and the load is calculated by the ADV_Thread thread.
            iLoad = 0;
        } catch (IOException e) {
            // Upon error, iLoad will default to it.
        }
        return iLoad;
      }
     
      //--------
      // getLoad - merge results from the HTTP and SSL methods
     
      public int getLoad(int iConnectTime, ADV_Thread caller) {
        int iLoadHTTP;
        int iLoadSSL;
        int iLoad;
        int iRc;
     
        String sCluster = caller.getCurrentClusterId();   // current cluster address
        int iPort = getAdviseOnPort();
        String sServer = caller.getCurrentServerId();
        String sHashKey = sCluster = ":" + sServer;     // hash table key
     
        if (ADV_TWOP_PORT_HTTP == iPort) {              // handle an HTTP server
          iLoadHTTP = getLoadHTTP(iConnectTime, caller);  // get the load for HTTP
     
          ADV_nte nteHTTP = newADV_nte(sCluster, iPort, sServer, iLoadHTTP);
          putNte(htTwopHTTP, "HTTP", sHashKey, nteHTTP);  // save HTTP load 
                                                          // information
          ADV_nte nteSSL = getNte(htTwopSSL, "SSL", sHashKey);  // get SSL 
                                                                // information 
          if (null != nteSSL) { 
            if (true == nteSSL.isCurrent(this)) {         // check the time stamp
              if (ADV_HOST_INACCESSIBLE != nteSSL.getLoadValue()) {    // is SSL 
                                                                       // working?
                iLoad = iLoadHTTP;
              } else {    // SSL is not working, so mark the HTTP server down
                iLoad= ADV_HOST_INACCESSIBLE;
              }
            } else {      // SSL information is expired, so mark the 
                          // HTTP server down
              iLoad = ADV_HOST_INACCESSIBLE; 
            }
          } else {        // no load information about SSL, report 
                          // getLoadHTTP() results
            iLoad = iLoadHTTP;
          }
        }
        else if (ADV_TWOP_PORT_SSL == iPort) {           // handle an SSL server
          iLoadSSL = getLoadSSL(iConnectTime, caller);   // get load for SSL
     
          ADV_nte nteSSL = new ADV_nte(sCluster, iPort, sServer, iLoadSSL);
          putNte(htTwopSSL, "SSL", sHashKey, nteSSL);   // save SSL load info.
     
          ADV_nte nteHTTP = getNte(htTwopHTTP, "SSL", sHashKey);   // get HTTP 
                                                                   // information
          if (null != nteHTTP) {
            if (true == nteHTTP.isCurrent(this)) {       // check the timestamp
              if (ADV_HOST_INACCESSIBLE != nteHTTP.getLoadValue()) {  // is HTTP 
                                                                      // working?
                iLoad = iLoadSSL; 
              } else {   // HTTP server is not working, so mark SSL down
                iLoad = ADV_HOST_INACCESSIBLE; 
              }
            } else {     // expired information from HTTP, so mark SSL down
              iLoad = ADV_HOST_INACCESSIBLE; 
            }
          } else {       // no load information about HTTP, report 
                         // getLoadSSL() results
            iLoad = iLoadSSL;
          }
        }
     
      //--------
      // error handler
     
        else { 
          iLoad = ADV_HOST_INACCESSIBLE;
        }
        return iLoad;
      }
    }
     
    

    WebSphere Application Server advisor

    WebSphere Application Server のサンプル・カスタム advisor は、install_path/servers/samples/CustomAdvisors/ ディレクトリーに入っています。 完全なコードはこの資料では掲載していません。

    完全な advisor はサンプルよりわずかに複雑です。上記の StringTokenizer の例よりコンパクトな特殊化された構文解析ルーチンを追加します。

    サンプル・コードのより複雑な部分は Java サーブレットにあります。 このサーブレットには、他のメソッドとともに、サーブレット仕様が必要とする init() および service() という 2 つのメソッドと、Java.lang.thread クラスが必要とする run() という 1 つのメソッドが入っています。

    サーブレット・コードの関連フラグメントは、以下のようになります。

    ...
     
      public void init(ServletConfig config) throws ServletException {
        super.init(config);
        ...
        _checker = new Thread(this);
        _checker.start();
      }
     
      public void run() {
        setStatus(GOOD);
     
        while (true) {
          if (!getKeepRunning()) 
            return;
          setStatus(figureLoad());
          setLastUpdate(new java.util.Date());
     
          try {
            _checker.sleep(_interval * 1000);
          } catch (Exception ignore) { ; }
        }
      }
     
      public void service(HttpServletRequest req, HttpServletResponse res)
                          throws ServletException, IOException {
     
        ServletOutputStream out = null;
        try {
          out = res.getOutputStream();
        } catch (Exception e) { ... }
        ...
        res.setContentType("text/x-application-LBAdvisor");
        out.println(getStatusString());
        out.println(getLastUpdate().toString());
        out.flush();
            return;
      }
     
      ...
    

    advisor から戻されるデータの使用

    アプリケーション・サーバーの既存パーツに対する標準呼び出しを使用したり、 またはカスタム advisor のサーバー側で相対するコードの新規部分を追加して、 戻されたロード値を調べてサーバー動作を変更することができます。 Java StringTokenizer クラスおよびその関連メソッドは、この調査を実行しやすくします。

    通常の HTTP コマンドのコンテンツは GET /index.html HTTP/1.0 です。

    このコマンドに対する通常の応答は、以下のようになります。

    HTTP/1.1 200 OK
    Date: Mon, 20 November 2000 14:09:57 GMT
    Server: Apache/1.3.12 (Linux and UNIX)
    Content-Location: index.html.en
    Vary: negotiate
    TCN: choice
    Last-Modified: Fri, 20 Oct 2000 15:58:35 GMT
    ETag: "14f3e5-1a8-39f06bab;39f06a02"
    Accept-Ranges: bytes
    Content-Length: 424
    Connection: close
    Content-Type: text/html
    Content-Language: en
     
    <!DOCTYPE HTML PUBLIC "-//w3c//DTD HTML 3.2 Final//EN">
    <HTML><HEAD><TITLE>Test Page</TITLE></HEAD>
    <BODY><H1>Apache server</H1>
    <HR>
    <P><P>This Web server is running Apache 1.3.12.
    <P><HR>
    <P><IMG SRC="apache_pb.gif" ALT="">
    </BODY></HTML>
     
    

    関心のある項目 (特に HTTP 戻りコード) は先頭行に入っています。

    HTTP 仕様は戻りコードを分類し、以下のように要約できます。

    サーバーが戻す可能性のあるコードが正確に分かる場合は、コードをこの例ほど詳細にする必要はありません。ただし、検出する戻りコードを制限すると、プログラムの将来の柔軟性を制限することになる場合があります。

    以下の例は、最小限の HTTP クライアントが入っているスタンドアロン Java プログラムです。 この例は HTTP 応答を調べるための単純な汎用パーサーを起動します。

    import java.io.*;
    import java.util.*;
    import java.net.*;
     
    public class ParseTest {
      static final int iPort = 80;
      static final String sServer = "www.ibm.com";
      static final String sQuery = "GET /index.html HTTP/1.0¥r¥n¥r¥n";
      static final String sHTTP10 = "HTTP/1.0";
      static final String sHTTP11 = "HTTP/1.1";
     
      public static void main(String[] Arg) {
        String sHTTPVersion = null;
        String sHTTPReturnCode = null;
        String sResponse = null;
        int iRc = 0;
        BufferedReader brIn = null;
        PrintWriter psOut = null;
        Socket soServer= null;
        StringBuffer sbText = new StringBuffer(40);
     
        try {
          soServer = new Socket(sServer, iPort);
          brIn = new BufferedReader(new InputStreamReader(
                                        soServer.getInputStream()));
          psOut = new PrintWriter(soServer.getOutputStream());
          psOut.println(sQuery);
          psOut.flush();
          sResponse = brIn.readLine();
          try {
            soServer.close();
          } catch (Exception sc) {;}
        }  catch (Exception swr) {;}
     
        StringTokenizer st = new StringTokenizer(sResponse, " ");
        if (true == st.hasMoreTokens()) {
          sHTTPVersion = st.nextToken();
          if (sHTTPVersion.equals(sHTTP110) || sHTTPVersion.equals(sHTTP11)) {
            System.out.println("HTTP Version: " + sHTTPVersion);
          } else {
            System.out.println("Invalid HTTP Version: " + sHTTPVersion);
          }
        } else {
          System.out.println("Nothing was returned");
          return;
        }
     
        if (true == st.hasMoreTokens()) {
          sHTTPReturnCode = st.nextToken();
          try {
            iRc = Integer.parseInt(sHTTPReturnCode);
          } catch (NumberFormatException ne) {;}
     
          switch (iRc) {
          case(200): 
            System.out.println("HTTP Response code: OK, " + iRc);
            break;
          case(400): case(401): case(402): case(403): case(404): 
            System.out.println("HTTP Response code: Client Error, " + iRc);
            break; 
          case(500): case(501): case(502): case(503):
            System.out.println("HTTP Response code: Server Error, " + iRc);
            break;
          default: 
            System.out.println("HTTP Response code: Unknown, " + iRc);
            break;
          }
        }
     
        if (true == st.hasMoreTokens()) {
          while (true == st.hasMoreTokens()) {
            sbText.append(st.nextToken());
            sbText.append("  ");
            }
          System.out.println("HTTP Response phrase: " + sbText.toString());
        }
      }
    }
     
    

    索引

    A C E G H I L M N O P R S T U V W
    A C E G H I L M N O P R S T U V W