PHP マニュアル
前のページ |  | 次のページ

# CXXXVIII. SAM - Simple Asynchronous Messaging: 単純な非同期メッセージング

# 導入

この拡張モジュールを使用すると、IBM WebSphere MQSeries 製品群のようなメッセージングシステム・キューイングシステムに PHP スクリプトからアクセスできるようになります。このインターフェイスは、 一般的な操作 (単純なテキストメッセージをキューに配送するなど) については限りなくシンプルに実行できるように設計されています。 また、熟練者向けには、より複雑な操作もできるようになっています。 大半のユーザが使用する場合には、複雑で膨大な設定オプションは無視することができます。

# インストール手順

## 前提条件

SAM 拡張モジュールは、IBM Messaging and Queuing ミドルウェア製品とのインターフェイスとして XMS のライブラリおよびクライアント側のコードを使用します。 このパッケージは、IBM support pack IA94 としてフリーでダウンロードできます。 このパッケージについての説明、そしてダウンロード用のリンクは Introducing XMS - The IBM Message Service API にあります。

SAM を使用して WebSphere MQ のメッセージングおよびキューイング機能にアクセスしたい場合は、 ローカル MQ キューマネージャあるいは WebSphere MQ クライアントパッケージをインストールする必要があります。 クライアントパッケージは、サポートパック (MQC6) としてフリーで公開されています。

単に、WebSphere Application Server のキューに対して WebSphere Platform Messaging protocol (WPM) を使用したメッセージの送受信を行いたいだけなら、MQC6 パッケージをインストールする必要はありません。

これらのパッケージをインストールしたら、次に XMS のバイナリや (もし使用するなら) MQ クライアントの bin ディレクトリが PATH 環境変数に含まれていることを確認しましょう。これにより、 Apache や PHP から関連する DLL/ライブラリ を見つけられるようになります。

## Linux でのインストール手順

SAM 拡張モジュールは PECL モジュールとして提供され、 次の手順でダウンロード、インストールすることができます。

    pear install sam

(php の環境にもよりますが、おそらく root になる必要があるでしょう)

このモジュールを PHP に読み込ませるために、 `php.ini` に

    extension=sam.so

を追加します。

PEAR インストーラを使用できない場合は、 拡張モジュールをダウンロードして手動でビルドします。

    pear download sam          # sam-<version>.tgz をダウンロードします
    tar -xzf sam-<version>.tgz
    cd sam-<version>
    phpize
    ./configure
    make
    make install               # おそらく root になる必要があるでしょう

最新のソースを使用したい場合は、cvs からソースを取得して、 上の手順で手動ビルドします。

## Windows でのインストール手順

ビルド済みのバイナリは現在公開されていないため、 自分でビルドする必要があります。この拡張モジュールのビルド手順は、 Windows 上での標準的な拡張モジュールビルド手順と同じです。

SAM 拡張モジュールを使用する予定の PHP と同じバージョンの、 PHP 自身のソースツリーが必要となります。これは php.net から取得します。 取得したソースを、どこかの作業ディレクトリに展開します。

また、PHP 拡張モジュールが使用するライブラリやヘッダを http://www.php.net/extra/win32build.zip から取得し、 作業ディレクトリの下に展開します。

するとこのような状態になります。

    c:\php-build\-
                  |
                  |---php-5.0.5--|---build
                  |              |---ext
                  |              |--- ...
                  |
                  |---win32build--|---bin
                                  |---include
                                  |---lib

コンパイラが必要です。たとえば、フリーの Visual Studio C++ Express が Microsoft のウェブサイトから取得可能です。 また、Microsoft Windows Platform SDK も必要となります。 これも Microsoft のウェブサイトからダウンロードできます。

SAM 拡張モジュールのソースを、pear を使用して (pear download sam) あるいは CVS から取得し、それを PHP ソースツリーの "ext" ディレクトリ内に作成した "sam" ディレクトリに配置します。

