Normativa desarrollo WSO2

INTRODUCCIÓN

1.1 Alcance

Esta normativa contiene información acerca de los requisitos que deben cumplirse para implantar un servicio en el bus de interoperabilidad de la Agencia Digital de Andalucía (ADA), posteriormente NEXO.

1.2 Condiciones de uso

Las normas recogidas en esta guía son de obligado cumplimiento, dentro del alcance especificado. La OT-I de la ADA, se reserva el derecho a la modificación de la norma sin previo aviso, tras lo cual, notificará del cambio a los actores implicados para su adopción inmediata. 

La OT-I podrá estudiar los casos excepcionales, en el caso de que algún actor considere necesario el incumplimiento de alguna de las normas y/o recomendaciones, deberá aportar previamente la correspondiente justificación fehacientemente documentada de la solución alternativa propuesta, así como toda aquella documentación que le sea requerida para proceder a su validación técnica. Tras el análisis de la información aportada, la OT-I informará de manera explícita sobre las conclusiones obtenidas para lograr encontrar una solución adaptada en la medida de lo posible a las directrices marcadas.

NORMATIVA DE DESARROLLO WSO2

2.1 Aspectos Generales

A continuación se describen algunos aspectos generales que deberán cumplirse para implantar un servicio en el bus de NEXO:

• El consumo de los servicios implantados en NEXO deberá ser obligatoriamente por protocolo HTTPS, de manera que es necesario restringir el protocolo HTTP a nivel de código.
• El protoloco TLS mínimo obligatorio para que las comunicaciones entre cualquier posible consumidor y NEXO se establezcan correctamente es el TLS v1.2, mientras que el máximo se corresponde con el TLS v1.3, siendo éste opcional. Nótese que este punto debe cumplirse para todas las nuevas incorporaciones de servicios en NEXO, ya que para los servicios ya implantados se está gestionando el cambio.
• Se deberá acordar con el sistema proveedor de NEXO un tiempo de respuesta máximo acorde con las especificaciones del mismo. Por defecto, si el proveedor no indica un tiempo de respuesta máximo, se seteará el timeout del servicio a 30s.

2.2 Estructura Proyectos

Los artefactos de WSO2 están comprendidos dentro de un proyecto denominado “Parent”. Dicho proyecto, está compuesto por los siguientes artefactos:

• Composite Application Project (Capp)
• ESB Config Project (CP)
• Registry Resource Project (RP)
• Data Services (DSS)

Todos estos artefactos, compartirán un parámetro denominado “groupId” con el proyecto Parent. El “groupId” tendrá el valor de “es.juntadeandalucia.ada.interoperabilidad”. Además, el proyecto Parent incluye una carpeta "Profile" que permite definir el valor de las variables del proyecto completo en función del entorno (perfil) correspondiente. 

2.2.1 Nombrado de artefactos

• Proyecto parent: Servicios[Intranet/Extranet][ACRONIMONombreServicio]Parent

  (El ACRÓNIMO son las siglas del organismo/sistema proveedor del servicio, que se informa para facilitar la ubicación conceptual del código fuente)

• Composite Application Project (Capp): Servicios[Intranet/Extranet][ACRONIMONombreServicio]_CApp
• ESB Config Project (CP): Servicios[Intranet/Extranet][ACRONIMONombreServicio]_CP
  • Nomenclatura API/PROXY: [INT/EXT]_[PUB/PRV]_[NombreServicio]_v[X]
  • Nomenclatura secuencias de flujo para PROXY: [INSEQUENCE/OUTSEQUENCE/FAULTSEQUENCE]_[SOAP]_[NOMBRESERVICIO]
  • Nomenclatura secuencias de flujo para API: [INSEQUENCE/OUTSEQUENCE/ FAULTSEQUENCE]_[NOMBRESERVICIO]_[METODO]_[NOMBRERECURSO]
• Registry Resource Project (RP): Servicios[Intranet/Extranet][ACRONIMONombreServicio]_RP
  • Ruta física=Ruta lógica: [REST/SOAP]/[Sistema]/[NombreParent]/[vx.y.z]/comun/[endpoints/wslds/...]
  • Nomenclatura endpoint:[NombreServicio]_Endpoint.xml (Si una API tuviera varios endpoint, diferenciar los endpoints según funcionalidad (recurso, método...))
  • Nomenclatura scripts: [NombreServicio]_[Funcionalidad]_Scripts.xml
  • Nomenclatura wsdl: [NombreServicio].wsdl
  • Nomenclatura xsd: [referencia original del xsd].xsd
