El API Apache SOAP v2.2

La distribuci�n Apache-SOAP puede ser instalada para usarse como cliente o como servidor. Este documento proporciona instrucciones de instalaci�n para �mbos casos.

Nota importante para los usuarios que est�n actualizando versiones anteriores de Apache SOAP:

Si estamos actualizado desde una versi�n anterior de Apache SOAP debemos asegurarnos de eliminar todos los ficheros class almacenados en el cach�, ficheros DeployedServices.ds etc. u obtendremos una variedad de extra�os errores. Si desplegamos Apache SOAP usando una applicaci�n Web, tambi�n se debe eliminar cualquier viejo WAR expandido. Los servicios desplegados dentro de la viejas versiones no pueden ser transferidos autom�ticamente a la nueva versi�n. Es decir, el viejo fichero DeployedServices.ds no puede ser le�do por esta nueva versi�n. Pedimos perdon por adelantado por los problemas que esto causar� a algunos usuarios. Si de hecho est�mos actualizando desde un vieja versi�n de Apache SOAP y obtenemos alguna divertida, excepci�n o comportamiento que no parezca usual, lo m�s probable es que el problema sea debido a una interacci�n inesperada con el c�digo de la vieja versi�n. Debemos hacer limpieza e intentarlo de nuevo o intentar instalar en un entorno virgen.

.�Desempaquetar la Distribuci�n

Asumimos que has descargado la distribuci�nbinaria de Apache-SOAP y has extraido el archivo en el directorio /foo. As�, los ficheros de la distribuci�n est�n en el directorio/foo/soap-2_2/.

Observa que si est�s en una m�quina Win32 deber�as reemplazar "/" con "\" cuando sigas estas instrucciones.

.�Instrucciones del Lado del Cliente

Nuestro classpath debe cotener /foo/soap-2_2/lib/soap.jar y lo siguiente:

  • mail.jar desde JavaMail
  • activation.jar desde JavaBeans Activation Framework
  • Un JAXP compatible, que tenga en cuenta los espacios de nombres XML, como Apache Xerces (v1.1.2 o posterior). Si tenemos otros analizadores XML que no tienen en cuentas los espacios en nombre en nuestro calsspath entonces el analizador que tenga en cuenta los espacios de nombres debe estar el primero en el classpath. De otro modo Apache SOAP no funcionar�.

Adicionalmente, para ejecutar los ejemplos que vienen con la distribuci�n, a�adimos /foo/soap-2_2 a nuestro classpath.

.�Instrucciones del Lado del Servidor

Necesitamos asegurarnos de que el classpath del servidor cotiene todos los componentes de arriba. Adem�s, para implementar servicios en lenguajes de script (como el ejemplo de la calculadora), a�adimos bsf.jar desde BSF y js.jar desde Rhino a nuestro classpath.

Para instalar el lado del servidor de Apache-SOAP, necesitamos un servidor de aplicaciones Web que soporte servlets y JSPs (tambi�n si queremos ejecutar el cliente admin).

Instalar el enrutador de servlets y el cliente admin: Las instrucciones de c�mo instalar vr�an de unos servidores de aplicaciones a otros. Aqu� tenemos algunas instrucciones para los servidores m�s populares:

.�Apache Tomcat v3.2

IMPORTANTE:

Tomcat viene con un analizador XML (lib/xml.jar) que tiene los interfaces DOM nivel 1. Incluso si ponemos xerces.jar de Xerces 1.1.2 en nuestro classpath, cualquier c�digo Java que se ejecute en Tomcat encontrar� los interfaces err�neos porque el fichero shell/batch que ejecuta Tomcat pone el classpath del usuario al final. Por eso, debemos editar tomcat.sh o tomcat.bat en el directorio bin/ y poner xerces.jar al principio del classapth.

Si ejecutamos startup.bat, la l�nea 105 (m�s o menos) de tomcat.bat se deber�a parecer a esta (l�nea 69 para Tomcat 3.2.1) :

set CP=path-to-xerces\xerces.jar;%CLASSPATH%;%CP% 

Si ejecutamos startup.sh, a�adimos la siguiente l�nea a tomcat.sh despu�s de la l�nea 113 (m�s o menos), siempre que est� antes de la l�nea export:

