&reftitle.examples;
Conexiones
Para realizar las funciones de mensajería y encolado de los mensajes,
se debe establecer una conexión con un servidor de mensajería creando un objeto SAMConnection
y llamando a su método "connect" , con un conjunto de propiedades
de conexión, para conectar el script PHP script al servidor de mensajería. Durante
el tiempo que el objeto SAMConnection no sea destruído, la conexión
estará activa y disponible para ser utilizada. Todos los objetos SAMConnection
serán destruídos cuando el script PHP finalice.
Se utilizarán el conjunto de propiedades por defecto en la conexión a un servidor
de mensajería, pero el script PHP debe especificar como mínimo el protocolo que será
utilizado.
Creación de una conexión y conexión a un servidor de mensajería remoto WebSphere MQSeries
connect(SAM_WMQ, array(SAM_HOST => 'myhost.mycompany.com',
SAM_PORT => 1506,
SAM_BROKER => 'mybroker'));
?>
]]>
Creación de una conexión y conexión a un servidor remoto WebSphere Application Server
connect(SAM_WPM, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging',
SAM_BUS => 'Bus1',
SAM_TARGETCHAIN => 'InboundBasicMessaging'));
?>
]]>
Creación de una conexión y conexión a un servidor MQTT
connect(SAM_MQTT, array(SAM_HOST => 'myhost.mycompany.com',
SAM_PORT => 1883));
?>
]]>
Mensajes
Los mensajes enviados y recibidos de las colas, se representan por el objeto
SAMMessage. El objeto SAMMessage encapsula el cuerpo del
mensaje (si existe alguno) y las propiedades de cabecera asociadas al
mensaje. Un objeto SAMMessage es proporcionado como un parámetro a una operación de mensajería o
devuelto como un resultado.
Creación de un mensaje con un cuerpo de texto simple
]]>
Los mensajes deben tener las propiedades de cabecera asociadas, lo que permitirá tener
control sobre el transporte del mensaje o información futura sobre la
aplicación receptora. Por defecto las propiedades del mensaje se distribuirán al
sistema de mensajería como strings y en ese caso pueden ser
definidas con la siguiente sintaxis sencilla:
Definición de una propiedad de formateado de texto utilizando la sintaxis por defecto
header->myPropertyName = 'textData';
?>
]]>
Si se desea pasar la información de tipo, se puede utilizar
una sintaxis alternativa, donde el valor y la declaración de tipo son pasados en un array
asociativo:
Establecer una propiedad empleando una declaración de tipo
header->myPropertyName = array(3.14159, SAM_FLOAT);
?>
]]>
Las propiedades también pueden extraerse de la cabecera del mensaje.
Recuperación de una propiedad desde la cabecera del mensaje
header->myPropertyName;
?>
]]>
Operaciones de mensajería
Todas las operaciones de mensajería se realizan a través de llamadas a métodos sobre el
objeto de conexión.
Para añadir un mensaje a una cola se utiliza en método "send" , para obtener un
mensaje de una cola se utiliza el método "receive". Otros métodos
proporcionan otras funcionalidades como la publicación, suscripción o el control
sobre las transacciones.
Añadir un mensaje a una cola y recibir una respuesta
header->SAM_REPLY_TO = 'queue://receive/test';
$correlid = $conn->send('queue://send/test', $msg);
if (!$correlid) {
// El Send falló!
echo "Send fallido ($conn->errno) $conn->error";
} else {
$resp = $conn->receive('queue://receive/test', array(SAM_CORRELID => $correlid));
}
?>
]]>
Publicar/Suscribir y suscripción a temas (topics)
SAM permite enviar mensajes a colas, o para WebSphere MQ
y WPM, publicar/suscribir temas.
El envío a un tema es especificado por SAM de la manera habitual, p.e. de la
forma 'topic://fred', mejor que de la forma 'queue://AQUEUE' utilizada para
operaciones punto a punto. Para publicar/suscribir únicamente es
necesario especificar el nombre del broker correcto en la llamada al método "connect"
del objeto SAMConnect y el tema deseado en el argumento de destino de las llamadas
a los métodos "send" y "receive" del objeto SAMConnect. La interface PHP es
sin embargo idéntica al modelo punto a punto.
Por defecto, SAM crea suscripciones no duraderas cuando se utiliza
publicar/suscribir. Esto significa que si una aplicación cliente está
inactiva cuando los mensajes se publiquen en un tema, entonces esta aplicación no
los recibirá cuando sea reactivada. SAM también permite realizar
suscripciones duraderas a temas cuando se usa el publicar/suscribir de WPM o WebSphere
MQ. El objetivo de estas suscripciones es permitir
que los datos sean recibidos por una aplicación cliente incluso si este cliente no estaba
activo en el momento de publicación de los datos.
Las suscripciones duraderas se especifican utilizando el método "subscribe"
del objeto SAMConnect. Este método toma el tema de destino como un parámetro de entrada y
devuelve un identificador de suscripción que puede ser utilizado en siguientes
llamadas "receive". Cuando la suscripción ya no se necesita, debe utilizarse el
método "unsubscribe" del objeto SAMConnection para eliminar la
suscripción.
Creación de una suscripción duradera a un tema
subscribe('topic://A');
if (!$subName) {
echo "Subscribe fallido";
} else {
# Subscribe OK
// ...
}
?>
]]>
Suscripción a un tema utilizando un servidor WebSphere Platform Messaging (WPM)
connect(SAM_WMQ, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging',
SAM_BUS => 'Bus1',
SAM_TARGETCHAIN => 'InboundBasicMessaging',
SAM_WPM_DUR_SUB_HOME => 'MyMachineNode01.server1-Bus1'));
$subName = $conn->subscribe('topic://A');
if (!$subName) {
echo "Subscribe fallido";
} else {
# Subscribe OK
// ...
}
?>
]]>
Recepción de datos publicados utilizando una suscripción duradera
receive($subName);
if ($msg) {
echo "Mensaje recibido OK";
} else {
echo "El receive falló";
}
?>
]]>
Eliminación de una suscripción duradera a un tema
unsubscribe($subName)) {
echo "Unsubscribe fallido";
}
?>
]]>
Control de errores
Todos los métodos SAMConnection que proporcionan acceso a operaciones de mensajería
devuelven &false; en caso de error en el procesado de la petición.
Adicionalmente, el objeto SAMConnection tiene dos propiedades: "errno"
y "error", que proporcionan respectivamente el código y literal del
último error ocurrido en la conexión.
Control de errores de un método que no devuelve resultado
commit()) {
// El commit falló!
echo "Commit fallido ($conn->errno) $conn->error";
}
?>
]]>
Control de errores de un método que devuelve resultado
send('queue://send/test', $msg);
if (!$correlid) {
// El Send falló!
echo "Send fallido ($conn->errno) $conn->error";
} else {
/* ... */
}
?>
]]>