Utilidades

Cosmos WebServer

Cosmos WebServer no funciona con licencias de tipo Cosmos SQL Desktop ni Cosmos SQL Workgroup.

Cosmos WebServer (CWS) es una utilidad que permite utilizar Cosmos como proveedor de servicios web, permitiendo crear servicios REST.

Cosmos WebServer se puede arrancar en línea de comando o bien como servicio Windows.

Una vez arrancado, el servidor atiende las peticiones HTTP en el puerto definido (por defecto 8081). Una petición puede convertirse en invocación a un método de una aplicación Cosmos configurada.

Esta utilidad está disponible a partir de la versión 6.0 de Cosmos, excepto el fichero de Log: Cwslog.log, que se ha incorporado a partir de la versión 7.2.

A continuación se detalla este funcionamiento.

ArquitecturaIr al principio de la página

El esquema básico de Cosmos WebServer (CWS) es el que se muestra en la siguiente figura:

Cosmos Web Server

Una instalación Cosmos WebServer estará compuesta por:

Cosmos WebServer utiliza la dll “JVM.dll” de la máquina virtual de Java. Por lo tanto, para ejecutar CWS es necesario disponer de una máquina virtual Java de 32 bits (con versión 1.8 o superior) instalada en la misma máquina que Cosmos WebServer.

A partir de la versión 7.4 de Cosmos, Cosmos WebServer admite también conexiones HTTPS.

La aplicación Cosmoswebserver.exe permite arrancar el servidor CWS desde la línea de comando o como servicio Windows.

ConfiguraciónIr al principio de la página

Fichero de configuración de la aplicación Cosmos WebServer

En el fichero de configuración de Cosmos Webserver se indicará, entre otras cosas, el puerto donde escuchará el servidor, la ruta del fichero de configuración de los servicios REST Cosmos, los parámetros propios de la máquina virtual Java (ruta del fichero cosmosrestserver.jar, parámetros de memoria) y, opcionalmente, la ruta de recursos HTML del servidor.

Variables de entorno

CONFIG
Esta variable indica la ruta del fichero de configuración de los servicios REST del servidor (la configuración de este fichero se explica en el apartado “Fichero de configuración del servidor REST”).

PORT
Indica el puerto del servidor donde CWS escuchará peticiones HTTP.

RESOURCEPATH
Esta variable de entorno indica la ruta del directorio donde CWS almacenará recursos que serán accesibles mediante la URL del servidor. Estos recursos podrán ser páginas HTML, ficheros de imágenes, etc.

NUMBEROFTHREADS
Esta variable será necesario definirla para que la ejecución de Cosmos WebServer sea multihilo, es decir, que permita procesar más de una petición REST a la vez sin tener que esperar a que finalice una para procesar la siguiente.

Para configurar una conexión HTTPS será necesario definir las siguientes variables:

SSL_PORT
Indica el puerto del servidor donde CWS escuchará peticiones HTTPS.

SSL_KEYSTORE
Indica la ruta del fichero de almacén de certificados.

SSL_KEYSTORE_PWD
Indica la contraseña del almacén de certificados.

SSL_KEYSTORE_ALIAS
Indica el alias del certificado que se desea utilizar. Si no se indica, utilizará el primer certificado del almacén.

SSL_KEYSTORE_ALIAS_PWD
Indica la contraseña del alias indicado en SSL_KEYSTORE_ALIAS. Si no se especifica, utilizará la contraseña indicada en SSL_KEYSTORE_PWD.

Si se produce un error en el proceso de arranque de Cosmos WebServer, el servicio no se iniciará y no se podrán realizar conexiones de ningún tipo. Por ejemplo, si la contraseña del almacén de certificados es incorrecta, o si el puerto de escucha HTTP o HTTPS indicado ya está en uso o si se indica el mismo puerto para las conexiones HTTP y HTTPS, se producirá un error en el proceso de arranque y no se podrán realizar conexiones con el servidor.

Fichero de configuración del servidor REST

En este fichero de configuración se especifica, en formato XML, el nombre de la aplicación Cosmos, el nombre de los módulos y de los métodos que serán los encargados de implementar los servicios REST, así como la ruta (URL) y verbo HTTP (GET, POST, PUT, DELETE, etc.) que se deberá emplear para acceder a cada uno de estos métodos. Cada servicio REST en Cosmos se corresponderá con un método definido en las secciones <module>, a las que se accederá mediante su ruta y la del módulo <module> y proyecto <Project> al que pertenecen (propiedades path de <Project>, <module> y <method>). Cada método Cosmos correspondiente con un servicio REST deberá retornar un string con el resultado de la ejecución del servicio REST.

Secciones del fichero de configuración

El nombre del parámetro, ya sea de tipo <queryParameter>, <urlParameter>, <bodyParameter> o <headerParameter>, deberá coincidir con el nombre del parámetro indicado en el fuente Cosmos del método.

Creación de un servicio REST en Cosmos

Un servicio REST en Cosmos se traduce como una función o método definido en un módulo de un proyecto en Cosmos, que recibe unos parámetros desde la URL o desde el cuerpo de una petición HTTP (request), y retorna un String con el resultado de la ejecución del mismo, así como de un código de estado donde se indica si la ejecución ha sido exitosa, fallida, etc.

