预定义类

SAMConnection

Object representing a connection to a Messaging Server

构造函数

  • new SAMConnection - construct a new connection object to allow connection to a messaging infrastructure.

方法

  • commit - a method that commits (successfully completes) an in-flight unit of work.

  • connect - a method that connects a PHP script to a messaging server.

  • disconnect - a method that disconnects a PHP script from a messaging server.

  • isConnected - a method that checks whether a PHP script is connected to a messaging server.

  • peek - a method that receives a message from a queue without removing it from the queue.

  • peekAll - a method that receives one or messages from a queue without removing them from the queue.

  • receive - a method that receives a message from a queue or subscription.

  • remove - a method that removes a message from a queue.

  • rollback - a method that cancels (rolls back) an in-flight unit of work.

  • send - a method that sends a message to a queue or posts to a topic

  • setDebug - a method that switches additional debugging output on or off

  • subscribe - a method that creates a subscription to one or more topics

  • unsubscribe - a method that destroys a subscription to one or more topics

属性

  • errno - the numeric error code for the last encountered error on this connection. This property is set to 0 if the last operation was successful.

  • error - the text description for the last encountered error on this connection

SAMMessage

Object representing a message to be sent or received

构造函数

属性

  • body - the body of the message.

  • header - the header properties of the message.

SAMConnection::commit

Commits (completes) the current unit of work

说明

bool SAMConnection::commit ( void )

Calling the "commit" method on a Connection object commits (completes) all in-flight transactions that are part of the current unit of work.

返回值

This method returns FALSE if an error occurs.

范例

示例 #1 Committing the current unit of work

<?php
  if (!$conn->commit()) {
    // The commit failed!
    echo "Commit failed ($conn->errno) $conn->error";
  }
?>

参见

SAMConnection::connect

Establishes a connection to a Messaging Server

说明

bool SAMConnection::connect ( string $protocol [, array $properties ] )

Calling the "connect" method on a SAMConnection object connects the PHP script to a messaging server. No messages can be sent or received until a connection is made.

参数

返回值

This method returns FALSE if an error occurs.

范例

示例 #1 Creating a connection to a Messaging Server using the IBM MQSeries protocol (WMQ)

<?php

$conn->connect(SAM_WMQ, array(SAM_HOST => 'Myhost.myco.com', SAM_PORT => 1506, SAM_BROKER => 'MyBroker'));

?>

示例 #2 Creating a connection with application transaction control and default host and port values

<?php

$conn->connect(SAM_WMQ, array(SAM_BROKER => 'MyBroker', SAM_TRANSACTIONS => SAM_MANUAL));

?>

示例 #3 Creating a connection to a Messaging Server using the IBM WebSphere Platform Messaging protocol (WPM)

<?php

$conn->connect(SAM_WPM, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging',
                              SAM_BUS => 'Bus1', SAM_TARGETCHAIN => 'InboundBasicMessaging'));

?>

参见

SAMConnection::__construct

Creates a new connection to a Messaging Server

说明

SAMConnection::__construct ( void )

Creates a new SAMConnection object.

范例

示例 #1 Creating a connection object and connecting to a Messaging Server

<?php

$conn = new SAMConnection();
$conn->connect(SAM_WMQ, array(SAM_HOST => localhost, SAM_PORT => 1414, SAM_BROKER => 'bull'));

?>

SAMConnection::disconnect

Disconnects from a Messaging Server

说明

bool SAMConnection::disconnect ( void )

Calling the "disconnect" method on a SAMConnection object disconnects the PHP script from a messaging server. No messages can be sent or received after a connection has been disconnected.

返回值

成功时返回 TRUE, 或者在失败时返回 FALSE

范例

示例 #1 Disconnecting from a Messaging Server

<?php

$conn->disconnect();

?>

参见

SAMConnection::errno

Contains the unique numeric error code of the last executed SAM operation

Description

int$SAMConnection->errno;

Contains the numeric error code of the last executed SAM operation on this connection. If the last operation completed successfully this property contains 0.

返回值

An integer greater than zero indicates the last error type encountered on the connection. Zero indicates that the last operation on this connection completed successfully.

范例

示例 #1 Using the error number and description properties

<?php
$conn = new SAMConnection();
$conn->connect(SAM_WMQ, array(SAM_HOST => 'localhost', SAM_PORT => 1506));
$msg = new SAMMessage('This is a simple text item');
if (!$conn->send('topic://test', $msg)) {
    // The Send failed!
    echo "Send failed ($conn->errno) $conn->error";
}
?>

