Cumplimiento normativo

Histórico de cambios

Los cambios en la normativa vendrán acompañados de un registro de las modificaciones. De este modo se podrá realizar un seguimiento y consultar su evolución. Ordenándose de mas recientes a menos recientes, prestando especial cuidado a las cabezeras de la tablas dónde se indican las fechas de entrada en vigor y versión.

1. Introducción 

En el presente documento se presenta la librería "estructuraApiClient", librería Java desarrollada por el SAS para facilitar el acceso a la información de la aplicación Estructura por terceras aplicaciones desarrolladas dentro de la organización.

Con esta librería los proveedores podrán abstraerse de los mecanismos de conexión existentes actualmente con la aplicación Estructura, facilitando considerablemente el acceso a la información de la misma y, lo que es más importante, conseguir desacoplar los aplicativos finales de Estructura, permitiendo que en un futuro Estructura pueda evolucionar sin impactar en el conjunto de aplicaciones que hacen uso de la misma.

2. Dependencias

3. Historial de Cambios

4. Servicios ofrecidos

5. Arquitectura de la librería

Puesto que a fecha de realización del presente documento los servicios web que ofrece Estructura para acceder a su información no permiten acceder a todo el catálogo de entidades almacenadas en Estructura, la única forma de acceder actualmente a dicha información es haciendo uso de Réplicas de base de datos.

Ya que el acceso a la información a través de réplicas de base de datos no está aconsejado por la gran dependencia que genera entre diferentes productos, la librería de acceso a la Estructura se ha desarrollado siguiendo un modelo de API/Implementación que permite exponer a los usuarios de la librería una API única que debe ser usada y una serie de implementaciones de dicha API, las cuales serán las verdaderas encargadas de acceder a la información.

Siguiendo este patrón se ha iniciado el desarrollo con una única implementación haciendo uso de réplicas (por ser la única forma posible actualmente), esperando que en un futuro se generen nuevas implementaciones que hagan uso de distintos métodos de acceso a Estructura (SOAP, REST, etc.). Los productos que estén ya desarrollados y haciendo uso de la API estándar podrán cambiar fácilmente de implementación si que el producto se vea afectado.

Requerimientos

Instalación

La librería desarrollada se encuentra desplegada en el repositorio de artefactos corporativo pudiendo ser incorporada en nuestro proyecto haciendo uso de maven:

<!-- Añadir en caso de hacer uso de la interfaz-->     
<dependencies>
          <dependency>
            <groupId>es.ja.csalud.sas.componentescomunes.estructuraApiClient</groupId>
            <artifactId>estructuraApiClient-api</artifactId>
            <version>${estructuraapi.version}</version><!-- Hasta la verisón 2.X.X-->
        </dependency>
<!-- Añadir en caso de hacer uso de la implementación-->      
        <dependency>
            <groupId>es.ja.csalud.sas.componentescomunes.estructuraApiClient</groupId>
            <artifactId>estructuraApiClient-jpa</artifactId>
            <version>${estructuraapi.version}</version><!-- Hasta la verisón 2.X.X-->
        </dependency>
   <dependencies> 

 <dependencyManagement>
 	<dependencies>
 		<dependency>
                <groupId>es.ja.csalud.sas.componentescomunes.estructuraApiClient</groupId>
                <artifactId>estructuraApiClient</artifactId>
                <version>${estructuraapi.version}</version>   <!-- A partir de la 3.X.X-->
                <type>pom</type>
                <scope>import</scope>
        </dependency>
  	<dependencies> 
 <dependencyManagement> 

<!-- Añadir en caso de hacer uso de la interfaz-->     
<dependencies>
          <dependency>
            <groupId>es.ja.csalud.sas.componentescomunes.estructuraApiClient</groupId>
            <artifactId>estructuraApiClient-api</artifactId>
            <version>${estructuraapi.version}</version><!-- A partir de la 3.X.X-->
        </dependency>
