doc-fr/reference/sam/examples.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- EN-Revision: 1.4 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<chapter xml:id="sam.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.examples;
 <section xml:id='sam.connections'>
  <title>Connexions</title>
  <para>
   Afin d'exécuter des fonctions de messageries et de mise en file d'attente, une connexion
   doit être établie avec un serveur de messagerie en créant un objet SAMConnection et en
   appelant sa méthode "connect", avec quelques propriétés de connexion, afin de connecter
   le script PHP au serveur de messagerie. Pendant le temps où l'objet SAMConnection n'est
   pas détruit, la connexion sera maintenue et disponible. Tous les objets SAMConnection seront
   détruis lorsque le script PHP se terminera.
  </para>
  <para>
   Quelques propriétés par défaut peuvent être utilisées pour la connexion au serveur de
   messagerie mais le script PHP doit spécifier au minimum le protocole à utiliser.
  </para>
  <para>
   <example>
    <title>Création d'une connexion et connexion à un serveur de messagerie
     distant WebSphere MQSeries</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>
  <para>
   <example>
    <title>Création d'une connexion et connexion à un serveur distant WebSphere Application</title>
    <programlisting role='php'>
<![CDATA[
<?php
$conn = new SAMConnection();
$conn->connect(SAM_WPM, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging',
                              SAM_BUS => 'Bus1',
                              SAM_TARGETCHAIN => 'InboundBasicMessaging'));
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Création d'un connexion et connexion à un serveur MQTT</title>
    <programlisting role='php'>
<![CDATA[
<?php
$conn = new SAMConnection();
$conn->connect(SAM_MQTT, array(SAM_HOST => 'myhost.mycompany.com',
                               SAM_PORT => 1883));
?>
]]>
    </programlisting>
   </example>
  </para>
 </section>  <!-- xml:id=sam.connections -->

 <section xml:id='sam.messages'>
  <title>Messages</title>
  <para>
   Les messages envoyés et reçus depuis les files d'attente sont représentés par l'objet
   SAMMessage. L'objet SAMMessage contient le corps du message (s'il existe) ainsi que
   les propriétés des en-têtes associés au message. L'objet SAMMessage est soit fourni
   en tant que paramètre d'une opération sur un message, ou retourné comme résultat.
  </para>
  <para>
   <example>
    <title>Création d'un message avec un corps texte simple</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage('This is a simple text message');
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Les messages doivent avoir des propriétés d'en-têtes associés, qui permettent le contrôle
   du transport du message ou fournissent des informations futures sur l'application réceptrice.
   Par défaut, les propriétés des messages sont délivrées au système de messagerie sous la
   forme de chaînes de caractères et dans ce cas, peuvent être définies comme ceci :
  </para>
  <para>
   <example>
    <title>Définition d'une propriété de formatage de texte en utilisant la syntaxe par défaut</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg->header->myPropertyName = 'textData';
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Si vous voulez passer des informations sur le type, une syntaxe alternative peut être
   utilisée où la valeur et le type sont passés dans un tableau associatif :
  </para>
  <para>
   <example>
    <title>Définition d'une propriété en spécifiant le type</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg->header->myPropertyName = array(3.14159, SAM_FLOAT);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Les propriétés peuvent également être extraites depuis l'en-tête d'un message.
  </para>
  <para>
   <example>
    <title>Récupération d'une propriété depuis l'en-tête d'un message</title>
    <programlisting role="php">
<![CDATA[
<?php
$myProperty = $msg->header->myPropertyName;
?>
]]>
    </programlisting>
   </example>
  </para>
 </section>  <!-- xml:id=sam.messages -->

 <section xml:id='sam.operations'>
  <title>Opérations de messagerie</title>
  <para>
   Toutes les opérations de messagerie sont exécutées via des appels aux méthodes sur l'objet
   de connexion. Pour ajouter un message à la file d'attente, la méthode <literal>"send"</literal>
   est utilisée, tandis que pour obtenir un message depuis la file d'attente, la méthode
   <literal>"receive"</literal> est utilisée. D'autres méthodes offrent d'autres fonctionnalités
   comme la publication, la souscription ou encore le contrôle sur les transactions.
  </para>
  <para>
   <example>
    <title>Ajout d'un message à la file d'attente et réception de la réponse</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage('Ceci est un message texte simple');