Este código deberá ser un código de estado estándar HTTP (200 – ok, 201 – created, 405 – Method not allowed, etc).

Este código de estado lo establecerá el método o función Cosmos correspondiente al servicio REST mediante la ejecución del método SetExecStatus de la clase Module al finalizar el cuerpo de la función.

Instalación y ejecución de Cosmos WebserverIr al principio de la página

La utilidad Cosmos WebServer puede ser iniciada desde la línea de comando o como servicio Windows.

Ejecución desde línea de comando

Para iniciar Cosmos WebServer desde la línea de comando tendremos que utilizar la siguiente sintaxis:

Cosmoswebserver.exe –ini c:\cosmos\etc\stockserver.ini

El problema de iniciar Cosmos WebServer desde la línea de comando reside en que, al reiniciarse el servidor donde está instalado, es necesario reiniciar manualmente Cosmos WebServer.

Este problema se soluciona instalando Cosmos WebServer como servicio Windows.

Ejecución como servicio Windows

Instalación del servicio

Para instalar Cosmos WebServer como servicio será necesario ejecutar Cosmos WebServer con el parámetro “–install <nombre_de_servicio>”.

Cosmoswebserver.exe –install ServicioWeb –user .\usuario –passwd passwd

El parámetro “nombre_de_servicio” indicará un nombre de servicio Windows no existente, y que será el que identificará al servicio de Cosmos WebServer.

Los parámetros “–user” y “–passwd” indican respectivamente el usuario que arranca el servicio y su contraseña. Estos parámetros son opcionales, si no se indican, el servicio arrancará con una cuenta de sistema local.

El servicio se instalará por defecto como “AUTOMÁTICO”, es decir, cuando se reinicie el servidor el servicio se iniciará automáticamente.

Inicio del servicio

Para iniciar el servicio CosmosWebServer instalado con “-install” se deberá ejecutar CosmosWebServer con el parámetro “–start <nombre_de_servicio>”.

Cosmoswebserver.exe –start ServicioWeb

Como hemos visto en el apartado Fichero de configuración de la aplicación Cosmos WebServer, CWS necesita el nombre de un fichero de configuración. Este nombre lo obtendrá CosmosWebServer del fichero cosmoswebserver.ini, que deberá estar situado en “COSMOSDIR\etc”. Por cada servicio que queramos instalar, se deberá definir una sección con el nombre del servicio y una variable, llamada INIFILE, con el path absoluto del fichero de configuración para ese servicio.

Parada del servicio

Para detener el servicio CosmosWebServer instalado con “-install” se deberá ejecutar CosmosWebServer con el parámetro “–stop <nombre_de_servicio>”.

Cosmoswebserver.exe –stop ServicioWeb

A partir de ese momento el servicio estará instalado, pero no disponible para aceptar nuevas conexiones, hasta que no se rearranque con “-start”.

Desinstalación del servicio

Para desinstalar el servicio CosmosWebServer instalado con “-install” se deberá ejecutar CosmosWebServer con el parámetro “-remove <nombre_de_servicio>”.

Cosmoswebserver.exe –remove ServicioWeb

Ficheros de LOGIr al principio de la página

Fichero log4j

El servidor Cosmos WebServer permite la generación de un fichero de log en el que se almacenará información del funcionamiento de Cosmos WebServer.

Cosmos WebServer utiliza la herramienta Log4j2 para la generación del fichero de log.

Por defecto, CosmosWeb Server no genera fichero de log. Si se desea que la aplicación almacene información de log se deberá indicar en el fichero de configuración de Cosmos WebServer (ver el apartado: Fichero de configuración de la aplicación Cosmos WebServer).

Fichero CosmosWebServer.log

Este fichero se crea en el directorio c:\tmp, y en él Cosmos WebServer escribirá la información generada en la instalación, puesta en marcha, parada y eliminación del servicio Windows o en el proceso de arranque de Cosmos WebServer como aplicación.

Fichero Cwslog.log

La salida de los errores generados por el runtime de Cosmos WebServer durante los procesos podrá ser a fichero si en el directorio temporal se crea un fichero con el nombre CWSLog.log.

Cosmos WebServer como servicio
Si se produce un error durante la ejecución de un servicio Cosmos y el ErrorLevel es mayor de 0, en el fichero de log se volcará información referente al error, así como el método y el módulo donde se ha producido el error, y la pila de llamadas de la aplicación.

Si se produce un error durante la ejecución y el ErrorLevel es igual a 0, no se escribirá la información del error en el fichero de log.

Si en el código fuente del servicio Cosmos se ejecuta el método Trace, en el fichero de log se escribirá el texto asociado al método Trace.

Cosmos WebServer como aplicación
Si se produce un error durante la ejecución de un servicio Cosmos y el ErrorLevel es mayor de 0, en el fichero de log se volcará información referente al error, así como el método y el módulo donde se ha producido el error, y la pila de llamadas de la aplicación. Esta misma información se mostrará en pantalla mediante un MessageBox.