• Data Services (DSS): Servicios[Intranet/Extranet][ACRONIMONombreServicio]_DSS
  • Nomenclatura dataservice:[NombreServicio]ServicioDSS.dbs
• Profiles: config-[entorno].properties 

2.3 Política de Versionado

Un número normal de versión debe tomar la forma X.Y.Z donde X, Y, y Z son enteros no negativos, donde X es la versión “major”, Y es la versión “minor”, y Z es la versión “patch”. Cada elemento debe incrementarse numéricamente en incrementos de 1. 

Una vez que un paquete versionado ha sido liberado (release), los contenidos de esa versión no deben ser modificados. Cualquier modificación debe ser liberada como una nueva versión. 

Nótese que la versión major en cero (0.y.z) es para desarrollo inicial. Cualquier cosa puede cambiar en cualquier momento. El servicio no debiera ser considerada estable.

2.3.1 Versionados de desarrollos en sistemas de control de versiones (Git)

Para el versionado de desarrollos en sistema de control de versiones se siguen las siguientes reglas:

• X: Aumentará cuando se producen cambios que rompan la compatibilidad de alguna manera con la versión anterior. (mayor)
• Y: Aumentará con cada funcionalidad añadida compatible con la versión anterior. (menor) 
• Z: Aumentará con correcciones compatibles con la versión anterior. (patch)

2.3.2 Versionado de componentes

Los proxies y APIs serán publicados con un sólo digito (vX), cuyo versionado seguirá la misma regla que el versionado de desarrollos. 

Caben excepciones a esta norma, cuando sea necesario mantener las dos versiones de un servicio x.y y x.(y+1) por determinados motivos, manteniéndose ambas dos disponibles y diferenciadas en la plataforma de interoperabilidad. 

De esta forma, solo se modificará el nombre del Proxy o API cuando sea introducida una nueva versión no compatible con la anterior (sería necesaria una adaptación por parte del cliente y nos permitirá mantener varias versiones del servicio activas al mismo tiempo).

Por tanto, el nombrado de las APIs y Proxies seguirá el patrón indicado anteriormente, [Visibilidad]_[Autenticacion]_[NombreServicio]_v[X], dónde:

• Visibilidad: INT (Interno) / EXT (Externo). Los servicios cuyo nombre empiecen por INT son solo accesibles desde la RCJA. Los EXT son accesibles desde dentro y desde fuera de la RCJA.
• Autenticacion: PUB (No tiene autenticación) / PRV (Es necesario autenticarse para consumir el servicio)
• NombreServicio: Nombre del servicio a publicar. 
• v[X]: versión de la api/proxy

En caso de nombres compuestos, utilizar UpperCamelCase. Ejemplo: INT_PUB_ServicioEjemplo_v1 

Nótese que las secuencias de flujo de cada servicio, también serán versionadas con la siguiente nomenclatura siempre que sea necesario mantener más de una versión disponible, en función de si se trata de api o proxy y de acuerdo a la normativa explicada en el punto anterior:

• Nomenclatura secuencias de flujo para PROXY: [INSEQUENCE/OUTSEQUENCE/FAULTSEQUENCE]_[SOAP]_[NOMBRESERVICIO]_v[X]
• Nomenclatura secuencias de flujo para API: [INSEQUENCE/OUTSEQUENCE/ FAULTSEQUENCE]_[NOMBRESERVICIO]_[METODO]_[NOMBRERECURSO]_v[X]

2.3.3 Versionado de CARS

Para actualización en el código fuente, que dé lugar a un nuevo desplegable carbon, es necesario versionar los CARBONAPPs, siguiendo el versionado de los desarrollos comentado anteriormente. Nótese que se debe cambiar la versión en el archivo pom.xml, que se encuentra dentro de la carpeta CApp de cada entorno. Indicar números de versión X.Y.Z

2.4 Uso de Maven y Compilación del proyecto

2.4.1 Definición y Uso

La construcción de aplicaciones Java EE es un proceso complejo en el cual deben realizarse tareas de construcción, empaquetado y despliegue en múltiples entornos. Estas aplicaciones suelen depender frecuentemente de un gran número librerías y frameworks de terceros. Por otro lado, se suelen gestionar recursos estáticos (CSS, Javascript, documentos...), ficheros de configuración, descriptores de despliegue; se requiere la realización de pruebas unitarias y, normalmente, se integran en sistemas de control de versiones como CVS o Subversión.

