Guía de los generadores del framework Seam

Guía de los generadores del framework Seam versión 2.2.0.GA por: María Consuelo Franky Dpto. Ingeniería de Sistemas Pontificia Universidad Javeriana email: lfranky@javeriana.edu.co Mayo de 2010 pg. 1

Tabla de Contenido 1 Propósito de este documento... 3 2 Creación previa de la base de datos del proyecto... 3 3 Listar los generadores y tareas disponibles: tarea help... 3 4 Generar y publicar un proyecto Seam... 3 4.1 Tarea setup: establece las propiedades del nuevo proyecto... 4 4.2 Tarea create-project: genera el proyecto Seam inicial... 4 4.3 Tarea explode: publica en el servidor el proyecto Seam en modo exploded... 6 4.4 Importar a Eclipse el proyecto Seam... 6 4.5 Tarea restart: actualiza el proyecto exploded en el servidor... 7 5 Tareas ANT del proyecto generado... 7 6 Cambiar el modo de publicación exploded/deployed... 7 7 Generar entidades y casos de uso CRUD a partir de la base de datos... 8 7.1 Configuración de la consola Hibernate... 8 7.2 Tarea generate-model : genera entidades a partir de tablas existentes en la base de datos... 8 7.3 Tarea generate-ui: genera páginas y acciones CRUD para entidades existentes... 11 7.4 Tarea generate : combina generate-model y generate-ui... 13 8 Agregar manejo básico de seguridad al proyecto generado: tarea add-identity-management... 13 9 Generar casos de uso... 14 9.1 Tarea new-action: genera un nuevo caso de uso de tipo acción sin forma... 14 9.2 Tarea new-form: genera un nuevo caso de uso de tipo acción con forma... 15 9.3 Tarea new-conversation: genera un nuevo caso de uso de tipo conversación... 15 9.4 Tarea new-entity: genera un nuevo caso de uso de tipo CRUD para una nueva entidad... 16 10 Distintos perfiles de publicación del proyecto generado... 17 11 Actualización de librerías del proyecto: tarea update-project... 17 12 Facilidades Hibernate para trabajar con las entidades del proyecto generado... 17 pg. 2

1 Propósito de este documento El Framework Seam 2.2.0.GA con generadores y ejemplos, se obtiene como el archivo jboss-seam-2.2.0.ga.zip en http://seamframework.org/download Las instrucciones para su instalación como proyecto Eclipse y publicación de los ejemplos se encuentra en el documento 0-guia-configuracion-javaee5.doc Los generadores Seam se pueden invocar mediante el comando seam.bat (localizado a nivel del directorio donde se descomprime jboss-seam-2.2.0.ga.zip) utilizando las opciones indicadas en el README del subdirectorio seam-gen. Una manera más amistosa de invocar los generadores Seam es mediante las tareas ANT del archivo build.xml del subdirectorio seam-gen. En Eclipse se debe inscribir este archivo build.xml en la ventana Ant para tener disponibles las tareas. En este documento se da una guía para usar en orden los generadores Seam como tareas ANT. 2 Creación previa de la base de datos del proyecto Para generar un proyecto Seam se debe tener previamente la base de datos con la que se va a trabajar. Hay 2 situaciones posibles respecto a la base de datos: Base de datos nueva:la base de datos puede estar vacía si se pretende crear tablas nuevas a partir de las entidades persistentes que se vayan agregando al proyecto. Base de datos antigua: La base de datos puede tener algunas tablas existentes (con o sin datos) si se pretende generar las entidades a partir de estas tablas. Adicionalmente se le agregarán nuevas tablas a partir de las entidades que se agreguen al proyecto. 3 Listar los generadores y tareas disponibles: tarea help En la ventana Ant de Eclipse invoque inicialmente la tarea help (de seam-gen): entregará una descripción de todos los comandos disponibles y equivale al README del subdirectorio seam-gen. 4 Generar y publicar un proyecto Seam Un proyecto Seam inicial tendrá la estructura extensible para poder agregar casos de usos consistentes en entidades, componentes ejbs 3 y páginas JSF. Para obtener un proyecto Seam inicial, se deben ejecutar en orden las siguientes tareas Ant: pg. 3