<!-- Añadir en caso de hacer uso de la implementación-->      
        <dependency>
            <groupId>es.ja.csalud.sas.componentescomunes.estructuraApiClient</groupId>
            <artifactId>estructuraApiClient-jpa</artifactId>
            <version>${estructuraapi.version}</version><!-- A partir de la 3.X.X-->
        </dependency>
   <dependencies> 

Configuración

Antes de comenzar a configurar nuestro proyecto, conviene recordar que la implementación de la API desarrollada con la que se cuenta actualmente se basa en acceso a la información a partir de un origen de datos específico para el acceso a sus datos, mientras que por otro lado la aplicación podrá tener otro origen de datos distinto para acceder a sus datos, de esta forma la aplicación puede estar en una base de datos mientras que la información de estructura sea recuperada de otra distinta.

Dicho esto, y siendo consciente de que existen diferentes formas de hacer lo mismo, a continuación se expone una serie de instrucciones a seguir para configurar un proyecto web que haga uso de esta librería y que se ejecutará en un contenedor Weblogic:

Configurar origen de datos

<server>
....
<include location="persistence-config-oracle-estructura.xml" /> <!-- Se puede modificar el nombre del fichero por el que resulte más adecuado para el ejemplo usaremos este -->
....
</server>

<server>
    <!-- Oracle driver -->
    <jdbcDriver id="oracle19-driver" libraryRef="oracle19-library" />

    <!-- Oracle driver library -->
    <library id="oracle19-library">
        <fileset dir="${server.config.dir}/lib/oracle" includes="ojdbc*.jar" />
    </library>

    <!-- Datasource -->
    <dataSource id="oracle" jndiName="jdbc/Diraya-Estructura-DS" queryTimeout="20s">
        <jdbcDriver libraryRef="oracle19-library"/>
        <properties.oracle URL="${jdbc.url}" user="${jdbc.user}" password="${jdbc.password}" /> <!-- queda a criterio del programador determinar las variables correctas. En caso de contenerizar el servidor, se deberá hacer uso de las secret y configmap descritos en el helm de despliegue -->
    </dataSource>

</server>

  <plugins>
            <plugin>
                <groupId>io.openliberty.tools</groupId>
                <artifactId>liberty-maven-plugin</artifactId>
                <configuration>
                    <copyDependencies>
                         <dependencyGroup>
                            <location>lib/oracle</location>
                            <dependency>
                                <groupId>com.oracle.database.jdbc</groupId>
                                <artifactId>ojdbc11</artifactId>
                                <version>${oracle.version}</version>
                            </dependency>
                        </dependencyGroup>
                    </copyDependencies>
                </configuration>
            </plugin>

Configurar persistence.xml: Configurar el fichero persistence.xml de nuestro proyecto web para añadir el orígen de datos configurado previamente. En este fichero se le asignara un nombre a la unidad de persistencia que posteriormente usará nuestro código a través de JPA. En el siguiente extracto puede verse como se crea una unidad de persistencia llamada "Diraya-Estructura-Persistence-Unit" y que es mapeada con el origen de datos que creamos previamente:

<persistence-unit name="Diraya-Estructura-Persistence-Unit" transaction-type="JTA">
    <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
    <jta-data-source>jdbc/Diraya-Estructura-DS</jta-data-source>
    <mapping-file>META-INF/est-bd-replica.xml</mapping-file>

    <class>es.ja.csalud.sas.componentescomunes.estructura.impl.*</class>
    <exclude-unlisted-classes>true</exclude-unlisted-classes>
</persistence-unit>

Es importante destacar que para aislar la unidad de persistencia del resto de la aplicación y evitar posibles conflictos, es recomendable añadir la etiqueta "class" y "exclude-unlisted-classes" con el valor que puede verse en el ejemplo para que la unidad de persistencia sólo actúe sobre el paquete indicado.
En cuanto al fichero de mapeo de entidades, pueden usarse cualquiera de los siguientes mapeos:

