Webservices en 4biz



Este documento describe la implementación de WebService en 4biz ESP. Con el nombre de Citrest, el servicio web utiliza la implementación RESTEasy del patrón RESTFul. A través de ejemplos prácticos, se presentarán los conceptos básicos, las estructuras de datos y las normas que deben seguirse en la implantación de nuevos servicios.

Representational State Transfer (REST) describe las arquitecturas que utilizan el protocolo HTTP o protocolos similares, restringiendo la interfaz a un conjunto de operaciones HTTP conocidas: GET, POST, PUT y DELETE.

Citrest utiliza RESTEasy, que es una implementación de la especificación JAX-RS que proporciona una API Java para servicios web RESTful mediante el protocolo HTTP.

Este documento no pretende presentar detalles sobre la implementación de RESTful o RESTEasy, ya que existe una amplia documentación en Internet sobre el tema, como http://www.jboss.org/resteasy.

Se ha creado una estructura en la base de datos para almacenar los datos necesarios para el funcionamiento de Citrest. El modelo de datos rest_v2.pdm se encuentra en el directorio CitCorporeWeb/Model. Todas las tablas mantenidas en Citrest tienen el prefijo Rest_ y tienen relaciones con otras tablas del modelo 4biz: ObjetoNegocio, Grupo, Usuario y ProcesamientoLotes.

Las Clases de Recursos son clases simples, POJO, que contienen anotaciones JAX-RS para indicar los mapeos y operaciones existentes.

Las clases Resources deben estar en el paquete br.com.centralit.4biz.rest.resource y seguir el patrón de nomenclatura utilizado en las demás clases Resources, Rest \N <NombreDelUC> Resources.java.

La Clase de Recurso que intercepta la llamada http al webservice debe ser mapeada en el archivo web.xml. Por ejemplo:

Se crea una nueva instancia de la Clase de Recurso para cada solicitud de recurso. Cada método de recurso recibe como parámetro una instancia hija de la clase CtMessage.java y devuelve un objeto del tipo CtMessageResp. A esta instancia se le asigna el valor del atributo MessageID. Esta instancia se pasa como parámetro al método Execute de la clase de utilidad RestOperationUtil.java.

La clase RestOperationUtil.java se encarga de realizar las validaciones y dirigir la solicitud de recurso a la clase responsable de la Operación.

El método Execute (entrada CtMessage) es el método llamado por las clases de Recursos y recibe como parámetro una instancia de CtMessage con el atributo MessageID asignado.

La clase RestOperationUtil obtiene de la clase RestUtil.java una instancia de cada Servicio y efectúa las siguientes comprobaciones:

Una vez realizadas estas validaciones, la clase realiza la Inicialización de la Operación, registrando los atributos en la tabla Rest_Execution. La tabla RestExecution funciona como una tabla de registro de Ejecución. Observe que la ejecución se crea con el estado NotInitiated, es decir, la operación no se ha inicializado todavía. Este estado se actualizará posteriormente en función del resultado de la ejecución de la operación.

Después de ejecutar el registro de ejecución, la clase RestOperationUtil instancia la clase Operation obtenida del atributo JavaClass de la tabla Rest_Operation y ejecuta la llamada al método execute.

El método Execute es una condición del contrato de la Interfaz IRestOperation. Las clases que implementan esta interfaz deben implementar el método de ejecución.

Para cada messageID, se hace una llamada a un método específico para su tratamiento.

Cada uno de estos métodos puede hacer llamadas a 4biz Services Layer para la reutilización de servicios.

Todas las clases responsables del funcionamiento del servicio web deben registrarse en la tabla Rest_Operation.

Cada operación tiene una clase asociada que obedece a una interfaz estándar RestOperation y es responsable de su ejecución.

La clase que realiza la operación puede ser de tipo Java o JavaScript (atributo ClassType). Actualmente, sólo se admite el tipo Java.

Una operación puede ser síncrona o asíncrona (atributo OperationType). Una operación síncrona se ejecuta de forma inmediata cuando se llama. Una operación asíncrona apunta al procesamiento por lotes. Actualmente, sólo se admiten operaciones síncronas.

Para que un determinado usuario pueda realizar una operación, al menos un grupo de usuarios debe estar asociado a la operación en la tabla Rest_Permission.

La tabla Rest_Parameter almacena los parámetros que pueden utilizarse para realizar operaciones. A continuación, algunos ejemplos de parámetros:

Cada operación puede tener uno o más dominios de parámetros en la tabla Rest_Domain.

Cada ejecución de una operación específica se registra en la tabla Rest_Execution. Esta tabla registra la fecha y hora de la solicitud, el ID del usuario que solicita la ejecución, la clase de entrada, los datos de entrada y el estado actual de la ejecución.

Cada resultado de una ejecución se registra en la tabla Rest_Log. Esta tabla registra la fecha y hora de ejecución, la clase de salida, los datos de salida y el estado de ejecución.

Para crear un nuevo recurso, el desarrollador debe seguir los siguientes pasos de parametrización:

Todas las clases utilizadas por Citrest deben estar definidas por un .XSD específico. A partir del .XSD, las clases pueden generarse automáticamente mediante el plug-in de eclipse o mediante xjc.jar, disponible en la iniciativa 0015 de SharePoint. Para generar las clases desde xjc, debe utilizar la siguiente línea de comandos:

El .XSD debe estar en el paquete br.com.centralit.4biz.rest.xsd y las clases generadas deben estar en el paquete br.com.centralit.4biz.rest.schema. En estos paquetes ya hay varias clases .XSD y varias utilizadas por Mobile que pueden servir de ejemplo.

La clase CtError es referenciada por las otras clases utilizadas para realizar las operaciones de Citrest.

Cada operación que se ejecuta en Citrest requiere un SessionID devuelto por el inicio de sesión. El inicio de sesión se implementa en la clase br.com.centralit.4biz.rest.resource.RestOperationResources y tiene como entrada un objeto de la clase CtLogin.

Como resultado del inicio de sesión, el objeto SessionID o CtError es devuelto por el inicio de sesión a través de la clase CtLoginResp.

El tratamiento de errores de cualquier método de ejecución debe cumplir con el patrón de encapsulación del objeto CtError implementado en la clase RestOperationUtil.

Para facilitar la comprensión, esta sección detalla la implementación y el funcionamiento del servicio GetByUser utilizado en el Mobile. Se encarga de devolver la lista de solicitudes e incidentes en el portafolio de trabajo de un determinado usuario.

Se han seguido los siguientes pasos para su implementación:

Estas entradas especifican que existe una nueva clase de recurso para RESTEasy y que cualquier URL que contenga / mobile / será interceptada por el servlet de servicio web.

La configuración y la implementación del web.xml anterior determinan eso: Las llamadas http: //.../mobile/notification/getByUser serán interceptadas por la clase RestMobileResources.