参见

SAMConnection::error

Contains the text description of the last failed SAM operation

说明

string$SAMConnection->error;

Contains the text description of the last failed SAM operation on this connection. If the last operation completed successfully this property contains an empty string.

返回值

A string containing the text description of the last error type encountered on the connection. An empty string indicates that the last operation on this connection completed successfully.

范例

示例 #1 Using the error number and description properties

<?php
$conn = new SAMConnection();
$conn->connect(SAM_WMQ, array(SAM_HOST => 'localhost', SAM_PORT => 1506));
$msg = new SAMMessage('This is a simple text item');
if (!$conn->send('topic://test', $msg)) {
    // The Send failed!
    echo "Send failed ($conn->errno) $conn->error";
}
?>

参见

SAMConnection::isConnected

Queries whether a connection is established to a Messaging Server

说明

bool SAMConnection::isConnected ( void )

Calling the "isConnected" method on a Connection object will check whether the PHP script is connected to a messaging server. No messages can be sent or received unless a connection has been established with a Messaging server.

返回值

This method returns TRUE if the SAMConnection object is successfully connected to a Messaging server or FALSE otherwise.

范例

示例 #1 Checking whether there us a connection to a Messaging Server

<?php

if ($conn->isConnected()) {
  echo 'Connection is active.';
} else {
  echo 'No active connection!';
}

?>

参见

SAMConnection::peek

Read a message from a queue without removing it from the queue

说明

SAMMessage SAMConnection::peek ( string $target [, array $properties ] )

参数

target
The identity of the queue from which to peek the message.

properties
An optional associative array of properties describing other parameters to control the peek operation.

Property namePossible values
SAM_CORRELIDThis is the target correlation id string of the message. This would typically have been returned by a "send" request.
SAM_MESSAGEIDThis is the message id string of the message which is to be peeked.

返回值

This method returns a SAMMessage object or FALSE if an error occurs.

范例

示例 #1 Retrieve the next message from a queue without removing it

<?php
$msg = $conn->peek('queue://receive/test');

if (!$msg) {
  // The peek failed!
  echo "Peek failed ($conn->errno) $conn->error";
}
?>

示例 #2 Retrieve a specific message from a queue without removing it from the queue

<?php

$msg = $conn->peek('queue://receive/test', array(SAM_MESSAGEID => $messageId));

?>

参见

SAMConnection::peekAll

Read one or more messages from a queue without removing it from the queue

说明

array SAMConnection::peekAll ( string $target [, array $properties ] )

参数

target
The identity of the queue from which messages should be peeked.

properties
An optional associative array of properties describing other parameters to control the peek operation.

Property namePossible values
SAM_CORRELIDThis is the target correlation id string of messages to be peeked. This would typically have been returned by a "send" request.
SAM_MESSAGEIDThis is the message id string of a message which is to be peeked.

返回值

This method returns an array of SAMMessage objects or FALSE if an error occurs.

范例

示例 #1 Retrieve all messages in a queue without removing them

<?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";
}
?>

示例 #2 Retrieve all messages from a queue with a matching correlation id

<?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";
   }

?>

参见

SAMConnection::receive

Receive a message from a queue or subscription

说明

SAMMessage SAMConnection::receive ( string $target [, array $properties ] )

参数

target
The identity of the queue, topic or subscription from which to receive the message.

properties
An optional associative array of properties describing other parameters to control the receive operation.

Property namePossible values
SAM_CORRELIDUsed to request selection of the message to receive based upon the correlation id string of the message.
SAM_MESSAGEIDUsed to request selection of the message to receive based upon the message id string of the message.
SAM_WAITTimeout value in milliseconds to control how long the request should block waiting to receive a message before returning with a failure if no message is available on the queue or topic. The default value is 0 meaning wait indefinitely and should be used with caution as the request may wait until the overall PHP script processing time limit has expired if no message becomes available.

返回值

This method returns a SAMMessage object or FALSE if an error occurs.

范例

示例 #1 Receiving a message from a queue

<?php
$msg = $conn->receive('queue://receive/test');

if (!$msg) {
  // The receive failed!
  echo "Receive failed ($conn->errno) $conn->error";
}
?>

示例 #2 Receiving a message from a queue with options

In this example the SAM_CORRELID option is used to specify a correlation id string to be used to identify the message to receive. A wait timeout of 10 seconds is also specified.

<?php

$msg = $conn->receive('queue://receive/test', array(SAM_CORRELID => $token, SAM_WAIT => 10000));

