From 3b3f8a0b4b1d23f87c006fd3f9eb0559441504fa Mon Sep 17 00:00:00 2001
From: Dave Renshaw <dsr@php.net>
Date: Wed, 22 Nov 2006 17:21:35 +0000
Subject: [PATCH] Updates for release 0.2.0 adding install, peek, peekAll and
 remove details.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@223732 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../sam/functions/SAM-Connection-commit.xml   |   2 +-
 .../sam/functions/SAM-Connection-connect.xml  |   2 +-
 .../functions/SAM-Connection-constructor.xml  |   2 +-
 .../functions/SAM-Connection-disconnect.xml   |   2 +-
 .../sam/functions/SAM-Connection-errno.xml    |   2 +-
 .../sam/functions/SAM-Connection-error.xml    |   2 +-
 .../functions/SAM-Connection-isConnected.xml  |   2 +-
 .../sam/functions/SAM-Connection-peek.xml     |  15 +-
 .../sam/functions/SAM-Connection-peekall.xml  | 142 ++++++++++++++++++
 .../sam/functions/SAM-Connection-receive.xml  |  12 +-
 .../sam/functions/SAM-Connection-remove.xml   |  17 ++-
 .../sam/functions/SAM-Connection-rollback.xml |   2 +-
 .../sam/functions/SAM-Connection-send.xml     |   6 +-
 .../functions/SAM-Connection-subscribe.xml    |   2 +-
 .../functions/SAM-Connection-unsubscribe.xml  |   2 +-
 reference/sam/functions/SAM-Message-body.xml  |   2 +-
 .../sam/functions/SAM-Message-constructor.xml |   2 +-
 .../sam/functions/SAM-Message-header.xml      |  13 +-
 18 files changed, 191 insertions(+), 38 deletions(-)
 create mode 100644 reference/sam/functions/SAM-Connection-peekall.xml

diff --git a/reference/sam/functions/SAM-Connection-commit.xml b/reference/sam/functions/SAM-Connection-commit.xml
index f99541ddea..74c99c6286 100644
--- a/reference/sam/functions/SAM-Connection-commit.xml
+++ b/reference/sam/functions/SAM-Connection-commit.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-commit'>
  <refnamediv>
   <refname>SAMConnection::commit()</refname>
diff --git a/reference/sam/functions/SAM-Connection-connect.xml b/reference/sam/functions/SAM-Connection-connect.xml
index 148bb84252..12b0381f52 100644
--- a/reference/sam/functions/SAM-Connection-connect.xml
+++ b/reference/sam/functions/SAM-Connection-connect.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-connect'>
  <refnamediv>
   <refname>SAMConnection::connect()</refname>
diff --git a/reference/sam/functions/SAM-Connection-constructor.xml b/reference/sam/functions/SAM-Connection-constructor.xml
index 3b93395c71..20c21eac3d 100644
--- a/reference/sam/functions/SAM-Connection-constructor.xml
+++ b/reference/sam/functions/SAM-Connection-constructor.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-constructor'>
  <refnamediv>
   <refname>SAMConnection::SAMConnection()</refname>
diff --git a/reference/sam/functions/SAM-Connection-disconnect.xml b/reference/sam/functions/SAM-Connection-disconnect.xml
index 7ee275fd3d..e28aa50ee0 100644
--- a/reference/sam/functions/SAM-Connection-disconnect.xml
+++ b/reference/sam/functions/SAM-Connection-disconnect.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-disconnect'>
  <refnamediv>
   <refname>SAMConnection::disconnect()</refname>
diff --git a/reference/sam/functions/SAM-Connection-errno.xml b/reference/sam/functions/SAM-Connection-errno.xml
index 036372a801..3c97bac038 100644
--- a/reference/sam/functions/SAM-Connection-errno.xml
+++ b/reference/sam/functions/SAM-Connection-errno.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id="function.SAM-Connection-errno">
  <refnamediv>
   <refname>SAMConnection->errno</refname>
