Transformación

WSO2 EI Tutorial: Message transformers and builders

Descripción de Message transformers and Builders

Hoy vamos a hablar de los Message builders and formatters, una parte esencial del funcionamiento del Enterprise Integrator (EI).

Ambos elementos nos permiten transformar y manejar el mensaje de entrada, a través de los builders, o de salida, a través de los formatters, de forma automática. El Enterprise Integrator tomará como base la cabecera ‘Content-type’ y en base a ella realizará una traducción u otra del mensaje. La traducción se llevará a cabo antes y después de que se realice la mediación del mismo, como se explica en el siguiente gráfico:

MESSAGE TRANSFORMERS

Para el caso de un message builder podemos ver un ejemplo de su funcionamiento si indicamos un ‘Content-type’ de tipo ‘application/xml’ o ‘application/json’ y enviar un mensaje del otro tipo. En dicho caso ocurrirá un error interno en el EI, ya que este intentaría transformar un mensaje de un tipo, cuando se le ha indicado que es otro concreto. Si pusiéramos el ‘Content-type’ correcto, realizaría la transformación del mensaje correctamente y lo incluiría dentro del cuerpo del mensaje SOAP.

Para el caso de los message transformer podemos ver su funcionamiento con el siguiente ejemplo práctico. En el tenemos una secuencia de salida que generará un mensaje en formato XML a través de un payloadFactory mediator, pero antes de enviar de vuelta dicho mensaje, cambiamos el ‘Content-type’ a ‘application/json’.

Secuencia de salida:

<sequence name="exitJSON" xmlns="http://ws.apache.org/ns/synapse">
     <payloadFactory media-type="xml">
       <format>
          <exit>
            <valueType>JSON</valueType>
          </exit>
       </format>
      </payloadFactory>
      <property name="messageType" scope="axis2" type="STRING" value="application/json"/>
      <property name="ContentType" scope="axis2" type="STRING" value="application/json"/>
      <send/>
</sequence>

Tras salir de la secuencia entrará en funcionamiento el ‘Message Formatter’ correspondiente y por tanto veríamos el mensaje en un formato JSON. Salida:

{ “exit”: { “valueType”: “JSON” } }

Transformaciones base en el producto

Estos elementos se encuentran configurados en el fichero ‘${EI_HOME}/conf/axis2/axis2.xml’, dentro de sus apartados correspondientes (elementos XML messageBuilders y messageFormatters respectivamente). Y por defecto el EI ya vendrá con determinados ‘Content-type’ base configurados, estos son:

  • application/octet-stream
  • application/x-www-form-urlencoded
  • application/json
  • application/xml
  • multipart/form-data
  • text/plain
  • application/soap+xml : unicamente para messageBuilders
  • text/xml : unicamente para messageBuilders

Cada uno de ellos está asociado a una clase Java que realizará la transformación correspondiente. Y en el caso de que indiquemos como salida algún otro ‘Content-type’, tal como hemos visto puede provocar un error dentro de nuestra integración.

Para evitar cosas de este tipo, podemos configurar nuevos elementos XML messageBuilders y/o messageFormatters dentro del fichero ‘axis2.xml’ asociados a los ‘Content-type’ que queramos que sean tratados por el Enterprise Integrator.

Transformaciones sin ‘Content-type’ asociado

El EI también nos permite configurar elementos XML messageBuilders y/o messageFormatters para los casos en que el ‘Content-type’ no venga incluido. Así podemos dar un tratamiento por defecto y evitar respuestas tratadas incorrectamente. Lo configuraremos en el fichero ‘axis2.xml’ siguiendo estos pasos:

  • Incluyendo el parámetro ‘defaultContentType’ con el valor ‘empty/content’
  • Incluyendo un nuevo elemento XML messageBuilders asociado el ‘Content-type’ ‘empty/content’ y a la clase de transformación que deseemos (puede ser cualquiera de las ya configuradas a otros messageBuilders).
  • Incluyendo un nuevo elemento XML messageFormatters asociado al ‘Content-type’ ‘empty/content’, y a la clase que nos permita transformar el mensaje como deseemos.

Transformaciones adoc

Por otro lado, al igual que podemos configurar determinadas transformaciones a distintos mensajes con un ‘Content-type’ concreto. Es posible que las actuales clases de transformación existentes no sean suficientes, y tengamos una necesidad concreta y no cubierta por defecto para un determinado ‘Content-type’. Como solución podemos crear nuestro ‘Message Builders’ o ‘Message Formatters’ propios. Para ello, debemos crear clases Java que implementan las interfaces ‘org.apache.axis2.builder.Builder’ o ‘org.apache.axis2.transport.MessageFormatter’, incluyendo las librerías que contengan dichas clases y configurar los elementos específicos en el fichero ‘axis2.xml’.

Evitar la transformación

Por último, indicar que también es posible indicar al EI que un determinado ‘Content-type’ no sea tratado por el ESB. Para ello debemos configurar en el fichero ‘axis2.xml’ el ‘Content-type’ deseado con la clase ‘org.wso2.carbon.relay.BinaryRelayBuilder’ para los ‘Message Builders’ o ‘org.wso2.carbon.relay.ExpandingMessageFormatter’ para los ‘Message Formatters’.

Esta puede ser una buena práctica en el caso de que tengamos una API con múltiples recursos, en los cuales se muestra la información con distintos formatos de ficheros. Si queremos que estos sean tratados como binarios y que sea el navegador el encargado de abrirlos adecuadamente, podremos configurar cada ‘Content-type’ según los ‘Message Builders’  o ‘Message Formatters’ indicados arriba.

Con todo esto hemos aprendido un poco más sobre el funcionamiento de una de los aspectos básicos para la integración de datos y sistemas: la transformación de los distintos mensajes dentro del bus de datos.

daniel blanco
Written By

Daniel Santiago Blanco Cuadrado

Senior Integration Engineer