?>

示例 #3 Receiving a message from a subscription

In this example we show how to receive a message from a subscription id.

<?php
$msg = $conn->receive($subscriptionName);

if (!$msg) {
  // The receive failed!
  echo "Receive failed ($conn->errno) $conn->error";
}
?>

Please note that $subscriptionName is a subscription id returned from an earlier subscribe call.

参见

SAMConnection::remove

Remove a message from a queue

说明

SAMMessage SAMConnection::remove ( string $target [, array $properties ] )

Removes a message from a queue.

参数

target
The identity of the queue from which to remove the message.

properties
An optional associative array of properties describing other parameters to control the remove operation.

Property namePossible values
SAM_CORRELIDThis is the target correlation id string of the message. This would typically have been returned by a "send" request.
SAM_MESSAGEIDThis is the message id string of the message which is to be removed.

返回值

This method returns FALSE if an error occurs.

范例

示例 #1 Removing a message from a queue by message id

<?php
if (!$conn->remove('queue://receive/test', array(SAM_MESSAGEID => $messageId))) {
  // The remove failed!
  echo "Remove failed ($conn->errno) $conn->error";
}
?>

SAMConnection::rollback

Cancels (rolls back) an in-flight unit of work

说明

bool SAMConnection::rollback ( void )

Rolls back an in-flight unit of work.

返回值

This method returns FALSE if an error occurs.

范例

示例 #1 Cancelling an in-flight unit of work

<?php
if (!$conn->rollback()) {
  // The rollback failed!
  echo "Rollback failed ($conn->errno) $conn->error";
}
?>

参见

SAMConnection::send

Send a message to a queue or publish an item to a topic

说明

string SAMConnection::send ( string $target , SAMMessage $msg [, array $properties ] )

The "send" method is used to send a message to a specific queue or to publish to a specific topic. The method returns a correlation id that can be used as a selector to identify reply or response messages when these are requested.

参数

target
If sending a message, the identity of the queue (queue://queuename) or if publishing to a topic the identity of the topic (topic://topicname) to which the message is to be delivered.

msg
The message to be sent or published.

properties
An optional associative array of properties describing other parameters to control the receive operation.

Property namePossible values
SAM_DELIVERYMODEIndicates whether the messaging server should ensure delivery or whether it is acceptable for messages to be lost in the case of system failures. The value of this property may be set to either SAM_PERSISTENT, to indicate that message loss is not acceptable, or SAM_NON_PERSISTENT, if message loss is acceptable. The resulting behaviour of the send will vary depending on the capabilities of the messaging server the PHP script is currently connected to. If the server does not support persistent messages and SAM_PERSISTENT is specified the send request will fail with an error indication showing the capability is not available.
SAM_PRIORITYA numeric value between 0 and 9 indicating the desired message delivery priority. A priority value of 0 indicates the lowest priority while 9 indicates highest priority. If no priority is specified a default will be assigned which is dependent on the messaging server being used.
SAM_CORRELIDA string to be assigned as a correlation id for this message. If no value is given the messaging server may assign a value automatically.
SAM_TIMETOLIVEA time in milliseconds indicating how long the messaging server should retain the message on a queue before discarding it. The default value is 0 indicating the message should be retained indefinitely.
SAM_WMQ_TARGET_CLIENTThis property is only valid when using WebSphere MQ and indicates whether or not an RFH2 header should be included with the message. This option may be set to either 'jms' or 'mq'. The default is 'jms' which means that an RFH2 header is included. If the value 'mq' is specified then no RFH2 is included with the message.

返回值

A correlation id string that can be used in a subsequent receive call as a selector to obtain any reply or response that has been requested or FALSE if an error occurred.

Note:

A correlation id will only be returned for a successful send to a queue destination (queue://xxxx) in which case it will reflect the message identity of the message on the queue. In the case of a send being used to publish data to a topic the return value will be TRUE as no correlation id is available for return.

范例

示例 #1 Send a message to a queue

<?php
$msg = new SAMMessage('This is a simple text message');
$correlId = $conn->send('queue://send/test', $msg);
if (!$correlId) {
    // The send failed!
    echo "Send failed ($conn->errno) $conn->error";
}

?>

示例 #2 Publish a message to a topic

<?php
$msg = new SAMMessage('This is a simple text item');
if (!$conn->send('topic://test', $msg)) {
    // The Send failed!
    echo "Send failed ($conn->errno) $conn->error";
}
?>

示例 #3 Send a request and receive a response

<?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_CORRELID => $correlid));
}
?>