CLASSPATH=path-to-xerces/xerces.jar:${CLASSPATH}

Desplegar Apache-SOAP sobre Tomcat:

Hay dos formas diferentes en las que desplegar realmente Apache SOAP sobre Tomcat:

  • M�todo 1: Desplegar el archivo Web.

    La distribuci�n Apache SOAP incluye un archivo Web en /soap-2_2/webapps/soap.war. Simplemente arrastrando este archivo al directorio webapps de Tomcat (por ejemplo: %tomcat_home%/webapps). Si desplegamos Apache SOAP en Tomcat de esta forma, no necesitareos tener nada del directorio /soap-2_2 en el classpath de nuestro servidor (los �tems importantes est�n includios en el archivo Web).

    Nota:
    Si copiamos el archivo web en el directorio webapps mientras Tomcat se est� ejecutando. Tendremos que reiniciar Tomcat antes de poder acceder a la aplicaci�n Web Apache SOAP.

    Debemos tener en mente que si queremos reemplazar una aplicaci�n Web Apache SOAP desplegada, con una versi�n posterior probablemente tendremos que apagar el servidor, eliminar el directorio expandido %tomcat_home%/webapps/soap, y reemplazar el fichero %tomcat_home%/webapps/soap.war con el nuevo.

  • M�todo 2: Crear un nuevo <Context> en fichero server.xml de Tomcat.

    Simplemente a�adimos un nuevo elemento <Context> dentro de %tomcat_home%/conf/server.xml:

    
    <Context path="/soap" docBase="path-to-apache-soap/webapps/soap" debug="1" reloadable="true"> 
    </Context>
    
    

    Ahora, nos aseguramos de tener los ficheros jar del directorio lib de esta distribuci�n en nuestro classpath y arrancamos Tomcat. Tambi�n, querremos tener en el classpath cualquier c�digo que queramos desplegar como servicios (por ejemplo /soap-2_2 si queremos desplegar algunos de los ejemplos incluidos).

Aceder al Contexto Apache SOAP:

Deber�amos poder desplegar servicios apuntando un navegador a:

http://hostname:port/soap/admin/

donde hostname es el host en el que se est� ejecutando Tomcat y port es el n�mero de puerto. El punto final SOAP para invocar servicios en este servidor es:

http://hostname:port/soap/servlet/rpcrouter 

.�BEA WebLogic Application Server v5.1

IMPORTANTE:

WebLogic viene con un analizador XML. Por eso, debemos editar startWeblogic.cmd o startWeblogic.sh en el directorio ra�z de weblogic y poner xerces.jar al principio de la variable de entorno WEBLOGIC_CLASSPATH.

Si ejecutamos startWeblogic.cmd, a�adimos lo sigueinte al principio de la selecci�n de WEBLOGIC_CLASSPATH en la l�nea 74:

path-to-xerces\xerces.jar;path-to-apache-soap\lib\soap.jar

Si ejecutamos startWeblogic.sh, a�andimos lo siguiente a la selecci�n de PRE_CLASSPATH en la l�nea 33:

path-to-xerces/xerces.jar:path-to-apache-soap/lib/soap.jar

La forma m�s simple de configurar WebLogic es:

  1. Copiar el directorio path-to-apache-soap/webapps/soap en el directorio path-to-weblogic-root/myserver/public_html. Despu�s de copiarlo la extructura de directorios se deber�a parecer a path-to-weblogic/myserver/public_html/soap/WEB-INF etc.
  2. A�adir las dos siguientes l�neas al fichero weblogic.properties -
    weblogic.httpd.register.soap/servlet/rpcrouter=org.apache.soap.server.http.RPCRouterServlet
    weblogic.httpd.initArgs.soap/servlet/rpcrouter=ServicesStore=DeployedServices.ds
    

Si queremos ejecutar los ejemplos de Apache-SOAP debemos asegurarnos de a�adirlos a WEBLOGIC_CLASSPATH o a PRE_CLASSPATH como se explica arriba.

Deber�amos poder desplegar servicios apuntando un navegador a:

http://hostname:port/soap/admin/

