El API Apache SOAP v2.2

• Instalación de Apache SOAP v2.2
• Desempaquetar la Distribución
• Instrucciones del Lado del Cliente
• Instrucciones del Lado del Servidor
• Apache Tomcat v3.2
• BEA WebLogic Application Server v5.1
• BEA WebLogic Application Server v6.0
• IBM WebSphere v3.5
• iPlanet Application Server 6.0
• JRun 3.0
• Probar la Instalación del Lado del Servidor

Instalación de 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.

 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

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

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

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

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

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

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.