参见

SAMConnection::setDebug

Turn on or off additional debugging output

说明

The "setdebug" method is used to turn on or off additional debugging output. The SAM framework will provide method/function entry and exit trace data plus additional information. Protocol specific implementations also provide extra output.

void SAMConnection::setDebug ( bool $switch )

参数

switch
If this parameter is set to TRUE additional debugging output will be provided. If the value is set to FALSE output of additional information will be stopped.

返回值

没有返回值。

范例

示例 #1 Turn on debugging output

<?php
$conn->setdebug(TRUE);
?>

示例 #2 Turn off debugging output

<?php
$conn->setdebug(FALSE);
?>

SAMConnection::subscribe

Create a subscription to a specified topic

说明

string SAMConnection::subscribe ( string $targetTopic )

The "subscribe" method is used to create a new subscription to a specified topic.

参数

targetTopic
The identity of the topic (topic://topicname) to subscribe to.

返回值

A subscription identifier that can be used in a subsequent receive call as a selector to obtain any topic data or FALSE if an error occurred. The subscription identifier should be used in the receive call in place of the simple topic name.

范例

示例 #1 Subscribe to a topic

<?php
$subid = $conn->subscribe('topic://A');
if (!$subid) {
  // The subscribe failed!
  echo "Subscribe failed ($conn->errno) $conn->error";
}
?>

参见

SAMConnection::unsubscribe

Cancel a subscription to a specified topic

说明

bool SAMConnection::unsubscribe ( string $subscriptionId [, string $targetTopic ] )

The "unsubscribe" method is used to delete an existing subscription to a specified topic.

参数

subscriptionId
The identifier of an existing subscription as returned by a call to the subscribe method.

返回值

This method returns FALSE if an error occurs.

范例

示例 #1 Delete a subscription

<?php
if (!$conn->unsubscribe($subid)) {
    // The unsubscribe failed!
    echo "Unsubscribe failed ($conn->errno) $conn->error";
}
?>

参见

SAMMessage::body

The body of the message

说明

string$SAMMessage->body;

The "body" property contains the actual body of the message. It may not always be set.

范例

示例 #1 Setting a text string into the body of a message

<?php
$msg = new SAMMessage();
$msg->body = 'This is a simple message';

?>

参见

SAMMessage::__construct

Creates a new Message object

说明

SAMMessage::__construct ([ mixed $body ] )

Creates a new SAMMessage object optionally specifying a message body.

参数

body
The optional body for the message.

范例

示例 #1 Creating a message

<?php

$msg = new SAMMessage();

?>

示例 #2 Creating a message with a simple text payload

<?php

$msg = new SAMMessage('This is a simple text message');

?>

SAMMessage::header

The header properties of the message

说明

object$SAMMessage->header;

The header property is a container for any system or user properties that area associated with the message.

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.

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.

The SAM defined properties are as follows:

Property name Possible values
SAM_MESSAGEID 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.
SAM_REPLY_TO A string providing the identity of the queue on to which responses to this message should be posted.
SAM_TYPE

An indication of the type of message to be sent. The value may be SAM_TEXT indicating the contents of the message body is a text string, or SAM_BYTES indicating the contents of the message body are some application defined format.

The way in which this property is used may depend on the underlying messaging server. For instance a messaging server that supports the JMS (Java Message Service) specification may interpret this value and send messages of type "jms_text" and "jms_bytes". In addition, if the SAM_TYPE property is set to SAM_TEXT the data provided for the message body is expected to be a UTF8 encoded string.

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:

示例 #1 Setting a text format property using the default syntax

<?php
$msg = new SAMMessage();

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

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:

示例 #2 Setting a text format property using a type hint

<?php
$msg = new SAMMessage();

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

When passing a type hint the type entry should be one of the SAM defined constant values as defined by the following table:

ConstantType description
SAM_BOOLEANAny 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.
SAM_BYTEAn 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.
SAM_DOUBLEA 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.
SAM_FLOATA 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.
SAM_INTAn 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.
SAM_LONGAn 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.
SAM_STRINGSAM will interpret the property value specified as a string and pass it to the messaging system accordingly.

范例

示例 #3 Setting properties as the sender of a message

<?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);
?>

示例 #4 Retreiving property values from a message

<?php

// accessing an application specific property
$intProp = $msg->header->MyIntProp;

// accessing a messaging system specific property
$encoding = $msg->header->JMS_IBM_Msgtype;

?>

参见

目录