sábado, 26 de agosto de 2006

Instalación de un servidor de web services

Introducción

Esta guía se refiere a la instalación de un servidor de web services basado en Apache Tomcat, con Java, y con una aplicación realizada con JBuilder 2006, con web services basados en el framework Axis. Si se utiliza otro IDE de desarrollo, debería ser muy similar, por lo que esta guía puede ser una base para adecuarse a las especificaciones concretas del IDE.

Las versiones aquí utilizadas son sólo recomendadas. Utilizar otra versión un poco reciente o un poco antigua debería, en teoría, funcionar sin problemas.

Esta guía se refiere a servidores en una plataforma Windows XP/2000/2003 Server, aunque los pasos deberían ser muy similares para máquinas Linux, con alguna particularidad del propio sistema operativo.

Esta guía es producto de varias instalaciones realizadas, y se ha optimizado los pasos y los requisitos de la instalación. El manual de instalación ha servido de base, pero se han omitido multitud de procesos que no eran necesarios, y adaptando otros a atajos.

Esta guía no es un tutorial para desarrollar web services. Se asume que el lector ha realizado su aplicativo de web services, y quiere realizar la instalación de un servidor en el que corran dichos web services.


Pasos

1. Instalación de Java
2. Instalación de Tomcat
3. Configuración variables de entorno del sistema
4. Comprobación funcionamiento de Apache Tomcat
5. Librerías necesarias
6. Instalación de nuestra aplicación de web services
7. Comprobar si la aplicación web está ejecutándose
8. Chequear nuestro sistema para ejecutar web services
9. Chequear el web service
10. Ejecutar el web service


1. Instalación de Java

Acceso a la página oficial de Java de Sun Microsystems

http://java.sun.com

Para acceder a la sección de descargas, click en el link “Java SE” en el módulo “Popular Download” (parte superior derecha)

Descargar el “Java Standard Edition Development Kit”. En mi caso he descargado “J2SE Development Kit 5.0 Update 8”, el cual está en el archivo

jdk-1_5_0_08-windows-i586-p.exe

Una vez descargado, ejecutar el programa e instalar Java. En mi caso, lo he instalado en el directorio

C:\jdk15008


2. Instalación de Tomcat

Acceso a la página de Tomcat

http://tomcat.apache.org/

