archived-doc-es/reference/sam/SAMMessage/header.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0d604bbc9d3b741d53e7fac26f5b24c306751e9a Maintainer: regiemix Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id='sammessage.header' xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>SAMMessage::header</refname>
  <refpurpose>
   Las propiedades en la cabecera del mensaje.
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <fieldsynopsis><type>object</type><varname>SAMMessage->header</varname></fieldsynopsis>
  <para>
   La propiedad <literal>header</literal> es un contenedor para propiedades del sistema o
   usuario cuyo espacio es asociado con el mensaje.
  </para>
  <para>
   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.
  </para>
  <para>
   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".
  </para>
  <para>
   Las propiedades SAM definidas son las siguientes:
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Nombre de propiedad</entry>
       <entry>Valores posibles</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><constant>SAM_MESSAGEID</constant></entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry><constant>SAM_REPLY_TO</constant></entry>
       <entry>
        Un string con la identificación de la cola en la cual deben ser publicadas
        las respuestas a ese mensaje.
       </entry>
      </row>
      <row>
       <entry><constant>SAM_TYPE</constant></entry>
       <entry>
        <para>
         Una indicación del tipo de mensaje a enviar. El valor puede ser
         <constant>SAM_TEXT</constant> lo que indica que el contenido del
         cuerpo del mensaje es un string de texto, o <constant>SAM_BYTES</constant>
         que indica que los contenidos del cuerpo del mensaje son de un formato específico definido
         por la aplicación.
        </para>
        <para>
         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 <literal>JMS (Java Message Service)</literal> puede
         interpretar este valor y enviar mensajes del tipo "<literal>jms_text</literal>"
         y "<literal>jms_bytes</literal>". Adicionalmente, si la
         propiedad <constant>SAM_TYPE</constant> se define con el valor <constant>SAM_TEXT</constant>
         los datos proporcionados por el cuerpo del mensaje se espera que sea un string codificado en
         UTF8.
        </para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
  <para>
   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:
  </para>
  <para>
   <example>
    <title>Configurar una propiedad de formato de texto utilizando la sintaxis por defecto</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage();

$msg->header->myPropertyName = 'textData';
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Si se desea pasar información de tipo, se podría utilizar una sintaxis altenativa 
   donde el valor y la declaración del tipo se pasan en un array
   asociativo:
  </para>
  <para>
   <example>
    <title>Establecer una propiedad de formato de texto con una declaración de tipo</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage();

$msg->header->myPropertyName = array('textData', SAM_STRING);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Si se pasa una declaració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:
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Constante</entry>
       <entry>Descripción del tipo</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><constant>SAM_BOOLEAN</constant></entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry><constant>SAM_BYTE</constant></entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry><constant>SAM_DOUBLE</constant></entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry><constant>SAM_FLOAT</constant></entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry><constant>SAM_INT</constant></entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry><constant>SAM_LONG</constant></entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry><constant>SAM_STRING</constant></entry>
       <entry>
        SAM interpretará el valor especificado como un string y lo pasará
        de ese modo al sistema de mensajería.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Configuración de propiedades como el emisor de un mensaje</title>
    <programlisting role="php">
<![CDATA[
<?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 declaració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);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Recuperación de valores desde un mensaje</title>
    <programlisting role="php">
<![CDATA[
<?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;

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><xref linkend="sammessage.body" /></member>
   </simplelist>
  </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:"~/.phpdoc/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
-->