4.1 TAREA SETUP: ESTABLECE LAS PROPIEDADES DEL NUEVO PROYECTO Al invocar la tarea setup (de seam-gen) se deben indicar interactivamente los siguientes valores que conformarán el archivo de propiedades del proyecto (en los paths usar / y no \): directorio del workspace de Eclipse, directorio de JBoss, nombre del proyecto, nombre del paquete base del proyecto, tipo de motor de base de datos, etc. Como resultado de la tarea, el driver JDBC indicado es instalado en el servidor JBoss y se crea el archivo de propiedades del proyecto build.properties bajo el subdirectorio seamgen Este archivo se puede editar si se quiere cambiar el valor de una propiedad (también se puede cambiar volviendo a ejecutar la tarea setup). Dentro de Eclipse se puede utilizar el editor JBoss Tools Properties Editor para editarlo de manera amistosa. 4.2 TAREA CREATE-PROJECT: GENERA EL PROYECTO SEAM INICIAL La tarea create-project (de seam-gen) crea el proyecto a partir de las propiedades indicadas en el archivo build.properties bajo el subdirectorio seam-gen El proyecto Seam generado constituye una estructura extensible para casos de usos que incluye inicialmente: todas las librerías y descriptores necesarios un ANT para la administración del proyecto: compilación, empaque y publicación archivos de propiedades para soportar varios idiomas datasource páginas iniciales, templates y hoja de estilos la clase Authenticator.java para soportar la autenticación A continuación se enumeran los principales archivos y directorios generados por Seam para un proyecto de tipo WAR (tomado del capítulo 2 de Seam in Action, Dan Allen, Manning Publications Co., 2009): pg. 4

Para un proyecto de tipo EAR se agregan los siguientes archivos: resources/meta-inf/application.xml describe los módulos de la aplicación resources/meta-inf/ejb-jar.xml describe el interceptor Seam en los componentes EJB3 deployed-jars-war.list lista de librerías que deben empacarse en el war deployed-jars-ear.list lista de librerías que deben empacarse en el ear pg. 5

4.3 TAREA EXPLODE: PUBLICA EN EL SERVIDOR EL PROYECTO SEAM EN MODO EXPLODED La tarea explode (de seam-gen) publica el proyecto en el servidor JBoss en modo exploded, es decir creando en el servidor un directorio con el contenido del ear. También publica el datasource. Antes de esta tarea debe subirse previamente el servidor JBoss (preferentemente desde Eclipse). La aplicación correspondiente al proyecto se puede invocar en: http://localhost:<puerto>/<proyecto> (por ejemplo http://localhost:8090/demojaveriana suponiendo que el puerto default 8080 de JBoss ha sido cambiado por 8090). Observar que la aplicación ofrece una página de bienvenida con una opción de Login que permite la autenticación del usuario mediante la acción Authenticator.java 4.4 IMPORTAR A ECLIPSE EL PROYECTO SEAM El proyecto Seam debe importarse a Eclipse usando File > New > Project : seleccione General > Project (not Java Project) e indique el nombre del proyecto (por ej: demojaveriana) Una vez inscrito el proyecto en Eclipse ir a sus propiedades (con click-derecho seleccionar Properties) y en Builders desactivar explode : de esta manera se evita que cada vez que se refresque el proyecto trate de hacer tareas como compilar y publicar en el servidor. pg. 6

4.5 TAREA RESTART: ACTUALIZA EL PROYECTO EXPLODED EN EL SERVIDOR El proyecto Seam publicado previamente en el servidor JBoss en modo exploded, debe actualizarse mediante la tarea restart (de seam-gen). Después de esta tarea se puede volver a invocar la aplicación correspondiente al proyecto en: http://localhost:<puerto>/<proyecto> 5 Tareas ANT del proyecto generado Cuando se inscribe en la ventana ANT de Eclipse el build.xml del proyecto Seam generado, se puede administrar directamente el proyecto sin depender de seam-gen, mediante las siguientes tareas: Para trabajar en modo de publicación exploded: explode: para publicar la aplicación en el servidor restart: para actualizar la aplicación en el servidor con cambios en páginas unexplode : para despublicar del servidor Para trabajar en modo de publicación deployed: deploy: para publicar la aplicación en el servidor clean: para eliminar el ear antes de invocar deploy undeploy : para despublicar del servidor Otros: archive: para generar el ear del proyecto sin publicarlo buildtest: para generar clases incluyendo tests unitarios en el directorio output folder del proyecto test: para ejecutar los tests del proyecto (consutar las instrucciones previas en el manual de Seam 0-seam_reference-2.2.0.GA.pdf). 6 Cambiar el modo de publicación exploded/deployed Aunque el modo de publicación exploded (que crea un directorio del proyecto en el servidor) permite hacer cambios de páginas web en caliente, no puede refrescar de igual manera los cambios ocurridos en las clases. Cada vez que se modifiquen las clases deberá entonces invocarse la tarea restart para lograr una actualización total en el servidor. Alternativamente se puede trabajar con el modo de publicación deployed (recomendado para operación) el cual publica en el servidor el archivo empacado.ear del proyecto. Las tareas para pasar del modo exploded al modo deployed son las siguientes: tarea unexplode: despublica un proyecto exploded pg. 7