diff --git a/reference/sam/functions/SAM-Connection-error.xml b/reference/sam/functions/SAM-Connection-error.xml
index af6a6683d6..c56e6e8eb1 100644
--- a/reference/sam/functions/SAM-Connection-error.xml
+++ b/reference/sam/functions/SAM-Connection-error.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
   <refentry id="function.SAM-Connection-error">
  <refnamediv>
   <refname>SAMConnection->error</refname>
diff --git a/reference/sam/functions/SAM-Connection-isConnected.xml b/reference/sam/functions/SAM-Connection-isConnected.xml
index f8c7df730d..f40cf38973 100644
--- a/reference/sam/functions/SAM-Connection-isConnected.xml
+++ b/reference/sam/functions/SAM-Connection-isConnected.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-isConnected'>
  <refnamediv>
   <refname>SAMConnection::isConnected()</refname>
diff --git a/reference/sam/functions/SAM-Connection-peek.xml b/reference/sam/functions/SAM-Connection-peek.xml
index 52a9a8ea2e..609508f403 100644
--- a/reference/sam/functions/SAM-Connection-peek.xml
+++ b/reference/sam/functions/SAM-Connection-peek.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-peek'>
  <refnamediv>
   <refname>SAMConnection::peek()</refname>
@@ -18,9 +18,6 @@
       <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam>
    </methodsynopsis>
   </classsynopsis>
-   <para>
-   Warning: This method is not currently implemented.
-   </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -50,9 +47,13 @@
            </thead>
            <tbody>
              <row>
-               <entry>SAM_SELECT</entry>
-               <entry>String selector used to select messages from the queue. Typically this the correlation id string  returned by a "send" request.</entry>
+               <entry>SAM_CORRELID</entry>
+               <entry>This is the target correlation id string of the message. This would typically have been returned by a "send" request.</entry>
              </row>
+             <row>
+               <entry>SAM_MESSAGEID</entry>
+               <entry>This is the message id string of the message which is to be peeked.</entry>
+             </row>             
            </tbody>
          </tgroup>
        </informaltable>
@@ -96,7 +97,7 @@ if (!$msg) {
 <![CDATA[
 <?php
 
-$msg = $conn->peek('queue://receive/test', array(SAM_SELECT => $token));
+$msg = $conn->peek('queue://receive/test', array(SAM_MESSAGEID => $messageId));
 
 ?>
 ]]>
diff --git a/reference/sam/functions/SAM-Connection-peekall.xml b/reference/sam/functions/SAM-Connection-peekall.xml
new file mode 100644
index 0000000000..894715c2a5
--- /dev/null
+++ b/reference/sam/functions/SAM-Connection-peekall.xml
@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+<refentry id='function.SAM-Connection-peekAll'>
+ <refnamediv>
+  <refname>SAMConnection::peekAll()</refname>
+  <refpurpose>
+   Read one or more messages from a queue without removing it from the queue.
+  </refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <classsynopsis>
+   <ooclass><classname>SAMConnection</classname></ooclass>
+   <methodsynopsis>
+    <type>array</type><methodname>peekAll</methodname>
+      <methodparam><type>string</type><parameter>target</parameter></methodparam>
+      <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam>
+   </methodsynopsis>
+  </classsynopsis>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>target</parameter></term>
+     <listitem>
+      <para>
+       The identity of the queue from which messages should be peeked.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>properties</parameter></term>
+     <listitem>
+      <para>
+       An optional associative array of properties describing other parameters to control the peek operation.
+       <informaltable>
+         <tgroup cols="2">
+           <thead>
+             <row>
+               <entry>Property name</entry>
+               <entry>Possible values</entry>
+             </row>
+           </thead>
+           <tbody>
+             <row>
+               <entry>SAM_CORRELID</entry>
+               <entry>This is the target correlation id string of messages to be peeked. This would typically have been returned by a "send" request.</entry>
+             </row>
+             <row>
+               <entry>SAM_MESSAGEID</entry>
+               <entry>This is the message id string of a message which is to be peeked.</entry>
+             </row>             
+           </tbody>
+         </tgroup>
+       </informaltable>
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   This method returns an array of SAMMessage objects or &false; if an error occurs.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Retrieve all messages in a queue without removing them</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+   $msgArray = $conn->peekAll('queue://receive/test');
+   if ($msgArray) {
+
+      foreach ( $msgArray as $key => $msg) {
+            echo "Message $key: body = $msg->body\n";
+         }
+      }
+   else
+      echo "PeekAll failed ($conn->errno) $conn->error";
+   }
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title>Retrieve all messages from a queue with a matching correlation id</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+   $msgArray = $conn->peekAll('queue://receive/test', array(SAM_CORRELID => $correlId ));
+   if ($msgArray) {
+
+      foreach ( $msgArray as $key => $msg) {
+            echo "Message $key: body = $msg->body\n";
+         }
+      }
+   else
+      echo "PeekAll failed ($conn->errno) $conn->error";
+   }
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </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:"../../../../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
+-->
diff --git a/reference/sam/functions/SAM-Connection-receive.xml b/reference/sam/functions/SAM-Connection-receive.xml
index 36a55fed61..ddaa91530d 100644
--- a/reference/sam/functions/SAM-Connection-receive.xml
+++ b/reference/sam/functions/SAM-Connection-receive.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-receive'>
  <refnamediv>
   <refname>SAMConnection::receive()</refname>