この拡張モジュールをビルドするには、ビルド環境を次の場所から開きます。 start menu->all programs->microsoft platform SDK for windows-> open build environment window->windows 200 build environment-> set windows 2000 build environment (retail)

これは、コマンドプロンプトを開き、プラットフォーム SDK などを使用するためのすべての環境変数を設定します。 次に、Visual Studio 用の環境変数を設定するために、このウィンドウでコマンド "vcvars32.bat" を実行します。

cd c:\php-build などとして、作業ディレクトリに移動します。 そして win32build ツール群にアクセスできるよう、そのパスを環境変数 PATH に追加します。

    set PATH=..\win32build\bin;%PATH%

buildconf.bat コマンドを実行します。これは configure.js ファイルを作成します。

cscript コマンドを実行します。

    cscript /nologo configure.js --with-sam="c:\program files\ibm\xms"

sam に渡している追加のパラメータは、XMS ライブラリやランタイムへのパスです。 これらは、このファイルの最初に書いてある前提条件によってインストールされているものです。

cscript のパラメータとして、php のビルドオプションのうちお好みのものを追加したり削除することもできます。

すべてがうまくいけば、あとは make を実行するだけです!

    nmake php_sam.dll

## Visual Studio 2005 用の追加手順

SAM 拡張モジュールを Microsoft Visual Studio 2005 のコンパイラでビルドしたい場合は、 さらに追加の手順が必要です。これにより、php_sam.dll が実行時に C ランタイムライブラリとリンクできるようにします。 この追加手順では、依存性マニフェストを DLL に組み込みます。 php_sam.dll が作成されたディレクトリ (通常は、php ソースディレクトリ配下の Release_TS あるいは Debug_TS) に移動し、次のように謎の呪文をとなえます。

    mt.exe -manifest php_sam.dll.manifest -outputresource:php_sam.dll;2

SAM 拡張モジュールを Microsoft Visual Studio 2005 のコンパイラやライブラリでビルドした場合は、 ランタイムコンポーネントが SAM を使用する予定のシステムにインストールされている必要があります。 そのためには、そこに Visual Studio 2005 をインストールするか、あるいはフリーで配布されている ランタイムパッケージ を使用します。

# API の使用法

## 接続

メッセージングやキューイングの関数を実行するには、 メッセージングサーバとの接続が確立されていなければなりません。そのためには、 SAMConnection オブジェクトを作成してその "connect" メソッドを実行します。 その際に、接続用のプロパティを指定します。SAMConnection オブジェクトが破棄されるまでの間は、接続が使用可能となります。 SAMConnection オブジェクトは、PHP スクリプトが終了する際に破棄されます。

メッセージングサーバに接続する際にはデフォルトのプロパティを使用することもできますが、 最低限、使用するプロトコルだけは PHP スクリプトで指定しなければなりません。

例 1. 接続の作成、およびリモートの WebSphere MQSeries Messaging Server への接続

`<?php $conn = new SAMConnection(); $conn->connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com, SAM_PORT => 1506, SAM_BROKER => mybroker)); ?>`

例 2. 接続の作成、およびリモートの WebSphere Application Server への接続

`<?php $conn = new SAMConnection(); $conn->connect(SAM_WMQ, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging', SAM_BUS => 'Bus1', SAM_TARGETCHAIN => 'InboundBasicMessaging')); ?>`

## メッセージ

キューとのメッセージの送受信を行うのが SAMMessage オブジェクトです。 SAMMessage オブジェクトは、メッセージ本文 (もしあれば) とそのメッセージに関連するヘッダプロパティをカプセル化します。 SAMMessage オブジェクトは、メッセージング操作の際のパラメータ、 そしてその返り値の両方に用いられます。

例 3. 単純なテキストのメッセージの作成

`<?php $msg = new SAMMessage('This is a simple text message'); ?>`

