php-doc-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
-->