dsr Mon Nov 13 16:57:28 2006 UTC
Added files:
/phpdoc/en/reference/sam .cvsignore constants.xml reference.xml
Log:
Initial versions
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sam/.cvsignore?view=markup&rev=1.1
Index: phpdoc/en/reference/sam/.cvsignore
+++ phpdoc/en/reference/sam/.cvsignore
functions.xml
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sam/constants.xml?view=markup&rev=1.1
Index: phpdoc/en/reference/sam/constants.xml
+++ phpdoc/en/reference/sam/constants.xml
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.1 $ -->
<section id="mq.constants">
&reftitle.constants;
&extension.constants;
<variablelist>
<varlistentry>
<term>
<constant>SAM_AUTO</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Automatic behaviour
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_BOOLEAN</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Type specifier used when setting properties on SAM_Message objects.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_BUS</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect attribute used to set the name of the enterprise service bus to
connect to.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_BYTE</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Type specifier used when setting properties on SAM_Message objects.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_BYTES</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Message body type descriptor.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_DELIVERYMODE</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Message header property.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_DOUBLE</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Type specifier used when setting properties on SAM_Message objects.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_ENDPOINTS</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect attribute used to define the possible endpoints to connect to.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_FLOAT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Type specifier used when setting properties on SAM_Message objects.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_HOST</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect attribute used to set the hostname of the required messaging
server.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_INT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Type specifier used when setting properties on SAM_Message objects.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_LONG</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Type specifier used when setting properties on SAM_Message objects.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_MANUAL</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Manual (script controlled) behaviour
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_NON_PERSISTENT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect attribute value used to request messages are not made persistent
on the messaging
server.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_PASSWORD</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect attribute used to define the password to be used for the user
account being used to
connect to a messaging server that requires authorisation for connections.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_PERSISTENT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect attribute value used to request messages are made persistent on
the messaging server
to protect against loss of messages in the event of failure.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_PORT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect attribute used to set the port number on which to communicate with
the
messaging server.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_PRIORITY</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Option name used on send requests to specify a delivery priority value.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_REPLY_TO</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Message propery used to specify the queue identity on to which the script
expects response
or reply messages to be posted.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_RTT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect protocol definition for selecting the IBM Realtime Transport
protocol for
communication with a business integration messaging server.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_SELECT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Receive attribute used to set the required message selector.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_STRING</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Type specifier used when setting properties on SAM_Message objects.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_TARGETCHAIN</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connection attribute used to set the required target chain identifier.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_TEXT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Message body type descriptor.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_TIMETOLIVE</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Message send option name used to specify the length of time a message
should be retained in milliseconds.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_TRANSACTIONS</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connection attribute used to set required transactional behaviour. May be
set to SAM_AUTO
(default) or SAM_MANUAL.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_USERID</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect attribute used to define the account to being used to
connect to a messaging server that requires authorisation for connections.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_WAIT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Receive property used to specify the wait timeout to be used when
receiving a message from a queue or subscription.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_WMQ</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect protocol definition for selecting the IBM WebSphere MQSeries
protocol for
communication with the desired messaging server.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_WMQ_BINDINGS</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect protocol definition for selecting the IBM WebSphere MQSeries
protocol for
communication with a local messaging server.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_WMQ_CLIENT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect protocol definition for selecting the IBM WebSphere MQSeries
protocol for
communication with a remote messaging server.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_WPM</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect protocol definition for selecting the IBM WebSphere Platform
Messaging protocol for
communication with a WebSphere Application Server messaging server.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</section>
<!-- 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:"../../../../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
-->
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sam/reference.xml?view=markup&rev=1.1
Index: phpdoc/en/reference/sam/reference.xml
+++ phpdoc/en/reference/sam/reference.xml
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.1 $ -->
<reference id="ref.sam">
<title>SAM - Simple Asynchronous Messaging</title>
<titleabbrev>SAM</titleabbrev>
<partintro>
<section id="sam.intro">
&reftitle.intro;
<para>
<!-- This warns that the extension is experimental -->
&warn.experimental;
<!-- This is the paragraph text -->
</para>
<para>
This extension provides access to the functionality of messaging and
queueing systems, such
as the IBM WebSphere MQSeries family of products, from PHP scripts. The
interface is designed
to make it extremely simple to do the more commonly required tasks such as
deliver simple text
messages to queues while still allowing skilled users to do more complex
messaging operations.
For many users the complexities of setting up numerous options can be
simply ignored.
</para>
</section> <!-- id=sam.intro -->
<section id='sam.installation'>
&reftitle.install;
<para>
This should be the installation section.
</para>
</section> <!-- id=sam.installation -->
<section id='sam.usage'>
<title>API Usage</title>
<section id='sam.connections'>
<title>Connections</title>
<para>
In order to perform any messaging and queueing functions a connection
must be established
with a messaging server by creating a SAMConnection object and calling
its "connect"
method, with a set of connection properties, to connect the PHP script
to the messaging
server. Until such time as the SAMConnection object is destroyed the
connection
will be maintained and available for use. All SAMConnection objects are
destroyed when
the PHP script exits.
</para>
<para>
A set of default properties may be used in connecting to a messaging
server but as a
minimum the PHP script must specify a protocol to be used.
</para>
<para>
<example>
<title>Creating a connection and connecting to a local Messaging Server
using all defaults</title>
<programlisting role='php'>
<![CDATA[
<?php
$conn = new SAMConnection();
$conn->connect(SAM_WMQ);
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Creating a connection and connecting to a remote Messaging
Server</title>
<programlisting role='php'>
<![CDATA[
<?php
$conn = new SAMConnection();
$conn->connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com,
SAM_PORT => 1506,
SAM_BROKER => mybroker));
?>
]]>
</programlisting>
</example>
</para>
</section> <!-- id=sam.connections -->
<section id='sam.messages'>
<title>Messages</title>
<para>
Messages sent to and received from queues are represented by the
SAMMessage object. The
SAMMessage object encapsulates the body of the message (if one exists)
and the header
properties associated with the message. A SAMMessage object
is either supplied as a parameter to a messaging operation or returned as
a result.
</para>
<para>
<example>
<title>Creating a message with a simple text body</title>
<programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage('This is a simple text message');
?>
]]>
</programlisting>
</example>
</para>
<para>
Messages may have header properties associated with them that provide
control over the
transport of the message or further information to the receiving
application. By default
message properties are delivered to the underlying messaging system as
strings and in
this case they may be set with the following simple syntax:
</para>
<para>
<example>
<title>Setting a text format property using the default syntax</title>
<programlisting role="php">
<![CDATA[
<?php
$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 property using a type hint</title>
<programlisting role="php">
<![CDATA[
<?php
$msg->header->myPropertyName = (3.14159, SAM_FLOAT);
?>
]]>
</programlisting>
</example>
</para>
<para>
Properties may also be extracted from the header of a message.
</para>
<para>
<example>
<title>Retrieving a property from a message header</title>
<programlisting role="php">
<![CDATA[
<?php
$myProperty = $msg->header->myPropertyName;
?>
]]>
</programlisting>
</example>
</para>
</section> <!-- id=sam.messages -->
<section id='sam.operations'>
<title>Messaging operations</title>
<para>
All messaging operations are performed through calls to methods on the
connection object.
To add a message to a queue the "send" method is used, to obtain a
message from a queue the
"receive" method is used. Other methods provide publish and subscribe
functionality and
control of transaction boundaries.
</para>
<para>
<example>
<title>Adding a message to a queue and receiving a response</title>
<programlisting role="php">
<![CDATA[
<?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) {
// The Send failed!
echo "Send failed ($conn->errno) $conn->error";
} else {
$resp = $conn->receive('queue://receive/test', array(SAM_SELECT =>
$correlid));
}
?>
]]>
</programlisting>
</example>
</para>
</section> <!-- id=sam.operations -->
<section id='sam.errors'>
<title>Error handling</title>
<para>
All SAMConnection methods that provide access to messaging operations
return &false;
if an error occurred in processing the request. In addition the
SAMConnection object
has two properties, "errno" and "error", that provide respectively the
error number and
text description of the last error to occur on the connection.
</para>
<para>
<example>
<title>Handling an error from a method that returns no result</title>
<programlisting role="php">
<![CDATA[
<?php
if (!$conn->commit()) {
// The commit failed!
echo "Commit failed ($conn->errno) $conn->error";
}
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Handling an error from a method that returns a result</title>
<programlisting role="php">
<![CDATA[
<?php
$correlid = $conn->send('queue://send/test', $msg);
if (!$correlid) {
// The Send failed!
echo "Send failed ($conn->errno) $conn->error";
} else {
...
}
?>
]]>
</programlisting>
</example>
</para>
</section> <!-- id=sam.errors -->
</section> <!-- id=sam.usage -->
<!-- class definition section -->
<section id='sam.classes'>
&reftitle.classes;
<!-- Connection class *************************************************** -->
<section id='sam.class.Connection'>
<title><classname>SAMConnection</classname></title>
<para>
Object representing a connection to a Messaging Server
</para>
<section id='sam.class.Connection.constructor'>
&reftitle.constructor;
<itemizedlist>
<listitem>
<para>
<link linkend='function.SAM-Connection-constructor'>new
SAMConnection</link> - construct a new connection object to allow connection to
a messaging infrastructure.
</para>
</listitem>
</itemizedlist>
</section> <!-- id=sam.class.Connection.constructor -->
<section id='sam.class.Connection.methods'>
&reftitle.methods;
<itemizedlist>
<listitem>
<para>
<link linkend='function.SAM-Connection-commit'>commit</link>
- a method that commits (successfully completes) an in-flight unit of
work.
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Connection-connect'>connect</link>
- a method that connects a PHP script to a messaging server.
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Connection-disconnect'>disconnect</link>
- a method that disconnects a PHP script from a messaging server.
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Connection-isConnected'>isConnected</link>
- a method that checks whether a PHP script is connected to a
messaging server.
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Connection-peek'>peek</link>
- a method that receives a message from a queue without removing it
from the queue.
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Connection-receive'>receive</link>
- a method that receives a message from a queue or subscription.
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Connection-remove'>remove</link>
- a method that removes a message from a queue.
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Connection-rollback'>rollback</link>
- a method that cancels (rolls back) an in-flight unit of work.
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Connection-send'>send</link>
- a method that sends a message to a queue or posts to a topic
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Connection-subscribe'>subscribe</link>
- a method that creates a subscription to one or more topics
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Connection-unsubscribe'>unsubscribe</link>
- a method that destroys a subscription to one or more topics
</para>
</listitem>
</itemizedlist>
</section> <!-- id=sam.class.Connection.methods -->
<section id='sam.class.Connection.properties'>
&reftitle.properties;
<itemizedlist>
<listitem>
<para>
<link linkend='function.SAM-Connection-errno'>errno</link> - the
numeric error code
for the last encountered error on this connection. This property is
set to 0 if the last
operation was successful.
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Connection-error'>error</link> - the text
description
for the last encountered error on this connection
</para>
</listitem>
</itemizedlist>
</section> <!-- id=sam.class.Connection.properties -->
</section> <!-- id=sam.class.Connection -->
<!-- Message class *************************************************** -->
<section id='sam.class.Message'>
<title><classname>SAMMessage</classname></title>
<para>
Object representing a message to be sent or received
</para>
<section id='sam.class.Message.constructor'>
&reftitle.constructor;
<itemizedlist>
<listitem>
<para>
<link linkend='function.SAM-Message-constructor'>new SAMMessage</link>
- construct a
new message.
</para>
</listitem>
</itemizedlist>
</section> <!-- id=sam.class.Message.constructor -->
<section id='sam.class.Message.properties'>
&reftitle.properties;
<itemizedlist>
<listitem>
<para>
<link linkend='function.SAM-Message-body'>body</link> - the body of
the message.
</para>
</listitem>
<listitem>
<para>
<link linkend='function.SAM-Message-header'>header</link> - the header
properties of the message.
</para>
</listitem>
</itemizedlist>
</section> <!-- id=sam.class.Message.methods -->
</section> <!-- id=sam.class.Message -->
</section> <!-- id=sam.classes -->
<!-- Include the stuff from constants.xml? -->
&reference.sam.constants;
</partintro>
<!-- This seems to create the table of contents -->
&reference.sam.functions;
</reference>
<!-- 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:"../../../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
-->