tarea deploy: publica un proyecto en modo deployed (si ocurre una excepción en esta tarea, debe bajarse el servidor para eliminar manualmente el directorio del proyecto en el servidor; luego reiniciar el servidor y volver a invocar la tarea deploy) Las tareas para pasar del modo deployed al modo explode son las siguientes: tarea undeploy: despublica un proyecto deployed tarea explode: publica un proyecto en modo exploded 7 Generar entidades y casos de uso CRUD a partir de la base de datos El framework Seam ofrece tareas de ingeniería reversa para generar entidades y casos de uso CRUD a partir de tablas existentes en la base de datos. 7.1 CONFIGURACIÓN DE LA CONSOLA HIBERNATE La configuración de consola Hibernate para el proyecto debe aparecer con el nombre del proyecto en la perspectiva Hibernate en la ventana Hibernate Configurations. Al expandirla en su sección Database deben verse las tablas de la base de datos del proyecto. Como prerequisitos: No debe haber espacios en la ruta de del directorio donde está instalado Eclipse ni en la ruta donde está el workspace. El archivo hibernate-console.properties debe contener el url de conexión a la base de datos en forma correcta, sin espacios adicionales después del nombre de la base de datos. Ejecutar la tarea buildtest (del proyecto generado) para colocar en el directorio output folder del proyecto (subdirectorio test-build) todas las clases y el descriptor persistence.xml Actualizar con Refresh tanto el proyecto con Refresh como la configuración de la consola hibernate del proyecto Reconstruir la configuración de consola Hibernate para el proyecto mediante la opción Rebuild configuration (con click-derecho). 7.2 TAREA GENERATE-MODEL : GENERA ENTIDADES A PARTIR DE TABLAS EXISTENTES EN LA BASE DE DATOS La tarea generate-model (de seam-gen) extiende el proyecto Seam previamente generado con clases de entidades correspondientes a todas las tablas de la base de datos. Alternativamente se puede delimitar el conjunto de tablas indicando un subconjunto en el descriptor resources/seam-gen.reveng.xml Abrir este descriptor con el editor Hibernate reverse engineering editor : pg. 8