donde hostname es el host en el que se est� ejecutando WebLogic y port es el n�mero de puerto. El punto final SOAP para invocar servicios en este servidor es:

http://hostname:port/soap/servlet/rpcrouter 

.�BEA WebLogic Application Server v6.0

Instalar la aplicaci�n web soap

Copiamos /path-to-apache-soap/webapps/soap a nuestro directorio de aplicaciones. Por ejemplo: para instalarlo dentro de "mydomain" colocamos el directorio en: c:/bea/wlserver6.0/mydomain/application/soap

Poner el fichero soap.jar en el classpath de la aplicaci�n

  1. Creamos un directorio c:/bea/wlserver6.0/mydomain/application/soap/WEB-INF/lib
  2. Copiamos soap.jar a este directorio.

Acceder a la aplicaci�n web soap

Deber�amos poder desplegar servicios apuntando un navegador a:

http://hostname:port/soap/admin

donde hostname es el host en el que se est� ejecutando WebLogic y port es el n�mero de puerto. El punto final SOAP para invocar servicios en este servidor es:

http://hostname:port/soap/servlet/rpcrouter 

Opcionalmente, Cambiar a un nuevo analizador xerces

WebLogic 6.0 viene un analizador xerces. Si queremos usar nuestro propio xerces.jar tendremos que editar nuestro script de arranque, y asegurarnos de que el CLASSPATH tiene el xerces.jar al principio, para que esas clases sean cargadas en vez de las de weblogic.jar.

Opcionalmente, configurar el fichero soap.xml

Nota:
Por alguna raz�n yo tuve que configurar esto, si no obten�a un error escibiendo en el fichero .ds

  1. Configurar la aplicaci�n web para que apunte al fichero de configuraci�n soap.xml.

    Editamos el fichero web.xml y a�adimos otro par�metro de inicializaci�n (por ejemplo, c:\bea\wlserver6.0\config\mydomain\applications\soap\WEB-INF\web.xml)

     
    <init-param>
      <param-name>ConfigFile</param-name>
      <param-value>c:\BEA\wlserver6.0\config\mydomain\applications\soap\soap.xml</param-value>
    </init-param>
    
    
  2. Configurar el fichero soap.xml (por ejemplo. c:\BEA\wlserver6.0\config\mydomain\applications\soap\soap.xml)
     
    <!-- Sample Apache SOAP Server Configuration File -->
    <soapServer>
        <!-- This section defines the same thing you get if you don't -->
    	<!-- specify anything at all - aka the default                -->
    	<configManager value="org.apache.soap.server.DefaultConfigManager" >
    	<option name="filename" 
    		value="c:\BEA\wlserver6.0\config\mydomain\applications\soap\DeployedServices.ds" />
    	</configManager>
    </soapServer>
    
    

.�IBM WebSphere v3.5

Estas instrucciones asumen:

  • WinNT 4.0 (similar para otras plataformas)
  • WebSphere Advanced Edition 3.5 with fix pack 2
IMPORTANTE:

WebSphere viene con un analizador XML (WebSphere\AppServer\lib\xml4j.jar) que usa interfaces DOM de nivel 1. Incluso si ponemos xerces.jar en el classpath, se cargar�n los interfaces incorrectos porque WebSphere pone el classpath del usuario al fina�. Por eso debemos editar el fichero WebSphere\AppServer\bin\admin.config y poner xerces.jar al principio de la variable com.ibm.ejs.sm.adminserver.classpath=

Para Configurar un Servidor SOAP:

Desde el men� WebSphere del men� Inicio de NT:

  1. Lanzar "Start Admin Server" y esperar hasta que se complete.
  2. Lanzar "Administrator's Console".