• META-INF/est-bd-replica.xml: Cuando nuestra cadena de conexión apunte a una base de datos donde existe una réplica de estructura en el esquema REP_PRO_EST. Este será la configuración usada en la mayoría de los casos
• META-INF/est-bd-original.xml: Cuando nuestra cadena de conexión apunte directamente a la base de datos de Estructura
• Cualquier otra configuración requerirá que el fichero xml sea redefinido por la aplicación que hace uso de la librería

Asignar EntityManager a la librería : Una vez configurada la unidad de persistencia sólo nos quedaría indicarle a la librería cuál va a ser el contexto de persistencia que queremos que use, ya que como se ha mencionado previamente, nuestra aplicación puede tener varios orígenes de datos distintos. Para ello nuevamente existen diferentes formas de hacerlo, a continuación se muestra una manera muy simple consistente en crear una clase que es ejecutada al iniciar nuestro servidor y se encarga de asignarle a la librería el contexto de persistencia a usar. A partir de este momento nuestra librería es completamente funcional.

@Singleton
@Startup
public class DaoEntityManagerConfig {

    @PersistenceContext(unitName = "Diraya-Estructura-Persistence-Unit")
    private EntityManager estructuraEntityManager;

    @PostConstruct
    public void init() {
        EntityManagerContainer.setEntityManager(estructuraEntityManager);
    }

}

import es.ja.csalud.sas.componentescomunes.estructura.impl.jpa.control.config.EntityManagerContainer;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.context.Initialized;
import jakarta.enterprise.event.Observes;
import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;

@ApplicationScoped
public class EntityManagerProducer {

    @PersistenceContext(unitName = "Diraya-Estructura-Persistence-Unit")
    private EntityManager estructuraEntityManager;

    public void init(@Observes @Initialized(ApplicationScoped.class) Object pointless)  {
        EntityManagerContainer.setEntityManager(estructuraEntityManager);
    }

}

Generar configuración de la API : A partir de la versión 2.x de la librería, al funcionar en base a Futures, se hace necesario el uso de un Executor encargado de gestionar los hilos que se vayan lanzando en el sistema. Para ello bastará con añadir un Produces en nuestro proyecto como el siguiente:

@Produces
@Singleton
public EstructuraApiConfig producerEstructuraApiConfig() {
	return new EstructuraApiConfigBuilder().executorPoolSize(20).build();
}

import es.ja.csalud.sas.componentescomunes.estructura.impl.jpa.control.config.EstructuraApiConfig;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Produces;
import jakarta.inject.Singleton;
import org.eclipse.microprofile.context.ManagedExecutor;
import org.eclipse.microprofile.context.ThreadContext;

@ApplicationScoped
public class EstructuraContext {
    @Produces
    @Singleton
    public EstructuraApiConfig producerEstructuraApiConfig() {
        ManagedExecutor executor = ManagedExecutor.builder()
                .propagated(ThreadContext.CDI, ThreadContext.APPLICATION)
                .maxAsync(20)
                .maxQueued(20)
                .build();
        return new EstructuraApiConfig.EstructuraApiConfigBuilder().executor(executor).executorPoolSize(20).build();
    }
}

6. Instrucciones de uso

Una vez configurado nuestro proyecto, el uso de la librería es tan simple como inyectar el servicio que deseemos utilizar (AreaConocimientoService, AreaHospitalariaService, etc) en cualquier parte de nuestro código para poder hacer uso de toda la funcionalidad que ofrece la librería.

A partir de la versión 2.0.0.1 de la librería se ha modificado el modo de uso de la librería de forma que todos los servicios existentes han sido evolucionados a servicios equivalentes que devuelven Futures en lugar de devolver directamente las entidades solicitadas. De esta forma el programador podrá paralelizar otras tareas mientras la librería obtiene el dato, cosa que hará que mejore el rendimiento considerablemente en el caso de que el dato tenga que ser obtenido por medio de servicios webs