Click en el link “Download Tomcat 4.1” (parte derecha en el módulo Downloads”. He descargado Apache Tomcat v4.1.31, que es la que utiliza JBuilder 2006. El fichero que descarga es el siguiente:

jakarta-tomcat-4.1.31-LE-jdk14.exe

Una vez descargado, ejecutar el programa y hacer estos pasos.

Using Java Development Kit found in c:\jdk15008 – Aceptar
No marcar NT Service (NT/2k/XP only) – Siguiente (si lo quieres como un servicio Tomcat que esté constantemente en tu máquina marca esta opción)
Destination folder: C:\tomcat4131 – Install
http/1.1 Connector Port: 8080
Administrator login. User name: admin – Password: admin


3. Configuración de variables de entorno del sistema

JAVA_HOME = C:\jdk15008
CLASSPATH = %JAVA_HOME%\lib
CATALINA_HOME = C:\tomcat4131



4. Comprobación funcionamiento de Apache Tomcat

Arrancar Tomcat: Inicio>Todos los programas>Apache Tomcat 4.1>Start Tomcat

Acceder a la siguiente URL desde tu navegador

http://127.0.0.1:8080/index.jsp

con lo que accederás a la página principal de Apache Tomcat, que será la señal de que Tomcat está funcionando.

Parar Tomcat: Inicio>Todos los programas>Apache Tomcat 4.1>Stop Tomcat


5. Librerías necesarias

AXIS

Axis es el framework que permite ejecutar web services en un servidor de aplicaciones. Debido a su arquitectura se ha convertido en un estándar, y es el principal que utiliza JBuilder (además del de Weblogic).

URL al site oficial de Axis:

http://ws.apache.org/axis/

URL a la zona de descargas:

http://people.apache.org/dist/axis/nightly/

Descargar el archivo:

axis-bin-1_4.zip

Descomprimir el archivo. Copiar todo el contenido de la carpeta axis-1_4\lib a C:\tomcat4131\common\lib. Los ficheros a copiar son:

axis.jar
axis-ant.jar
axis-schema.jar
commons-discovery-0.2.jar
commons-logging-1.0.4.jar
jaxrpc.jar
log4j-1.2.8.jar
log4j.properties
saaj.jar
wsdl4j-1.5.1.jar


6. Instalación de nuestra aplicación de web services

Hay que localizar los directorios y archivos a desplegar en Tomcat.

En el directorio del proyecto de nuestra aplicación (directorio de desarrollo en JBuilder) debe encontrarse el directorio WebModule creado por Tomcat. En mi caso, se llama WebModuleNeoGateway. Este directorio contiene toda la aplicación que hemos creado con JBuilder.

JBuilder crea otro directorio que es un módulo de despliegue de web service, el cual se llama WebServiceDeploymentModules.

Por cada web service creado, generará un archivo .wsdl, el cual es un fichero xml que contiene los descriptores que informan del web service, como sus métodos y parámetros, entre otras cosas. En mi caso, creé un web service llamado WSNeogateway, el cual tiene asociado el fichero descriptor de web service WSNeogateway.wsdl.

Por tanto, copiar los directorios WebModuleNeoGateway, WebServiceDeploymentModules y el archivo WSNeogateway.wsdl al directorio C:\tomcat4131\webapps con el Tomcat parado.

Cuando se arranca Tomcat, desplegará los archivos que se van ejecutando de nuestras aplicaciones (páginas html, páginas, jsp, servlets, WebServices…) en el directorio C:\tomcat4131\work\Standalone\localhost. Este será el directorio de ejecución, mientras que el directorio C:\tomcat4131\webapps será el directorio de instalación o alojamiento.


7. Comprobar si la aplicación web está ejecutándose

Arrancar Tomcat. Acceder a la página principal (http://127.0.0.1:8080/index.jsp). Seleccionar la opción Tomcat Manager en el módulo de administración (parte superior izquierda). Solicitará la validación del usuario administrador. Escribir en el campo usuario “admin”, y en el campo contraseña “admin.”. Una vez validado, aparecerá la consola del gestor de aplicaciones web de Tomcat (Tomcat Web Application Manager). Se expondrán en una lista las aplicaciones web que se están ejecutando y su estado. Entre esta lista debería estar la nuestra.

Desde esta consola es posible parar (stop), recargar (reload), ejecutar (Start) o eliminar (remove) nuestra aplicación Web.


8. Chequear nuestro sistema para ejecutar web services

JBuilder crea por defecto una página de inicio basada en Axis, la cual permite chequear y verificar los web services que hemos creado. Para acceder a dicha página escribir la URL de acceso

http://127.0.0.1:8080/WebModuleNeoGateway/index.html

o bien hacer clic sobre el enlace de la misma en la consola del gestor de aplicaciones web de Tomcat.

Debería aparecer una página Web con el título “JBuilder Apache Axis Admin Console”, la cual contiene varios enlaces útiles.

Para validar que la instalación de las librerías y todos los recursos necesarios, hacer clic sobre el link “Validate the local installation’s configuration”.

Este link lleva a

http://127.0.0.1:8080/WebModuleNeoGateway/happyaxis.jsp

donde se comprobará una a una todas las librerías que Axis requiere para una correcta ejecución del web service. En primer lugar aparecerán las librerías necesarias. Todas las librerías correctas aparecen como “Found …”. Si alguna faltara, no podría ejecutarse el web service, y en el chequeo ofrecerá un enlace a la página oficial de la librería que falta, con lo cual puede accederse e instalar dicha librería en el directorio C:\tomcat4131\commons\lib para satisfacer esta necesidad. Un ejemplo que podría ocurrir sería con la librería activation.jar si JBuilder no la incluyó en el directorio WEB-INF\lib de nuestra aplicación.

A continuación comprobará una serie de librerías opcionales, como la de mail.jar o xmlsec.jar, que no son obligatorias para el correcto funcionamiento.

A continuación hace un chequeo del servidor de aplicaciones Tomcat (Examining Application Server) y de las propiedades del sistema (Examining System Properties). Esta parte es solamente informativa.

Lo realmente importante es la sección de librerías requeridas, que es obligatoria de cumplir.


9. Chequear el web service

Una vez satisfechas las necesidades del punto anterior, acceder a la página de consola Axis que JBuilder generó

http://127.0.0.1:8080/WebModuleNeoGateway/index.html

Acceder al link “View the list of deployed web services”. Este link accederá a la página

http://127.0.0.1:8080/WebModuleNeoGateway/servlet/AxisServlet

la cual mostrará los web services que están desplegados en Tomcat. Además del nuestro (WSNeogateway), mostrará dos de ejemplo que incorpora Axis, que son AdminService y Version. Junto a los nombres de los web services aparecerá un link “wsdl”, el cual accederá a la url, y debajo los métodos publicados.

http://127.0.0.1:8080/WebModuleNeoGateway/services/?wsdl

y mostrará el contenido del archivo wsdl con todas las características necesarias para el despliegue y funcionamiento de dicho web service.

En el caso de mi web service, la url será

http://127.0.0.1:8080/WebModuleNeoGateway/services/WSNeogateway?wsdl

y el resultado o contenido (aunque salga un poco "descogorciado" si veis el fuente del HTML vereis que el xml está bien. Blogger lo reformatea automáticamente y puede salir un poco desordenado):



Si se estudia detenidamente este archivo, mi web service contiene un método llamado run, y los parámetros que recoge son: uniqueID, catMessage, typeMessage, priority, date, data y aux. Asimismo el web service retornará una cadena de texto con un resultado. El fragmento que da esta información es el siguiente:



10. Ejecutar el web service

Para ejecutar el web service hay que llamar en la url al parámetro “method” para indicar el nombre del método (en nuestro caso “run”), y a continuación, con el separador & (ampersand) las parejas de parámetros y valores. Por ejemplo:

http://127.0.0.1:8080/WebModuleNeoGateway/services/Version?method=getVersion

Este ejemplo, devolvería el siguiente resultado



Un ejemplo de llamada a mi web service sería

http://127.0.0.1:8080/WebModuleNeoGateway/services/WSNeogateway?method=run&uniqueID=0123456789&catMessage=MESSENGER&typeMessage=REQUEST_CONTACTS&priority=1&date=20060826021407

Los parámetros data y aux son opcionales en mi aplicativo, por eso se han omitido en este caso.