Desde la Consola de Administraci�n:

  1. Console/Tasks/Create Application Server
    1. Selecionamos Web Applications: No necesitamos Enterprise Beans para SOAP. Luego
    2. Application Server Properties: selecionamos Application Server Name como "SOAP" (u otro nombre de nuestra elecci�n). Luego
    3. Application Server Start Option: "Do not start the server automatically after creating it". Luego
    4. Node Selection: seleccionamos nuestro nodo. Luego
    5. Select Virtual Host: seleccionamos "default_host". Luego
    6. Servlet Engine Properties: Aceptamos los valores por defecto. Luego
    7. Web Application Properties: Selecciomos Web Application Web Path a "/soap". Podemos usar culaquier otro path que nos guste, incluyedo el valor por defecto de WebSphere "/webapp/SoapWebApp", pero usar "/soap" mantiene las URLs sencillas y es como lo usamos en estas instrucciones. Luego
    8. Specify System Servlets: Enable JSP 1.0 or 1.1.
    9. Terminamos de crear la aplicaci�n de servidor SOAP.
  2. En la vista de �rbol, abrimos SoapWebApp, y seleccionamos la pesta�a Advanced:
    1. Cambiamos Document Root a "C:\install-dir\soap-2_2\webapps\soap".
    2. Seleccionamos el classpath a:
      • C:\XML\apache\soap-2_2\lib\soap.jar
      • C:\XML\apache\soap-2_2
      • C:\tools\BSF\lib\bsf.jar
      • C:\tools\BSF\lib\bsfengines.jar
      • C:\Tools\Rhino\js.jar
      • C:\Tools\Rhino\jstools.jar
      • nuestras clases de servidor SOAP, si existen.
  3. Console/Tasks/Add a Servlet
    1. Servlet: "No". No arrancamos el serivdor autom�ticamente despu�s de crearlo. Luego
    2. Servlet: Seleccionamos la aplicaci�n web "SOAPWebApp" para contener el servlet. Luego
    3. Servlet: Seleccionamos "create user-defined servlet". Luego
    4. Servlet:
      1. Seleccionamos el nombre del servlet a "rpcrouter"
      2. Seleccionamos el nombre de la clase del servlet a "org.apache.soap.server.http.RPCRouterServlet".
      3. A�adimos "default_host/soap/servlet/rpcrouter" al path web del servlet. Observa que s�lo necesitamos teclear "servlet/rpcrouter" en el d�alogo que aparece.
      Luego
    5. Servlet: Aceptamos los valores por defecto.
    6. Finalizamos
  4. Arrancamos el servidor "SOAP".

Podemos listar y desplegar servicios SOAP apuntando el navegador a:

http://hostname:port/soap/admin

Alternativamente, podemos desplegar servicios configurando nuestro classpath y usando:


java org.apache.soap.server.ServiceManagerClient 
     http://hostname:port/soap/servlet/rpcrouter 
     deploy <DeploymentDescriptor.xml>

El punto final para invocar a los servicios SOAP en este servidor es:

http://hostname:port/soap/servlet/rpcrouter

.�iPlanet Application Server 6.0

Desplegar la Aplicaci�n Web Apache SOAP

  1. Arrancar la Herramienta de Despliegue del Servidor de Aplicaci�n iPlanet
  2. Abrir el fichero soap.war desde la distribuci�n expandida de Apache SOAP. Este fichero est� localizado bajo soapinstalldir/webapps/soap.war. Cuando se nos pida a�adirlo al descritor de despliegue de iPlanet, pulsamos OK. Si se nos informa de que no se pueden resolver algunas referencias a clases, ignoramos el aviso ya que en el siguiente paso a�adiremos el soporte de las librer�as en el classpath.
  3. A�adimos el fichero soap.jar al �rea WEB-INF/lib/ del fichero WAR. De forma alternativa, podemos a�adir el fichero soap.jar al classapth de arranque del servidor de aplicaci�n.
  4. Grabamos el ficheros soap.war modificado.
  5. Desplegamos el m�dulo soap.war en el servidor de aplicaciones.

Una vez desplegada, la aplicaci�n Web est� instalada en el directorio installdir/APPS/modules/soap/ del servidor de aplicaciones. Si navegamos al directorio WEB-INF/classes/ de la aplicaci�n web desplegada, observaremos que las clases Java para los servicios de ejemplo de Apache SOAP se han incluido en la aplicaci�n Web.

A�adir Soporte para Librer�as en el Classpath del Servidor

Descargamos una copia de un JAXP compatible, un analizador XML que tenga en cuenta los espacios de nombres como Xerces, que se ha comprobado que funciona apropiadamente con SOAP 2.2.