メッセージにはヘッダプロパティを関連付けることができます。 これは、メッセージの配送方法を制御したり、 受け取り側のアプリケーションに詳しい情報を提供したりするものです。 デフォルトでは、メッセージのプロパティは文字列として配送されます。 この場合は、プロパティを設定する際に次のような簡単な構文を使用します。

例 4. デフォルト構文による、テキスト形式のプロパティの設定

`<?php $msg->header->myPropertyName = 'textData'; ?>`

デフォルト以外の構文で使用する型情報を渡す場合は、値と型情報を連想配列で渡します。

例 5. 型ヒントを使用したプロパティの設定

`<?php $msg->header->myPropertyName = array(3.14159, SAM_FLOAT); ?>`

プロパティは、メッセージのヘッダから取り出すことができます。

例 6. メッセージのヘッダからのプロパティの取得

`<?php $myProperty = $msg->header->myPropertyName; ?>`

## メッセージング操作

すべてのメッセージング操作は、接続オブジェクトのメソッドをコールすることで行います。 キューにメッセージを追加するには "send" メソッドを使用し、 キューからメッセージを取得するには "receive" メソッドを使用します。 その他のメソッドには、配信や購読機能、 そしてトランザクションの境界の制御などがあります。

例 7. キューへのメッセージの追加および応答の取得

`<?php $msg = new SAMMessage('This is a simple text message'); $msg->header->SAM_REPLY_TO = 'queue://receive/test'; $correlid = $conn->send('queue://send/test', $msg); if (!$correlid) { // 送信に失敗しました! echo "Send failed ($conn->errno) $conn->error"; } else { $resp = $conn->receive('queue://receive/test', array(SAM_CORRELID => $correlid)); } ?>`

## 配信/購読およびトピックの購読

SAM では、メッセージをキューに送信するか、あるいは WebSphere MQ および WPM ではトピックに配信/購読することができます。 トピックを SAM に指定するには、場所を指定する際に 'queue://AQUEUE' ではなく 'topic://fred' 形式を使用します。 配信/購読 機能を使用するには、正しいブローカ名を CAMConnect の "connect" コール時に指定し、対象のトピックを SAMConnect の "send" および "receive" コール時に指定する必要があります。 それ以外については、PHP のインターフェイスは point to point モデルと同じです。

デフォルトでは、SAM は永続的でない購読を作成して配信/購読を行います。 つまり、メッセージをトピックに配信しているときにクライアントアプリケーションがアクティブでなくなると、 その後アプリケーションが再開しても受信処理は行われないということです。 WPM あるいは WebSphere MQ の配信/購読 を使用している場合は、 SAM でトピックへの永続的な購読を作成することができます。 こうすると、データの配信時にクライアントがアクティブでなかったとしても、 アプリケーションでデータを受信することができるようになります。

永続的な購読を指定するには SAMConnect の "subscribe" コールを使用します。 このメソッドは、対象となるトピックを入力パラメータとして受け取り、 購読 ID を返します。この ID を使用して、"receive" コールを行います。 購読が不要になった場合は、SAMConnection の "unsubscribe" メソッドを使用して購読を削除します。

例 8. トピックに対する永続的な購読の作成

`<?php $subName = $conn->subscribe('topic://A'); if (!$subName) { echo "購読に失敗しました"; } else { # 購読に成功しました ... } ?>`

例 9. WebSphere Platform Messaging (WPM) サーバを使用したトピックの購読

`<?php
$conn = new SAMConnection();
// 注意: WPM での配信/購読では、永続的な購読を保持するメッセージングエンジン
// (SAM_WPM_DUR_SUB_HOME) を接続の際に指定する必要があります
$conn->connect(SAM_WMQ, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging',
SAM_BUS => 'Bus1',
SAM_TARGETCHAIN => 'InboundBasicMessaging'
SAM_WPM_DUR_SUB_HOME => 'MyMachineNode01.server1-Bus1'));
$subName = $conn->subscribe('topic://A');
if (!$subName) {
echo "購読に失敗しました";
} else {
# 購読に成功しました
...
}
?>`