$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));
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </section>  <!-- xml:id=sam.operations -->

 <section xml:id='sam.pubsub'>
  <title>Publication/Souscription à un sujet</title>
  <para>
   SAM permet d'envoyer des messages soit à la file d'attente, ou, pour WebSphere
   MQ et WPM, de publier/souscrire à des sujets. L'envoi à un sujet est spécifié
   à SAM de la façon habituelle, i.e. sous la forme 'topic://fred', plutôt que
   sous la forme 'queue://AQUEUE', utilisée pour une opération de point à point.
   Pour publier/souscrire, il est tout simplement nécessaire de spécifier le correct
   du courtier lors de l'appel à la méthode "connect" de l'objet SAMConnect et le
   sujet désiré dans l'argument de destination des appels aux méthodes "send" et
   "receive" de l'objet SAMConnect. L'interface PHP est cependant identique au
   model point à point.
  </para>
  <para>
   Par défaut, SAM crée des souscriptions non durables lors de l'utilisation des
   fonctionnalités de publication/souscription. Cela signifie que si l'application
   cliente est inactive lorsque les messages sont publiés sur un sujet, alors il
   ne les recevra pas lorsqu'il redemarrera. SAM permet également des souscriptions
   durables à un sujet lors de l'utilisation de WPM ou WebSphere. Le but de ces
   souscriptions est de permettre aux données d'être reçues par une application
   cliente même si le client n'est plus actif au moment où les données sont publiées.
  </para>
  <para>
   Les souscriptions durables sont spécifiées en utilisant l'appel à la méthode
   "suscribe" de l'objet SAMConnect. Cette méthode prend le sujet destinataire en
   tant qu'argument d'entrée et retourne l'identifiant de souscription qui pourra
   être utilisé lors des prochains appels à la méthode "receive". Lorsque la
   souscription n'est plus nécessaire, la méthode "unsubscribe" de l'objet
   SAMConnection dot être utilisée pour effacer la souscription.
  </para>
  <para>
   <example>
    <title>Création d'une souscription durable à un sujet</title>
    <programlisting role="php">
<![CDATA[
<?php

$subName = $conn->subscribe('topic://A');

if (!$subName) {
   echo "Échec de la souscription";
} else {
    # Souscription Ok
    // ...
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Souscription à un sujet en utilisant un serveur WebSphere Platform Messaging (WPM)</title>
    <programlisting role="php">
<![CDATA[
<?php
$conn = new SAMConnection();
// Note: Pour une publication/souscription sur un WPM, lors de la connexion, le nom du moteur de messagerie
// qui gère la souscription durable (SAM_WPM_DUR_SUB_HOME) doit être spécifié.
$conn->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 "Échec de la souscription";
} else {
    # Souscription Ok
   // ...
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Réception des données publiées en utilisant une souscription durable</title>
    <programlisting role="php">
<![CDATA[
<?php

$msg = $conn->receive($subName);
if ($msg) {
   echo "Réception d'un message Ok";
} else {
    echo "Échec de la réception";
}

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Effacement d'une souscription durable à un sujet</title>
    <programlisting role="php">
<![CDATA[
<?php

if (!$conn->unsubscribe($subName)) {
   echo "Échec lors de l'effacement de la souscription";
}

?>
]]>
    </programlisting>
   </example>
  </para>
 </section>  <!-- xml:id=sam.pubsub -->

 <section xml:id='sam.errors'>
  <title>Gestion des erreurs</title>
  <para>
   Toutes les méthodes SAMConnection qui fournissent un accès aux opérations
   de messagerie retourne &false; si une erreur survient durant le processus.
   En plus de cela, l'objet SAMConnection a deux propriétés, "errno" et "error",
   qui fournissent respectivement le numéro et la description de la dernière
   erreur survenue sur la connexion.
  </para>
  <para>
   <example>
    <title>Gestion d'une erreur depuis une méthode qui ne retourne aucun résultat</title>
    <programlisting role="php">
<![CDATA[
<?php
if (!$conn->commit()) {
    // Le commit a échoué !
    echo "Le commit a échoué : ($conn->errno) $conn->error";
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Gestion d'une erreur depuis une méthode qui retourne un résultat</title>
    <programlisting role="php">
<![CDATA[
<?php
$correlid = $conn->send('queue://send/test', $msg);

if (!$correlid) {
    //L'envoi a échoué !
    echo "L'envoi a échoué : ($conn->errno) $conn->error";
} else {
  /* ... */
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </section>  <!-- xml:id=sam.errors -->

</chapter>

<!-- 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
-->