Para evitar conflictos con el analizador XML empaquetado con el servidor de aplicaciones, debemos asegurarnos de que las librer�as del analizador JAXP compatible aparecen al inicio del classpath del servidor de aplicaciones.

Si estamos planeando ejecutar los ejemplo de Apache SOAP que tratan con el lenguajes de script del lado del servidor como JavaScript, tenemos que descargar las librer�as Bean Scripting Framework y Rhino JavaScript y a�adir los ficheros bsf.jar y js.jar al principio del classpath del servidor de aplicaciones.

Como mail.jar y activation.jar ya est�n presentes en el classpath del servidor de aplicaciones no necesitamos realizar ninguna configuraci�n especial para permitir que Apache SOAP acceda a estas librer�as.

Configuraci�n del Classpath sobre Windows.

Sobre Windows el servidor de aplicaciones usa la configuraci�n del CLASSPATH defina en el registro del servidor de aplicaciones. (Seleccionar la variable de entorno CLASSPATH de windows no afectar� a las selecciones usadas por el servidor de aplicaciones). Para modificar el registro:

  1. Ejecutamos kregedit, el editor de registro del servidor de aplicaciones.
  2. Navegamos hasta SOFTWARE\iPlanet\Application Server\6.0
  3. Seleccionamos Java\ClassPath y luego seleccionamos Edit->Modify para cambiar el valor.
  4. A�adimos los ficheros de Rhino js.jar (opcional), bsf.jar (opcional) y de Xerces al inicio del classpath:
    d:\rhino\js.jar;d:\bsf-2_2\lib\bsf.jar;d:\xerces-1_4_0\xerces.jar;...
    
  5. Reiniciamos el servidor de aplicaciones para recargar las selecciones del registro.

Configuraci�n del Classpath sobre UNIX (iPlanet Application Server 6.0 SP2)

Modificamos el script installdir/ias/bin/kjs para incluir el soporte de los ficheros jar. El script kjs arranca la JVM que contiene el contenedor de EJBs del servidor de aplicaciones.

installdir/ias/bin/kjs: 

	... 
	SOAP_CLASSES=/opt/rhino/js.jar:/opt/bsf-2_2/lib/bsf.jar:/opt/xerces-1_4_0/xerces.jar
	CLASSPATH=$SOAP_CLASSES:$THIRD_PARTY_JDBC_CLASSPATH:$GX_ROOTDIR/classes/java/jdbc20.jar: 
	$GX_ROOTDIR/classes/java/javax.jar:...

Reiniciamos el servidor de aplicaciones para recoger los cambios del classpath.

Configuraci�n del Classpath sobre UNIX (iPlanet Application Server 6.0 SP3)

En iPlanet Application Server 6.0 SP3 la selecci�n del classpath usada por el script kjs est� almacenada en una selecci�n de entorno com�n. Hacemos los cambios en la variable CLASSPATH de kjs:

installdir/ias/iasenv.ksh: 

... 
	# Union of all CLASSPATHS
	SOAP_CLASSES=/opt/rhino/js.jar:/opt/bsf-2_2/lib/bsf.jar:/opt/xerces-1_4_0/xerces.jar 
	export CLASSPATH=$SOAP_CLASSES:${TOMCAT_DIR}/jasper.jar:...

Reiniciamos el servidor de aplicaciones para recoger los cambios del classpath.

Probar la Instalaci�n de Apache SOAP

Accedemos a la siguiente URL para arrancar el interface administrativo:


http://<web server host>/NASApp/soap/admin/index.html

Accedemos a los Servlets RPC Router y Message Router desde las siguientes URLs:


http://<web server host>/NASApp/soap/servlet/rpcrouter

http://<web server host>/NASApp/soap/servlet/messagerouter 

Si nuestra instalaci�n de Apache SOAP es correcta, el navegador mostrar�:

SOAP (RPC|Message) Router
Sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.

Como el contenedor Web del servidor de aplicaciones no carga por defecto los ficheros index.html, debemos incluir el nombre de los ficheros index.html en las URLs. De otro modo, obtendremos GX Error en el navegador cuando intentemos acceder a URLs como NASApp/soap/admin/.

