El API Java para Mensajes XML (JAXM) proporciona una forma est�ndard para enviar mensajes sobre Internet desde la plataforma Java. Est� basado en las especificaciones SOAP 1.1 y SOAP con Attachments y puede extenderse para trabajar con protocolos de alto nivel como ebXML o BizTalk.
Para poder hacer mensajer�a JAXM, un negocio usa un servicio de proveedor de mensajer�a, que hace el trabajo detr�s de la escena requerido para transportar y enrutar los mensajes. El proveedor de mensajer�a implementa el API JAXM, de forma similar a como un driver para una base de datos implementa el API JDBC. Todos los mensajes JAXM van a trav�s del proveedor de mensajer�a, por eso cuando un negocio env�a un mensaje, el mensaje primero va a los emisores del proveedor de mensajer�a, luego a los recipientes del proveedor de mensajer�a, y finalmente al recipiente destino. Tambi�n es posible enrutar un mensaje para que vaya directamente a los recipientes, llamados actors, antes de �r a su �ltimo destino.
Como todos los mensajes van a trav�s de �l, un proveedor de mensajer�a puede tener cuidado de los detalles como la asignaci�n de identificadores de mensajes y de seguir la pista de si un mensaje hab�a sido enviado antes. Un proveedor de mensajer�a tambi�n puede intentar reenviar un mensaje que no ha alcanzado su destino en el primer intento de env�o. Lo bonito de un proveedor de mensajer�a es que el cliente que usa la tecnolog�a JAXM ("cliente JAXM") est� totalmente despreocupado de lo que el proveedor est� haciendo en segundo plano. El cliente JAXM simplemente hace llamadas a m�todos de JAXM, y el proveedor de mensajer�a, trabajando con el contenedor, si existe uno, hace que todo suceda.
Aunque no es necesario, la mensajer�a JAXM normalmente tiene lugar dentro de un contenedor, generalmente un servlet o un contenedor J2EE. Una de las ventajas de estar en un contenedor es que podemos tener oyentes, lo que hace posible recibir mensajes de forma as�ncrona. El oyente recibe el mensaje como una operaci�n, y el recipiente env�a una respuesta como una operaci�n subsecuente, lo que hace la mensajer�a as�ncrona. Cuando no hay oyentes, los mensajes se env�an mediante un m�todo que se bloquea hasta que obtiene una respuesta. Esta clase de mensajer�a es s�ncrona, lo que significa que enviar un mensaje y recibir una respuesta son una operaci�n cont�nua y que nada sucede hasta que la operaci�n se haya completado.
Un mensaje JAXM se compone de dos partes, un parte SOAP obligatoria y una parte attachment opcional. La parte SOAP, que consta de un objeto SOAPEnvelope que contiene un objeto SOAPHeader y un objeto SOAPBody, puede contener un documento XML como el contenido de el mensaje que est� siendo enviado. Si queremos enviar varios documentos o contenidos que no sean un documento XML, nuestro mensaje necesitar� contener una parte de attachment. No hay limitaci�n en el contenido de la parte attachment, por eso podemos enviar im�genes o cualquier otra clase de contenido.
�Crear un Mensaje
�Obtener una Conexi�n a un Proveedor de Mensajer�a
Lo primero que un cliente JAXM debe hacer es obtener una conexi�n a su proveedor de mensajer�a. Usamos la conexi�n para crear un objeto MessageFactory, que luego puede usarse para crear objetos Message. Una vez que se ha rellenado el mensaje, se usar� de nuevo la conexi�n para env�ar el mensaje.
El siguiente c�digo demuestra la obtenci�n de una factor�a de mensajes y su uso para crear una conexi�n. Las primeras dos l�neas usan el API JNDI para recuperar el objeto ConnectionFactory apropiado desde el servicio de nombres donde fue registrado con el nombre "CoffeeBreakProvider". Cuando este nombre l�gico se pasa como un argumento, el m�todo lookup devuelve el objeto ConnectionFactory al que se uni� el nombre l�gico. El valor devuelto es un Object Java, que debe ser dirigido a un objeto ConnectionFactory para que se pueda utilizar para crear una conexi�n. La tercera l�nea usa un m�todo JAXM para obtener realmente la conexi�n:
Context ctx = getInitialContext();
ConnectionFactory cf = (ConnectionFactory)ctx.lookup("CoffeeBreakProvider");
Connection con = cf.getConnection();
El ejemplar Connection con representa una conexi�n al proveedor de mensajer�a "The Coffee Breaks". En las siguientes l�neas de c�digo, se usa para crear un objeto MessageFactory, que luego es usado para crear un objeto Message:
MessageFactory messageFactory = con.getMessageFactory(); Message m = messageFactory.createMessage();
Parte de la flexibilidad del API JAXM es que permite especificar un uso para una cabecera SOAP. Por ejemplo, los protocolos ebXML o BizTalk pueden construirse sobre mensajer�a SOAP. Este uso de SOAP mediante uno grupo de est�ndars o industriales dado se llama un "perfil" (profile). Si se da el m�todo getMessageFactory sin argumentos, como se hizo en el fragmento de c�digo anterior, devolver� un objeto MessageFactory que produce un mensaje que usa el perfil base SOAP. As�, el objeto Message m creado en la l�nea de codigo anterior soportar� un mensaje SOAP b�sico. Si se le pasa un perfil al m�todo getMessageFactory, los objetos Message creados por el objeto MessageFactory resultante soportar�n el perfil especificado. Por ejemplo, en el siguiente fragmento de c�digo, m2 soportar� el perfil que se suministr� a getMessageFactory:
MessageFactory messageFactory2 = con.getMessageFactory(<profile>); Message m2 = messageFactory2.createMessage();
Cada uno de los nuevos objetos Message m y m2 contienen autom�ticamente el objeto SOAPPart requerido, pero sus cabeceras no tienen ning�n contenido todav�a. Las siguientes secciones ilustran las formas t�picas para a�adir contenido.
�Rellenar un Mensaje
Hay dos formas para a�adir contenido a un mensaje:
- Pasar un objeto javax.xml.transform.Source al objeto SOAPEnvelope. El objeto Source puede ser un SAXSource, un DOMSource, o un StreamSource. Este objeto contiene el contexto para el mensaje y tambi�n la informaci�n necesaria para actuar como una fuente de entrada. Un objeto StreamSource contendr� el contenido como un documento XML; los objetos SAXSource o DOMSource contendr�n contenido e instrucciones para transformarlo en un documento XML.
- Crear elementos separados conteniendo el contenido y a�adi�ndolos individualmente. En este caso, construimos un document XML, usando objetos String, COMMENT, y CDATA seg�n sea necesario.
�Rellenar la Parte SOAP de un Mensaje
Como se explic� antes, todos los mensajes creados con un objeto SOAPPart, que tiene un objeto SOAPEnvelope contienen un objeto SOAPHeader y otro SOAPBody. Una forma de a�adir contenido a la parte SOAP de un mensaje es crear un objeto SOAPHeaderElement o un SOAPBodyElement y a�adir un documento XML que hemos construido con objetos String, COMMENT, y CDATA. Otra forma es a�adir contenido al objeto SOAPEnvelope pas�ndole un objeto javax.xml.transform.Source, que podr�a ser un objeto SAXSource, un DOMSource, o un StreamSource.
El siguiente fragmento de c�digo ilustra c�mo a�adir contenido como un objeto StreamSource. El primer paso siempre es obtener el objeto SOAPPart desde el objeto Message y usarlo para obtener un objeto SOAPEnvelope:
SOAPPart soapPart = m.getSOAPPart(); SOAPEnvelope soapEnvelope = soapPart.getSOAPEnvelope();
Luego el c�digo construye el documento XML a a�adir. Usa un objeto DocumentBuilderFactory para obtener un objeto DocumentBuilder. Luego analiza el fichero dado para producir el documento que se usar� para inicializar el objeto newDOMSource. Finalmente, el c�digo pasa el objeto DOMSource domSource al objeto SOAPEnvelope:
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
DocumentBuilder db = dbf.newDocumentBuilder();
Document doc = db.parse("file:///foo.bar/soap.xml");
DOMSource domSource = new DOMSource(doc);
soapEnvelope.setContent(domsrc);
�Rellenar la Parte de Attachment de un Mensaje
Un objeto Message podr�a no tener parte attachment, pero si tiene algo que no sea un documento XML, debe tener una parte attachment. Podr�a haber cualquier n�mero de partes attachment, y podr�an contener cualquier cosa, desde texto plano (incluyendo documento XML) a ficheros de im�genes. En el siguiente fragmento de c�digo, el contenido es una imagen en un fichero JPEG, cuya URL se usa para inicializar el objeto javax.activation.DataHandler dh. El objeto Message m crea el objeto AttachmentPart attachPart, que es inicilizado con el DataHandler que contiene la URL de la imagen. Finalmente, el mensaje se a�ade attachPart a s� mismo:
URL url = new URL("http://foo.bar/img.jpg");
DataHandler dh = new DataHandler(url);
AttachmentPart attachPart = m.createAttachmentPart(dh);
m.addAttachmentPart(attachPart);
�Enviar un Mensaje
Una vez que hemos rellenado el objeto Message, estamos preparados para enviarlo usando un objeto Connection (una conexi�n a nuestro proveedor de mensajer�a). Si la mensajer�a es as�ncrona, es decir, se hace en el contexto de un contenedor como un Servlet o un contenedor J2EE, se env�a usando el m�todo send. Si la aplicaci�n que env�a el mensaje no se est� ejecutando en un contenedor, lo que significa que la mensajer�a es s�ncrona, se usa el m�todo call. Los par�metros para �mbos m�todos son (1) el objeto Message que est� siendo enviado y (2) el objeto Endpoint que representa el destino al que se est� enviando. El siguiente fragmento de c�digo envia el mensaje as�ncronamente porque usa el meodo send. Crea un objeto Endpoint endPoint desde una URI para el recipiente deseado y luego pasa los objetos endPoint y m al m�todo send:
Endpoint endPoint = new Endpoint("http://foo.bar/Service");
con.send(m, endPoint);
Si nuestra aplicaci�n no se est� ejecutando en un contenedor, necesitamos usar el m�todo call para enviar el mensaje. Este m�todo toma los mismos par�metros que el m�todo send, pero, al contraro que �l, se bloquea hasta que recibe una respuesta, como se muestra en la siguiente l�nea de c�digo:
Message reply = con.call(m, endPoint);