Download Herramienta de Generación de Código Framework

Herramienta de Generación de Código
Framework ATLAS
Versión 1.1
Área de Aplicaciones Especiales y Arquitectura de
Software
Framework Atlas
Crystal Reports 2008
Hoja de Control
Título
Manual de Usuario de la Herramienta de Generación de Código de ATLAS
Documento de
NORMATIVA ATLAS
Referencia
Responsable
ICM
Versión
1.1
Fecha Versión
Fecha
1
Revisado/Validado por:
2
12/06/2012
Revisión/Validación
Aprobado por:
Fecha Aprobación
Registro de Cambios
Versión
Causa del Cambio
Responsable del Cambio
Fecha del Cambio
Área de Aplicaciones Especiales y
1.0
Versión inicial del documento
1.1
Nueva versión de la herramienta
que incluye generación de
pantallas.
Listado de ficheros modificados
y/o creados por la herramienta
Documentada incrementalidad
parcial.
Documentado alcance y
funcionalidades futuras
Arquitectura de Software
23/02/2012
Área de Aplicaciones Especiales y
Arquitectura de Software
Página 2 de 20
12/06/2012
Framework Atlas
Crystal Reports 2008
Índice
1
INTRODUCCIÓN ................................................................................................................................................................ 4
1.1
1.2
2
AUDIENCIA OBJETIVO .............................................................................................................................................. 4
CONOCIMIENTOS PREVIOS ...................................................................................................................................... 4
USO DE LA HERRAMIENTA ........................................................................................................................................... 6
2.1
2.2
2.3
2.4
2.5
2.6
2.7
CONFIGURACIÓN DE LA CONSOLA DE HIBERNATE .......................................................................................... 7
CONFIGURACIÓN DEL PAQUETE JAVA ................................................................................................................. 8
CONFIGURACIÓN DE LA CONEXIÓN A BASE DE DATOS ................................................................................... 9
SELECCIÓN DE LAS TABLAS .................................................................................................................................... 9
EJECUCIÓN ................................................................................................................................................................. 11
COMPROBACIÓN DE CÓDIGO GENERADO ......................................................................................................... 14
EJECUCIÓN DE LA APLICACIÓN ............................................................................................................................ 17
3
USO INCREMENTAL DE LA HERRAMIENTA .......................................................................................................... 19
4
ALCANCE DE LA VERSIÓN ACTUAL ......................................................................................................................... 20
Página 3 de 20
Framework Atlas
Crystal Reports 2008
Contenido
1
INTRODUCCIÓN
A partir de la versión 1.2.0 del framework de desarrollo de aplicaciones ATLAS, se incluye una herramienta de
generación automática de código. Esta herramienta permite, a partir de un modelo de datos, generar una serie
de clases Java que se utilizarán para acceder a ese modelo de datos desde una aplicación ATLAS.
En la versión actual, además del código Java, la herramienta genera las pantallas que permiten administrar el
contenido de las tablas seleccionadas, con las operaciones de alta, baja y modificación.
La versión actual de la herramienta genera el siguiente código fuente:
-
Clases con los objetos de Domino
-
Clases con los DAOs
-
Clases con los Servicios
-
Clase(s) con la Fachada
-
Tests de JUnit de los servicios
-
Backing Beans de JSF
-
Ficheros xhtml con las pantallas para los listados de entidades
-
Ficheros xhtml con las pantallas para los formularios de alta y edición de entidades
La herramienta nos permite seleccionar las tablas de las que queremos generar el código, y a partir de ellas realiza
una ingeniería inversa del modelo de datos y genera el código en la aplicación.
Para el desarrollo de la herramienta se ha tomado como punto de partida el plugin JBoss Hibernate Tools, y se
ha personalizado su configuración para adaptarlo a las necesidades propias de ATLAS.
En este documento se describe cómo configurar la herramienta, y cómo utilizarla para generar código fuente.
1.1
AUDIENCIA OBJETIVO
Este documento está orientado a toda aquella persona que desee desarrollar una aplicación con el framework
ATLAS y para ello requiera interaccionar con un modelo de datos.
1.2
CONOCIMIENTOS PREVIOS
Para un completo entendimiento del documento, el lector deberá tener conocimientos previos sobre las siguientes
tecnologías:
Lenguaje Java
Spring
JSF
Página 4 de 20
Framework Atlas
Crystal Reports 2008
Hibernate
Framework de desarrollo de aplicaciones ATLAS
Página 5 de 20
Framework Atlas
Crystal Reports 2008
2
USO DE LA HERRAMIENTA
Este documento toma como punto de partida un Arquetipo Web recién generado, y asume que se dispone del
entorno Eclipse correctamente configurado y con el plugin JBoss Hibernate Tools instalado. Si no se dispone del
arquetipo o el entorno, para más información sobre cómo configurar el entorno y generar un arquetipo web,
consultar el manual ATLAS_MUS_Preparacion_Entorno_Desarrollo.
En los ejemplos mostrados en este documento se ha utilizado un arquetipo web generado con los siguientes
parámetros:
Para configurar el entorno de desarrollo para utilizar la herramienta, y posteriormente utilizarla es necesario realizar
los pasos descritos en los siguientes apartados.
Página 6 de 20
Framework Atlas
Crystal Reports 2008
2.1
CONFIGURACIÓN DE LA CONSOLA DE HIBERNATE
Antes de poder utilizar la ingeniería inversa, es necesario crear una Consola de Hibernate. Para ello, pulsamos con
el botón derecho sobre la carpeta “generador”, seleccionamos “New -> Other -> Hibernate Console
Configuration”:
Pulsamos sobre “Next” y aparece la pantalla para crear una nueva consola.
Página 7 de 20
Framework Atlas
Crystal Reports 2008
En este pantalla, pulsamos sobre “Finish” y la consola ya estará creada.
2.2
CONFIGURACIÓN DEL PAQUETE JAVA
Las clases que generará la herramienta estarán dentro de un paquete que puede ser configurado a través de la
variable “generador.paquete” del fichero “web/src/main/resources/environment.properties”. Se deberá
modificar el valor de esta variable para configurar el paquete en el que deseamos generar las clases Java:
Página 8 de 20
Framework Atlas
Crystal Reports 2008
2.3
CONFIGURACIÓN DE LA CONEXIÓN A BASE DE DATOS
Para que la herramienta pueda conectarse a la base de datos, debemos modificar el fichero de configuración del
arquetipo situado en “web/generador/hibernate.cfg.xml”, y modificar las siguientes propiedades:
hibernate.connection.url: Cadena de conexión JDBC.
-
Ej: jdbc:oracle:thin:@icm21:1521:denivel2
hibernate.connection.username: Usuario de conexión a la base de datos.
-
Ej: DBA_EJPL
hibernate.connection.password: Contraseña de conexión.
hibernate.default_schema: Schema de conexión (igual que el usuario).
-
2.4
Ej: DBA_EJPL
SELECCIÓN DE LAS TABLAS
Antes de ejecutar la herramienta tenemos que seleccionar las tablas para las que queremos realizar la generación.
Para ello, debemos abrir el fichero “generador/hibernate.reveng.xml”, y seleccionar la pestaña “Table Filters”:
Página 9 de 20
Framework Atlas
Crystal Reports 2008
Aquí, pulsamos sobre el botón “Refresh”, y aparecerá un desplegable en el que debemos seleccionar consola de
hibernate que ya habíamos creado:
En ese momento es posible que aparezca el siguiente mensaje:
Página 10 de 20
Framework Atlas
Crystal Reports 2008
Pulsamos sobre “Yes”, y ya podemos desplegar en la zona “Database Schema” todas las tablas del esquema.
Debemos seleccionar las tablas que queramos, y pulsar sobre “Include…”, para pasarlas a la zona de la izquierda
y que así sean utilizadas para la generación de código.
Cuando hayamos terminado de seleccionar las tablas, pulsaremos sobre “Save” para guardar el fichero:
2.5
EJECUCIÓN
Una vez que ya hemos terminado de configurar la herramienta, podemos proceder a su ejecución para generar el
código. La ejecución de la herramienta se realiza mediante Maven, para ello pulsamos con el botón derecho sobre
el proyecto “XXXX_web”, y seleccionamos “Run As… -> Maven build”:
Página 11 de 20
Framework Atlas
Crystal Reports 2008
En la pantalla que aparece, deberemos rellenar los siguientes valores:
-
Goal: generate-resources
-
Profiles: generador
Posteriormente pulsamos sobre el botón “Run” para ejecutar Maven con esos valores:
Página 12 de 20
Framework Atlas
Crystal Reports 2008
Comenzará entonces la ejecución de la herramienta, que mostrará todo el log por la consola:
Página 13 de 20
Framework Atlas
Crystal Reports 2008
Nota 1
Si se ha seleccionado alguna tabla que no contenga definida una PRIMARY KEY, la herramienta de generación
de código preguntará por pantalla qué columnas identifican unívocamente los elementos de esa tabla. Debemos
introducir los nombres de las columnas EN MAYÚSCULA separados por coma (si pulsamos “Enter” sin introducir
ningún nombre de columna, utilizará todas las columnas de la tabla como clave única):
Nota 2
Es importante revisar el log de la consola, porque en ocasiones se muestran advertencias sobre ficheros que no
se han creado porque ya existían, o modificaciones que no se ha podido realizar.
2.6
COMPROBACIÓN DE CÓDIGO GENERADO
Una vez ejecutada la herramienta, sólo queda comprobar que el código se ha generado correctamente. Para ello,
debemos pulsar con el botón derecho sobre el proyecto “XXXX_Web”, y seleccionar la opción “Refresh”:
Página 14 de 20
Framework Atlas
Crystal Reports 2008
Podemos comprobar entonces que se han generado los ficheros deseados, tanto Java como xhtml dentro de las
carpetas correspondientes del arquetipo. A continuación se muestra una tabla con los ficheros que crea y/o
modifica la herramienta de generación de código durante su ejecución:
Creación /
Fichero
Descripción
Modificación
Creación, sólo Entidades de dominio asociadas a cada una
src/main/java/xxxx/domain/YYYY.java
si no existe
src/main/java/xxxx/dao/BaseDAO.java
Creación, sólo
src/main/java/xxxx/dao/BaseDAOImpl.java
si no existe
de las tablas seleccionadas.
Clases padre de las que heredan los
distintos DAOs para cada una de las tablas
seleccionadas.
src/main/java/xxxx/dao/YYYYDAO.java
Creación, sólo Clases con los DAOs para cada una de las
src/main/java/xxxx/dao/YYYYDAO.java
si no existe
entidades.
Creación, sólo Bean de respaldo de JSF para el
src/main/java/xxxx/jsf/YYYYBean.java
si no existe
Modificación
(si no existen
src/main/java/xxxx/jsf/NavigationResults.java
ya los
cambios)
src/main/java/xxxx/services/BaseService.java
Creación, sólo
src/main/java/xxxx/services/BaseServiceImpl.java
si no existe
mantenimiento de los catálogos
Resultados de navegación de las distintas
páginas JSF, que se utilizan en facesnavigation.xml
Clases padre de las que heredan los
distintos Servicios para cada una de las
tablas seleccionadas.
src/main/java/xxxx/services/YYYYService.java
Creación, sólo Clases con los Servicios para cada una de
src/main/java/xxxx/services/YYYYServiceImpl.java
si no existe
Creación si no
src/main/java/xxxx/services/facade/XxxxFacade.java
src/main/java/xxxx/services/facade/XxxxFacadeImpl.java
existe, y
modificación.
las entidades.
Clases con la fachada y la implementación
para el paquete xxxx.
Creación, sólo Clases con los Tests de JUnit de cada uno
src/test/java/xxxx/services/YYYYServiceTest.java
si no existe
src/main/resources/conf/applicationContext-
Modificación
database.xml
src/main/resources/conf/applicationContext-dao.xml
Modificación
de los servicios.
Incluye el paquete de las clases generadas
en la entrada “packagesToScan”.
Incluye los Beans para los distintos DAOs.
Incluye los Beans para los distintos
src/main/resources/conf/applicationContextservices.xml
Modificación
Servicios.
Crea y/o modifica el bean de la fachada para
inyectar los servicios.
Incluye las opciones de menú
src/main/resources/menu.xml
Modificación
correspondientes a cada uno de los
catálogos administrados
Página 15 de 20
Framework Atlas
Crystal Reports 2008
src/main/resources/msg/messages_es.properties
Modificación
src/main/webapp/WEB-INF/faces-managed-beans.xml
Modificación
src/main/webapp/WEB-INF/faces-navigation.xml
Modificación
src/main/webapp/secure/catalogos.xhtml
src/main/webapp/secure/listaYYYY.xhtml
src/main/webapp/secure/formularioYYYY.xhtml
Incluye todos los textos mostrados en las
distintas pantallas
Incluye la declaración de los distintos
Managed Beans.
Incluye las reglas de navegación para las
distintas pantallas
Creación si no Página principal de administración de
existe
catálogos
Creación si no Página JSF para listado de elementos de la
existe
entidad YYYY
Creación si no Página JSF para edición y alta de elementos
existe
de la entidad YYYY
Nota 1
En casos excepcionales es posible que algunos de los tests de JUnit no se ejecuten correctamente, en ese caso
será necesario revisar los logs de ejecución para identificar los posibles errores y corregirlos.
En tablas con Primary Key única y numérica, el generador de código asume que se cumple la normativa de
Base de Datos y ERWIN V7, por lo que asume que existe una secuencia con la nomenclatura
XXXX_S_NOMBRETABLA, que utilizan las entidades para crear nuevos objetos. Un fallo típico en los tests de
JUnit es al tratar de insertar un objeto de algún tipo de datos para el cuál no existe la secuencia.
Nota 2
En tablas con foreign keys no nulas a otras entidades de dominio , la herramienta de generación de código
genera el código de los Tests de JUnit, pero deja comentada la anotación @Test, y por tanto el test no se
ejecuta. En estos casos deberá modificarse el test manualmente, y posteriormente descomentar la anotación para
que se ejecute el test.
Para saber dónde hay que modificar el test, la herramienta deja un comentario “// TODO: “ en las líneas concretas:
Página 16 de 20
Framework Atlas
Crystal Reports 2008
Nota 3
Puede observarse que para poder tratar las entidades de manera genérica en las pantallas de administración de
catálogos, la herramienta de generación de código crea tres métodos anotados como @Transient en las
entidades de dominio. Estos métodos son:
-
getPKAsString y getPKFromString: necesarios para identificar una entidad a través de una cadena
de texto.
-
getTextoListaValores: Utilizado para mostrar un texto descriptivo de la entidad cuando se muestra
dentro de una lista de valores.
2.7
EJECUCIÓN DE LA APLICACIÓN
Por último, debemos de ejecutar Maven para compilar el proyecto (goals “clean install”), y comprobar que los tests
de JUnit generados se ejecutan correctamente.
Página 17 de 20
Framework Atlas
Crystal Reports 2008
Después, procederemos a ejecutar la aplicación para comprobar que efectivamente se han generado las pantallas
de mantenimiento de catálogos. La herramienta de generación automática de código genera una sub-opción de
menú por cada catálogo, en la opción “Mantenimiento de Catálogos”:
Página 18 de 20
Framework Atlas
Crystal Reports 2008
3
USO INCREMENTAL DE LA HERRAMIENTA
La herramienta está pensada para poderse ejecutar incrementalmente, de manera que se puedan generar las
pantallas correspondientes a una serie de tablas, y en el futuro cuando se añadan tablas nuevas volverse a
ejecutar con las nuevas.
Así, antes de introducir una modificación en el código, la herramienta comprueba que dicha modificación no exista
ya, de forma que no realiza ninguna modificación dos veces.
Nota
La incrementalidad de la herramienta de generación de código es incrementalidad a nivel de tabla, no a nivel
de campo. Si se modifican las columnas de una tabla para la que ya se generó el código, es necesario eliminar
primero manualmente el código anterior para que vuelva a generarse el código con los campos modificados.
Página 19 de 20
Framework Atlas
Crystal Reports 2008
4
ALCANCE DE LA VERSIÓN ACTUAL
La versión actual de la herramienta genera correctamente las pantallas para el mantenimiento cualquier tabla de
base de datos independientemente de que se cumpla o no la nueva normativa (Erwin 7). Por tanto, pueden
generarse pantallas para la administración de tablas heredadas que no tengan integridad referencial, o que tengan
claves únicas identificadas por varios campos.
Sin embargo, existen algunas limitaciones que se irán resolviendo en versiones futuras:
1) Vistas: La herramienta no identifica que una entidad se refiere a una vista, por lo que añade los métodos y
pantallas para edición, creación y eliminación de elementos (imposible en una vista). En el futuro la
herramienta identificará que se trata de una vista y sólo generará los métodos y pantallas necesarios.
2) Campos Lob (Blob y Clob): La herramienta no administra tablas con campos de tipo Blob/Clob, en el
futuro se incluirá esta funcionalidad para que pueda descargarse el Blob/Clob a un fichero local (o subirse
a la aplicación si se trata de un alta / modificación).
En la versión actual, las pantallas asociadas a tablas con campos Blob/Clob tienen un mensaje indicando
que no se soporta dicho campo:
Página 20 de 20