(PECL sam >= 0.1.0)
SAMMessage::header — Las propiedades en la cabecera del mensaje.
La propiedad header es un contenedor para propiedades del sistema o usuario cuyo espacio es asociado con el mensaje.
Las propiedades pueden ser asignadas por el emisor del mensaje para controlar la forma en la que los sistemas de mensajería tratan el mensaje o pueden ser asignadas por el propio sistema de mensajería para comunicarle al receptor información extra sobre el mensaje o sobre el modo en que éste ha sido tratado.
Algunas propiedades son interpretadas por SAM si las constantes se han definido para ello. Sin embargo, la mayoría de las propiedades son ignoradas por la implementación SAM y simplemente pasan a través de los sistemas de mensajería permitiendo a la aplicación utilizar nombres de propiedades específicos o definir sus propias propiedades de "usuario".
Las propiedades SAM definidas son las siguientes:
| Nombre de propiedad | Valores posibles |
|---|---|
SAM_MESSAGEID |
Cuando se recibe un mensaje, este campo contiene el identificador unívoco del mensaje tal y como ha sido asignado en el servidor de mensajería subyacente. Cuando se envía un mensaje este campo es ignorado. |
SAM_REPLY_TO |
Un string con la identificación de la cola en la cual deben ser publicadas las respuestas a ese mensaje. |
SAM_TYPE |
Una indicación del tipo de mensaje a enviar. El valor puede ser
La forma en la que esta propiedad se utiliza, puede depender del servidor de mensajería
subyacente. Por ejemplo un servidor de mensajería que soporta la
especificación JMS (Java Message Service) puede
interpretar este valor y enviar mensajes del tipo "jms_text"
y "jms_bytes". Adicionalmente, si la
propiedad |
Cuando se configuran los valores de las propiedades es útil a menudo dar una indicación del formato en el que la propiedad debe ser distribuida al sistema de mensajería. Por defecto, los valores de la propiedad se distribuyen como texto y la siguiente sintaxis simple puede utilizarse para configurar un valor:
Ejemplo #1 Configurar una propiedad de formato de texto utilizando la sintaxis por defecto
<?php
$msg = new SAMMessage();
$msg->header->myPropertyName = 'textData';
?>
Si se desea pasar información de tipo, se podría utilizar una sintaxis altenativa donde el valor y la indicación del tipo se pasan en un array asociativo:
Ejemplo #2 Configurar una propiedad de formato de texto indicando el tipo
<?php
$msg = new SAMMessage();
$msg->header->myPropertyName = array('textData', SAM_STRING);
?>
Si se pasa una indicación de tipo, el tipo de la entrada debe ser una de las constandes definidas por SAM según se recogen en la siguiente tabla:
| Constante | Descripción del tipo |
|---|---|
SAM_BOOLEAN |
Cualquier valor pasado será interpretado como un valor lógico, verdadero o falso. Si el valor no puede ser interpretado como un valor booleano PHP, el valor que se pasa al sistema de mensajería es indefinido. |
SAM_BYTE |
Un valor entero con signo de 8-bits. SAM intentará convertir el valor de la propiedad especificada en un valor de un byte para pasarlo al sistema de mensajería. Si se pasa un valor de tipo string, se intentará interpretar el string como un valor numérico. Si el valor numérico no puede ser expresado en un valor binario con signo de 8 bits los datos pueden perderse en la conversión. |
SAM_DOUBLE |
Un valor long de punto flotante. SAM intentará convertir el valor de la propiedad especificada en un valor de punto flotante con 15 dígitos de precisión. Si se pasa un valor de tipo string, se intentará interpretar el string como un valor numérico. Si el valor pasado no puede expresarse en un valor de punto flotante de 15 dígitos, los datos pueden perderse en la conversión. |
SAM_FLOAT |
Un valor short de punto flotante. SAM intentará convertir el valor de la propiedad especificada en un valor de punto flotante con 7 dígitos de precisión. Si se pasa un valor de tipo string, se intentará interpretar el string como un valor numérico. Si el valor pasado no puede ser expresado como un valor de 7 dígitos de punto flotante, los datos pueden perderse en la conversión. |
SAM_INT |
Un valor entero con signo de 32-bits. SAM intentará convertir el valor de la propiedad especificado, en un valor de 32 bits para pasarlo al sistema de mensajería. Si se pasa un valor de tipo string, se intentará interpretar el string como un valor numérico. Si el valor numérico no puede expresarse en un valor binario con signo de 32 bits, los datos pueden perderse en la conversión. |
SAM_LONG |
Un valor entero con signo de 64 bits. SAM intentará convertir el valor especificado en la propiedad en un valor de 64 bits para pasarlo al sistema de mensajería. Si se pasa un valor de tipo string, se intentará interpretar el string como un valor numérico. Si el valor numérico no puede expresarse como un valor binario con signo de 64 bits, los datos se pueden perder en la conversión. |
SAM_STRING |
SAM interpretará el valor especificado como un string y lo pasará de ese modo al sistema de mensajería. |
Ejemplo #3 Configuración de propiedades como el emisor de un mensaje
<?php
$msg = new SAMMessage('Este es un mensaje de test');
// definición de propiedades específicas SAM...
$msg->header->SAM_REPLY_TO = 'queue://test/replyQueue';
// definición de propiedades arbitrarias...
//
// una propiedad de tipo string por defecto
$msg->header->myStringProp1 = 'una propiedad de tipo string';
// una propiedad de tipo string con una indicación de tipo
$msg->header->myStringProp2 = array('otra propiedad de tipo string', SAM_STRING);
// una propiedad de tipo booleano
$msg->header->myBoolProp = array(FALSE, SAM_BOOL);
// propiedades de formato numérico
$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);
?>
Ejemplo #4 Recuperación de valores desde un mensaje
<?php
// acceso a propiedades específicas de aplicación
$intProp = $msg->header->MyIntProp;
// acceso a propiedades específicas del servidor de mensajería
$encoding = $msg->header->JMS_IBM_Msgtype;
?>