mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-26 13:58:55 +00:00
dd07341fae
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@343888 c90b9560-bf6c-de11-be94-00142212c4b1
294 lines
9.4 KiB
XML
294 lines
9.4 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xml:id='sammessage.header' xmlns="http://docbook.org/ns/docbook">
|
|
<refnamediv>
|
|
<refname>SAMMessage::header</refname>
|
|
<refpurpose>
|
|
The header properties of the message
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<fieldsynopsis><type>object</type><varname>SAMMessage->header</varname></fieldsynopsis>
|
|
<para>
|
|
The <literal>header</literal> property is a container for any system or
|
|
user properties that area associated with the message.
|
|
</para>
|
|
<para>
|
|
Properties may be assigned by the sender of a message to control the way
|
|
the messaging systems handles it or may be assigned by the messaging
|
|
system itself to tell the recipient extra information about the message or
|
|
the way in which it has been handled.
|
|
</para>
|
|
<para>
|
|
Some properties are understood by SAM in which case constants have been
|
|
defined for them. The majority of properties however are ignored by the
|
|
SAM implementation and simply passed through to the underlying messaging
|
|
systems allowing the application to use messaging specific property names
|
|
or to define its own "user" properties.
|
|
</para>
|
|
<para>
|
|
The SAM defined properties are as follows:
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Property name</entry>
|
|
<entry>Possible values</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><constant>SAM_MESSAGEID</constant></entry>
|
|
<entry>
|
|
When a message is received this field contains the unique
|
|
identifier of the message as allocated by the underlying
|
|
messaging system. When sending a message this field is ignored.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>SAM_REPLY_TO</constant></entry>
|
|
<entry>
|
|
A string providing the identity of the queue on to which
|
|
responses to this message should be posted.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>SAM_TYPE</constant></entry>
|
|
<entry>
|
|
<para>
|
|
An indication of the type of message to be sent. The value may be
|
|
<constant>SAM_TEXT</constant> indicating the contents of the
|
|
message body is a text string, or <constant>SAM_BYTES</constant>
|
|
indicating the contents of the message body are some application
|
|
defined format.
|
|
</para>
|
|
<para>
|
|
The way in which this property is used may depend on the underlying
|
|
messaging server. For instance a messaging server that supports the
|
|
<literal>JMS (Java Message Service)</literal> specification may
|
|
interpret this value and send messages of type "<literal>jms_text</literal>"
|
|
and "<literal>jms_bytes</literal>". In addition, if the
|
|
<constant>SAM_TYPE</constant> property is set to <constant>SAM_TEXT</constant>
|
|
the data provided for the message body is expected to be a UTF8 encoded
|
|
string.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
When setting the values of properties it is often useful to give a hint as
|
|
to the format in which the property should be delivered to the messaging
|
|
system. By default property values are delivered as text and the
|
|
following simple syntax may be used to set a value:
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Setting a text format property using the default syntax</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$msg = new SAMMessage();
|
|
|
|
$msg->header->myPropertyName = 'textData';
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
If it is desired to pass type information an alternative syntax may be
|
|
used where the value and the type hint are passed in an associative
|
|
array:
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Setting a text format property using a type hint</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$msg = new SAMMessage();
|
|
|
|
$msg->header->myPropertyName = array('textData', SAM_STRING);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
When passing a type hint the type entry should be one of the SAM defined
|
|
constant values as defined by the following table:
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Constant</entry>
|
|
<entry>Type description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><constant>SAM_BOOLEAN</constant></entry>
|
|
<entry>
|
|
Any value passed will be interpreted as logical true or false.
|
|
If the value cannot be interpreted as a PHP boolean value the value
|
|
passed to the messaging system is undefined.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>SAM_BYTE</constant></entry>
|
|
<entry>
|
|
An 8-bit signed integer value. SAM will attempt to convert the
|
|
property value specified into a single byte value to pass to the
|
|
messaging system. If a string value is passed an attempt will be
|
|
made to interpret the string as a numeric value. If the numeric
|
|
value cannot be expressed as an 8-bit signed binary value data may
|
|
be lost in the conversion.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>SAM_DOUBLE</constant></entry>
|
|
<entry>
|
|
A long floating point value. SAM will attempt to convert the
|
|
property value specified into a floating point value with 15 digits
|
|
of precision. If a string value is passed an attempt will be made to
|
|
interpret the string as a numeric value. If the passed value cannot
|
|
be expressed as a 15 digit floating point value data may be lost in
|
|
the conversion.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>SAM_FLOAT</constant></entry>
|
|
<entry>
|
|
A short floating point value. SAM will attempt to convert the
|
|
property value specified into a floating point value with 7 digits of
|
|
precision. If a string value is passed an attempt will be made to
|
|
interpret the string as a numeric value. If the passed value cannot
|
|
be expressed as a 7 digit floating point value data may be lost in
|
|
the conversion.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>SAM_INT</constant></entry>
|
|
<entry>
|
|
An 32-bit signed integer value. SAM will attempt to convert the
|
|
property value specified into a 32-bit value to pass to the messaging
|
|
system. If a string value is passed an attempt will be made to
|
|
interpret the string as a numeric value. If the numeric value cannot
|
|
be expressed as an 32-bit signed binary value data may be lost in the
|
|
conversion.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>SAM_LONG</constant></entry>
|
|
<entry>
|
|
An 64-bit signed integer value. SAM will attempt to convert the
|
|
property value specified into a 64-bit value to pass to the messaging
|
|
system. If a string value is passed an attempt will be made to
|
|
interpret the string as a numeric value. If the numeric value cannot
|
|
be expressed as an 64-bit signed binary value data may be lost in the
|
|
conversion.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>SAM_STRING</constant></entry>
|
|
<entry>
|
|
SAM will interpret the property value specified as a string and pass
|
|
it to the messaging system accordingly.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title>Setting properties as the sender of a message</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$msg = new SAMMessage('This is a test message');
|
|
|
|
// defining SAM specific properties...
|
|
$msg->header->SAM_REPLY_TO = 'queue://test/replyQueue';
|
|
|
|
// defining arbitrary properties...
|
|
//
|
|
// a default string property
|
|
$msg->header->myStringProp1 = 'a string property';
|
|
// a string property with a type hint
|
|
$msg->header->myStringProp2 = array('another string property', SAM_STRING);
|
|
|
|
// a boolean property
|
|
$msg->header->myBoolProp = array(FALSE, SAM_BOOL);
|
|
|
|
// numeric format properties
|
|
$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);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Retreiving property values from a message</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
// accessing an application specific property
|
|
$intProp = $msg->header->MyIntProp;
|
|
|
|
// accessing a messaging system specific property
|
|
$encoding = $msg->header->JMS_IBM_Msgtype;
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><xref linkend="sammessage.body" /></member>
|
|
</simplelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|