En la pestaña Overview seleccionar la configuración de consola Hibernate del proyecto En la pestaña Table Filters: oprimir el botón Refresh para ver las tablas de la base de datos y luego seleccionar aquéllas para las cuales se van a generar entidades. Tener cuidado de no seleccionar vistas. Opcionalmente pueden indicarse los nombres de los atributos Java que se van a generar para las columnas de las tablas, transformación de tipos de la base de datos a tipos Java, código para calcular atributos transientes etc. (ver el manual 4-Hibernatetools_Reference_Guide.pdf) Es importante asegurarse de que las tablas seleccionadas no tienen restricciones de integridad duplicadas. Invocar la tarea generate-model: genera una clase entidad (bajo el subdirectorio src/main).por cada tabla seleccionada en el descriptor seam-gen.reveng.xml Ejemplos del texto del descriptor seam-gen.reveng.xml son los siguientes (tomado del capítulo 2 de Seam in Action, Dan Allen, Manning Publications Co., 2009; otros ejemplos pueden encontrarse en: https://www.hibernate.org/hib_docs/tools/reference/en/html/reverseengineering.html ): Indicar los nombres de las propiedades (atributos) de algunas de las entidades Java que van a generarse e indicar métodos adicionales en esas entidades: pg. 9

Filtrar las tablas que van a generar entidades e indicar relaciones faltantes que no aparecen en la base de datos o para buscar conjuntos de tablas, en <table-filter> se indican patrones de esquema y de nombres de tablas; con exclude=false las tablas encontradas se incluyen en un conjunto inicialmente vacío, o de lo contrario las tablas encontradas se excluyen del conjunto total de tablas; se puede usar el carácter especial * en los patrones de nombres a buscar o en <table> puede indicarse el nombre de la entidad correspondiente a una tabla, nombres de atributos (como se mostró en el ejemplo anterior), y relaciones faltantes entre tablas que generarán relaciones entre entidades. pg. 10

<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE hibernate-reverse-engineering SYSTEM "http://hibernate.sourceforge.net/hibernate-reverse-engineering-3.0.dtd"> <hibernate-reverse-engineering> <table-filter match-schema="equipment" match-name="prdct" exclude="false"/> <table-filter match-schema="equipment" match-name="mfr" exclude="false"/> <table-filter match-schema="equipment" match-name="eq_typ" exclude="false"/> <table name="eq_typ" class="org.open18.model.equipmenttype"/> <table name="prdct" class="org.open18.model.product"> <foreign-key foreign-table="mfr"> <column-ref local-column="mfr_id" foreign-column="id"/> </foreign-key> <foreign-key foreign-table="eq_typ"> <column-ref local-column="eq_typ_id" foreign-column="id"/> </foreign-key> </table> <table name="mfr" class="org.open18.model.manufacturer"/> </hibernate-reverse-engineering> 7.3 TAREA GENERATE-UI: GENERA PÁGINAS Y ACCIONES CRUD PARA ENTIDADES EXISTENTES La tarea generate-ui (de seam-gen) genera casos de uso CRUD para todas las entidades existentes en el proyecto. Cada caso de uso CRUD permitirá ver la lista de instancias de una entidad y realizar las operaciones de creación, consulta, actualización y eliminación de una instancia. Además permitirá navegar siguiendo las relaciones entre las entidades. Debe tomarse la precaución de guardar una copia de los fuentes de un caso de uso CRUD generado y modificado previamente para una entidad, pues los fuentes serán reemplazados por los que genere esta tarea. Como resultado de la tarea y después de republicar el proyecto en el servidor (con las tareas ANT clean y deploy), se tendrá en la página principal del proyecto un menú con enlace para cada caso de uso CRUD generado, por ej: pg. 11

Al invocar un caso de uso CRUD aparece un filtro opcional de búsqueda y la lista de instancias de la entidad asociada mediante una tabla paginada y ordenable por cualquiera de sus columnas, por ej: Al seleccionar un elemento de la lista aparecerá la página que muestra la instancia junto con sus relaciones con maestros y detalles, por ej: pg. 12

También permite crear una nueva instancia de la entidad, asociándola a una instancia maestra y a una o varias instancias de entidades detalle. Utiliza validaciones AJAX para los campos de la nueva instancia. NOTA: eventualmente la página de edición de una entidad que tiene varias entidades maestras puede presentar el error de repetir el id de 2 elementos dentro de la página. Para corregir este error se debe cambiar el id en uno de esos elementos. 7.4 TAREA GENERATE : COMBINA GENERATE-MODEL Y GENERATE-UI La tarea generate (de seam-gen) produce los efectos combinados de las tareas generatemodel (generar entidades a partir de la base de datos) y generate-ui (generar casos de uso CRUD para las entidades del proyecto). 8 Agregar manejo básico de seguridad al proyecto generado: tarea add-identity-management Esta tarea add-identity-management (de seam-gen) genera entidades para soportar el manejo de seguridad (cuentas de usuario, roles y permisos) apoyándose en el componente Identity proporcionado por Seam. El proyecto se debe republicar en el servidor (con las tareas ANT clean y deploy) para crear las tablas correspondientes en la base de datos. pg. 13

Suponiendo que el modo de persistencia del proyecto es update (especificado en el descriptor persistence-dev.xml) se debe ejecutar sobre la base de datos el script resources/import-dev.sql para insertar las cuentas iniciales de usuarios. La tarea también genera una página para administrar usuarios y roles: 9 Generar casos de uso El framework Seam ofrece generadores de casos de uso de 4 tipos. En cualquiera de ellos se genera como punto de arranque una página y el soporte de clases con el fin de que el programador pueda seguir extendiendo los archivos generados incorporando la lógica de negocio. 9.1 TAREA NEW-ACTION: GENERA UN NUEVO CASO DE USO DE TIPO ACCIÓN SIN FORMA La tarea new-action (de seam-gen) extiende el proyecto Seam previamente generado con el soporte para un nuevo caso consistente en: Un EJB de sesión sin estado (SLSB) con un método de acción Una página con un botón que invoca la acción Test unitario (JUnit) y test funcional del caso de uso (TestNG) Se debe republicar el proyecto en el servidor (con las tareas ANT clean y deploy) para observar el funcionamiento del caso de uso (invocado desde un enlace en la barra superior). pg. 14

9.2 TAREA NEW-FORM: GENERA UN NUEVO CASO DE USO DE TIPO ACCIÓN CON FORMA La tarea new-form (de seam-gen) extiende el proyecto Seam previamente generado con el soporte para un nuevo caso consistente en: Un EJB de sesión con estado (SFSB) con un método de acción Una página con un forma Test unitario (JUnit) y test funcional del caso de uso (TestNG) Se debe republicar el proyecto en el servidor (con las tareas ANT clean y deploy) para observar el funcionamiento del caso de uso (invocado desde un enlace en la barra superior). 9.3 TAREA NEW-CONVERSATION: GENERA UN NUEVO CASO DE USO DE TIPO CONVERSACIÓN La tarea new-conversation (de seam-gen) extiende el proyecto Seam previamente generado con el soporte para un nuevo caso consistente en: Un EJB de sesión con estado (SFSB) con 3 métodos de acción que trabajan en modo conversación (anotaciones @Begin y @End de Seam) Una página con 3 botones que invocan las acciones pg. 15

Se debe republicar el proyecto en el servidor (con las tareas ANT clean y deploy) para observar el funcionamiento del caso de uso (invocado desde un enlace en la barra superior). 9.4 TAREA NEW-ENTITY: GENERA UN NUEVO CASO DE USO DE TIPO CRUD PARA UNA NUEVA ENTIDAD La tarea new-entity (de seam-gen) extiende el proyecto Seam previamente generado con el soporte para un nuevo caso consistente en: Una nueva entidad con 3 atributos (id, version, name) 2 clases que extienden EJB internos del framework Seam y que ofrecen las acciones para manejar la lista de instancias de la entidad o manejar una instancia particular Una página que mostrará la lista de instancias de la entidad y otra página para mostrar y editar una instancia particular. Para que el servidor pueda crear en la base de datos la tabla correspondiente a la nueva entidad, es necesario que el modo de persistencia del proyecto sea update, modo indicado en el descriptor persistence-dev.xml Se debe republicar el proyecto en el servidor (con las tareas ANT clean y deploy) para observar el funcionamiento del caso de uso (invocado desde un enlace en la barra superior). pg. 16

10 Distintos perfiles de publicación del proyecto generado El proyecto generado con Seam ofrece 3 perfiles que permite 3 tipos de publicación en el servidor: dev (desarrollo), prod (producción) y test. El perfil se selecciona mediante la propiedad profile del archivo build.properties Por ejemplo se puede seleccionar el perfil de producción así: profile=prod Suponiendo que <perfil> representa uno de los 3 perfiles, para cada uno de ellos Seam genera los siguientes archivos de configuración: build-<perfil>.properties: propiedades utilizadas por el ant del proyecto persistence-<perfil>.xml : configuración de persistencia JPA import-<perfil>.sql : script de inserción de datos cuando el modo de persistencia es create <basedatos>-<perfil>-ds.xml : define el datasource con el que se va a trabajar; <basedatos> es un nombre arbitrario que en general corresponde al nombre de la base de datos. 11 Actualización de librerías del proyecto: tarea update-project Con esta tarea update-project (de seam-gen)se bajan las versiones más recientes de las librerías que utiliza el proyecto generado (para lo cual seam-gen utiliza las facilidades de maven). Es aconsejable hacer una copia previa del proyecto, pues la actualización de librerías puede tener impacto en el funcionamiento del proyecto, sobre todo si ya se le ha agregado código después de la generación inicial. 12 Facilidades Hibernate para trabajar con las entidades del proyecto generado Pueden usarse las facilidades de Hibernate referentes al editor HQL para probar queries JPQL sobre las entidades del proyecto y para obtener un diagrama de sus relaciones: Configurar la consola de Hibernate tal como se indicó en la sección 7.1 En la perspectiva Hibernate situarse en la ventana Hibernate Configurations y reconstruir la configuración de la consola Hibernate para el proyecto, mediante la opción Rebuild configuration (con click-derecho). pg. 17

Al expandir la sección Configuration deben aparecer las entidades del proyecto y en la sección Session Factory debe aparecer la lista de clases asociadas. Con click-derecho sobre una entidad se puede solicitar la opción Open Mapping Diagram que muestra un diagrama completo de las relaciones entre entidades, indicando las tablas asociadas. Solicitar la opción HQL editor sobre la configuración de la consola Hibernate: se abrirá la ventana que permite editar y ejecutar consultas JPQL. Se podrán obtener los resultados (instancias de entidades) y ver el SQL correspondiente a la consulta. pg. 18