El problema es que cada aplicación puede tomar un enfoque diferente para desarrollar cada una de estas necesidades. Esto provoca numerosos problemas:

• Existe gran heterogeneidad en los aplicativos.
• No se suele reutilizar todo lo que se pudiera.
• El tiempo de adaptación de una persona a un proyecto suele ser alto, ya que cada proyecto tiene un propio enfoque tecnológico y funcional.
• Este aspecto es aún más grave en el mantenimiento de un sistema de información, donde la curva de aprendizaje es demasiado elevada.
• Es difícil llevar un control de la calidad del código fuente y la documentación entregada.
• El proceso de subida de versiones suele ser engorroso: los ficheros que empaquetan la aplicación (usualmente un WAR o un EAR) suelen contener en su interior ficheros de configuración, por lo que no se puede utilizar el mismo fichero en diversos entornos (como desarrollo, preproducción o producción).

Apache Maven intenta solucionar estos déficits. Maven es un “Project Management Framework”, esto es, un framework de gestión de proyectos de software, que proporciona un modelo estándar de gestión y descripción de proyectos. Maven da soluciones a tareas que abarcan desde la compilación hasta la distribución, despliegue y documentación de los proyectos. Se podría describir como “un sistema de estándares, un repositorio, y un software usado para manejar y describir proyectos. Define un ciclo de vida estándar para la construcción, prueba, y despliegue de componentes del proyecto. Proporciona un marco que permita la reutilización fácil de la lógica común de la estructura para todo los proyectos que siguen los estándares Maven.” 

El principal objetivo de Maven es que un desarrollador pueda adaptarse al método de trabajo de un proyecto en el menor tiempo posible, disminuyendo su curva de aprendizaje. 

Para lograr este objetivo primordial de Maven se encarga de diversas materias:

• Facilita el proceso de construcción.
• Proporciona un sistema de construcción uniforme. Maven se basa en la definición de metadatos del proyecto, en el Project Object Model (POM), almacenados en un fichero denominado pom.xml, unida a la utilización de una serie de plugins comunes a los proyectos que utilizan Maven. Todos los proyectos Maven funcionan de la misma forma, por lo que el esfuerzo de aprendizaje sólo se hace una vez.
• Proporciona información útil sobre el proyecto. Partiendo de la información almacenada en el POM (Project Object Model) Maven puede gestionar automáticamente información del proyecto de gran utilidad, como por ejemplo:
  • Lista de cambios (CHANGELOG) desde el control de versiones.
  • Dependencias transitivas. Por ejemplo: struts.jar, que a su vez depende de commons-beanutils.jar
  • Informes de la ejecución de pruebas unitarias.
• Ayuda a utilizar las “mejores practicas” de desarrollo (Best Practices). Maven obliga a aceptar una serie de convenciones y costumbres que aportan claros beneficios. Por ejemplo, marca una estructura estándar para el código fuente, la documentación, existe un único sitio donde describir el proyecto, obliga a tener el código fuente de las pruebas unitarias de forma separada pero relacionada, etc.
• Permite introducir nuevos servicios de forma sencilla: plugins para la creación automática de un portal Web del proyecto fácilmente configurable, para el cálculo de métricas de calidad del código fuente, para su despliegue en los entornos de desarrollo, preproducción y producción, etc.

2.4.2 Características

Maven dispone por defecto de una serie de funcionalidades avanzadas, las cuales describiremos a continuación. De todas formas hemos de tener en cuenta que Maven dispone de un gran número de plugins que le otorgan un enorme valor añadido, además, aquel que quiera puede crear sus propios plugins.

Sobre las características disponibles, destacamos las siguientes:

• Creación sencilla y ágil de un nuevo proyecto o módulo.
• Estandarización de la estructura de un proyecto, y de las técnicas relacionadas con éste. De esta forma, se mejora la adaptación de los desarrolladores y la homogeneización del software. Maven propone una estructura estándar de un proyecto: El proyecto se describe en su totalidad en el fichero pom.xml, y existe una localización estándar para el código fuente, los recursos, el código de la aplicación Web, etc.
• Maven incluye un potente mecanismo de gestión de las dependencias de un proyecto sobre librerías propias o de terceros. Gracias a la descripción de estas dependencias en el pom.xml, Maven puede realizar una serie de tareas útiles como actualizaciones automáticas (incluyendo la descarga de las librerías necesarias), y la resolución de dependencias transitivas (una librería depende de otra). Maven posibilita la reutilización de librerías propias.
• Maven permite una sencilla gestión simultánea de varios proyectos.
• Maven dispone de un enorme repositorio de librerías Open Source en constante actualización, de forma que los desarrolladores pueden acceder a las versiones más actualizadas de las mismas.
• Maven es extensible: dispone de multitud de plugins y de la posibilidad de creación de otros que necesitemos.
• Nos proporciona un acceso inmediato a nuevas funcionalidades requiriendo un esfuerzo muy pequeño de configuración.
• Construcción basada en modelos: en función de la definición, Maven puede generar diversos formatos de empaquetado de proyectos: WAR, EAR, JAR...
• Gestión de releases y publicación: Maven se integra con sistemas de gestión de versiones (como CVS o SVN) y gestiona la publicación de releases.

2.4.3 Maven en WSO2

Como producto basado en Java, el proyecto multimódulo WSO2 ESB/WSO2 EI se puede construir con Maven . Los proyectos Maven Multi Module contienen múltiples módulos con cada uno su propio archivo pom. Usamos Maven en desarrollo continuo, lo que le da una gestión extra a un proyecto y la posibilidad de tenerlo como parte de un proyecto más grande. 

Para un desarrollo, utilizamos subproyectos de tipo carbon archive, esb y registration. También podemos agregar mediadores personalizados, proyectos java personalizados, así como (sub)proyectos de prueba.

En el Archivo Pom del proyecto parent de Maven se contemplaran la siguiente norma:

• El groupId debe ser es.juntadeandalucia.ada.interoperabilidad
• En el elemento modules deber estar todos los componentes del desarrollo siendo el CApp el ultimo de la lista.En el elemento properties se configuras las parámetros de configuración para el desarrollo que se obtiene los ficheros config-{entorno}.properties, la nomenclatura de estas propiedades son:
  •  [cpv/rpv/dss].[tipo de parametro por ejemplo ep si es un url del backend].nombre_parametro
• Por ultimo hay que añadir el objeto profiles que sería los distintos perfiles que se corresponde con los entornos existentes.

2.4.4 Compilación

Para la compilación se debe cumplir los siguientes requisitos:

• Usar Maven en una versión superior o igual a apache-maven-3.5.0
• Usa lar versión de JDK jdk1.8.0_191

Para la compilación se debe ejecutar desde el directorio parent: mvn clean install -P entorno -Dmaven.test.skip, donde entorno será: Pruebas/Preproducción/Producción

NORMATIVAS DE USO

En este apartado se va a definir la normativa de desarrollo en WSO2.

3.1 Normativa API REST

• Se ha de nombrar la API según la política de nombrado del apartado 2.2.1.  
• Uso de URL's (normativa, contexto y recurso): 
  • En el tipo de servicio REST hay que tener en cuenta que la url está enfocada a realizar algún tipo de operación CRUD sobre recursos, por lo que las APIs publicadas en Nexo deben respetar la siguiente norma:
    • Contexto de la API: Debe ser igual al nombre de la API
    • Path del recurso: no debe Obtener ningún tipo de verbo, por lo tanto si el fin del recurso es obtener ejemplos el recurso se definiría mediante el método GET y el path del recurso con el nombre del recurso a obtener /ejemplos
• Estructura de secuencias y nomenclatura: La secuencias tendrán que crearse en el componente CP y referenciadas en la API siguiendo la nomenclatura indicada en el apartado 2.2.1.

3.2 Normativa SOAP 

• Nombre de proxy service: El nombre del proxy service que se vaya a desarrollar debera seguir la nomenclatura indicada en el apartado 2.2.1.
• Estructura de secuencias y nomenclatura : La secuencias tendrán que crearse en el componente CP y referenciadas en el proxy siguiendo la nomenclatura indicada en el apartado 2.2.1.

3.3 Normativa Uso DSS

• Nombre Data Service: El nombre del DataService deberá seguir la nomencaltura indicada en el apartado 2.2.1.
• Datasource: La configuración del datasource deberá definirse desde los ficheros de configuración de WSO2 y el nombre deberá seguir la nomenclatura indicada en el apartado 2.2.1.
• Path recurso: El objetivo del DSS es realizar operaciones CRUD sobre un recurso por lo tanto el path definido en el recurso no puede contener un verbo