@@ -47,10 +47,12 @@
            </thead>
            <tbody>
              <row>
-               <entry>SAM_SELECT</entry>
-               <entry>
-                String selector used to select messages from the queue. Typically this the correlation id string  returned by a "send" request.
-               </entry>
+               <entry>SAM_CORRELID</entry>
+               <entry>Used to request selection of the message to receive based upon the correlation id string of the message.</entry>
+             </row>
+             <row>
+               <entry>SAM_MESSAGEID</entry>
+               <entry>Used to request selection of the message to receive based upon the message id string of the message.</entry>
              </row>
              <row>
                <entry>SAM_WAIT</entry>
diff --git a/reference/sam/functions/SAM-Connection-remove.xml b/reference/sam/functions/SAM-Connection-remove.xml
index 1875f55b58..8bfc757508 100644
--- a/reference/sam/functions/SAM-Connection-remove.xml
+++ b/reference/sam/functions/SAM-Connection-remove.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-remove'>
  <refnamediv>
   <refname>SAMConnection::remove()</refname>
@@ -18,9 +18,6 @@
       <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam>
    </methodsynopsis>
   </classsynopsis>
-   <para>
-   Warning: This method is not currently implemented.
-   </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -50,9 +47,13 @@
            </thead>
            <tbody>
              <row>
-               <entry>SAM_SELECT</entry>
-               <entry>String selector used to select messages from the queue. Typically this the correlation id string  returned by a "send" request.</entry>
+               <entry>SAM_CORRELID</entry>
+               <entry>This is the target correlation id string of the message. This would typically have been returned by a "send" request.</entry>
              </row>
+             <row>
+               <entry>SAM_MESSAGEID</entry>
+               <entry>This is the message id string of the message which is to be removed.</entry>
+             </row>        
            </tbody>
          </tgroup>
        </informaltable>
@@ -74,11 +75,11 @@
   &reftitle.examples;
   <para>
    <example>
