SAMMessage::header

(PECL sam >= 0.1.0)

SAMMessage::header — メッセージのヘッダプロパティ

説明

object $SAMMessage->header;

header プロパティは、メッセージと関連付けられるシステムプロパティやユーザープロパティのコンテナとなります。

プロパティは、メッセージの送信者によってメッセージングシステムでの動作を制御するために指定されたり、あるいはメッセージングシステム自身によって受信者に追加情報・メッセージの処理方法を知らせるために指定されたりします。

SAM が理解できるいくつかのプロパティについては、対応する定数が定義されています。しかし、SAM の実装は大半のプロパティを無視し、そのままメッセージングシステムに渡します。これにより、アプリケーションがメッセージング固有のプロパティを使用したり、独自の "ユーザー" プロパティを定義することができるようになります。

SAM で定義済みのプロパティは次のようになります。

プロパティ名とりうる値

SAM_MESSAGEID メッセージを受信する場合は、このフィールドにはメッセージを識別する一意な ID が含まれます。これは、メッセージングシステムによって自動的に割り当てられるものです。メッセージを送信する場合は、このフィールドは無視されます。

SAM_REPLY_TO このメッセージに対する返信を投稿するキューの識別子を指定します。

プロパティ名	とりうる値
`SAM_MESSAGEID`	メッセージを受信する場合は、このフィールドにはメッセージを識別する一意な ID が含まれます。これは、メッセージングシステムによって自動的に割り当てられるものです。メッセージを送信する場合は、このフィールドは無視されます。
`SAM_REPLY_TO`	このメッセージに対する返信を投稿するキューの識別子を指定します。
`SAM_TYPE`	送信するメッセージの型を指定します。 `SAM_TEXT` はメッセージ本文の内容がテキスト文字列であることを示し、 `SAM_BYTES` はメッセージ本文の内容が何らかのアプリケーションで定義されているフォーマットであることを意味します。このプロパティの使用法は、メッセージングサーバーに依存します。たとえば、JMS (Java Message Service) の仕様をサポートしているメッセージングサーバーは、このプロパティを解釈して "jms_text" 型および "jms_bytes" 型のメッセージを送信します。さらに、`SAM_TYPE` プロパティが `SAM_TEXT` に設定された場合は、メッセージ本文のデータが UTF8 エンコードされた文字列であるものと期待されます。

SAM_TYPE

送信するメッセージの型を指定します。 SAM_TEXT はメッセージ本文の内容がテキスト文字列であることを示し、 SAM_BYTES はメッセージ本文の内容が何らかのアプリケーションで定義されているフォーマットであることを意味します。

このプロパティの使用法は、メッセージングサーバーに依存します。たとえば、JMS (Java Message Service) の仕様をサポートしているメッセージングサーバーは、このプロパティを解釈して "jms_text" 型および "jms_bytes" 型のメッセージを送信します。さらに、SAM_TYPE プロパティが SAM_TEXT に設定された場合は、メッセージ本文のデータが UTF8 エンコードされた文字列であるものと期待されます。

プロパティの値を設定する際には、その内容をメッセージングシステムにどのように配送するかのヒントを指定すると便利なことがあります。デフォルトではプロパティの値はテキストとして扱われます。この場合は、以下のシンプルな構文で値を設定します。

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


<?php
$msg = new SAMMessage();

$msg->header->myPropertyName = 'textData';
?>

型情報を渡したい場合は、別の構文を使用します。この場合は、値と型ヒントを連想配列で渡します。

例2 型ヒントを使用することによる、テキスト形式のプロパティの設定


<?php
$msg = new SAMMessage();

$msg->header->myPropertyName = array('textData', SAM_STRING);
?>

型ヒントを渡す際には、次の表にある SAM の定義済み定数のいずれかを使用します。

定数	型の説明
`SAM_BOOLEAN`	渡された値は、true あるいは false の論理値として解釈されます。その値が PHP の boolean 値として解釈できない場合は、メッセージングシステムに渡される値は未定義となります。
`SAM_BYTE`	符号つき 8 ビット整数値です。SAM は、このプロパティの値を 1 バイトの値に変換してメッセージングシステムに渡します。文字列が渡されると、それを数値として解釈しようとします。数値として解釈した結果が符号つき 8 ビットの範囲に収まらない場合は、変換の際にデータの損失が発生します。
`SAM_DOUBLE`	長浮動小数点数値です。SAM は、このプロパティの値を 15 桁の浮動小数点値に変換します。文字列が渡されると、それを数値として解釈しようとします。数値として解釈した結果が 15 桁の浮動小数点値の範囲に収まらない場合は、変換の際にデータの損失が発生します。
`SAM_FLOAT`	浮動小数点数値です。SAM は、このプロパティの値を 7 桁の浮動小数点値に変換します。文字列が渡されると、それを数値として解釈しようとします。数値として解釈した結果が 7 桁の浮動小数点値の範囲に収まらない場合は、変換の際にデータの損失が発生します。
`SAM_INT`	符号つき 32 ビット整数値です。SAM は、このプロパティの値を 32 ビットの値に変換してメッセージングシステムに渡します。文字列が渡されると、それを数値として解釈しようとします。数値として解釈した結果が符号つき 32 ビットの範囲に収まらない場合は、変換の際にデータの損失が発生します。
`SAM_LONG`	符号つき 64 ビット整数値です。SAM は、このプロパティの値を 64 ビットの値に変換してメッセージングシステムに渡します。文字列が渡されると、それを数値として解釈しようとします。数値として解釈した結果が符号つき 64 ビットの範囲に収まらない場合は、変換の際にデータの損失が発生します。
`SAM_STRING`	SAM は、このプロパティの値を文字列に変換してメッセージングシステムに渡します。

例

例3 プロパティに、メッセージの送信者を設定する


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

// SAM 固有のプロパティを設定します...
$msg->header->SAM_REPLY_TO = 'queue://test/replyQueue';

// 任意のプロパティを定義します...
//
// デフォルトの文字列形式のプロパティ
$msg->header->myStringProp1 = 'a string property';
// 型ヒントつきの文字列プロパティ
$msg->header->myStringProp2 = array('another string property', SAM_STRING);

// boolean のプロパティ
$msg->header->myBoolProp = array(FALSE, SAM_BOOL);

// 数値形式のプロパティ
$msg->header->myIntProp = array(32768, SAM_INT);
$msg->header->myLongProp = array(9876543, SAM_LONG);
$msg->header->myByteProp1 = array(123, SAM_BYTE);
$msg->header->myByteProp2 = array('12', SAM_BYTE);
$msg->header->myFloatProp = array(3.141592, SAM_FLOAT);
$msg->header->myDoubleProp = array(3.14159265358979, SAM_DOUBLE);
?>

例4 メッセージからのプロパティの値の取得


<?php

// アプリケーション固有のプロパティにアクセスします
$intProp = $msg->header->MyIntProp;

// メッセージングシステム固有のプロパティにアクセスします
$encoding = $msg->header->JMS_IBM_Msgtype;

?>

参考

SAMMessage::body