例 10. 永続的な購読による、配信されたデータの受信

`<?php $msg = $conn->receive($subName); if ($msg) { echo "メッセージの受信に成功しました"; } else { echo "受信に失敗しました"; } ?>`

例 11. トピックへの永続的な購読の削除

`<?php if (!$conn->unsubscribe($subName)) { echo "購読解除に失敗しました"; } ?>`

## エラー処理

SAMConnection のメソッドでメッセージング操作を行うものはすべて、 リクエスト処理中にエラーが発生すると `FALSE` を返します。 さらに SAMConnection オブジェクトはふたつのプロパティ "errno" および "error" を保持しています。これらはそれぞれ、 接続上でおこった最後のエラーのエラー番号およびエラー内容のテキストを表します。

例 12. 結果を返さないメソッドからのエラーの処理

`<?php if (!$conn->commit()) { // コミットに失敗しました! echo "Commit failed ($conn->errno) $conn->error"; } ?>`

例 13. 結果を返すメソッドからのエラーの処理

`<?php $correlid = $conn->send('queue://send/test', $msg); if (!$correlid) { // 送信に失敗しました! echo "Send failed ($conn->errno) $conn->error"; } else { ... } ?>`

# 定義済みクラス

## SAMConnection

メッセージングサーバとの接続を表すオブジェクトです。

### コンストラクタ

- new SAMConnection - 新しい接続オブジェクトを作成し、メッセージング環境への接続を可能にします。

### メソッド

- commit - 現在作業中の内容をコミット (正常に完了) するメソッドです。

- connect - PHP スクリプトをメッセージングサーバに接続させるメソッドです。

- disconnect - PHP スクリプトとメッセージングサーバとの接続を解除するメソッドです。

- isConnected - PHP スクリプトがメッセージングサーバと接続しているかどうかを調べるメソッドです。

- peek - メッセージをキューから取得し、それをキューに残したままにしておくメソッドです。

- peekAll - ひとつあるいは複数のメッセージをキューから取得し、それをキューに残したままにしておくメソッドです。

- receive - メッセージをキューあるいは購読から取得するメソッドです。

- remove - メッセージをキューから削除するメソッドです。

- rollback - 現在作業中の内容をキャンセル (ロールバック) するメソッドです。

- send - キューにメッセージを送信したり、トピックの投稿したりするメソッドです。

- subscribe - ひとつあるいは複数のトピックを購読するためのメソッドです。

- unsubscribe - ひとつあるいは複数のトピックの購読を解除するメソッドです。

### プロパティ

- errno - この接続で最後に発生したエラーのエラーコードを表す数値です。 直近の処理が正常に終了した場合は、このプロパティは 0 となります。

- error - この接続で最後に発生したエラーの説明テキストです。

## SAMMessage

送受信するメッセージを表すオブジェクトです。

### コンストラクタ

- new SAMMessage - 新しいメッセージを作成します。

### プロパティ

- body - メッセージの本文です。

- header - メッセージのヘッダプロパティです。

# 定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

`SAM_AUTO` (string)

  自動的に処理します。

`SAM_BOOLEAN` (string)

  型指定子。SAM_Message オブジェクトにプロパティを設定する際に使用します。

`SAM_BUS` (string)

  接続の属性で、接続するエンタープライズサービスバスの名前を設定します。

`SAM_BYTE` (string)

  型指定子。SAM_Message オブジェクトにプロパティを設定する際に使用します。

`SAM_BYTES` (string)

  メッセージ本文の型指定子。

`SAM_CORRELID` (string)

  リクエストを受信、送信および削除する際に使用する属性で、 特定のメッセージを指定します。

`SAM_DELIVERYMODE` (string)

  メッセージヘッダのプロパティです。

`SAM_DOUBLE` (string)

  型指定子。SAM_Message オブジェクトにプロパティを設定する際に使用します。

`SAM_ENDPOINTS` (string)

  接続の属性で、接続先エンドポイントを指定します。

`SAM_FLOAT` (string)

  型指定子。SAM_Message オブジェクトにプロパティを設定する際に使用します。

`SAM_HOST` (string)

  接続の属性で、メッセージングサーバのホスト名を設定します。

`SAM_INT` (string)

  型指定子。SAM_Message オブジェクトにプロパティを設定する際に使用します。

`SAM_LONG` (string)

  型指定子。SAM_Message オブジェクトにプロパティを設定する際に使用します。

`SAM_MANUAL` (string)

  手動で (スクリプトで制御して) 処理します。

`SAM_MESSAGEID` (string)

  リクエストを受信および削除する際に使用する属性で、 特定のメッセージを指定します。

`SAM_NON_PERSISTENT` (string)

  接続の属性で、リクエストメッセージをメッセージングサーバ上で 持続させないことを指定します。

`SAM_PASSWORD` (string)

  接続の属性で、接続時に認証が必要なメッセージングサーバに対する 接続パスワードを指定します。

`SAM_PERSISTENT` (string)

  接続の属性で、リクエストメッセージをメッセージングサーバ上で 持続させることを指定します。これにより、 処理に失敗した際にメッセージを失うことを防ぎます。

`SAM_PORT` (string)

  接続の属性で、メッセージングサーバと接続する際のポート番号を設定します。

`SAM_PRIORITY` (string)

  リクエストを配送する際の優先度を設定するオプション名です。

`SAM_REPLY_TO` (string)

  メッセージのプロパティで、 そのスクリプトが応答あるいは返信の配送先として想定しているキューを指定します。

`SAM_RTT` (string)

  接続プロトコルを指定します。IBM Realtime Transport プロトコルを使用してビジネスインテグレーションメッセージングサーバと通信します。

`SAM_STRING` (string)

  型指定子。SAM_Message オブジェクトにプロパティを設定する際に使用します。

`SAM_TARGETCHAIN` (string)

  接続の属性で、ターゲットチェイン識別子を指定します。

`SAM_TEXT` (string)

  メッセージ本文の型指定子。

`SAM_TIMETOLIVE` (string)

  メッセージ送信時のオプション名。 メッセージを保持し続ける時間をミリ秒で指定します。

`SAM_TRANSACTIONS` (string)

  接続の属性で、トランザクションの振る舞いを指定します。SAM_AUTO (デフォルト) あるいは SAM_MANUAL のいずれかです。

`SAM_USERID` (string)

  接続の属性で、接続時に認証が必要なメッセージングサーバに対する 接続アカウントを指定します。

`SAM_WAIT` (string)

  受信時のプロパティで、キューや購読からメッセージを取得する際のタイムアウトを指定します。

`SAM_WMQ` (string)

  接続プロトコルを指定します。IBM WebSphere MQSeries プロトコルを使用してメッセージングサーバと通信します。

`SAM_WMQ_BINDINGS` (string)

  接続プロトコルを指定します。IBM WebSphere MQSeries プロトコルを使用してローカルのメッセージングサーバと通信します。

`SAM_WMQ_CLIENT` (string)

  接続プロトコルを指定します。IBM WebSphere MQSeries プロトコルを使用してリモートのメッセージングサーバと通信します。

`SAM_WMQ_TARGET_CLIENT` (string)

  リクエストを送信する際に使用するオプション名です。 ターゲットクライアントモードを指定します。デフォルトの 'jms' あるいは 'mq' のいずれかを指定します。 デフォルトの 'jms' は、RFH2 ヘッダがメッセージとともに送信されることを意味します。 一方、'mq' の場合は RFH2 は含まれません。

`SAM_WPM` (string)

  接続プロトコルを指定します。IBM WebSphere Platform Messaging プロトコルを使用して WebSphere Application Server メッセージングサーバと通信します。

前のページ | ホーム | 次のページ
runkit_superglobals | 上に戻る | SAMConnection::commit()