-    <title>Removing a message from a queue with options</title>
+    <title>Removing a message from a queue by message id</title>
     <programlisting role="php">
 <![CDATA[
 <?php
-if (!$conn->remove('queue://receive/test', array(SAM_SELECT => $token))) {
+if (!$conn->remove('queue://receive/test', array(SAM_MESSAGEID => $messageId))) {
   // The remove failed!
   echo "Remove failed ($conn->errno) $conn->error";
 }
diff --git a/reference/sam/functions/SAM-Connection-rollback.xml b/reference/sam/functions/SAM-Connection-rollback.xml
index f2a069840d..157b7a0488 100644
--- a/reference/sam/functions/SAM-Connection-rollback.xml
+++ b/reference/sam/functions/SAM-Connection-rollback.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-rollback'>
  <refnamediv>
   <refname>SAMConnection::rollback()</refname>
diff --git a/reference/sam/functions/SAM-Connection-send.xml b/reference/sam/functions/SAM-Connection-send.xml
index c2455c973f..dbc3d831b9 100644
--- a/reference/sam/functions/SAM-Connection-send.xml
+++ b/reference/sam/functions/SAM-Connection-send.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-send'>
  <refnamediv>
   <refname>SAMConnection::send()</refname>
@@ -78,10 +78,10 @@
               </entry>
              </row>
              <row>
-               <entry>SAM_SELECT</entry>
+               <entry>SAM_CORRELID</entry>
                <entry>
                 A string to be assigned as a correlation id for this message. If no value is given the messaging server
-                may assign automatically.
+                may assign a value automatically.
                </entry>
              </row>
              <row>
diff --git a/reference/sam/functions/SAM-Connection-subscribe.xml b/reference/sam/functions/SAM-Connection-subscribe.xml
index 90d9763acc..ebd3a60e67 100644
--- a/reference/sam/functions/SAM-Connection-subscribe.xml
+++ b/reference/sam/functions/SAM-Connection-subscribe.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-subscribe'>
  <refnamediv>
   <refname>SAMConnection::subscribe()</refname>
diff --git a/reference/sam/functions/SAM-Connection-unsubscribe.xml b/reference/sam/functions/SAM-Connection-unsubscribe.xml
index 7cc4621532..b3e6f180c0 100644
--- a/reference/sam/functions/SAM-Connection-unsubscribe.xml
+++ b/reference/sam/functions/SAM-Connection-unsubscribe.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Connection-unsubscribe'>
  <refnamediv>
   <refname>SAMConnection::unsubscribe()</refname>
diff --git a/reference/sam/functions/SAM-Message-body.xml b/reference/sam/functions/SAM-Message-body.xml
index 0352446ceb..8d8438cddb 100644
--- a/reference/sam/functions/SAM-Message-body.xml
+++ b/reference/sam/functions/SAM-Message-body.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Message-body'>
  <refnamediv>
   <refname>SAMMessage::body</refname>
diff --git a/reference/sam/functions/SAM-Message-constructor.xml b/reference/sam/functions/SAM-Message-constructor.xml
index a6527b3193..228fe3ff15 100644
--- a/reference/sam/functions/SAM-Message-constructor.xml
+++ b/reference/sam/functions/SAM-Message-constructor.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Message-constructor'>
  <refnamediv>
   <refname>SAMMessage::SAMMessage()</refname>
diff --git a/reference/sam/functions/SAM-Message-header.xml b/reference/sam/functions/SAM-Message-header.xml
index 44f9f72b8d..c2ddb50ac2 100644
--- a/reference/sam/functions/SAM-Message-header.xml
+++ b/reference/sam/functions/SAM-Message-header.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id='function.SAM-Message-header'>
  <refnamediv>
   <refname>SAMMessage::header</refname>
@@ -31,6 +31,13 @@
         </row>
       </thead>
       <tbody>
+        <row>
+          <entry>SAM_MESSAGEID</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>SAM_REPLY_TO</entry>
           <entry>
@@ -88,7 +95,7 @@
 <?php
    $msg = new SAMMessage();
 
-   $msg->header->myPropertyName = ('textData', SAM_STRING);
+   $msg->header->myPropertyName = array('textData', SAM_STRING);
 ?>
 ]]>
     </programlisting>
@@ -213,7 +220,7 @@
 <![CDATA[
 <?php
 
-   // accessing an application specifc property
+   // accessing an application specific property
    $intProp = $msg->header->'MyIntProp';
 
    // accessing a messaging system specific property