19 HTTPクライアント・アクセス

この項では、Apache Commons HttpClientライブラリ、およびWebCenter Sitesとこのライブラリとの統合について説明します。

この章には次の項が含まれます:

• 第19.1項「Apache Commons HttpClient」

• 第19.2項「WebCenter Sitesとの統合」

• 第19.3項「HTTPClientのパラメータとWebCenter Sitesのプロパティ」

19.1 Apache Commons HttpClient

WebCenter Sitesでは、すべてのHTTPアクセスの基本ライブラリとしてApache Commons HttpClientが使用されます。HttpClientは、バージョン3以降では、http://jakarta.apache.org/commons/httpclient/preference-api.htmlに投稿されるパラメータをサポートします。

パラメータは次のように機能します。

• HttpClientパラメータは、HttpClientコンポーネントのランタイム動作を変更します。たとえば、Post操作でデフォルトとは異なるタイムアウトを設ける場合、その実行前にPostMethod.getParams().setParam("timeout", 1000)をコールできます。

• HttpClientパラメータは、階層形式でリンクできます。上から下の順序で、階層のレベルは、グローバル、クライアント、ホストおよびメソッドになります。上位レベルでパラメータに設定される値は、下位レベルの同等のパラメータの値によってオーバーライドされます。

HttpClientは、その柔軟性にもかかわらず、パラメータの設定がプログラムのみで行われるという制限があります。パラメータ値をユーザーが指定したり、自動的にライブラリから取得できる場合、構成ファイルを書き込むことはできません。ただし、WebCenter Sites統合では、次の項の第19.2項「WebCenter Sitesとの統合」で説明するようにこの制限がなくなっています。

注意: WebCenter Sitesでは、http://jakarta.apache.org/commons/httpclient/preference-api.htmlに投稿されるパラメータが使用されます。パラメータは、表19-1にリストされており、(前述のサイトから複製された)説明も記載されています。HttpClientで定義されているように、パラメータとその機能の変更は自動的にサポートされません。

19.2 WebCenter Sitesとの統合

WebCenter Sitesは、ユーザーが構成可能なプロパティ・ファイルの作成をWebCenter Sitesユーザーに許可することでHttpClient機能を抽象化します。ファイルの作成後、ユーザーは必要なHttpClientパラメータ(値がデフォルト値と異なるパラメータ)をそのファイルに移入し、プロパティ・ファイルをクラスパスに配置します。WebCenter Sitesは、クラスパスからプロパティ・ファイルをロードし、事前定義済の構文に従ってパラメータを解析します(表19-1を参照)。HttpAccess APIは、パラメータを取得して、それらをランタイムで適用します。

WebCenter Sitesは、レベルが、HttpAccess Java API (WebCenter Sites Java Docsで提供される)で定義されるレベルと直接対応するパラメータ階層をサポートします。レベルごとに、1つ以上のプロパティ・ファイルを実装に応じて作成でき、HttpClientパラメータの任意の組合せを移入できます。レベルとプロパティ・ファイルの命名規則を次に示します。

注意: プロパティ・ファイルは、WebCenter Sitesプロパティ・エディタの外部でテキスト・ファイルとして作成する必要があります。プロパティ・ファイルの名前は、大文字と小文字が区別されるため、すべて小文字にする必要があります。

• HttpAccess (レベル1)

  プロパティ・ファイル: httpaccess.properties。ユーザーは、パラメータとその値をhttpaccess.propertiesファイルで指定します。このファイルは、作成されるすべてのHttpAccessインスタンスに適用されます。

  オーバーライド: HttpAccessレベルのパラメータ値は、レベル2、3および4 (次の説明を参照)の同等のパラメータの値でオーバーライドされます。

• HostConfig (レベル2)

  プロパティ・ファイル: <プロトコル>-<ホスト名>-<ポート番号>.properties。ユーザーは、ホストに固有のパラメータを各プロパティ・ファイルで指定します。たとえば、ポート7001でアクセス可能なtargetserverというホストの場合、プロパティ・ファイルの名前はhttp-targetserver-7001.propertiesとなり、このファイルには、そのホストに固有のHttpClientパラメータが含まれます。

  オーバーライド: HostConfigレベルのパラメータ値は、HttpAccessレベルの同等のパラメータの値をオーバーライドします。