En el siguiente fragmento de código puede verse un ejemplo sencillo en el que se ha diseñado un servicio llamado "EpisodioService" el cual hará tres acciones típicas de sistemas sanitarios: En primer lugar buscará en su propia base de datos un episodio a partir de un identificador dado, posteriormente usará la librería de Estructura (Marcado en rojo) para recuperar la información asociada de la cama en la que se encuentra ingresado el paciente. Tras esta llamada la librería devuelve un Future y el hilo de ejecución continua, por lo que podemos recuperar en paralelo las citas del paciente (Marcado en verde):

public class EpisodioService {

    private EpisodioDao episodioDao;
    private CitasService citasService;
    private UbicacionService ubicacionService;

    @Inject
    public EpisodioService(EpisodioDao episodioDao, CitasService citasService, UbicacionService ubicacionService) {
        this.episodioDao = episodioDao;
        this.citasService = citasService;
        this.ubicacionService = ubicacionService;
    }

    public EpisodioDTO getEpisodio(Long numEpisodio) {
        EpisodioDTO result = null;

        Context context = GeneradorContexto.createContext(...); 

        Episodio epiAux = episodioDao.getByPk(numEpisodio);
        FutureTask<Ubicacion> ubicacionFuture = ubicacionService.getUbicacionByCodigo(context, TipoUbicacionEnum.CAMA, epiAux.getCodCama())
        List<Citas> citas = citasService.getByEpisodio(numEpisodio);
        if (epiAux != null) {
            result = new EpisodioDTO();
            result.setNumEpisodio(epiAux.getNumEpisodio());
            result.setFchIngreso(epiAux.getFchIngreso());
            result.setCama(ubicacionFuture.get());
        }

        return result;
    }
}

        Mención especial requiere el atributo "Context", marcado en azul en el ejemplo anterior. Este objeto tiene como objetivo ser un contenedor de información que representa el contexto en el que nos encontramos. 
      

        Actualmente, sólo consta de un objeto de tipo MacoUser, el cual podrá usarse el día de mañana para validar los usuarios en MACO. Por ello, el objetivo es tener un servicio encargado de generar los contextos que se pasarán a la API de Estructura (En este ejemplo, sería el objeto GeneradorContexto), de esta forma, al generarse siempre el contexto desde un punto común, cuando sea necesario realizar nuevas modificaciones, estas podrán realizarse en un único punto y aplicarán automáticamente a todo el código. Consulte JavaDoc para ver detalle del objeto. Este objeto debe ser pasado como parámetro en todas las llamadas a la librería, de esta forma la implementación de la API que se esté usando podrá hacer uso del contexto para validar el usuario.
      

7. JavaDoc y Código Fuente

Toda la documentación del proyecto en forma de JavaDoc, así como el código fuente del mismo, se encuentra desplegado al Artifactory del SAS, por lo que el programador podrá descargarlo y consultarlo para ver el detalle de todas las clases de la librería.
Se recomienda especialmente consultar JavaDoc de los servicios principales de la API (AreaConocimientoService, AreaHospitalariaService, etc), donde podrá ver el detalle de todas las operaciones permitidas actualmente.

Pruebas de carga

Contexto:

• Base de datos: Entornos de desarrollo de DAE, réplica de Estructura
• Servidor web: Servicios REST publicados en una aplicación de ejemplo. Internamente hace uso de la API de Estructura
  • Intel Core i7 2520M 2.5GHz
  • 8GB Ram
  • Windows 7 64Bits
  • Weblogic 12.1.3 (1GB Ram)
• Cliente REST: jMeter 3.0

Pruebas:

En la siguiente captura puede observarse un rendimiento de unas 1000 peticiones por segundo en las pruebas de carga realizadas.

Sobre los errores producidos, se deben a urls mal formadas: