Forum und email

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

導入

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

SAM 拡張モジュールは、さまざまなメッセージングミドルウェアシステムにアクセスするための手段として 非常にシンプルな API を提供するフレームワークです。 現在このパッケージに標準で組み込まれているのは、 MQTT (MQ Telemetry Transport) メッセージングプロトコルのサポート および IBM Messaging and Queuing ミドルウェア製品群のサポートです。 SAM は、その他のメッセージングシステムをサポートするために拡張できるよう設計されています。 この拡張モジュールは、C あるいは PHP で書くことができます。

インストール手順

SAM フレームワークおよび MQTT サポートをビルドして使用するためには、 特にその他の前提条件はありません。 MQTT 以外のプロトコルのサポートはライブラリとして提供されており、 クライアント側のコードの中にはは XMS を使用するものもあります。

組み込みの MQTT サポートを使用したいだけである場合は、 SAM を拡張モジュールとしてビルドして設定するか、 あるいは単に "php_sam.php" を PHP スクリプトから "requires" あるいは "requires_once" で読み込みます。この場合は、 コードをインストールするだけでよく、拡張モジュールをビルドする必要はありません。 これを行うには、pear インストーラで次のように指定します。

       
      pecl install -B SAM

前提条件

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
XMS サポートを使用して IBM Messaging and Queuing family にアクセスしたい場合は、 SAM XMS 拡張モジュールも有効にしなければなりません。
       
extension=sam_xms.so

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

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

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

Windows でのインストール手順

SAM のウェブサイトにあるビルド済みバイナリは、非常に限られた範囲のものになっています。 そのため、おそらく自分でビルドすることになるでしょう。この拡張モジュールのビルド手順は、 Windows 上での標準的な拡張モジュールビルド手順と同じです。

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

また、PHP 拡張モジュールが使用するライブラリやヘッダを https://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 コマンドに適切なオプションをつけて実行します。 SAM 拡張モジュールフレームワークと MQTT サポートだけをビルドするのなら

       
cscript /nologo configure.js --with-sam
SAM フレームワークおよび XMS サポートをビルドするのなら
       
cscript /nologo configure.js --with-sam --with-sam_xms="c:\program files\ibm\xms"

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

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

すべてがうまくいけば、あとは SAM フレームワーク用の make を実行するだけです!

       
nmake php_sam.dll
また、もし XML サポートを使用するのなら、sam_xms 拡張モジュールも make しなければなりません。
       
nmake php_sam_xms.dll

Visual Studio 2005 を使用して DLL をビルドする場合は、 これ以降に進む前に次の追加手順を実行しなければなりません。

作成された DLL (php_sam.dll およびオプションで php_sam_xms.dll) を、PHP をセットアップしたディレクトリ以下の適切な場所にコピーします。 このモジュールを PHP に読み込ませるために、次の行を php.ini に追加しておきましょう。

       
extension=php_sam.dll
XMS サポートを使用して IBM Messgaing and Queuing family にアクセスしたい場合は SAM XMS 拡張モジュールも有効にする必要があります。
       
extension=php_sam_xms.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
XMS 機能を使用する場合は、同様に SAM XMS DLL も指定しなければなりません。
       
mt.exe -manifest php_sam_xms.dll.manifest -outputresource:php_sam_xms.dll;2

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

プロトコルサポートおよびマッピング

SAM フレームワークを拡張して、他のメッセージングプロトコルや通信機構をサポートさせることができます。 新しいプロトコルや接続ライブラリのサポートを追加するには、 それをサポートするクラスを定義する必要があります。これは C 拡張モジュールあるいは PHP スクリプトとして作成します。また、"ファクトリ" スクリプトも作成しなければなりません。 サポートクラスは、SAMConnection クラスの全メソッドを実装する必要があります。 SAMConnection を継承してはいけません。ファクトリスクリプトはフレームワークからコールされ、 実装クラスのインスタンスを作成します。SAM がどのファクトリをコールするのかは、 "connect" の最初のパラメータで指定したプロトコルによって決まります。

デフォルトでは、connect でプロトコルに SAM_MQTT ("mqtt") を指定した場合に 組み込みの MQTT サポートを使用します。その他のプロトコルを指定した場合は XMS 拡張モジュールを使用します。 新たなプロトコルのサポートを追加したりデフォルトの挙動を変更したりするには、 php.ini の [sam] セクションにエントリを追加します。 デフォルトのマッピングは、以下のエントリと同等です。

       
[sam]
sam.factory.mqtt=mqtt
sam.factory.wmq=xms
sam.factory.wmq:client=xms
sam.factory.wmq:bindings=xms
sam.factory.wpm=xms
sam.factory.rtt=xms
これらの例でわかるように、エントリは "sam.factory.pppp=xxx" という形式になります。pppp の部分が connect コール時に指定するプロトコル文字列で、 xxx はファクトリ名のサフィックスです。 注意: SAM では、これらのプロトコルに対応する定数を定義しています。たとえば SAM_WMQ=wmq、SAM_WPM=wpm、SAM_RTT=rtt、SAM_MQTT=mqtt などとなります。

connect コールの際にこれを指定すると、 SAM はそのプロトコル名を php.ini のエントリから探し、対応するファクトリスクリプト sam_factory_xxx.php をコールします。 エントリが見つからなかった場合は、デフォルトは XMS となります。

API の使用法

接続

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

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

Example#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));
?>

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

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

Example#3 接続の作成、および MQTT サーバへの接続

<?php
   $conn 
= new SAMConnection();
   
$conn->connect(SAM_MQTT, array(SAM_HOST => 'myhost.mycompany.com',
                                 
SAM_PORT => 1883));
?>

メッセージ

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

Example#4 単純なテキストのメッセージの作成

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

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

Example#5 デフォルト構文による、テキスト形式のプロパティの設定

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

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

Example#6 型ヒントを使用したプロパティの設定

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

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

Example#7 メッセージのヘッダからのプロパティの取得

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

メッセージング操作

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

Example#8 キューへのメッセージの追加および応答の取得

<?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" メソッドを使用して購読を削除します。

Example#9 トピックに対する永続的な購読の作成

<?php

      $subName 
$conn->subscribe('topic://A');

      if (!
$subName) {
         echo 
"購読に失敗しました";
      } else {
         
# 購読に成功しました
         
...
      }
?>

Example#10 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 {
      
# 購読に成功しました
      
...
   }
?>

Example#11 永続的な購読による、配信されたデータの受信

<?php

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

?>

Example#12 トピックへの永続的な購読の削除

<?php

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

?>

エラー処理

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

Example#13 結果を返さないメソッドからのエラーの処理

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

Example#14 結果を返すメソッドからのエラーの処理

<?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 - キューにメッセージを送信したり、トピックの投稿したりするメソッドです。

  • setDebug - 追加のデバッグ出力をオンあるいはオフにするメソッドです。

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

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

プロパティ

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

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

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_MQTT (string)
MQTT (MQ Telemetry Transport) プロトコルを使用するための 接続プロトコル定義です。
SAM_MQTT_CLEANSTART (bool)
任意で指定する接続オプションで、MQTT サーバに対して このクライアントに関する事前のすべての接続データの削除を指示します。 また、クライアントとの接続が明示的に解除されたり 予期せず解除されたりしたら、購読を削除するよう指示します。
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 メッセージングサーバと通信します。

目次