• リクエスト(レベル3)

  プロパティ・ファイル: <リクエスト・タイプ>.properties。ここで、<リクエスト・タイプ>は、post、getまたはloginのいずれかの値を取ります。ユーザーは、リクエストに固有のパラメータを指定します。たとえば、post.propertiesは、postのインスタンスに適用可能なHttpClientパラメータを指定します。

  オーバーライド: リクエスト・レベルのパラメータ値は、HttpAccessレベルおよびHostConfigレベルの同等のパラメータの値をオーバーライドします。

• ホスト別、リクエスト別(レベル4)

  プロパティ・ファイル: <リクエスト・タイプ>-<プロトコル>-<ホスト名>-<ポート番号>.properties。ここで、<リクエスト・タイプ>は、post、getまたはloginのいずれかの値を取ります。このプロパティ・ファイルのパラメータは、リクエスト・レベルのパラメータとして機能します。ただし、これらは特定のホストに適用されます。

  オーバーライド: 「ホスト別、リクエスト別」レベルで指定されたパラメータ値は、その特定のホストについて、HttpAccessレベル、HostConfigレベルおよびリクエスト・レベルの同等のパラメータの値をオーバーライドします。次の例では、オーバーライドが「ホスト別、リクエスト別」レベルからどのように有効になるかを示します。この例では、ユーザーはlogin-http-m2-7002.propertiesというプロパティ・ファイルを定義します。ここでは、http.connection.timeoutを100秒に指定します。タイムアウトは、m2というホスト・マシンとポート7002に厳密に適用されます。タイムアウト値は、上位レベルでm2に指定されるすべてのタイムアウト値をオーバーライドします。他のすべてのホスト・マシンの場合、タイムアウト値は影響を受けません。

WebCenter Sitesは、HttpClientによって定義されるすべてのパラメータを、外部から構成可能な方法でサポートします。さらに、WebCenter Sitesは、ユーザーが外部でパラメータを構成できるようにして、4番目のレベル(ホスト別、リクエスト別)でパラメータを指定しやすくすることでHttpClientの機能を拡張します。

HttpClientでサポートされるすべてのパラメータの他に、WebCenter SitesのHttpAccess APIでは、httpaccess.propertiesで構成プロパティcs.SecureProtocolSocketFactoryを定義します。このプロパティは、SSL (Secure Socket Layer)接続に使用されるプロトコル・ソケット・ファクトリを指定します。http://jakarta.apache.org/commons/httpclient/sslguide.htmlで3つの実装を入手できます。自己署名証明書を使用するホストにSSLで接続する場合、次の内容を構成する必要があることに注意してください。

cs.SecureProtocolSocketFactory=org.apache.commons.httpclient.  contrib.ssl.EasySSLProtocolSocketFactory

WebCenter Sitesでは、このEasySSLProtocolSocketFactoryクラスは用意されていません。このクラスはhttp://jakarta.apache.org/commons/httpclient/sslguide.htmlで取得できます。(すぐ上のリンクにある)Apache実装はSunに固有のため、SunおよびIBM JDKでは必ず異なる形式で構築してください。あるいは、HttpClientドキュメントに基づき、各自のソケット・ファクトリ実装を作成できます。

HttpAccess APIはパラメータを直接サポートしないため、パラメータを明示的に設定できないHttpClient階層には2つのレベル(接続マネージャと接続)があることに注意してください。ただし、これは、ユーザーがそれらのパラメータを構成できないということではありません。パラメータは、HttpAccess APIの対応する上位または下位レベルで指定できます。

19.2.1 実装

WebCenter Sitesユーザーは、どのような方法でWebCenter SitesのHTTPアクセスを構成するのでしょうか。ユーザーは、プロパティ・ファイルを適切な名前で作成し、それらをクラスパスに配置するのみです。インフラストラクチャでファイルを取得して使用します。これは、特にパラメータの数が指定される場合は作業量が多いように思われます。ただし、デフォルトでは、プロパティやプロパティ・ファイルを作成する必要はありません。すべてのデフォルトが使用され、HttpClientによって最適な推測値が取得されます。通常はこれが指定のシステムに対する最適な設定となります。95%は最適な推測値で十分であり、ユーザーはプロパティ・ファイルを作成する必要はありません。