.�JRun 3.0

IMPORTANTE: JRun viene con un analizador XML, que por defecto oculta a Xerces y por lo tanto causa problemas con nuestra instalaci�n SOAP. Tendremos que seguir el paso 1 de abajo!

  1. Abrimos el fichero global.properties de JRun (en path-to-JRun/lib) y a�adimos el fichero xerces.jar al principio de la l�nea jrun.classpath. Aparecer� de esta forma:
    jrun.classpath=E:/xerces-1_2_3/xerces.jar;{jrun.rootdir}/lib/ext;{jrun.rootdir}/lib/jrun.jar;
    {jrun.rootdir}/lib/install.jar
    
  2. Vamos dentro de JMC, y seleccionamos la secci�n "Web Applications" de nuestro servidor (Yo uso JRun Default Server). Pulsamos sobre "deploy an application".
  3. Seleccionamos el directorio /webapps/soap de Apache-SOAP (bajo java/ en la distribuci�n fuente, o en el directorio ra�z de la distribuci�n binaria) en la caja "Servlet War File or Directory".
  4. Ponemos un nombre a la aplicaci�n (por ejemplo "xml-soap"), y una URL base (por ejemplo "/soap")
  5. Seleccionamos un directorio de despliegue (por ejemplo el directorio por defecto de JRun, m�s el nombre de la aplicaci�n, que puede ser C:/JRun/servers/default/xml-soap)
  6. Pulsamos "deploy"
    (en este punto deber�amos obtener un mensaje diciendo que la aplicaci�n se ha desplegado con �xito)
  7. Vamos al �rea "java settings" de nuestro servidor por defecto, y a�adimos el fichero jar de Apache-SOAP y el directorio base al classpath. Para la distribuci�n fuente, estos podr�an est�n en SOAPROOT/java/build/lib/soap.jar y SOAPROOT/java/build. Para la distribuci�n binaria, ser�an SOAPROOT/lib/soap.jar y SOAPROOT. Se deber�a parecer a esto (la distribuci�n fuente en D:/xml-soap):
    {jrun.rootdir}/servers/lib
    {jrun.server.rootdir}/lib
    D:/xml-soap/java/build/lib/soap.jar
    D:/xml-soap/java/build
    
  8. Reiniciamos el servidor. NOTA: debemos apagar y reiniciar tanto el servidor de adminstraci�n como el servidor por defecto para que tengan efecto los cambios que hemos hecho en el fichero global.propoerties. S�lo necesitamos hacer esto una vez.
  9. Probamos a acceder a http://localhost/soap/servlet/rpcrouter y vemos si obtenemos un mensajes "I can't do GET".

Si lo de arriba funcion�, sabemos que el servlets se ha instalado con �xito. Ahora deber�amos poder desplegar servicios apuntando nuestro navegador a:

 
http://localhost/soap/index.html

�Tu servidor de aplicaciones no est� listado? Ver las instrucciones para Tomcat (por ejemplo) te puede dar las ideas para hacerlo tu mismo. Sino, primero chequea la FAQ (http://xml.apache.org/soap/faq) y luego puedes preguntar en la lista de usuarios de Apache-SOAP; igual algui�n ha tenido tu mismo problema anteriormente. Puedes subscribirte en esta lista en http://xml.apache.org/soap/mail.html.

.�Probar la Instalaci�n del Lado del Servidor

Apuntamos nuestro navegador a:

	http://localhost:port/soap/servlet/rpcrouter

y a:

	http://localhost:port/soap/servlet/messagerouter

Donde port es 8080, o 4040, o cualquier otro puerto que est� escuchadno nuestro servidor HTTP particular. El navegador mostrar� esto:

    SOAP (RPC|Message) Router
    

Sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.

Si no vemos este mensaje, nuestro servidor no est� configurado correctamente. Si lo vemos, ahora sabemos a que URLs dirigir nuestro navegador.

COMPARTE ESTE ARTÍCULO

COMPARTIR EN FACEBOOK
COMPARTIR EN TWITTER
COMPARTIR EN LINKEDIN
COMPARTIR EN WHATSAPP