El API Apache SOAP v2.2

Escribir clientes para acceder a servicios basados en SOAP RPC es bastante sencillo. Apache SOAP proporciona un API del lado del cliente para asistirnos en la construcci�n de la solicitud SOAP, y luego asistirnos en la la interpretaci�n de al respuesta. Conceptualmente, los servicios basados en RPC son relativamente f�ciles de entender, porque lo conceptos implicados son aquellos que pueden encontrarse en cualquier lenguaje basado en procedimiento. Para invocar a un procedimiento, necesitamos su nombre y los par�metros a pasarle. Cuando la invocaci�n se completa, necesitamos extraer cualquier informaci�n de respuesta desde el valor de retorno y/o desde los par�metros de salida.

Los pasos b�sicos para crear un cliente que interact�e con un servicio basado en SOAP RPC son los siguientes:

1. Obtener la descripci�n del interface del servicio SOAP, para que podamos conocer las firmas de los m�todos que deseamos invocar.

   Podemos buscar un fichero WSDL (o alg�n otro formato de definici�n de interface) para el servicio, o directamente en su implementaci�n

2. Nos aseguramos de que hay serializadores registrados para todos los par�metros que deseamos enviar, y deserializadores para toda la informaci�n que recibiremos de vuelta.

   Los par�metros deben ser serializados/deserializados hacia/desde XML antes de poder ser transmitidos/recibido, y por eso Apache SOAP proporciona varios serializadores/deserializadores que est�n disponibles. Si necesitamos transmitir o recibir un tipo que no ha sido registrado, necesitamos escribir y registrar nuestro propio serializador/deserializador.

3. Creamos el objeto org.apache.soap.rpc.RPCMessage.Call.

   Este objeto es el interface principal para el c�digo RPC SOAP subyacente.

4. Seleccionamos la URI objetivo dentro del objeto Call usando el m�todo setTargetObjectURI(...).

   Pasado en la URN que el servicio es usado para identificarse a si mismo en su descriptor de despliegue.

5. Seleccionamos el nombre del m�todo que deseamos invocar dentro del objeto Call usando el m�todo setMethodName(...).

   Este debe ser uno de los m�todos expuestos por el servicio que est� identificado por la URN dada en el paso anterior.

6. Creamos cualquier objeto Parameter necesario para la llamada RPC y los seleccionamos dentro del objeto Call usando el m�todo setParams(...).

   Nos aseguramos de que tenemos el mismo n�mero de par�metros y del mismo tipo que est� esperando el servicio. Tambi�n nos aseguramos de que hay registrados serializadores/deserializadores para los objetos que van a ser transmitidos/recibidos (ver paso 2).

7. Ejecutamos el m�todo invoke(...) del objeto Call y capturamos el objeto Response que se devuelto desde invoke(...).

   El m�todo invoke(...) acepta dos par�metros, el primero es una URL que identifica el punto final en el que reside el servicio (por ejemplo, http://localhost/soap/servlet/rpcrouter) y el segundo es el valor situado en la cabecera SOAPAction. Recuerda que la llamada a RPC es s�ncrona, y que por eso puede tardar un poco en completarse.

8. Chequeamos el objeto Response para ver si se ha generado alg�n fallo usando el m�todo generatedFault().
9. Si ha ocurrido alg�n fallo, lo recuperamos usando el m�todo getFault(...), de otro modo extraemos cualquier resultado usando los m�todos getReturnValue() y getParams() respectivamente.

   Aunque la mayor�a de los proveedores s�lo devolver�n un resultado, si hemos creado nuestro propio proveedor (o hemos obtenido uno de alg�n lugar), tambi�n podr�a devolver par�metros de salida

Como se supone que SOAP es un est�ndard, deber�amos poder usar los clientes que creemos con el API Apache SOAP para acceder a servicios que se ejecutan en diferentes implemetnaciones, y viceversa.

�Nota Especial: Interact�ar con Servicios con Estado

Los servicios podr�an ser con estado - es decir, una vez que se ha empezado una interacci�n con un servicio, una ser�e de llamadas a �l podr�an ser independientes unas de las otras. Apache SOAP soporta servicios de autor�a con estado (mediante desplegar con un ciclo de vida de sesi�n) As� como llamando a servicios con estado. Actualmente el soporte de sesi�n s�lo est� disponible para HTTP.

El mantenimiento de sesi�n HTTP est� activo por defecto. Lo que significa que si un servicio con el que estamos hablando mediante HTTP selecciona las cookies HTTP apropiadas para mentener la sesi�n, est�s ser�n copiadas y almacenadas en el objeto Call, luego la cookie ser� enviada de vuelta al servidor, as� mentenemos la sesi�n. As�, todo lo que tenemos que hacer es asegurar que s�lo se usa un ejemplar del objeto Call a trav�s de las llamadas que deseamos hacer sobre la misma sesi�n HTTP.

El ejemplo "addressbook2" muestra un ejemplo de esto en acci�n.

�Nota Especial: Usar RPC sobre SMTP

Para hacer RPC sobre SMTP en Apache-SOAP se necesita tener disponible una cierta infraestructura de e-amil. Necesitamos un servidor SMTP, un servidor POP3 y una direcci�n de e-mail que podamos usar para ser el equivalente del router HTTP del lado del servidor. Es decir, todas las llamadas SOAP RPC son enviadas a una direcci�n espec�fia que procesa las solicitudes de alguna forma y env�a el resultado al emisor. Para evitar duplicidad de la infraestructura en el lado del servidor, hemos implementado el SMTP de lado del servidor como un puente que recibe los correos enviados a la direcci�n e-amil del router SOAP mediante POP3, postea el sobre SOAP a una infraestructura HTTP SOAP existente y env�a la respuesta de vuelta al emiso de la petici�n mediante SMTP.

En el lado del cliente, la aplicaci�n env�a la solicitud SOAP mediante SMTP a la direcci�n e-mail del router SOAP indicando la direcci�n a la que se deber�a enviar la respuesta. Luego, arranca un servidor POP3 para ver si la respuesta ha llegado. Cuando lo hace, el sobre es analizado y la respuesta es extra�da. Estamos usando un Bean POP3 de alphaWorks para el esqueleto POP3 y este bean no soporta descarga selectiva de e-mail. como resultado de la implementaci�n actual que trata sobre el "next message" que llega a la direcci�n de respuesta del cliente para ser un mensaje que contiene la respuesta a la solicitud. La implicaci�n es que la implementaci�n actual no permite que hagamos m�ltiples llamadas RPC usando la misma direcci�n de retorno al mismo tiempo.