稀にデフォルト以外のパラメータ値が必要な場合、WebCenter Sitesインフラストラクチャでは、ユーザーにプロパティ・ファイルでの構成の指定を許可することで、値を実装できるようにします。これにより、HttpClient自体が構築基盤である構成機能一式がユーザーに提供されます。

19.3 HTTPClientのパラメータとWebCenter Sitesのプロパティ

この項の表では、Apache Commons HttpClientでサポートされるパラメータについて説明します。表の説明は、次のサイトから複製されたものです。

http://jakarta.apache.org/commons/httpclient/preference-api.html

構文とデフォルト値は、WebCenter Sitesに固有であるため、Oracleで定義されています。構文はわかりやすく、次の表の「構文」フィールドは空白のままになっています。

パラメータとその機能の変更は自動でサポートされないことに注意してください。次の表の情報は、Oracleで更新が発行されるまで有効です。

HttpClientパラメータのサポートに加えて、WebCenter Sitesでは次のプロパティを定義します。

プロパティ: cs.SecureProtocolSocketFactory

使用: httpaccess.propertiesファイルにのみ適用可能

説明: 開いているSSL Socket接続を使用したクラスを定義

デフォルト: 空。HttpClientのJSSEベースのデフォルト実装が使用されます。詳細はhttp://jakarta.apache.org/commons/httpclient/sslguide.htmlを参照してください。

表19-1 HttpClientのパラメータ