3.4 Normativa Uso Colas

El protocolo JMS (Java Message Service) puede ser empleado en el bus de servicios del producto Enterprise Integrator dentro del conjunto de componentes de WSO2. Con la correspondiente configuración de este protocolo es posible definir listeners de una cola de mensajes, de modo que un proxy del bus se mantiene a la escucha de la cola de mensajes que se le haya definido. A continuación se define cómo configurar este protocolo para un gestor de colas ActiveMQ. 

En primer lugar, para hacer uso de este protocolo se debe configurar el archivo de configuración axis2.xml ubicado en la ruta EI_HOME/conf/axis2. Dentro del mismo, añadir la siguiente etiqueta dentro del conjunto de los transportReceiver:

En caso de que se desee mantener una conexión con un gestor de colas en alta disponibilidad (en este caso un ActiveMQ clusterizado) se deberá configurar el parámetro “java.naming.provider.url” que indica la dirección tcp del gestor de colas del que los servicios del bus serán consumidores. La configuración se basa en contener dentro de la palabra clave failover las direcciones de los servidores a los que apuntar:

Además de añadir la etiqueta del transportReceiver se debe confirmar que el protocolo se encuentra bien configurado dentro del conjunto de los transportSender:

Por último, para el caso del gestor de colas ActiveMQ, se debe incluir la siguiente lista de dependencias de los siguientes .jar para la ruta EI_HOME/lib (se adjuntan a la página para facilitar su descarga):

NORMATIVAS DE MONITORIZACIÓN

Para poder mostrar los indicadores de negocios de los servicios desarrollados, es necesario insertar las secuencias genéricas implementadas para este fin. De esta forma, se definen las variables necesarias que se mostrarán en los logs para poder explotarlas con ELK. El proyecto generado mediante el arquetipo maven contendrá referencia a las secuencias de monitorización generales para que todos los servicios desplegados en el bus de NEXO puedan ser monitorizados. 

Estas secuencias son las siguientes:

• En la inSequence la secuencia de monitorización de la petición: 
  • Servicios REST: 
    • SEQ_COMUN_MONITORIZAR_REQUEST_API
  • Servicios SOAP: 
    • SEQ_COMUN_MONITORIZAR_REQUEST
• En la outSequence, la secuencia de monitorización de la respuesta:
  • Servicio REST: 
    • SEQ_COMUN_MONITORIZAR_RESPONSE_API
    • SEQ_PUBLISHEVENT_MONITORIZAR_API
  • Servicio SOAP: 
    • SEQ_COMUN_MONITORIZAR_RESPONSE
    • SEQ_PUBLISHEVENT_MONITORIZAR_PROXY
• En la faultSequence, la secuencia de monitorización del fallo:
  • Servicios REST: 
    • SEQ_COMUN_MONITORIZAR_FAULT_API
  • Servicios SOAP: 
    • SEQ_COMUN_MONITORIZAR_FAULT

Estas secuencias se deberán seleccionar en función del tipo de servicio, ya sea REST o SOAP para cada petición, respuesta o fallo. Se deberán referenciar al principio de cada una de esas secuencias (inSecuence, outSecuence o faultSecuence) de la siguiente forma: <sequence key="gov:/servicios/Comunes/Secuencias/[NombreSecuencia].xml" />

En el caso de que el desarrollo contenga validaciones, se deberá añadir una referencia a la secuencia de la faultSequence, ya que en caso de que falle la validación del mensaje se deberá mostrar dicho error.

NORMATIVAS DE MANTENIMIENTO DE CÓDIGO FUENTE

Una vez finalizados los desarrollos tanto del servicio en sí como del test-suite, es necesario que el código fuente quede subido al repositorio de código utilizado por la OTI, Git. 

Para la subida al repositorio se usará dentro del mensaje del commit la siguiente nomenclatura: “ADD/UPDATE/FIX #id Comentario de funcionalidad añadida, actualizada o corregida”, dónde:

• ADD: Se añade nueva funcionalidad.
• UPDATE: Se realiza una actualización sobre una funcionalidad existente.
• FIX: Se realiza un correctivo sobre alguna funcionalidad existente.
• #Id: identificador de tarea de TEO en la que se describen los trabajos a realizar

Además, cuando el commit pertenezca a un entregable completo y validado de un resultado final, se deberá crear la tag correspondiente con la siguiente nomenclatura de tag name: “vx.y.z”

GLOSARIO