名前	説明
http.authentication.preemptive	認証を先制して試行するかどうかを定義します。 タイプ: ブール デフォルト値: <未定義>
http.connection.stalecheck	失効した接続のチェックを使用するかどうかを決定します。失効した接続のチェックを無効にすると、サーバー側で閉じられた接続でリクエストを実行する際に、I/Oエラーは取得されますが、パフォーマンスはわずかに向上します。 タイプ: ブール デフォルト値: <未定義>
http.connection.timeout	接続が確立されるまでのタイムアウト。値が0の場合、タイムアウトは使用されません。 タイプ: 整数 デフォルト値: <未定義>
http.connection-manager.class	デフォルトのHTTP接続マネージャ・クラス。 タイプ: クラス 構文: 完全修飾クラス名 デフォルト値: SimpleHttpConnectionManagerクラス
http.connection-manager.max-per-host	ホスト構成ごとに許可される最大接続数を定義します。これらの値は、HttpConnectionManagerの特定のインスタンスからの接続数にのみ適用されます。このパラメータは、タイプMapの値を予測します。値は、HostConfigurationのインスタンスをIntegerにマップする必要があります。デフォルト値は、ANY_HOST_CONFIGURATIONを使用して指定できます。 タイプ: マップ 構文: ${<ホスト>;<ポート>;<プロトコル>; <最大接続数>}を指定 デフォルト値: <未定義>
http.connection-manager.max-total	全体に許可される最大接続数を定義します。この値は、HttpConnectionManagerの特定のインスタンスからの接続数にのみ適用されます。 タイプ: 整数 デフォルト値: <未定義>
http.connection-manager.timeout	HTTP接続マネージャからHTTP接続を取得する際に使用されるタイムアウト(ミリ秒単位)。 タイプ: ロング デフォルト値: <未定義>
http.dateparser.patterns	解析に使用される日付パターン。パターンは、コレクションに格納され、SimpleDateFormatと互換する必要があります。 タイプ: コレクション 構文: 各要素が${<要素>}で囲まれたコレクションを指定します。たとえば、${EEE, dd-MMM-yyyy HH-mm- ss z}${EEE, dd MMM yy HH:mm:ss z}のようになります。 デフォルト値: EEE, dd MMM yyyy HH:mm:ss zzzEEEE, dd-MMM-yy HH:mm:ss zzzEEE MMM d HH:mm:ss yyyyEEE, dd-MMM-yyyy HH:mm:ss zEEE, dd-MMM-yyyy HH-mm-ss zEEE, dd MMM yy HH:mm:ss zEEE dd-MMM-yyyy H:mm:ss zEEE dd MMM yyyy HH:mm:ss zEEE dd-MMM-yyyy HH-mm-ss zEEE dd-MMM-yy HH:mm:ss zEEE dd MMM yy HH:mm:ss zEEE,dd-MMM-yy HH:mm:ss zEEE,dd-MMM-yyyy HH:mm:ss zEEE, dd-MM-yyyy HH:mm:ss z
http.default-headers	各リクエストでデフォルトによって送信されるリクエスト・ヘッダー。このパラメータは、コレクション・タイプの値を予測します。コレクションは、HTTPヘッダーを含むことが予想されます。 タイプ: コレクション 構文: ${name=<ヘッダー名>; value=<ヘッダー値>}で各ヘッダーを指定 デフォルト値: <未定義>
http.method.multipart.boundary	MultipartRequestEntityと一緒に使用するマルチパート境界文字列。このプロパティを設定しない場合、リクエストごとにランダム値が生成されます。 タイプ: 文字列 構文: デフォルト値: <未定義>
http.method.response.buffer.warnlimit	警告をトリガしないバッファ済レスポンスの最大サイズ(バイト単位)。バッファ済レスポンスがこのサイズを超えると、警告がログにトリガされます。設定しない場合、制限は1MBになります。 タイプ: 整数 デフォルト値: 1
http.method.retry-handler	失敗したメソッドの再試行に使用されるメソッド再試行ハンドラ。詳細は、例外処理ガイドを参照してください。 タイプ: HttpMethodRetryHandler 構文: 完全修飾クラス名 デフォルト値: デフォルトの実装
http.protocol.allow-circular-redirects	循環リダイレクト(同じ場所へのリダイレクト)を許可するかどうかを定義します。HTTP仕様では、循環リダイレクトを許可するかどうかが十分に明確ではないため、オプションで循環リダイレクトを有効にできます。 タイプ: ブール デフォルト値: <未定義>
http.protocol.content-charset	コンテンツ本文のエンコードに使用される文字セット。 タイプ: 文字列 デフォルト値: ISO-8859-1
http.protocol.cookie-policy	Cookie管理に使用されるCookieポリシー。 タイプ: 文字列 デフォルト値: CookiePolicy.RFC_2109
http.protocol.credential-charset	資格証明のエンコードで使用される文字セット。定義しない場合、"http.protocol.element-charset"の値を使用する必要があります。 タイプ: 文字列 デフォルト値: <未定義>
http.protocol.element-charset	HTTPプロトコル要素(ステータス行およびヘッダー)のエンコードおよびデコードに使用される文字セット。 タイプ: 文字列 デフォルト値: US-ASCII
http.protocol.expect-continue	エンティティを包含するメソッドの「Expect: 100-Continue」ハンドシェイクを有効にします。「Expect: 100-Continue」ハンドシェイクにより、リクエスト本文を含むリクエスト・メッセージを送信するクライアントは、リクエスト本文を送信する前に、(リクエスト・ヘッダーに基づき)元のサーバーがリクエストを受け入れるかどうかを判断できます。 「Expect: 100-continue」ハンドシェイクを使用すると、ターゲット・サーバーの認証を必要とするエンティティ包含リクエスト(POSTやPUTなど)のパフォーマンスが大幅に改善されます。「Expect: 100-continue」ハンドシェイクでは、HTTP/1.1プロトコルをサポートしないHTTPサーバーとプロキシに関する問題が生じることがあるため、注意して使用してください。 タイプ: ブール デフォルト値: <未定義>
http.protocol.head-body-timeout	非準拠サーバーからのHEADレスポンスに応答して送信されるコンテンツ本文の待機時間をミリ秒単位で設定します。パラメータを設定しないか、-1に設定する場合、非準拠レスポンス本文のチェックが無効になります。 タイプ: 整数 デフォルト値: <未定義>
http.protocol.max-redirects	追跡するリダイレクトの最大数を定義します。リダイレクトの数を制限する目的は、無限ループを防止することです。 タイプ: 整数 デフォルト値: <未定義>
http.protocol.reject-head-body	HEADリクエストに応答して送信されるコンテンツ本文を拒否するかどうかを定義します。 タイプ: ブール デフォルト値: <未定義>
http.protocol.reject-relative-redirect	相対リダイレクトを拒否するかどうかを定義します。 タイプ: ブール デフォルト値: <未定義>
http.protocol.single-cookie-header	Cookieを単一のレスポンス・ヘッダーに置くかどうかを定義します。 タイプ: ブール デフォルト値: <未定義>
http.protocol.status-line-garbage-limit	HTTPレスポンスのステータス・コードを予測する前に、無視できる行の最大数を定義します。 HTTP/1.1永続接続の場合、破損したスクリプトが不正なContent-Length (送信されたバイト数が指定の数よりも多い)を返すという問題が生じます。場合によっては、不正なレスポンスの後ではなく、次のレスポンスの前に生じることがあります。そのため、HttpClientは、このように余分な行をスキップできるようになっています。ステータス行の前のガベージおよび空の行を拒否するには、これを0に設定します。無制限を指定するには、Integer.MAX_VALUEを使用します。 タイプ: 整数 デフォルト値: <未定義>
http.protocol.strict-transfer-encoding	無効なTransfer-Encodingヘッダーを含むレスポンスを拒否するかどうかを定義します。 タイプ: ブール デフォルト値: <未定義>
http.protocol.unambiguous-statusline	HTTPメソッドで曖昧なHTTPステータス行を拒否するかどうかを定義します。 タイプ: ブール デフォルト値: <未定義>
http.protocol.version	HTTPメソッドによってデフォルトで使用されるHTTPプロトコル・バージョン。 タイプ: HttpVersion 構文: <(整数)メジャー>.<(整数)マイナー>、1.1など デフォルト値: HttpVersion_1_1
http.protocol.warn-extra-input	予想(Content-Lengthヘッダーで指定される数など)よりも多いバイト数がレスポンスで提供される場合のHttpClientの動作を定義します。このような余分なデータによって、キープ・アライブ・リクエストに対するHTTP接続の信頼性が低くなるため、悪質なレスポンス・データ(偽造ヘッダーなど)が原因で、その接続を使用する次のリクエストに対して不適切な結果が生じる可能性があります。このパラメータをtrueに設定する場合、余分な入力データを検出すると、ログに警告が生成されます。 タイプ: ブール デフォルト値: <未定義>
http.socket.linger	秒単位の遅延時間(SO_LINGER)。このオプションは、TCPソケットのclose()からの即時戻りを無効および有効にします。ゼロ以外の整数のタイムアウトでこのオプションを有効にすると、ピアに書き込まれたすべてのデータの送信と確認の保留がブロックされます。この時点で、ソケットは正常に終了します。値が0の場合、オプションは無効になります。値が-1の場合、JREのデフォルトが使用されます。 タイプ: 整数 デフォルト値: <未定義>
http.socket.receivebuffer	Socket.setReceiveBufferSize(int)で設定する値。この値は、ソケットで受信されるデータに使用するバッファのサイズに関する、アプリケーションからカーネルへの提案になります。 タイプ: 整数 デフォルト値: <未定義>
http.socket.sendbuffer	Socket.setSendBufferSize(int)で設定する値。この値は、ソケットで送信されるデータに使用するバッファのサイズに関する、アプリケーションからカーネルへの提案になります。 タイプ: 整数 デフォルト値: <未定義>
http.socket.timeout	メソッドの実行時に使用されるソケットのタイムアウト(SO_TIMEOUT)をミリ秒単位で設定します。タイムアウト値がゼロの場合、無限タイムアウトとみなされます。 タイプ: 整数 デフォルト値: <未定義>
http.socket.timeout	データを待機するタイムアウトになるデフォルトのソケット・タイムアウト(SO_TIMEOUT)(ミリ秒単位)。タイムアウト値がゼロの場合、無限タイムアウトとみなされます。この値は、ソケット・タイムアウトをHTTPメソッド・パラメータで設定しない場合に使用されます。 タイプ: 整数 デフォルト値: <未定義>
http.tcp.nodelay	Nagleのアルゴリズムを使用するかどうかを決定します。Nagleのアルゴリズムは、送信されるセグメントの数を最小限に抑えて帯域幅の節約を試みます。アプリケーションでネットワーク待機時間を減らしてパフォーマンスを改善する必要がある場合、(TCP_NODELAYを有効にすることで)Nagleのアルゴリズムを無効にできます。帯域幅の消費は増加しますが、データの送信速度は上がります。 タイプ: ブール デフォルト値: <未定義>
http.useragent	HTTPメソッドで使用されるUser-Agentヘッダーのコンテンツ。 タイプ: 文字列 デフォルト値: <公式のリリース名>、Jakarta Commons-HttpClient/3.0など