Atlas Normativa

ATLAS
Normativa
Versin 1.13 (Corresponde a Versin de ATLAS 1.2.4)
Arquitectura de Software
Framework Atlas
Normativa Hoja de Control
Ttulo Documento de Referencia Responsable Versin
NORMATIVA
Arquitectura de Software 1.13 Fecha Versin 11/07/2013
Registro de Cambios Responsable del Cambio rea de Aplicaciones 1.0 Versin inicial del documento, se parte de la normativa creada antes de desarrollar el framework Modificaciones sobre versin 1.0: Norma: JSFHttpSession: Se cambia la redaccin de la norma ya que poda malinterpretarse. Norma: JSFNavegacion: Se modifica la nomenclatura de la clase para el caso de haber varios bloques funcionales. Norma: SNDependencias: Se modifica la norma para permitir varios ficheros de contexto. Norma: DAODependencias: Nueva norma sobre versin 1.0. Se incluye una norma para la nomenclatura del fichero de contexto de los DAOS. Aunque esta norma no exista el arquetipo ya vena con esta nomenclatura. Especiales y Arquitectura de Software 24/05/2010
Versin
Causa del Cambio
Fecha
rea de Aplicaciones Especiales y Arquitectura de Software 02/07/2010
1.1
Modificaciones sobre versin 1.1: 1.2 applicationContext-database.xml: Ya no se anotan las clases, se hace por paquete con la propiedad packagesToScan. EntornoEjecucion: Se cambia de la jdk de Sun a la jRockit. rea de Aplicaciones Especiales y Arquitectura de Software 17/08/2010
Se modifica la versin de la jdk y versin de weblogic 1.3 Modificaciones sobre versin 1.2: Apartado 6.3.5: Se incluye un aviso al rea de Aplicaciones Especiales y 31/08/2010
2 de 191
Framework Atlas
Normativa Responsable del Cambio Arquitectura de Software
Versin
Causa del Cambio final del apartado. Apartado 6.4.3: Nueva implementacin en la clase Cliente de los mtodos equals / hashcode / toString. Se aade una recomendacin a este respecto Apartado 6.4.4: Se incluye informacin sobre BaseDAO y se actualiza el cdigo correspondiente. Se adaptan las normas segn esta nueva implementacin. Se amplia la norma ADCatalogos para indicar que no se debe borrar en cascada sobre un catlogo. Apartado 6.4.4.1: Nuevo apartado y norma ADNamedParameter para uso obligatorio de named parameters en consultas de BBDD. Apartado 6.4.6.1: Se elimina un texto El siguiente ejemplo en el apartado 6.4.6.1 que no tena lugar ah ya que est prohibido su uso. Norma Arquetipos: Aadido a la norma requisito para arquetipo de proyectos. Apartado 9.5: Nueva regla INTNomClient
Fecha
1.4
Se incluyen las siguientes buenas practicas: - JSFMessages - JSFStoreError - JSFAtlasFacesUtils - JSFAccesoMessages Que se refieren a la utilizacin de la clase AtlasFacesUtils en distintos casos. Modificaciones sobre versin 1.4: Apartado 6.3.3: Se incluye nueva norma SNSpringLIB slo para mdulos de tipo librera Apartado 6.3.3: Se modifica la norma SNDependencias indicando que no aplica a mdulos de tipo librera Apartado 6.4.2.3: Se modifica la norma DAODependencias indicando que no aplica a mdulos de tipo librera Apartado 7: Se modifica la norma CONFNomenclatura sustituyendo nombre de proyecto por nombre de mdulo.
1.5 -
3 de 191
Framework Atlas
Normativa Responsable del Cambio
Versin -
Causa del Cambio Apartado 7: Se incluyen dos nuevas normas sobre las particularidades en la configuracin de los mdulos de tipo librera. Apartado 5: Nueva norma VERSIONADO. Apartado 9.7.1: Se modifica la normativa de acceso a Crystal Reports. Se modifica la norma SOLRptConf.
Fecha
Modificaciones sobre versin 1.5: Apartado 5: Se actualiza grfico de mdulos para eliminar el sufijo intra. El framework Atlas permite que el mismo mdulo sirva para intranet e Internet por lo tanto este sufijo ya no tiene sentido. 1.6 Apartado 6: Modificada norma JSFJavascript. Apartado 7: Modificada norma CONFEntorno. Apartado 10.1: Se incluye la posibilidad de excluir la comprobacin de normas en la herramienta de validacin. Modificaciones sobre versin 1.6: Apartado 8.1: Nueva norma SBAutoPerfiles 1.7 Nuevo Apartado 6.3.6: Ficheros temporales. Apartado 6.3.6: Nueva norma SNFicherosTemporales y nueva buena prctica SNNomFicheroTemporal Apartado 6.2.1: Nuevas buenas prcticas JSFGet y JSFEL. Apartado 6.2.1.9: Modificada buena prctica JSFAjaxLimite. Apartado 11.1 Tipos de pruebas: Incluida nuevo tipo de prueba para las rea de Aplicaciones Especiales y Arquitectura de Software 21/09/2011 rea de Aplicaciones Especiales y Arquitectura de Software 25/04/2011
4 de 191
Framework Atlas
Versin
Causa del Cambio pruebas de los servicios web. Por lo tanto se incluye una nueva norma TestServicioWeb Se actualiza el nombre del Area (Area de Aplicaciones Especiales y Arquitectura Software) Modificaciones sobre versin 1.7: Apartado 6.4.4: Modificado cdigo fuente de clases BaseDAO y BaseDAOImpl
Fecha
1.8
Apartado 6.3.2: Incluidas en los arquetipos las clases BaseService y BaseServiceImpl. Aadida la nueva buena prctica ADBaseService
Apartado 6.2.1: PAGINAS JSF: Se eliminan las referencias a la librera de componentes de JSF Tomahawk, ya que ha dejado de utilizarse.
Apartado 6.2.3 Configuracion de JSF: Se incluye la posibilidad de usar anotaciones. rea de Aplicaciones Especiales y Arquitectura de Software 14/06/2012
1.9 -
Nuevo Apartado 6.2.3.5: Anotaciones. Buena Prctica JSFMessages: Se cambia el uso de t:message a h:message.
Buena Prctica JSFStoreError: Se cambia el uso de t:message a h:message.
Buena Practica JSFSavestate Se sustituye el uso del componente savestate de tomahawk por una etiqueta propia de atlas atlas:guardarEstado
1.10
Nuevo apartado 6.2.1.10: Ayuda contextual.
Nueva buena practica JSFAYUDA Modificado apartado 6.2.1.7 Uso de
5 de 191
Framework Atlas
Versin
Causa del Cambio Javascript para hablar de Jquery.
Fecha
Nueva regla JSFJQuery Nuevo apartado 10.3 Generacin automtica de cdigo
Apartado 6.3.1 Modificada norma SNFacade para quitar que la fachada debe gestionar la transaccionalidad. Nueva buena practica SNFacadeWS que recomienda no generar fachada en los servicios web.
Apartado 6.2.1.8: Normas de estilo Nueva norma JSFIFRAME que prohibe el uso de IFRAMES.
Apartado 10: Servicios Web. Nuevo apartado. Se aaden una nueva norma WSSECURITY.
Apartado 9.3: Modificado Servicio de Certificados digitales pasa a llamarse Servicio de Criptografa. Se modifica el texto de la norma SICert.
1.11
Apartado 8.1: Se incluye informacin sobre los mecanismos implementados para cumplir los requisitos mnimos del Esquema Nacional de Seguridad en el acceso a las aplicaciones. Se crea nueva norma SBENS. 01/03/2013
Apartado 9.7.10: Envo de SMS. Se modifica para que en lugar de invocar al servicio web de mentes se utiliza un servicio propio de Atlas llamado Servicio de envo de SMS.
Apartado 9.7.11: Visor Mapas. Nuevo componente.
1.12
Apartado 12: Entrega. Se cambia Unidad
25/03/2013
6 de 191
Framework Atlas
Versin
Causa del Cambio de Recepcin de Aplicaciones por Unidad de Paso a Produccin y he informa acerca de la creacin de repositorio de subversion. Indice: Se regenera el indice ya que no estaba bien.
Fecha
1.13
Apartado 6.4.3.2: Se elimina la regla ADLOB.
29/05/2013
7 de 191
Framework Atlas
Normativa
ndice 1 INTRODUCCION ................................................................................................................................................. 10 1.1 1.2 2 3 4 5 AUDIENCIA OBJETIVO ............................................................................................................................... 10 CONOCIMIENTOS PREVIOS ...................................................................................................................... 11
DESCRIPCION ..................................................................................................................................................... 13 PORTAL PARA EL DESARROLLO DE APLICACIONES ........................................................................... 15 ENTORNO DE DESARROLLO ......................................................................................................................... 16 PROYECTOS, MODULOS Y ARQUETIPOS .................................................................................................. 18 5.1 5.2 5.3 5.4 MODULO WEB .............................................................................................................................................. 21 MODULO LIBRERA .................................................................................................................................... 22 MODULO SERVICIO WEB........................................................................................................................... 23 MODULO BATCH ......................................................................................................................................... 24
ARQUITECTURA ................................................................................................................................................ 24 6.1 CONSIDERACIONES GENERALES ............................................................................................................ 24 6.2 PRESENTACION ........................................................................................................................................... 26 6.2.1 PAGINAS JSF......................................................................................................................................... 28
6.2.1.1 6.2.1.2 6.2.1.3 6.2.1.4 6.2.1.5 6.2.1.6 6.2.1.7 6.2.1.7.1 6.2.1.7.2 6.2.1.7.3 6.2.1.7.4 6.2.1.8 6.2.1.9 6.2.1.10 Manejo de eventos ............................................................................................................................................... 31 Recuperacin de parmetros ................................................................................................................................ 33 Validadores .......................................................................................................................................................... 35 Conversores ......................................................................................................................................................... 37 Internacionalizacin ............................................................................................................................................. 37 Estructura y decoracin de la pgina .................................................................................................................... 39 Uso de javascript .................................................................................................................................................. 44 Uso de JQuery en pginas JSF ......................................................................................................................... 44 Uso del objeto JQuery ..................................................................................................................................... 44 Uso de ready en sustitucin del evento onLoad............................................................................................... 45 Localizacin de elementos por Id .................................................................................................................... 45 Normas de estilo .................................................................................................................................................. 46 Interfaces ricas de usuario (RIA) ......................................................................................................................... 47 Ayuda contextual ............................................................................................................................................. 49 Manejo de excepciones ........................................................................................................................................ 54 Navegacin .......................................................................................................................................................... 56
6.2.2
6.2.2.1 6.2.2.2
MANAGED BEANS .............................................................................................................................. 50 CONFIGURACIN DE JSF ................................................................................................................... 57

faces-config.xml ................................................................................................................................................... 58 faces-managed-beans.xml .................................................................................................................................... 58 faces-navigation.xml ............................................................................................................................................ 60 Archivos de configuracin adicionales y web.xml ............................................................................................... 63 Anotaciones ......................................................................................................................................................... 63
6.2.3
6.2.3.1 6.2.3.2 6.2.3.3 6.2.3.4 6.2.3.5
6.2.4 USO DE LA SESIN ............................................................................................................................. 65 6.3 SERVICIOS DE NEGOCIO ........................................................................................................................... 66 6.3.1 FACHADA.............................................................................................................................................. 68 6.3.2 SERVICIOS ............................................................................................................................................ 72 6.3.3 INYECCION DE DEPENDENCIAS ...................................................................................................... 77 6.3.4 MANEJO DE EXCEPCIONES .............................................................................................................. 80 6.3.5 TRANSACCIONALIDAD ..................................................................................................................... 83 6.3.6 FICHEROS TEMPORALES................................................................................................................... 88 6.4 ACCESO A DATOS ....................................................................................................................................... 90 6.4.1 DATASOURCE Y SESIONES DE HIBERNATE ................................................................................. 93 6.4.2 CONFIGURACIN ................................................................................................................................ 94
6.4.2.1 6.4.2.2 6.4.2.3 enviroment.properties .......................................................................................................................................... 94 applicationContext-database.xml ......................................................................................................................... 94 applicationContext-dao.xml ................................................................................................................................. 96
6.4.3
6.4.3.1 6.4.3.2
ENTIDADES DE DOMINIO.................................................................................................................. 98
Mapeo relacional................................................................................................................................................ 104 Tipos de datos BLOB y CLOB (LOB) ............................................................................................................... 106
8 de 191
Framework Atlas
Normativa 6.4.4
6.4.4.1 6.4.4.2 6.4.4.3
DATA ACCESS OBJECTS .................................................................................................................. 107

Ejecucin de consultas ....................................................................................................................................... 117 Manejo de excepciones ...................................................................................................................................... 119 Transaccionalidad .............................................................................................................................................. 119
6.4.5 6.4.6
6.4.6.1 6.4.6.2 6.4.6.3
LLAMADA A PROCEDIMIENTOS ALMACENADOS DESDE HIBERNATE ............................... 121 CACHS EN HIBERNATE ................................................................................................................. 123
Las cachs de primer y segundo nivel ................................................................................................................ 123 Las cachs distribuidas....................................................................................................................................... 125 La cach de consultas ......................................................................................................................................... 126
7 8
CONFIGURACION ............................................................................................................................................ 127 SERVICIOS BASICOS ...................................................................................................................................... 132 8.1 8.2 8.3 8.4 SERVICIO DE AUTENTICACION Y AUTORIZACION ........................................................................... 132 COMPONENTES DE PRESENTACION ..................................................................................................... 137 SERVICIO DE TRAZAS .............................................................................................................................. 138 SERVICIO DE AUDITORIA DE SEGURIDAD .......................................................................................... 140
INTEGRACION .................................................................................................................................................. 141 9.1 SERVICIO DE GESTIN DOCUMENTAL ................................................................................................ 142 9.2 SERVICIO DE PLANIFICACION ............................................................................................................... 143 9.3 SERVICIO DE CRIPTOGRAFIA................................................................................................................. 144 9.4 SERVICIO DE BUSSINESS INTELLIGENT .............................................................................................. 145 9.5 SERVICIO DE INVOCACIN DE SERVICIOS WEB ............................................................................... 147 9.6 SERVICIO DE PROCESOS DE NEGOCIO ................................................................................................. 148 9.7 OTRAS SOLUCIONES ................................................................................................................................ 149 9.7.1 REPORTING ........................................................................................................................................ 150 9.7.2 COMPOSICION DE DOCUMENTOS................................................................................................. 152 9.7.3 GESTION DE DOCUMENTOS EXCEL ............................................................................................. 154 9.7.4 GESTION DE DOCUMENTOS PDF ................................................................................................... 155 9.7.5 GENERACION DE GRAFICOS .......................................................................................................... 156 9.7.6 MANIPULACION DE ARCHIVOS MULTIMEDIA .......................................................................... 157 9.7.7 ACCESO A PLATAFORMA Y DISPOSITIVOS LOCALES ............................................................. 158 9.7.8 XML ...................................................................................................................................................... 159 9.7.9 ENVIO DE CORREO ........................................................................................................................... 161 9.7.10 ENVIO DE SMS ................................................................................................................................... 165 9.7.11 VISOR DE MAPAS .............................................................................................................................. 166 9.7.12 SERVICIOS WEB ................................................................................................................................ 167
10
HERRAMIENTAS .......................................................................................................................................... 168
10.1 VALIDACION DE NORMATIVA............................................................................................................... 168 10.2 VALIDACION DE CODIFICACION JAVA ............................................................................................... 170 10.3 GENERACION AUTOMTICA DE CODIGO ........................................................................................... 172 10.3.1 ACCESO A DATOS ............................................................................................................................. 173 10.3.2 SERVICIOS DE NEGOCIO ................................................................................................................. 174 10.3.3 PRESENTACION ................................................................................................................................. 175 11 11.1 11.2 11.3 12 13 A1.1 A1.2 PRUEBAS ........................................................................................................................................................ 178 TIPOS DE PRUEBAS ................................................................................................................................... 178 PLAN DE PRUEBAS.................................................................................................................................... 183 DOCUMENTACION DEL CODIGO ........................................................................................................... 184 ENTREGA ....................................................................................................................................................... 185 ENLACES RELACIONADOS ...................................................................................................................... 186 NORMAS ..................................................................................................................................................... 187 BUENAS PRACTICAS .............................................................................................................................. 191
9 de 191
Framework Atlas
Normativa 1 INTRODUCCION
La presente gua presenta el framework de desarrollo para todas las aplicaciones de la Comunidad de Madrid y establece la normativa a cumplir en estos desarrollos. El framework se ha denominado Atlas y los desarrollos deben cumplirlo en su ltima versin pblicada. En esta normativa se incluyen dos tipos de indicaciones para el correcto desarrollo de aplicaciones: o Normas: Son requisitos de obligado cumplimiento, y se encuentran definidas dentro de una caja de color azul:
NORMA
o
NombreDeNorma Contenido de la norma.
Buenas prcticas: Son recomendaciones para el desarrollo. No son de obligado cumplimiento aunque para un correcto funcionamiento se recomienda cumplirlas siempre que sea posible. Se encuentran definidas dentro de una caja de color
PRACTICA
BUENA
NombreDeBuenaPractica Contenido de la Buena Prctica.
1.1
AUDIENCIA OBJETIVO
Este documento va dirigido a jefes de proyecto, analistas y desarrolladores de proyectos que utilicen el framework Atlas.
10 de 191
Framework Atlas
Normativa 1.2 CONOCIMIENTOS PREVIOS
Para un completo entendimiento del documento, el lector deber tener conocimientos previos sobre las tecnologas que forman parte del framework. A continuacin se muestra una tabla con las distintas tecnologas utilizadas por cada uno de los elementos del framework.
Servicio Respositorio maven Gestin del proyecto IDE de desarrollo Entorno de Desarrollo Servidor de Aplicaciones Motor de base de datos Control de versiones Integracin continua Maquina virtual java Arquetipos Generacin de nuevos proyectos Presentacin Servicios Acceso a Datos Servicios Web Servicio de Autenticacin y Autorizacin Servicios Bsicos Componentes de Presentacin Servicio de Trazas Servicio de Auditoria Servicio de Gestin Documental Servicio de Planificacin Servicio de ASF Integracin Servicio de Bussiness Inteligent Servicio de Invocacin de Servicios Web Servicio de Procesos de Negocio Artifactory Maven Eclipse
Tecnologa
Oracle Weblogic 10.3.3 Oracle Subversin Cruise Control JRockit JDK 1.6.0_20 Maven y Eclipse JSF, RichFaces, Ajax4JSF, Facelets Spring Hibernate Axis 2 Spring Security JSF, RichFaces, Ajax4JSF, Facelets Spring AOP y Log4J Spring AOP e Hibernate Documentum 6.0 Control M ASF 3.5 SAP Bussiness Objects XI 3.1 Axis 1.4 Oracle BPM 10
Arquitectura
11 de 191
Framework Atlas
Normativa Documentos PDF Reporting Composicin de documentos Documentos Excel Generacin de Grficos Otras soluciones Archivos multimedia Acceso a dispositivos locales XML Envo de correo Envio de SMS Monitorizacin Pruebas de carga Herramientas Pruebas de aceptacin Pruebas unitarias Validacin normativa Validacin esttica de cdigo IText Crystal Reports 2008 Velocity Apache POI JFreechart Java Media FrameWork API (JMF) Applet Jaxb Java Mail Servicio web mentes_ws JMS y JMX JMeter Selenium JUnit Maven Checkstyle y PMD
12 de 191
Framework Atlas
Normativa 2 DESCRIPCION
El framework Atlas es un conjunto de componentes de software para simplificar el desarrollo de las aplicaciones, ya que implementan aquellos requisitos que son compartidos por muchas de ellas. Otra parte del framework es la normativa que garantiza la homogeneidad de los desarrollos y vela por conseguir un cdigo de calidad. A continuacin se muestra una imagen que contiene los distintos elementos del framework.
o o o
Entorno de desarrollo: Herramientas necesarias para el desarrollo de aplicaciones con el framework Atlas Arquitectura: Son los pilares que constituyen la base fundamental del Framework (JSF, Spring e Hibernate) Servicios Bsicos: Servicios de uso comn en la mayora de los aplicaciones
13 de 191
Framework Atlas
Normativa o o o o Arquetipos: Generadores de nuevos proyectos con la estructura bsica de un proyecto Atlas (plantillas de partida para el arranque de nuevos proyectos). Integracin: Integracin con otras tecnologas como Documentum, BPM, etc Herramientas: Utilidades de testing, validacin y monitorizacin de aplicaciones. Normativa: Normativa de obligado cumplimiento para el desarrollo de aplicaciones con el framework.
14 de 191
Framework Atlas
Normativa 3 PORTAL PARA EL DESARROLLO DE APLICACIONES
Toda la documentacin y recursos del framework Atlas se encuentra accesible en el portal para el desarrollo de aplicaciones de la Unidad de Arquitectura y Soporte de Aplicaciones en la url: http://gestiona.madrid.org/arquitecturasw.
Esta web es el canal de comunicacin de la Unidad de Arquitectura y Soporte de Aplicaciones hacia los proveedores. Cada vez que se publica algo en la web se incluye una noticia indicando la actualizacin que se ha realizado. El proveedor por lo tanto tiene la responsabilidad de conectarse asiduamente a esta web para estar al corriente de las modificaciones.
Las consultas relacionadas con el desarrollo de aplicaciones se deben dirigir a la Unidad de Arquitectura y Soporte de Aplicaciones a travs del portal para el desarrollo en el apartado Contactar con Arquitectura en la pgina de Inicio.
15 de 191
Framework Atlas
Normativa 4 ENTORNO DE DESARROLLO
Las siguientes imagenes muestran los elementos a grandes rasgos
Entorno Desarrollo Proveedor
Eclipse + plugin Maven (+ plugin subversion)
Maven
Repositorio Local
Base de Datos (Oracle)
Servidor de Aplicaciones (WebLogic)
Entorno ICM
Artifactory
Arquetipos
jar web
Portal para el desarrollo Subversion
batch
service
Artefactos
CruiseControl
docum
Oracle Weblogic
En el manual Error! No se encuentra el origen de la referencia. detallan los productos y versiones de los mismos que son necesarios para el desarrollo de aplicaciones con el framework Atlas. Por otra parte se indica como preparar el entorno para comenzar a desarrollar aplicaciones.
16 de 191
Framework Atlas
Normativa
Entorno El proveedor deber replicar en sus instalaciones el entorno de desarrollo de ICM en cuanto a productos y versiones de los mismos. Las aplicaciones debern desarrollarse teniendo en cuenta los siguientes aspectos relativos al entorno: En el entorno de produccin podrn ser desplegadas en modo cluster, tanto en varias instancias de un mismo o diferentes servidores de aplicaciones. No deben usar funcionalidades o tecnologas dependientes del sistema operativo sin la previa aprobacin de ICM. No deben usar funcionalidades propietarias del servidor de aplicaciones, sin la previa aprobacin de ICM, para garantizar al mximo la portabilidad entre servidores de aplicaciones. Los ficheros generados por las aplicaciones y que se necesiten dejar en disco se ubicarn segn se indique en un parmetro del fichero de configuracin. Esta ubicacin corresponder con un directorio compartido por las distintas maquinas que compongan el cluster. Las aplicaciones web y servicios web se van a ejecutar en varias maquinas virtuales por lo tanto los objetos que se dejen en la memoria de la maquina virtual no estarn replicados en las diferentes instancias.
NORMA NORMA
EntornoEjecucion Las aplicaciones se desplegarn en el servidor de aplicaciones Oracle Weblogic 10.3.3 y se ejecutarn con la JDK JRockit 1.6.0_20 por lo tanto el codigo entregado deber estar probado con esta versin de JDK y funcionar correctamente en este servidor de aplicaciones.
17 de 191
Framework Atlas
Normativa 5 PROYECTOS, MODULOS y ARQUETIPOS
Las aplicaciones de la Comunidad de Madrid se definirn en el marco de un proyecto, denominando a las distintas aplicaciones que se desarrollen para un proyecto mdulos. Por lo tanto podemos decir que un proyecto es un conjunto de mdulos. Todos los proyectos de la Comunidad de Madrid tienen un nombre de 4 letras que identifican al proyecto y que van a ser fundamentales en la nomenclatura de muchos de los elementos del proyecto por lo tanto es fundamental disponer de este identificador antes de abordar ningn tipo de desarrollo. A continuacin se muestra la estructura de carpetas sobre como se debe crear un proyecto y sus correspondientes mdulos.
PROYECTO
XXXX
MODULOS
XXXX_MODD
BASE DATOS
XXXX_APP
APP WEB
XXXX_WS
SERVICIO WEB
XXXX_BATCH
BATCH
XXXX_LIB
LIBRERIA
Atencin xxxx se corresponde con el nombre del proyecto y como podemos ver este nombre forma parte del nombre de los mdulos. Observar que el separador utilizado en el nombre de los mdulos es el guin bajo.
18 de 191
Framework Atlas
Normativa Dentro de los mdulos de un proyecto nos podemos encontrar con mdulos del framework Atlas o con otro tipo de mdulos (por ejemplo un mdulo de Documentum, un mdulo de base de datos, etc). Los distintos tipos de mdulos que podemos implementar con el framework Atlas son: o o o o Mdulo web: Para implementar aplicaciones de tipo web. Mdulo librera: Para implementar libreras (jars). Mdulo servicio web: Para implementar servicios web. Mdulo batch: Para implementar aplicaciones o procesos que se ejecutarn en modo batch.
Los arquetipos son plantillas de proyectos Maven que se utilizarn como punto de partida de cualquier mdulo desarrollado con el framework Atlas. Antes de crear ningn mdulo debemos crear el propio proyecto, partiendo de un arquetipo de proyecto que crea la estructura necesaria.
Arquetipos
NORMA
Todo proyecto debe partir obligatoriamente de un arquetipo de tipo proyecto (atlasfrmarquetipos-generador-proyecto). El desarrollo de cualquier mdulo de un proyecto sern submdulos de ste, que obligatoriamente se deben hacer partiendo del arquetipo correspondiente al mdulo en cuestin.
Actualmente se dispone de los siguientes arquetipos dentro del framework Atlas:
ARQUETIPOS atlasfrm-arquetiposgenerador-proyecto
DESCRIPCION Genera un proyecto base de partida para cualquier aplicacin de ATLAS. Cualquiera de los mdulos del proyecto debern ser submdulos de ste.
Tipo de mdulo Proyecto de inicio
atlasfrm-arquetiposgenerador-web
Genera un proyecto Maven preparado para el desarrollo de mdulos web con JSF, Spring e Hibernate.
Mdulo web
atlasfrm-arquetiposgenerador-servicioweb
Genera un proyecto Maven de tipo web listo para desplegar un servicio
Mdulo servicio web
19 de 191
Framework Atlas
Normativa web con Axis2, Spring e Hibernate atlasfrm-arquetiposgenerador-documentumweb Genera un proyecto Maven de tipo web listo para ser utilizado con aplicaciones que se integren con Documentum atlasfrm-arquetiposgenerador-batch Genera un proyecto Maven preparado para el desarrollo de mdulos de tipo batch, con sus scripts de ejecucin preparada para distribucin. Contiene configuraciones de Spring e Hibernate atlasfrm-arquetiposgenerador-jar Genera un proyecto Maven preparado para el desarrollo de mdulos de tipo librera (jar). Mdulo librera Mdulo batch Mdulo web
NOMArchivo
NORMA NORMA NORMA
Los nombres de los archivos slo pueden estar formados por caracteres [a-z] y guiones medio y bajo, no pudindose utilizar caracteres acentuados ni la letra ee. En los nombres de los archivos pueden utilizarse letras maysculas cuando sea conveniente.
NOMPaquetes Los nombres de los paquetes de clases Java slo pueden estar formados por caracteres [a-z] en minscula, no pudindose utilizar caracteres acentuados ni la letra ee.
VERSIONADO Todos los proyectos deben versionarse utilizando los mecanismos de versionado que ofrece Maven, utilizando la etiqueta <version> que se encuentra dentro del fichero pom.xml. Siempre que se realicen modificaciones sobre un mdulo y se proceda a una entrega (en cualquier entorno) se ha de modificar el nmero de versin. El nmero de versin estar formado por tres digitos. Ejemplo 1.0.3
20 de 191
Framework Atlas
Normativa 5.1 MODULO WEB
Para el desarrollo de mdulos web el framework Atlas incluye un arquetipo web que se deber utilizar para la implementacin del mismo. Para obtener ms informacin sobre el arquetipo web consultar el manual ATLAS_MUS_Arquetipo_Web. IMPLWEB Para implementar un mdulo/aplicacin web se crear un mdulo partiendo del arquetipo web y con la siguiente nomenclatura:
NORMA
xxxx_yyyy donde xxxx se corresponde con el nombre del proyecto yyyy se corresponde con el nombre descriptivo del web (No se puede poner en este nombre el sufijo web ya que se la va a incluir automticamente al generar el mdulo desde el arquetipo)
21 de 191
Framework Atlas
Normativa 5.2 MODULO LIBRERA
En algunos proyectos nos encontramos con que determinadas cdigo debe de estar compartido por varios mdulos del proyecto, en ese caso es necesario crear un nuevo mdulo de tipo librera cuya dependencia ser incluida en cada uno de los mdulos que lo necesite. LIBCOMUN Cuando varios mdulos de una o varias aplicaciones tengan cdigo en comn, ya sean mtodos o clases, se deber crear una librera de clases que servir para compartir el cdigo comn anterior.
Para el desarrollo de mdulos librera el framework Atlas incluye un arquetipo jar que se deber utilizar para la implementacin del mismo. Para obtener ms informacin sobre el arquetipo jar consultar el manual Error! No se encuentra el origen de la referencia..
NORMA
IMPLLIB Para implementar un mdulo librera se crear un mdulo partiendo del arquetipo jar y con la siguiente nomenclatura:
NORMA
xxxx_lib_<yyyy> donde xxxx se corresponde con el nombre del proyecto yyyy se corresponde con el nombre descriptivo de la librera (Este nombre es opcional y debe distinguir a una librera de otra)
22 de 191
Framework Atlas
Normativa 5.3 MODULO SERVICIO WEB
Si existe la necesidad de que determinada funcionalidad de nuestra aplicacin sea expuesta como un servicio web a otras aplicaciones se deber crear un mdulo especfico que implemente el servicio web. El framework Atlas incluye un arquetipo de servicio web que se deber utilizar para la implementacin del mismo. Para obtener ms informacin sobre el arquetipo de servicio web consultar el manual Error! No se encuentra el origen de la referencia.. IMPLWS Para implementar un servicio web se crear un mdulo partiendo del arquetipo servicio web y con la siguiente nomenclatura:
NORMA
xxxx_ws_<yyyy> donde xxxx se corresponde con el nombre del proyecto yyyy se corresponde con el nombre descriptivo del servicio web (Este nombre es opcional y debe distinguir a un servicio web de otro)
Para facilitar la integracin de las aplicaciones clientes con este tipo de mdulos es necesario proporcionales una librera cliente que permita invocar a los mtodos publicados en el servicio web. Por lo tanto todos los mdulos de tipo servicio web llevarn incluido un submdulo con la parte cliente necesaria para invocarlos. Este submdulo ya se encuentra en el arquetipo de servicio web. WSLibCliente Cada mdulo de tipo servicio web debe incluir su correspondiente librera cliente que ser un submdulo de tipo librera con la siguiente nomenclatura:
NORMA
xxxx_ws_<yyyy>_lib donde xxxx se corresponde con el nombre del proyecto yyyy se corresponde con el nombre descriptivo del servicio web (Este nombre es opcional y debe distinguir a un servicio web de otro)
23 de 191
Framework Atlas
Normativa 5.4 MODULO BATCH
Si existe la necesidad de que determinada funcionalidad de nuestra aplicacin sea ejecute en modo batch se crear un mdulo de tipo batch. El framework Atlas incluye un arquetipo de aplicaciones batch que se deber utilizar para la implementacin del mismo. Para obtener ms informacin sobre el arquetipo de batch consultar el manual Error! No se encuentra el origen de la referencia. .
IMPLBatch Para implementar un servicio web se crear un mdulo partiendo del arquetipo servicio web y con la siguiente nomenclatura:
NORMA
xxxx_batch_<yyyy> donde xxxx se corresponde con el nombre del proyecto yyyy se corresponde con el nombre descriptivo del batch (Este nombre es opcional y debe distinguir a un programa batch de otro)
ARQUITECTURA
El framework Atlas est basado fundamentalmente en tres tecnologas: JSF, Spring e Hibernate, que dan soporte a la implementacin de las distintas capas de la aplicacin: Presentacin: Java Server Faces (JSF) Servicios: Spring Acceso a datos: Hibernate
Es fundamental el conocimiento por parte del desarrollador de estas tres tecnologas para poder llevar a cabo con exito el desarrollo de una aplicacin con el framework Atlas. 6.1 CONSIDERACIONES GENERALES
A continuacin se exponen una serie de normas que son de carcter general para el cdigo Java a desarrollar.
24 de 191
Framework Atlas
Normativa REFLEXION No est permitido el uso de la Reflectividad (bien sea para buscar e invocar mtodos o bien para acceder a atributos de una clase), a no ser que sea previamente autorizada por ICM.
NORMA NORMA NORMA NORMA
GARBAGE No est permitida la invocacin directa al garbage collector mediante System.gc(), a no ser que tras consultarlo sea autorizada por ICM.
MULTIHILO En aplicaciones web o servicios web no pueden utilizarse hilos (threads) de ejecucin distintos del hilo principal, a no ser que sea previamente autorizado por ICM.
CLASESIGUALES No puede haber dos clases que se llamen igual aunque estn en dos paquetes distintos.
25 de 191
Framework Atlas
Normativa 6.2 PRESENTACION
La lgica de presentacin de la aplicacin abarca todos los aspectos relacionados con la presentacin de informacin al usuario final. La arquitectura de Atlas se basa principalmente en el uso de la tecnologa Java Server Faces (JSF) para la creacin de la lgica de presentacin de la aplicacin, si bien hay ciertas funcionalidades que son responsabilidad de esta capa y que emplean algn framework o producto adicionales. No obstante para ciertas tipologas de aplicaciones (aplicaciones meramente informativas, esto es, aquellas cuyo principal objetivo es mostrar informacin al usuario final) el uso de esta tecnologa complica la integracin con la infraestructura actual de ICM. Tal es el caso de las aplicaciones o sitios Web que dependen de madrid.org implementados mediante las herramientas que ofrece el gestor de contenidos corporativo de ICM (Fatwire). Este tipo de aplicaciones estn fuera del alcance del presente documento, las cuales estn sujetas a una normativa propia. La arquitectura de componentes que proporciona JSF, incluye: Un API para representar componentes de interfaz de usuario y gestionar: o o o o o o Su estado. Los eventos generados por la interfaz. La validacin y conversin de datos en el lado del servidor. La definicin de las reglas de navegacin entre pginas. Los aspectos relacionados con internacionalizacin y accesibilidad. Los puntos de extensin para todas estas caractersticas.
Libreras de etiquetas personalizadas para implementar la interfaz de las Java Server Faces y para asociar los componentes a los objetos del lado del servidor.
Desde el punto de vista del desarrollo, una aplicacin JSF es como cualquier otra aplicacin web Java. Tpicamente, una aplicacin JSF incluye las siguientes piezas principales: Un conjunto de pginas xhtml, que usarn etiquetas especiales definidas por la especificacin JSF. Un conjunto de managed beans, que no son ms que JavaBeans que definen propiedades y funciones para los componentes de interfaz de usuario de las pginas. Archivos de configuracin para la aplicacin, que definen las reglas de navegacin y configuran los beans y los componentes a medida. Un descriptor de despliegue (el fichero web.xml de toda aplicacin web). Los componentes y objetos a medida creados por el desarrollador para ampliar el modelo estndar (nuevos componentes visuales, validadores, conversores, etc.).
26 de 191
Framework Atlas
Normativa La siguiente figura muestra el modelo de componentes que propone JSF, adems se resumen las principales funcionalidades aportadas por dicha tecnologa y que se encuentran incluidas en el presente documento.
Funcionalidades Componentes de IU Integracin con modelo de objetos Gestin de contexto de usuario Modelo de renderizado Manejo de eventos en el servidor Conversin de tipos y validacin Navegacin Internacionalizacin
Modelo
Managed Beans
Vista
Componentes UI
Controlador
FacesServlet
Una de las mayores ventajas de JSF es que ofrece una clara separacin entre presentacin y comportamiento. JSF permite hacer un mapeo de las peticiones HTTP a elementos especficos para el manejo de eventos adems de manejar los elementos de interfaz de usuario como si fueran objetos con estado en el lado del servidor. Otra ventaja importante de la tecnologa JSF es que permite utilizar los componentes de interfaz de usuario sobre cualquier otra tecnologa de presentacin para otro tipo de dispositivos. Y lo ms importante, JSF aporta una arquitectura para manejar el estado de los componentes, el proceso de los datos, la validacin de las entradas del usuario y el manejo de eventos. El uso de JSF aporta las siguientes ventajas adicionales: Es un estndar JEE. Esto asegura que los principales fabricantes de servidores de aplicaciones e IDEs sean compatibles con JSF. Al ser un modelo basado en componentes, la productividad es mayor y se fomenta la reutilizacin. Posibilita el uso de herramientas de diseo visuales. Ofrece una separacin ntida entre presentacin y lgica de negocio, y por tanto, de los roles involucrados. Flexibilidad. Permite a los desarrolladores la ampliacin de los componentes de las libreras de etiquetas e incluso la creacin de otros nuevos. Apta para la gestin de clientes heterogneos (WML, Wap, HTML, XML, etc.).
En la actualidad existen un extenso conjunto de libreras de componentes JSF, tanto comerciales como de cdigo abierto. Para el desarrollo de aplicaciones Atlas pueden utilizarse alguna de ellas. JSFComponentes
NORMA
Para la implementacin de la interfaz de usuario de las aplicaciones con JSF, slo se podrn emplear los componentes propios de Atlas, los de MyFaces, RichFaces y sus extensiones. Las libreras para estos componentes ya se encuentran dentro del repositorio Maven de ICM.
27 de 191
Framework Atlas
Normativa 6.2.1 PAGINAS JSF
En las pginas JSF se situan los distintos elementos que formaran las pginas a mostrar al usuario final de la aplicacin.
JSFXHTML Todos los ficheros JSF debern ser documentos XHTML con extensin .xhtml. Como sistema de codificacin se emplear UTF-8. Los componentes Web transmitirn todas las
NORMA NORMA
pginas con dicho sistema de codificacin (encoding="UTF-8"). Todas las pginas JSF se ubicarn en la carpeta src/main/webapp y subcarpetas. Para distinguir aquellas pginas cuyo acceso est securizado estas se ubicarn en una carpeta llamada src/main/webapp/secure. Dentro de esta carpeta se podrn crear las subcarpetas necesarias para poder llevar una gestin de perfiles de acceso.
JSFPOB Las pginas deben de ser compatibles con las versiones de Navegador Internet Explorer 6.0 o superior y Mozilla Firefox 2 o superior. Los mdulos que se desarrollen para los usuarios de la Intranet deben funcionar correctamente con el POB (Puesto ofimtico bsico) que tienen instalado en su PC.
A continuacin se muestra un ejemplo de pgina JSF: Ejemplo de pgina JSF <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:jsp="http://java.sun.com/JSP/Page" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:atlas="http://atlas.core.componentes/jsf" xmlns:c="http://java.sun.com/jstl/core" xmlns:fn="http://java.sun.com/jsp/jstl/functions" xmlns:a4j="http://richfaces.org/a4j" xmlns:rich="http://richfaces.org/rich" version="2.0"> <ui:composition template="/WEB-INF/layout/vc.xhtml"> <ui:define name="rastroMigas">
28 de 191
Framework Atlas
Normativa <ui:include src="/secure/rastroMigas/rastro.xhtml" /> </ui:define> <ui:define name="menuVertical"> <ui:include src="/secure/menu/menu.xhtml" /> </ui:define> <ui:define name="content"> <h:form id="mainPanel"> <atlas:guardarEstado id="stateIdCliente" value="#{clientesBean.cliente}" /> <h:panelGroup> <h:panelGrid width="70%" columns="3"> <h:outputLabel id="outputLabelNombre" for="inputTextNombre" styleClass="label" value="#{bundle['inputText.nombre']}" /> <h:panelGroup> <h:inputText id="inputTextNombre" size="50" maxlength="50" styleClass="cajaTextoObligat" value="#{clientesBean.cliente.nombre}" required="true" /> </h:panelGroup> <h:panelGroup> <h:message for="inputTextNombre" styleClass="mensajeERRORtxt" showDetail="true" showSummary="false" /> </h:panelGroup> <h:outputLabel id="outputLabelApellido1" for="inputTextApellido1" styleClass="label" value="#{bundle['inputText.apellido1']}" /> <h:panelGroup> <h:inputText id="inputTextApellido1" size="50" maxlength="50" styleClass="cajaTextoObligat" value="#{clientesBean.cliente.apellido1}" required="true"> </h:inputText> </h:panelGroup> <h:panelGroup> <h:message for="inputTextApellido1" styleClass="mensajeERRORtxt" showDetail="true" showSummary="false"/> </h:panelGroup> ... <h:outputText styleClass="botonAplicacionTXT" value="#{bundle['boton.vuelta_atras']} " /> <h:graphicImage value="img/portal/filtro.jpg" alt="#{bundle['boton.vuelta_atras']}" /> </h:commandLink> <h:commandLink id="guardarLink" action="#{clientesBean.guardarCliente}" styleClass="buttonsRowLeftColumn"> <h:outputText styleClass="botonAplicacionTXT" value="#{bundle['boton.guardar_cliente']} " /> <h:graphicImage value="img/portal/filtro.jpg" alt="#{bundle['boton.guardar_cliente']}" /> </h:commandLink> ... </ui:composition> </html>
29 de 191
Framework Atlas
Normativa
El acceso a la capa de negocio desde las pginas JSF se har a travs de clases java llamadas managed beans o beans de respaldo. La asociacin de datos entre los componentes de las pginas y sus managed beans se puede hacer de dos maneras: Asociacin de valores: permite configurar una propiedad de un componente de la pgina mediante un atributo de un bean.
Ejemplo de asociacin de valores <h:inputText id="inputTextNombre" size="50" maxlength="50" styleClass="cajaTextoObligat" value="#{clientesBean.cliente.nombre}" required="true" />
Asociacin a mtodos: permite configurar una propiedad de un componente de la pgina con el resultado de la invocacin a un mtodo del bean.
Ejemplo de asociacin a mtodos <h:commandLink id="guardarLink" action="#{clientesBean.guardarCliente}" styleClass="buttonsRowLeftColumn"> <h:outputText styleClass="botonAplicacionTXT" value="#{bundle['boton.guardar_cliente']}" /> <h:graphicImage value="img/portal/filtro.jpg" alt="#{bundle['boton.guardar_cliente']}" /> </h:commandLink>
JSFManagedBean
PRACTICA PRACTICA
BUENA
Se recomienda que desde cada pgina JSF solamente se acceda a un nico managed bean que ofrecer la interfaz necesaria para la invocacin de esa pgina, salvo en el caso de varias pginas que gestionen el mismo tipo de invocaciones.
JSFGet En la asociacin de valores, JSF llama al mtodo get correspondiente del bean para obtener el valor. Se recomienda no poner lgica en estos mtodos, ya que pueden ser llamados un nmero elevado de veces durante el ciclo de vida de una peticin. En caso de que el valor a
BUENA
30 de 191
Framework Atlas
Normativa devolver deba calcularse u obtenerse de base de datos debera hacerse en otro mtodo que se ejecute slo una vez (constructor de la clase, mtodo action del componente que desencadene la accin).
JSFNegocio
NORMA
Desde las pginas JSF solamente se podr acceder a managed beans. No est permitido la invocacin a los objetos de acceso a datos (DAOs) de la aplicacin ni objetos de servicio de negocio. Tampoco est permitido el uso de cdigo Java directamente en la pgina JSF.
PRACTICA PRACTICA
JSFTamano Las pginas JSF se debern disear y modularizar de tal forma que no tomen unas dimensiones excesivas.
BUENA
JSFEL
BUENA
Se recomienda no utilizar expresiones EL excesivamente complejas en las pginas XHTML, para esos casos es preferible codificar la expresin en una propiedad del managed bean y hacer referencia a dicha propiedad.
6.2.1.1
Manejo de eventos
El manejo de eventos debe realizarse mediante acciones siempre que sea posible. En el atributo action se debe indicar el mtodo JSF que ser invocado ante el click de un usuario en los elementos commandLink, commandButton o cualquier componente que herede dicho comportamiento. Este mtodo debe ser pblico, sin parmetros y retornar un String con la direccin que tomarn las reglas de navegacin:
En la pgina JSF <h:commandLink id="guardarLink" action="#{clientesBean.guardarCliente}" styleClass="buttonsRowLeftColumn"> <h:outputText styleClass="botonAplicacionTXT" value="#{bundle['boton.guardar_cliente']} " /> <h:graphicImage value="img/portal/filtro.jpg"
31 de 191
Framework Atlas
Normativa alt="#{bundle['boton.guardar_cliente']}" /> </h:commandLink>
En el managed bean /** * Este metodo inserta o modifica un cliente en el sistema. * * @throws atlas.core.exceptions.ServiceException * Lanza atlas.core.exceptions.ServiceException ante cualquier error * @return <code>java.lang.String</code> Devuelve la regla de navegacion * <code>NavigationResults.VOLVER_LISTADO_CLIENTES</code>. */ public String guardarCliente() throws ServiceException { try { facade.insertOrUpdateCliente(cliente); } catch (ServiceException se) { AtlasFacesUtils.storeOnRequestError(FacesContext.getCurrentInstance(), "error.CLIENTES_MODIFICAR", se); throw se; } return NavigationResults.VOLVER_LISTADO_CLIENTES; } Para ms informacin sobre el uso de NavigationResults ver el apartado de Managed Beans. En caso de existir la necesidad de acceder a elementos de la interfaz de usuario durante la ejecucin se puede capturar la llamada mediante un actionListener, esto permite recibir informacin sobre el estado de los componentes visuales del cliente mediante el parmetro que es enviado:
En la JSF <h:commandLink action="#{miBean.accion}" actionListener="#{miBean.escuchadorAccion}"> <h:outputText value="#{bundle['texto_del_link']}"/> </h:commandLink>
En el managed bean: accion public String accion() { //Lgica de la accion. return NavigationResults.MOSTRAR_RESULTADO; }
En el managed bean: escuchadorAccion public void escuchadorAccion(ActionEvent evento) { //Lgica relacionada con los componentes UI del cliente por ejemplo,
32 de 191
Framework Atlas
Normativa //recuperar los hijos y facets del componente: evento.getComponent().getFacetsAndChildren(); } JSFAcciones Como norma general, se emplear el manejo de eventos mediante acciones (en lugar de ActionListeners) si bien se deber elegir con cuidado que alternativa de las dos ser la ptima
PRACTICA
BUENA
en cada caso.
En el caso de manejo de eventos mediante actionListeners se recomienda que se realice en conjuncin con acciones estndar, incluyendo la lgica de control de aplicacin en estas ltimas y delegando slo las tareas relacionadas con manejo avanzado de los componentes de usuario a los actionListeners.
Por otro lado, estn los escuchadores de propiedades (ValueChangeListener) que permiten ejecutar mtodos de un managed bean cuando cambia una propiedad de un componente de interfaz de usuario:
En la pgina JSF <h:selectBooleanCheckbox id="changeColorMode" valueChangeListener="#{resumeBean.changeColorMode}" onchange="submit()" /> immediate="true"
En el managed bean public void changeColorMode(ValueChangeEvent event) { boolean flag = ((Boolean) event.getNewValue()).booleanValue(); setUsingColorNames(!flag); }
6.2.1.2
Recuperacin de parmetros
Como norma general no ser necesario enviar parmetros adicionales ya que JSF se encargar de realizar llamadas a los mtodos set de los atributos que representan los campos de un formulario, pero habr casos en los que ser necesario el envo de informacin adicional. Un claro ejemplo es el caso de una funcionalidad maestro-detalle donde se debe enviar un elemento de un listado para poder mostrar posteriormente el detalle del mismo. Para ello disponemos de dos mecanismos: o f:setPropertyActionListener
33 de 191
Framework Atlas
Normativa o f:param
El primero consiste en el envo del objeto completo al realizar la accin. Anidando el componente setPropertyActionListener dentro de un commandLink o un commandButton conseguimos que JSF actualice los valores de propiedades e incluso objetos completos al realizar una accin:
Ejemplo de updateActionListener <atlas:listaPaginada ..............> <h:column .....> <h:commandButton value="#{bundle['texto_del_boton']}" action="#{miBean.mostrarCliente}"> <f:setPropertyActionListener value="#{item}" target="#{miBean.cliente}"/> </h:commandButton> </h:column> </atlas:listaPaginada> En este ejemplo cuando se invoca el mtodo mostrarCliente en el atributo cliente se establece el valor item. Lamentablemente no siempre es posible hacer uso de esta estrategia, por ejemplo en acciones que tienen el atributo immediate="true". Para estas situaciones disponemos de otro mtodo que nos permite enviar parmetros de tipos de dato primitivos (no objetos o arrays). Cualquier componente de tipo commandButton, commandLink, outputLink o derivados de los mismos acepta componentes anidados de tipo f:param, que enva el valor asociado a una clave como parmetro de la request. Al ser enviado como parmetro de la request podemos recuperar dichos parmetros en cualquier punto del ciclo de vida de JSF, incluso en el constructor del Managed Bean si fuese necesario:
En la JSF <atlas:listaPaginada ..............> <h:column .....> <h:commandButton value="#{bundle['texto_del_boton']}" action="#{miBean.mostrarCliente}"> <f:param value="#{item.idCliente}" name ="parametroIdCliente"/> </h:commandButton> </h:column> </atlas:listaPaginada> En el managed bean public String mostrarCliente() { Long idCliente = (Long) FacesSupport.getParameter("parametroIdCliente"); //Cargamos el cliente a partir de su Id llamando a la fachada de
34 de 191
Framework Atlas
Normativa //servicios this.cliente = gestionFacade.cargarCliente(idCliente); return NavigationResults.MOSTRAR_CLIENTE; } Mediante estas tcnicas y el uso del componente atlas:guardarEstado que se explicar en detalle ms adelante podemos reducir al mximo el uso de la sesin. 6.2.1.3 Validadores
La arquitectura de JSF ofrece mecanismos para automatizar la validacin de los datos de una aplicacin. Del mismo modo, ofrece la posibilidad de crear validadores a medida. Las validaciones estndar de JSF se realizan en el servidor, aunque tambin es posible hacer validaciones en el cliente (mediante javascript). Los errores de validacin se pueden mostrar mediante los mensajes de JSF utilizando <h:message/> o <h:messages/>.
Ejemplo de uso de un validador standard <h:inputText id="number1" value="#{calcFormBean.number1}" maxlength="2" size="25" required="true"> <f:validateLongRange minimum="1" maximum="10" /> </h:inputText> <h:message id="number1Error" for="form1:number1" styleClass="error" /> Esta validacin comprueba que se haya introducido un valor numrico en el campo number1, y que su longitud no supere los 2 caracteres. Adems se comprueba que el nmero introducido est entre el 1 y 10. Si los datos introducidos son errneos, se mostrar un mensaje de error. Tambin existen validadores estndar asociados a ciertos componentes de entrada de datos.
Ejemplo de campo obligatorio <h:outputLabel id="outputLabelNombre" for="inputTextNombre" styleClass="label" value="#{bundle['inputText.nombre']}" /> <h:panelGroup> <h:inputText id="inputTextNombre" size="50" maxlength="50" styleClass="cajaTextoObligat" value="#{clientesBean.cliente.nombre}" required="true" /> </h:panelGroup> <h:panelGroup> <h:message for="inputTextNombre" styleClass="mensajeERRORtxt" showDetail="true" showSummary="false" /> </h:panelGroup>
35 de 191
Framework Atlas
Normativa En el ejemplo anterior hacemos uso de dicho componente para mostrar un error cuando el usuario no introduzca nada en el campo inputTextNombre.
JSFMessages
PRACTICA
Si deseamos personalizar el mensaje de error a mostrar cuando se produzca un error de validacin, es recomendable el uso del componente de JSF para mostrar mensajes (<h:message/> o <h:messages/>). Para aadir mensajes al contexto se recomienda utilizar los mtodos creados a tal efecto en en la clase atlas.componentes.utiles.AtlasFacesUtils.
BUENA NORMA
JSF tambin permite realizar validaciones a nivel de aplicacin. Este tipo de validaciones se consideran validaciones de lgica de negocio. Bsicamente, la validacin a nivel de aplicacin conlleva aadir cdigo extra a los mtodos de los managed beans, que hacen comprobaciones adicionales sobre los datos obtenidos. Por ejemplo, en una aplicacin que implemente un carrito de la compra, la validacin a nivel de formulario comprobara si una cantidad introducida es vlida (previa conversin de la cantidad a un objeto java conocido), y la validacin a nivel de aplicacin podra validar si el usuario ha excedido su lmite de crdito.
JSFValidacion Todas las validaciones sobre campos de un formulario se han de implementar en el servidor. Si se desea realizar las validaciones en el cliente, deber existir una comprobacin idntica en el lado del servidor, ya sea mediante validacin estndar de JSF o mediante validacin a nivel de aplicacin.
36 de 191
Framework Atlas
Normativa JSFCustomValidator Cuando sea necesario realizar una validacin genrica para la que Atlas no ofrezca un validador estndar, se implementar uno a medida. Para crear un validador a medida se crear una clase Java que implemente la interfaz
NORMA
Validator, con la siguiente nomenclatura: o <nombre>Validator
Donde nombre ser sustituido por el nombre del validador. Estas clases se incluirn en el paquete jsf.validators del bloque funcional correspondiente. En el caso de que sean validadores genricos para todo el proyecto se pueden ponen en un bloque funcional comn.
6.2.1.4
Conversores
Los datos procedentes de una peticin Http son cadenas de caracteres. Por eso es necesario un mecanismo de conversin de dichas cadenas al tipo de datos deseado (el declarado en el managed bean vinculado al campo del formulario).
Ejemplo de uso de un conversor <h:outputText value="#{user.dateOfBirth}"> <f:convertDateTime type="both" dateStyle="full" /> </h:outputText> JSFCustomConversor Cuando sea necesario realizar un conversor particular para la que Atlas no ofrezca un conversor estndar, se implementar uno a medida. Para crear un conversor a medida se crear una clase Java que implemente la interfaz
NORMA
Converter, con la siguiente nomenclatura: o <nombre>Converter
Donde nombre ser sustituido por el nombre del conversor. Estas clases se incluirn en el paquete jsf.converters del bloque funcional correspondiente. En el caso de que sean conversores genricos para todo el proyecto se pueden ponen en un bloque funcional comn.
6.2.1.5
Internacionalizacin
37 de 191
Framework Atlas
Normativa
El conjunto de elementos culturales, polticos y especficos de una regin representados en una aplicacin se denominan locale. Las aplicaciones deberan personalizar la presentacin de los datos en funcin del locale preferido del usuario, de esta manera se puede definir el concepto de internacionalizacin (Tambin conocida como I18n) como el proceso de separar las dependencias locale del cdigo fuente de la aplicacin. Ejemplos de dependencias locale pueden ser el conjunto de caracteres, encoding, moneda, formato de tiempo, calendarios, etc. El concepto de Localizacin (Tambin conocido como L10n) es el proceso de adaptar una aplicacin internacionalizada a un locale especfico, por lo que las aplicaciones tendrn que estar internacionalizadas de forma previa a ser localizadas. JSF dispone de un potente soporte a la internacionalizacin y la localizacin. Para desarrollar una aplicacin completamente internacionalizada, todos los literales incluyendo etiquetas, campos de fecha, campos numricos, campos de texto, mensajes de error y textos mostrados como alternativa a las imgenes se han de externalizar a un archivo de propiedades. El entorno de ejecucin de JSF determina el locale de un usuario en base a la configuracin de su navegador, aunque se puede establecer por configuracin el locale de la misma. JSF usa la clase ResourceBundle para cargar los mensajes de texto del archivo de propiedades y mostrarlos en los componentes de presentacin.
JSFInternalizacion En las pginas JSF no puede haber literales de texto en un idioma especfico. Las aplicaciones contendrn un fichero para almacenar los mensajes internacionalizados. Este fichero se ubicar en la carpeta src/main/resources/msg, con la siguiente nomenclatura:
NORMA
messages_xx.properties
Donde xx es el sufijo del locale al que corresponden los ficheros de mensajes. Este fichero contendr todos los mensajes de la aplicacin. El mecanismo de internacionalizacin no aplica a mensajes incluidos en trazas, al no ser directamente visualizados por los usuarios finales. Al menos se debe de entregar el fichero de mensajes del locale espaol (es).
Los distintos arquetipos ya vienen preparados con estos ficheros de mensajes y la configuracin necesaria para trabajar con ellos. Desde la pgina JSF cuando queramos acceder a los textos del fichero de internacionalizacin se utilizar el objeto bundle tal y como se muestra en el siguiente ejemplo:
38 de 191
Framework Atlas
Normativa
Ejemplo de uso de literales internacionalizados <h:outputLabel id="outputLabelNombre" for="inputTextNombre" styleClass="label" value="#{bundle['inputText.nombre']}" />
PRACTICA

JSFAccesoMessages Para acceder a los elementos del fichero de mensajes se recomienda utilizar el mtodo getStringFromBundle de la clase atlas.componentes.utiles.AtlasFacesUtils.
BUENA
6.2.1.6
Estructura y decoracin de la pgina
En muchos casos surge la necesidad de implementar un mecanismo mediante el cual mantengamos una estructura (layout) consistente entre todas las pginas que conforman la aplicacin Web, lo que implicar tener elementos comunes de pgina para ser implementados como componentes reutilizables. La tecnologa elegida para lograr esto es Facelets, que permite incluir plantillas reutilizables de forma dinmica implementando de forma abstracta el patrn composite view y decorator. Facelets es un lenguaje basado en plantillas que utiliza el concepto de rbol de componentes fomentando la reutilizacin, permitiendo definir componentes como composicin de otros componentes. Podemos destacar las siguientes caractersticas sobre Facelets: Trabajo basado en plantillas. Basado en la composicin de componentes. Creacin de etiquetas lgicas a la medida. Soporte completo a EL, incluyendo funciones. Desarrollo amigable para el diseador grfico gracias al concepto de decorador. Creacin de libreras de componentes. Lenguaje integrado son JSTL. No son necesarios ficheros de configuracin XML. El API de facelets son totalmente independientes del contenedor.
39 de 191
Framework Atlas
Normativa Dentro del framework Atlas se han creado los distintos layouts que tienen que utilizar las aplicaciones desarrolladas con este framework. El uso de estos layouts garantiza la homogeneidad de los desarrollos y facilita el mantenimiento de los mismos.
Los layouts que ofrece el framework son:
hc.xhtml
(Horizontal+Contenido). Incluye un men horizontal, y en el resto de la pgina se muestra el contenido.
hvc.xhtml: (Horizontal+Vertical+Contenido). Incluye un men horizontal, uno vertical y en el resto de la pgina se muestra el contenido.
40 de 191
Framework Atlas
Normativa hv.xhtml (Horizontal+Visual). Incluye un men horizontal, y en el resto de la pgina se muestra el men visual.
hvv.xhtml (Horizontal+Vertical+Visual). Incluye un men horizontal, men vertical y en el resto de la pgina se muestra el men visual.
vc.xhtml
(Vertical + Contenido). Incluye un men vertical, y en el resto de la pgina se muestra el contenido.
41 de 191
Framework Atlas
Normativa vv.xhtml: (Vertical + Visual). Incluye un men vertical, y en el resto de la pgina se muestra el men visual.
c.xhtml
(Contenido) Incluye solamente la cabecera y el pie.
NORMA
JSFLayout El layout de pginas web debe ser alguno de los que ofrece el framework Atlas.
Ejemplo de uso de layout con men vertical <?xml version="1.0" encoding="UTF-8"?> <jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:atlas="http://atlas.core.componentes/jsf" xmlns:c="http://java.sun.com/jstl/core" xmlns:fn="http://java.sun.com/jsp/jstl/functions" xmlns:a4j="http://richfaces.org/a4j"
42 de 191
Framework Atlas
Normativa xmlns:rich="http://richfaces.org/rich" version="2.0"> <jsp:text> <![CDATA[ <?xml version="1.0" encoding="UTF8" ?> ]]> </jsp:text> <jsp:text> <![CDATA[ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> ]]> </jsp:text> <html xmlns="http://www.w3.org/1999/xhtml"> <ui:composition template="/WEB-INF/layout/vc.xhtml"> <ui:define name="rastroMigas"> <ui:include src="/secure/rastroMigas/rastro.xhtml" /> </ui:define> <ui:define name="menuVertical"> <ui:include src="/secure/menu/menu.xhtml" /> </ui:define> <ui:define name="content"> . . . Aqui se pondra el contenido de nuestra pgina </ui:define> </ui:composition> </html> </jsp:root>
JSFPanel
NORMA
La ubicacin de los distintos elementos que forman la pgina se realizar con los componentes que JSF ofrece: PanelGrids y PanelGroup. No se utilizarn directamente tablas de html.
Para ms informacin y ejemplos de layout acceder a la aplicacin de componentes.
43 de 191
Framework Atlas
Normativa 6.2.1.7 Uso de javascript JSFJavascript Se debe minimizar el uso de Javascript y el cdigo javascript que se incluya debe ser compatible con los navegadores.
NORMA NORMA
En el caso de utilizar codigo javascript este se implementar mediante funciones que se ubicarn en ficheros xxxx.js. Donde xxxx es el nombre de la aplicacin. Los ficheros de javascript debern ubicarse dentro de la carpeta src/main/webapp/js. Los ficheros js que se incluyen en los arquetipos no pueden ser modificados.
jQuery es una biblioteca de JavaScript que permite simplificar la manera de interactuar con los documentos HTML, manipular el rbol DOM, manejar eventos, desarrollar animaciones y agregar interaccin con la tcnica AJAX a pginas web. Por lo tanto si se requiere realizar algunas de estas operaciones en las aplicaciones Atlas se deber utilizar este framework. Este framework javascript ya viene incluido en la distribucin de RichFaces que viene configurada en los arquetipos de ATLAS, por lo que no ser necesario incluir ningn fichero adicional en el proyecto. JSFJQuery Solo est permitido el uso del framework javascript JQuery que viene incluido en la versin de RichFaces. No se podrn incluir frameworks diferentes a este ni otras versiones que no sea la interna de RichFaces.
Para usar JQuery en el proyecto, se han de tener en cuenta las siguientes consideraciones: 6.2.1.7.1 Uso de JQuery en pginas JSF
Para usar JQuery en nuestras pginas JSF ser necesario incluir esta sentencia en la pgina .xhtml: Sentencia a incluir en la pgina .xhtml para utilizar jQuery <h:outputScript name="jquery.js" target="head" /> De esta forma se estar haciendo uso de la versin interna de Richfaces. 6.2.1.7.2 Uso del objeto JQuery
Para usar el objeto JQuery, no se podr utilizar el alias $, que es de uso comn en este framework, ya que da problemas con las expresiones JSF. A continuacin se muestran dos ejemplos uno que NO Funciona y otro que SI funciona: Uso del objeto JQuery en pgina xhtml
44 de 191
Framework Atlas
Normativa <h:outputScript name="jquery.js" target="head" /> <h:outputScript> $('#elementId').text('Nuevo contenido'); // NO funciona jQuery('#elementId').text('Nuevo contenido'); // SI funciona </h:outputScript> 6.2.1.7.3 Uso de ready en sustitucin del evento onLoad
En ocasiones es necesario realizar acciones una vez se haya cargado la pgina. Normalmente se hace uso del evento onLoad del tag body que es invocado una vez que se ha cargado toda la pgina. Se recomienda, en lugar de utilizar ese evento, hacer uso del mtodo ready del objeto JQuery ya que este mtodo se ejecuta una vez inicializado el rbol DOM de la pgina en el navegador. A continuacin se muestra un ejemplo:
Sustitucin de onLoad por evento ready <h:outputScript name="jquery.js" target="head" /> <h:outputScript> jQuery(document).ready(function() { // Incicializar pagina ... }); </h:outputScript>
6.2.1.7.4
Localizacin de elementos por Id
Cuando se quiere localizar un elemento de la pgina por su identificador, el carcter de composicin usado por JSF : genera problemas con JQuery, ya que tambin es un operador de seleccin. Por lo tanto para no tener problemas hay que transformarlo para escaparlo antes de pasarlo a JQuery. A continuacin se muestra un ejemplo: Escapado para poder localizar elementos por Id <h:outputScript name="jquery.js" target="head" /> <h:form id="formularioDatos"> <f:subview id="vista1"> <h:inputText id="nombre" />  </f:subview> </h:form> <h:outputScript> nombreId = '#{rich:clientId(nombre)}'.replace(/:/g, '\\:'); jQuery(# + nombreId).value = ATLAS; </h:outputScript>
45 de 191
Framework Atlas
Normativa La operacin marcada en amarillo en el ejemplo anterior obtiene el Id real del elemento nombre (formularioDatos:vista1:nombre), mientras que la parte marcada en verde lo modifica para su uso con jQuery (formularioDatos\:vista1\:nombre). 6.2.1.8 Normas de estilo
Existe un documento llamado Atlas Gua de Estilo que incluye informacin sobre: o o o Estilo de las aplicaciones Accesibilidad Usabilidad
Es necesario leer este documento antes de abordar la implementacin de las pginas JSF. JSFAccesiblidad
NORMA NORMA NORMA
Las aplicaciones de la Comunidad de Madrid que se publiquen en Internet tendrn que cumplir un Nivel de Conformidad "A" de WCAG, esto implicar que las aplicaciones sean estrictas en el cumplimiento de las normas de prioridad 1 especificadas en el Anexo Gua de Estilo del framework Atlas.
JSFImagenes Las imgenes a utilizar en las aplicaciones del framework Atlas debern ubicarse dentro de la carpeta src/main/webapp/img
JSFCSS Las hojas de estilo se ubicaran en la carpeta src/main/webapp/css. Dentro de esta carpeta se encuenta un fichero llamado atlas.css que incluye los estilos de Atlas. Este fichero no se puede modificar. En el caso de necesitar nuevos estilos estos se crearn dentro de un fichero con la siguiente nomenclatura xxxx.css Donde xxxx es el nombre de la aplicacin. Nunca se podrn definir estilos directamente dentro de una pgina.
46 de 191
Framework Atlas
Normativa JSFIFRAMES
NORMA
6.2.1.9
Se prohibe la utilizacin de IFrames. En el caso de que sea necesario utilizarlos es necesario consultar previamente a su utilizacin a la Unidad de Arquitectura y Software de Aplicaciones justificando debidamente su necesidad.
Interfaces ricas de usuario (RIA)
Existen tecnologas que pretenden mejorar las aplicaciones web asemejndolas todo lo posible a las aplicaciones de escritorio tradicionales. La arquitectura de ICM permite crear aplicaciones RIA utilizando AJAX de dos maneras: Mediante la librera Ajax4JSF Usando los componentes JSF del framework Atlas que poseen comportamiento asncrono con AJAX de forma transparente. Ajax4JSF se incluye dentro de los componentes RichFaces. Es una librera open source que se integra totalmente en la arquitectura de JSF y extiende la funcionalidad de sus etiquetas dotndolas con tecnologa Ajax de forma limpia y sin aadir cdigo Javascript. Mediante esta librera se puede variar el ciclo de vida de una peticin JSF, recargar determinados componentes de la pgina sin necesidad de recargarla por completo, realizar peticiones al servidor automticas, control de cualquier evento de usuario, etc. Esta aproximacin tiene las siguientes ventajas: La cantidad de javascript que hay que escribir (y mantener) es mnima. Esto reduce enormemente el tiempo de depuracin y pruebas necesarias cuando se trabaja en un entorno multi-navegador. Fcil integracin: Ajax4JSF apenas requiere la modificacin del cdigo existente. Soporte Facelets: Es una solucin que se integra a la perfeccin con la tecnologa de decoracin y estructura de pginas, es decir, facelets. Compatibilidad. No es necesario desarrollar otra aplicacin para cuando el navegador no soporta AJAX. En este caso, la aplicacin se comportar de la forma tradicional, refrescando la pgina completa.
JSFAjax
NORMA
Si se desea dotar de capacidades AJAX a las pginas JSF se utilizar Ajax4JSF. El uso de cualquier otra tecnologa RIA deber ser consensuado previamente con ICM.
47 de 191
Framework Atlas
Normativa
El arquetipo web ya viene configurado para trabajar con Ajax4JSF. La forma mas sencilla de incluir ajax4JSF en una pgina es incluir una regin y todo lo que se incluya dentro de esta se refrescar parcialmente.
Ejemplo de uso de regin ajax <a4j:form id="allRoomsForm2" ajaxSubmit="true" reRender="roomsTable,scroll_1,scroll_2" status="ajaxStatus"> <a4j:region id="region1" selfRendered="true">
..
</a4j:region> </a4j:form>
JSFAjaxInterac
NORMA
La invocacin de funcionalidad AJAX debe ser siempre consecuencia de una interaccin con el usuario, por ejemplo, al seleccionar el valor de un combo, se carga de manera dinmica los valores de otro. En concreto, la carga inicial de una pgina no debe implicar la ejecucin de funcionalidad AJAX.
JSFAjaxLimite Se recomienda limitar la cantidad de informacin intercambiada mediante AJAX. Para esto se recomienda restringir las regiones AJAX de modo que se procese el mnimo
PRACTICA
nmero de componentes. Las regiones se pueden anidar y no es necesario que los componentes que se vayan a actualizar estn dentro de la regin. Tambin se recomienda el uso del atributo AjaxSingle en aquellas situaciones en las que slo sea necesario que se procese el componente que desencadena el evento. Por ltimo, en ocasiones es preferible recargar la pgina de nuevo, a intercambiar mediante AJAX gran cantidad de informacin, y utilizar componentes estndar a utilizar componentes AJAX si no se va a hacer uso de propiedades especficas del componente.
BUENA
48 de 191
Framework Atlas
Normativa 6.2.1.10 Ayuda contextual La ayuda contextual en una aplicacin favorece y mejora la experiencia de usuario facilitando el uso de la aplicacin. Para incluir este tipo de ayuda en una pgina de nuestra aplicacin utilizaremos el icono podemos encontrar en la ruta src/main/webapp/img ico_ayuda.gif de los arquetipos. Dentro de los formularios JSF se puede incluir ayuda contextual para cada uno de los elementos mediante el uso de la etiqueta de richfaces rich:toolTip. Mediante esta etiqueta se muestra un pequeo popup no modal en el cual se puede mostrar informacin adicional. que
Ejemplo de uso de rich:toolTip en un campo de un formulario

<h:panelGrid columns="2" cellpadding="0" cellspacing="0"> <h:inputText id="inputTextClienteNombre" size="50" maxlength="50" styleClass="cajaTexto" required="false" value="#{clienteBean.nombreFilter}" onkeypress="trapEnter(event,'filterPanel:filtrarLink',true);"/> <a4j:outputPanel styleClass="paddingleft5"> <h:graphicImage value="img/ico_ayuda.gif" alt="#{bundle['tooltipFilter.clientenombre']}"/> <rich:tooltip value="#{bundle['tooltipFilter.clientenombre']}"/> </a4j:outputPanel> </h:panelGrid>
El mensaje a mostrar dentro del tooltip se ha de obtener del fichero de mensajes de la aplicacin tal y como se puede ver en el ejemplo anterior.
En los arquetipos de Atlas se han incluido ejemplos de uso de tooltip en los formularios de ejemplo, y la herramienta de generacin automtica de cdigo tambin genera estos tooltips en las pginas de listados y detalles de entidades. Si se desea una ayuda contextual ms completa a nivel de pgina se har utilizando el componente <atlas:panelAyuda> que muestra un icono en la parte superior derecha que enlaza con la pgina xhtml de ayuda correspondiente a dicha pgina. Esta pgina se muestra en un popup no modal para que pueda ser visualizada mientras se est trabajando con la aplicacin. Las pginas de ayuda se incluirn en una carpeta llamada help y la nomenclatura de las mismas deber ser la misma de la pgina original ms un sufijo _help. Para ms informacin consultar el manual de usuario ATLAS_MUS_Componente_Panel_ayuda.
49 de 191
Framework Atlas
Normativa
En la siguiente pgina podemos ver el icono que enlaza con la ayuda en la parte superior derecha de la pgina.
Al pulsar sobre el icono nos mostrar el panel de la ayuda de la siguiente forma:
JSFAYUDA
PRACTICA
BUENA
Se recomienda incluir ayuda contextual en las aplicaciones utilizando el componente rich:toolTip para elementos individuales y atlas:panelAyuda para ayudas a nivel de pgina.
6.2.2
MANAGED BEANS
50 de 191
Framework Atlas
Normativa Los managed beans o beans de respaldo son las clases que incluyen los atributos y mtodos que van a ser invocados desde las pginas JSF. Los distintos mtodos que puede tener un managed bean son: 1. Gettter y setter de los atributos 2. Mtodos manejadores de eventos de accin 3. Mtodos de manejo de eventos de cambio de valor 4. Mtodos de accin
JSFMBeansImpl Dentro de una aplicacin en cada bloque funcional se han de crear los managed beans que darn cobertura a las peticiones de las pginas JSF.
NORMA
La nomenclatura de estas clases ser: <nombre>Bean Donde <nombre> debe ser sustituido por el nombre del Bean. Estas clases Java se crearn en el paquete jsf dentro del bloque funcional correspondiente.
A continuacin se muestra parte de un ejemplo de managed bean. El ejemplo completo se puede ver dentro del arquetipo de aplicaciones web. ClientesBean.java package ejpl.gestion.jsf; import /** * Esta clase representa el Backing Bean * para las pginas que hagan uso de la * entidad ejpl.gestion.domain.Cliente . * @author ICM * @version 1.0. */ @Component public class ClientesBean { /** * Identificador del numero de serie para serializacion */ private static final long serialVersionUID = 1L; /** * Servicio de la fachada */
51 de 191
Framework Atlas
Normativa private GestionFacade facade; /** * Cliente actual */ private Cliente cliente = null; /** * Filtro para el nombre del cliente */ private String nombreCliente = null; /** * Constructor por defecto. * * Se realizan las operaciones de * inicializacin para los Managed Beans */ public ClientesBean() { this.cliente = new Cliente(); cliente.setEstadoCivil(new EstadoCivil()); } /** * @return <code>ejpl.gestion.domain.Cliente</code> Devuelve el objeto de * dominio cliente asociado al Backing Bean. */ public Cliente getCliente() { return this.cliente; } /** * @param cliente <code>ejpl.gestion.domain.Cliente</code> Modifica el * objeto de dominio asociado al Backing Bean. */ public void setCliente(Cliente cliente) { this.cliente = cliente; } /** * Este metodo obtiene un cliente a partir de un identificador/PK obtenida * de la request. * * @throws atlas.core.exceptions.ServiceException * Lanza atlas.core.exceptions.ServiceException ante cualquier error * @return <code>java.lang.String</code> Devuelve la regla de navegacion * <code>NavigationResults.MODIFICAR_CLIENTE</code>. */ public String cargarCliente() throws ServiceException { String paramIdCliente = AtlasFacesUtils.getFromRequest(FacesContext.getCurrentInstance(), "idCliente"); try { if (paramIdCliente != null) { Integer idCliente = Integer.valueOf(paramIdCliente); this.cliente = facade.obtenerClientePorId(idCliente); } } catch (ServiceException se) {
52 de 191
Framework Atlas
Normativa AtlasFacesUtils.storeOnRequestError(FacesContext.getCurrentInstance(), "error.CLIENTES_OBTENER", se); // return NavigationResults.MOSTRAR_ERROR; throw se; } return NavigationResults.MODIFICAR_CLIENTE; } /** * Este metodo inserta o modifica un cliente en el sistema. * * @throws atlas.core.exceptions.ServiceException Lanza * atlas.core.exceptions.ServiceException ante cualquier error * producido. * @return <code>java.lang.String</code> Devuelve la regla de navegacion * <code>NavigationResults.VOLVER_LISTADO_CLIENTES</code>. */ public String guardarCliente() throws ServiceException { try { facade.insertOrUpdateCliente(cliente); } catch (ServiceException se) { AtlasFacesUtils.storeOnRequestError(FacesContext.getCurrentInstance(), "error.CLIENTES_MODIFICAR", se); // return NavigationResults.MOSTRAR_ERROR; throw se; } return NavigationResults.VOLVER_LISTADO_CLIENTES; } ... }
NORMA NORMA
JSFAnotacion Las clases que representan los Managed Beans de JSF debern tener la anotacin @Component.
JSFMBAtributos Los atributos de un managed bean se definirn como privados, con mtodos get y set para aquellas propiedades que vayan a ser vinculadas a un componente de una pgina JSF.
JSFMBunico
PRACTICA
BUENA
Se recomienda crear un managed bean por cada pgina JSF, de tal manera que tanto los datos como el comportamiento de esta pgina sean manejados por el bean en cuestin. Un managed bean no debera mezclar atributos o comportamientos de dos pginas que no estn relacionadas.
53 de 191
Framework Atlas
Normativa
El acceso a los datos persistentes deber realizarse a travs de la capa de negocio, haciendo uso de la fachada que dicha capa expondr a tal efecto. Adems no est permitida la invocacin directa a servicios de negocio sin pasar por la fachada.
class j sf
ClientesBean + + + + + + + + + + + + + + + + + + + + + cliente: Cliente = null clientesScroller: HtmlDataScroller = new HtmlDataScr... facade: GestionFacade nombreCliente: String = null orderAndFilterClientes: OrderAndFilterBean = null serialVersionUID: long = 1L {readOnly} cargarCliente() : String ClientesBean() filtrar() : String getCliente() : Cliente getClientesScroller() : HtmlDataScroller getFacade() : GestionFacade getNombreCliente() : String getOrderAndFilterClientes() : OrderAndFilterBean getTimeZone() : T imeZone guardarCliente() : String nuevoCliente() : String obtenerClientes(int, int, Object, Object) : List<Cliente> obtenerTotalClientes(Object) : int setCliente(Cliente) : void setClientesScroller(HtmlDataScroller) : void setEstadoCivil(String) : void setFacade(GestionFacade) : void setIdEstadoCivil(String) : void setNombreCliente(String) : void setOrderAndFilterClientes(OrderAndFilterBean) : void volver() : String
interface facade::GestionFacade + -facade + + + + + + deleteCliente(Cliente) : void insertCliente(Cliente) : void insertOrUpdateCliente(Cliente) : void obtenerClientePorId(Integer) : Cliente obtenerClientes(int, int, Object, Object) : List<Cliente> obtenerTotalClientes(Object) : int updateCliente(Cliente) : void
Pgina JSF
JSFFacade
NORMA
6.2.2.1
El acceso a la capa de negocio desde los managed beans siempre se debe hacer a travs de la fachada. Esto implica que desde las clases managed beans no se puede invocar ni DAOs ni ningn servicio que no sea la fachada.
Manejo de excepciones
JSF no ofrece un mecanismo automtico para el manejo de las excepciones producidas dentro de los managed beans, aunque si dispone de ciertos elementos que ayudan en la gestin de las mismas. Dentro del API de JSF existe una clase que permite mostrar mensajes genricos (normalmente mensajes de error) llamada FacesMessage. Aadiendo un objeto de esta clase al contexto de la JSF, este mensaje se puede mostrar en cualquier JSF mediante una etiqueta estndar. Mediante el uso de esta clase, podemos tratar las excepciones de los beans de la aplicacin, de forma que cuando se produzcan se almacene uno de estos mensajes:
54 de 191
Framework Atlas
Normativa JSFException Todos los mtodos de los managed beans que hagan uso de la fachada, tratarn las excepciones que esta pueda lanzar, que siempre sern de tipo ServiceException o clases que hereden de esta. La forma de manejar la excepcin depender del origen de la misma, distinguiendo entre excepciones de negocio (excepcin creada a medida) y excepciones del sistema.
NORMA
En el primer caso, se atrapar la excepcin y se implementar el cdigo que deseemos que se ejecute en base a las reglas de nuestro negocio. Es decir, si por ejemplo se produce una supuesta excepcin (creada a medida) BlockedUserException indicando que un usuario est bloqueado, se podra implementar una funcionalidad que redirija la peticin inicial a otra aplicacin externa que permita desbloquear la cuenta del usuario.
En el segundo caso, siempre se redirigir a una pgina de error que extraer la excepcin encapsulada dentro del ServiceException (como por ejemplo una DataAccessException) mostrando un mensaje amigable al usuario final en funcin de la excepcin manejada.
Los mtodos del bean podran manejar las excepciones de la siguiente forma:
Ejemplo de manejo de excepciones /** * Este metodo inserta o modifica un cliente en el sistema. * * @throws atlas.core.exceptions.ServiceException Lanza * atlas.core.exceptions.ServiceException ante cualquier error * producido. * @return <code>java.lang.String</code> Devuelve la regla de navegacion * <code>NavigationResults.VOLVER_LISTADO_CLIENTES</code>. */ public String guardarCliente() throws ServiceException { try { facade.insertOrUpdateCliente(cliente); } catch (ServiceException se) { AtlasFacesUtils.storeOnRequestError(FacesContext.getCurrentInstance(), "error.CLIENTES_MODIFICAR", se); throw se; } return NavigationResults.VOLVER_LISTADO_CLIENTES; }
Cuando se produce una excepcin, el mtodo est almacenando un mensaje en el contexto de JSF. Para presentar el error tendramos que incluir en la pgina JSF la etiqueta h:message.
55 de 191
Framework Atlas
Normativa
JSFStoreError
PRACTICA
BUENA
Para enviar el mensaje de error de una excepcin a la pgina jsf se recomienda utilizar el mtodo storeOnRequestError de la clase atlas.componentes.utiles.AtlasFacesUtils. Este metodo deja en el contexto de JSF el mensaje de error para que luego pueda se capturado por la etiqueta h:message.
Tambin se manejarn las excepciones que puedan producirse en otros puntos del bean (constructor, mtodo init, listeners, etc.).
6.2.2.2
Navegacin
JSFNavegacion Los valores posibles para la navegacin dinmica de los managed beans se han de almacenar en una clase aparte, para tenerlos todos localizados en un mismo lugar.
NORMA
Esta clase debe llamarse NavigationsResults y ubicarse en el paquete jsf de cada bloque funcional. En el caso de que se tengan varios bloques funcionales hay que aadir por delante el nombre del bloque funcional para poder distinguir una clase de otra. (Ejemplo <bloquefuncional>NavigationResults). En esta clase se definirn como constantes (public static final String) todos los caminos de la navegacin.
A continuacin se muestra un ejemplo de esta clase NavigationResults.java package ejpl.gestion.jsf; /** * Esta clase representa constantes asociadas * a las reglas de navegacion de la aplicacion. * @author ICM * @version 1.0. * @since Atlas 1.0.0. */ public final class NavigationResults { /** * Constructor para que no se genere el publico por defecto
56 de 191
Framework Atlas
Normativa */ protected NavigationResults() { } /** * Operacion de navegacion: Resultado de la operacion correcto. */ public static final String SUCCESS = "success"; /** * Operacion de navegacion: Resultado de la operacion fallido. */ public static final String FAILURE = "failure"; /** * Operacion de navegacion: Salir de la aplicacion. */ public static final String LOGOUT = "logout"; /** * Operacion de navegacion: Nuevo Cliente. */ public static final String NUEVO_CLIENTE = "nuevoCliente"; /** * Operacion de navegacion: Modificar Cliente. */ public static final String MODIFICAR_CLIENTE = "modificarCliente"; /** * Operacion de navegacion: Eliminar Cliente. */ public static final String ELIMINAR_CLIENTE = "eliminarCliente"; /** * Operacion de navegacion: Volver al listado de Clientes. */ public static final String VOLVER_LISTADO_CLIENTES = "volverListadoClientes"; /** * Operacion de navegacion: Mostrar pagina de error. */ public static final String MOSTRAR_ERROR = "mostrarError"; } Los mtodos de las clases managed beans debern utilizar estas variables en la respuesta de los mtodos de accin tal y como se puede ver en los ejemplos anteriormente expuestos. Los elementos de navegacin indicados en el fichero NavigationResults debern ser utilizados en el fichero de JSF de configuracin de la navegacin tal y como se comenta en el apartado 2.1.3.3 facesnavigation.xml.
6.2.3
Configuracin de JSF
57 de 191
Framework Atlas
Normativa Para realizar la configuracin necesaria para los componentes JSF de las aplicaciones del framework Atlas tenemos que tener en cuenta que esta configuracin se encuentra dentro de tres ficheros. Estos ficheros los podemos encontrar en el arquetipo web previamente configurados en el directorio src/main/webapp/WEB-INF. Fichero de configuracin faces-config.xml faces-managed-beans.xml faces-navigation.xml Descripcin Fichero principal de configuracin de JSF. No se puede modificar este fichero. Fichero donde se definen los managed beans de la aplicacin en caso de no usar anotaciones. Fichero donde se configuran las reglas de navegacin de la aplicacin.
6.2.3.1
faces-config.xml
El fichero de configuracin faces-config.xml ya incluye: o o Configuracin de los resolver de variables y propiedades que permiter inyectar beans de Spring en los managed beans. Configuracin de los ficheros de mensajes y de los locales. JSFfacesconfigxml
NORMA
6.2.3.2
La configuracin que se encuentra dentro del fichero faces-config.xml del arquetipo no se puede modificar. En el caso de que se desee modificar se debe solicitar la correspondiente autorizacin a ICM justificando dicha necesidad.
faces-managed-beans.xml
La definicin de los managed beans puede hacerse de dos maneras: mediante un fichero de configuracin o con anotaciones, para el primer caso utilizaremos el fichero faces-managed-beans.xml. La forma de aadir managed beans es la siguiente:
Ejemplo de configuracin de managed bean <managed-bean> <description>Bean de clientes</description> <managed-bean-name>clientesBean</managed-bean-name> <managed-bean-class> ejpl.gestion.jsf.ClientesBean </managed-bean-class> <managed-bean-scope>request</managed-bean-scope> <managed-property> <property-name>facade</property-name> <value>#{facade}</value>
58 de 191
Framework Atlas
Normativa </managed-property> <managed-property> <property-name>orderAndFilterClientes</property-name> <value>#{orderAndFilterClientes}</value> </managed-property> </managed-bean> Uso del contexto dentro del faces-managed-beans.xml El contexto de una aplicacin Web permite el almacenamiento de informacin relevante a lo largo de la ejecucin de diversas operaciones por parte del usuario. Las decisiones sobre el mantenimiento del estado tienen impacto en el rendimiento de la aplicacin, as como en la disponibilidad y la escalabilidad. Estas decisiones incluyen elegir la capa de la aplicacin donde manejar el estado, el mbito apropiado para cada elemento a almacenar y como mantener el estado en un entorno distribuido. En las aplicaciones JEE el estado tiene distintos mbitos, entendindose como mbito a los distintos lugares desde donde ese estado es accesible. Resumiendo, se puede decir que el estado en la capa de presentacin se puede mantener en cuatro mbitos.
JSF amplia estos mbitos, permitiendo guardar y restaurar el estado de los componentes para cada peticin tanto en el cliente como en el servidor:
mbito Pgina
Descripcin Aplicable slo a pginas JSF contiene datos que solo son vlidos en el contexto de una pgina. Cuando una JSF redirige o incluye a otra, cada pgina define su propio estado.
Peticin
Permite almacenar informacin que ser accesible por todos los componentes Web que intervengan en esa peticin hasta que se genere la respuesta al usuario.
Sesin
Permite almacenar informacin que ser accesible por todos los componentes Web durante la sesin del usuario, que durar desde que el usuario entre en la aplicacin hasta que salga de ella o transcurra un tiempo mximo de inactividad.
Aplicacin Permite almacenar informacin que ser accesible por todos los componentes de la aplicacin web en cualquier momento (mientras la aplicacin est activa). Cliente Servidor El rbol de componentes JSF se guarda en un campo oculto dentro de la peticin Http El rbol se almacena en la sesin Http
59 de 191
Framework Atlas
Normativa Para definir el contexto de un managed bean se utiliza el atributo managed-bean-scope. JSFRequest Los managed beans deben ser siempre de mbito request, pudiendo ser de mbito sesin tan slo en casos excepcionales y justificados.
Atlas amplia este modelo haciendo posible escribir aplicaciones sin necesidad del uso del HttpSession. Toda la informacin tanto de la vista como del modelo (managed beans) puede ser codificada y enviada al cliente. Esto se lleva a cabo mediante una etiqueta presente en la librera de componentes de Atlas:
NORMA
<atlas:guardarEstado> <atlas:guardarEstado id="save1" value="#{calcForm.number1}" /> El nico requisito para poder almacenar un objeto completo, es que el bean implemente el interfaz java.io.Serializable
JSFSavestate El problema principal del almacenamiento de informacin (tanto del rbol de componentes como de los managed beans) es el rendimiento.
PRACTICA
BUENA
El tiempo de serializacin y deserializacin de los objetos aumenta considerablemente el tiempo de respuesta ante una peticin, del mismo modo que el ancho de banda consumido (y por tanto de tiempo de transferencia de las pginas). Por lo tanto se recomienda reducir el uso del componente guardarEstado a casos imprescindibles.
6.2.3.3
faces-navigation.xml
El fichero de configuracin faces-navigation.xml incluye las reglas de navegacin de JSF. Presenta dos tipos de navegacin: Esttica: cuando desde una pgina se va directamente a otra. Esto se hace definiendo las reglas de navegacin en el fichero de configuracin.
60 de 191
Framework Atlas
Normativa Dinmica: cuando una accin o cierta lgica determina la pgina a la que navegar. Esto lo soporta permitiendo que los componentes definan como destino de su navegacin el resultado de una consulta a un manejador de acciones, donde se codifica la navegacin dinmica, frente a la definicin de un destino fijo.
A continuacin se muestra un ejemplo de las reglas de navegacin para una aplicacin simple:
Ejemplo de faces-navigation.xml <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN" "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">  <!-Fichero donde se definen todas --> <!-las reglas de navegacin de la aplicacin -->  <faces-config> <navigation-rule> <description> Reglas de navegacion para la pagina index.xhtml </description> <from-view-id>/secure/index.xhtml</from-view-id> <navigation-case> <from-outcome>nuevoCliente</from-outcome> <to-view-id>/secure/formularioCliente.xhtml</to-view-id> </navigation-case> <navigation-case> <from-outcome>modificarCliente</from-outcome> <to-view-id>/secure/formularioCliente.xhtml</to-view-id> </navigation-case> <navigation-case> <from-outcome>eliminarCliente</from-outcome> <to-view-id>/secure/index.xhtml</to-view-id> </navigation-case> </navigation-rule> <navigation-rule> <description> Reglas de navegacion para la pagina formularioCliente.xhtml </description> <from-view-id>/secure/formularioCliente.xhtml</from-view-id> <navigation-case> <from-outcome>volverListadoClientes</from-outcome> <to-view-id>/secure/index.xhtml</to-view-id> </navigation-case> </navigation-rule> </faces-config>
61 de 191
Framework Atlas
Normativa JSFNavDes Se ha de ofrecer un comentario explicativo en el atributo description para cada regla de navegacin definida en el archivo de configuracin navigation-rule.xml
Mediante reglas de navegacin de JSF se puede hacer uso de patrones, de forma que una serie de pginas lleven a una dada:
NORMA
Ejemplo de regla de navegacin con patrones <navigation-rule> <description> Regla de navegacin para todas las pginas de la carpeta pages </description> <from-view-id>/pages/*</from-view-id> <navigation-case> <from-outcome>menu</from-outcome> <to-view-id>/menu/main_main.jsp</to-view-id> </navigation-case> <navigation-case> <from-outcome>info</from-outcome> <to-view-id>/menu/info.jsp</to-view-id> </navigation-case> </navigation-rule>
Tambin se pueden especificar destinos globales de forma que desde cualquier pgina se pueda navegar una dada. El siguiente ejemplo muestra como con esta caracterstica se puede implementar una opcin de ayuda global para la aplicacin:
Ejemplo de regla de navegacin global <navigation-rule> <navigation-case> <from-outcome>globalhelp</from-outcome> <to-view-id>/menu/generalHelp.jsp</to-view-id> </navigation-case> </navigation-rule>
62 de 191
Framework Atlas
Normativa 6.2.3.4 Archivos de configuracin adicionales y web.xml JSFConfAdicional Si el tamao de los ficheros faces-managed-beans.xml o faces-navigation.xml creciese en exceso, se permite crear ficheros adicionales que agrupen los beans/reglas por funcionalidad. Dichos ficheros debern denominarse:
NORMA
faces-managed-beans-yyyy.xml faces-navigation-yyyy.xml
Donde yyyy puede ser cualquier trmino en minsculas que sea representativo de la funcionalidad que agrupan los ficheros. Adems, en el parmetro javax.config.CONFIG_FILES del archivo web.xml del proyecto deber aadirse referencias a los nuevos ficheros de configuracin.
El fichero de configuracin web.xml del arquetipo ya viene preconfigurado con todos los parmetros de configuracin de JSF. JSFwebxml La configuracin de JSF que se encuentra en el arquetipo dentro del fichero de configuracin web.xml no se puede modificar (excepto el parmetro javax.config.CONFIG_FILES si se incluyesen ficheros de configuracin adicionales). En el caso de que se desee modificar se debe solicitar la correspondiente autorizacin a ICM justificando dicha necesidad.
6.2.3.5
NORMA
mismo.
Anotaciones
Como se ha comentado previamente existe la posibilidad de declarar un managed bean mediante anotaciones. El efecto de declarar un bean con anotaciones o en el faces-managed-beans.xml es el
Para declarar un bean usaremos la anotacin @ManagedBean. La anotacin tiene un atributo name, pero si no se especifica el nombre por defecto del bean ser el de la clase con la primera letra minscula. Para especificar el mbito del bean se utilizar la anotacin @RequestScoped (@SessionScoped, @ApplicationScoped para otros mbitos).
63 de 191
Framework Atlas
Normativa Para inicializar propiedades del bean se utiliza la anotacin @ManagedProperty en la declaracin de la propiedad en el bean. La anotacin tiene la propiedad value, que puede tener un valor literal o bien referenciar otro objeto en el contexto. Las anotaciones anteriores estn en el paquete javax.faces.bean. A continuacin se muestra un ejemplo de anotaciones sobre la clase ClienteBean.
ClienteBean.java package ejpl.gestion.jsf; /** * Bean de cliente */ @ManagedBean @RequestScope public class ClienteBean { /** * Servicio de la fachada */ @ManagedProperty(value=#{facade}) private GestionFacade facade; /** * Bean para orden y filtro del listado */ @ManagedProperty(value=#{orderAndFilterCliente}) private OrderAndFilterBean orderAndFilter; }
64 de 191
Framework Atlas
Normativa 6.2.4 Uso de la Sesin
En el servidor de aplicaciones se crea un objeto sesin por cada usuario que se conecta, y se mantiene all durante un tiempo. Cuando una aplicacin tiene mucha concurrencia, esto puede ser un problema grave en un entorno de produccin debido a la cantidad de memoria ocupada por estas sesiones. La situacin se complica en un entorno de clster, en el que la informacin de sesin tiene que replicarse entre 2 o ms instancias del servidor de aplicaciones. JSFSesion El contenido de la sesin nunca debe exceder los 4 Kbytes de tamao
NORMA NORMA NORMA NORMA
Cuando sea necesario almacenar una cantidad de informacin importante (superior a 4Kbytes) durante un tiempo de vida superior a la peticin, siempre y cuando haya sido previamente autorizado por ICM, se implementar el mecanismo de persistencia en BBDD indicado por el framework Atlas. En cualquier caso se deben eliminar de la sesin los datos cuando ya no sean necesarios.
JSFHttpSession Se debe minimizar el uso del objeto HttpSession. En caso de que se necesite solamente se podr utilizar el objeto HttpSesion desde los managed beans.
JSFTiempoSesion El tiempo de vida de la sesin ser establecido a nivel del servidor de aplicaciones, nunca se definir a nivel de la aplicacin. Por tanto las aplicaciones no podrn depender de un valor concreto de dicho tiempo para su correcto funcionamiento.
JSFUsoSesion Cada vez que se acceda a un objeto de la sesin se debe comprobar previamente la existencia de dicho objeto y actuar en consecuencia, para prevenir errores ante una prdida de sesin.
65 de 191
Framework Atlas
Normativa JSFCreacionSesion
NORMA
La sesin ser creada automticamente por el framework por lo tanto las aplicaciones no pueden crearla, esto significa que no se puede obtener el objeto sesin de la siguiente forma: request.getSession(true).
JSFAtlasFacesUtils
PRACTICA
1
BUENA
Para obtener o establecer elementos en la sesin utilizar los mtodos creados para ellos en la clase atlas.componentes.utiles.AtlasFacesUtils. Tambin hay mtodos similares para el mbito request.
6.3
SERVICIOS DE NEGOCIO
Los servicios de negocio son aquellos que implementan la lgica que complementa las operaciones de acceso a datos para cubrir los requisitos de negocio de una aplicacin. La arquitectura de aplicaciones del framework Atlas busca simplificar la creacin e integracin de aplicaciones de negocio, por lo que est construida en base a una arquitectura orientada a servicios ( SOA). En una arquitectura SOA, los servicios de negocio no tienen porqu ser implementados como servicios web. El uso de servicios web debera limitarse a aquellos casos en los que realmente se vaya a sacar provecho a esta aproximacin. Como norma general, se expondrn como servicios web aquellos servicios con una funcionalidad de negocio que sea susceptible de ser reutilizada en otras aplicaciones, que ofrezcan una granularidad gruesa e interfaces bien definidos. En este tipo de servicios, los interfaces han de definir el intercambio de datos de negocio, no el intercambio de objetos. Para obtener mas informacin sobre los servicios web dentro del framework Atlas ir al apartado 8. SERVICIOS WEB. Para el resto de casos se emplearn servicios de negocio implementados como clases Java simples (POJOs) con una clara orientacin a servicio, haciendo uso de las funcionalidades que Spring ofrece.
Nivel de granularidad en la que el interfaz del servicio define relativamente pocos mtodos de servicio para conseguir un objetivo de negocio, mediante parmetros orientados a documento
66 de 191
Framework Atlas
Normativa De esta forma en un momento dado uno de estos servicios puede ser expuesto como servicio web para ser empleado por otras aplicaciones. Los beneficios de esta aproximacin son los siguientes: Simplificacin en el desarrollo de componentes de negocio. Simplificacin del ensamblaje y despliegue de soluciones de negocio construidas como redes de servicios. Aumento de la flexibilidad y agilidad. Proteccin de la inversin en tecnologa y lgica de negocio existente. Simplificacin de las pruebas.
Dentro de la capa de servicios vamos a identificar dos tipos de elementos: o o Fachada Servicios
La siguiente figura muestra un ejemplo de una parte de la capa de servicios del framework ATLAS:
class facade
interface GestionFacade + + + + + + + deleteCliente(Cliente) : void insertCliente(Cliente) : void insertOrUpdateCliente(Cliente) : void obtenerClientePorId(Integer) : Cliente obtenerClientes(int, int, Object, Object) : List<Cliente> obtenerTotalClientes(Object) : int updateCliente(Cliente) : void
serv ices::ClienteServ iceImpl + + + + + + + + + clienteDAO: ClienteDAO ClienteServiceImpl() deleteCliente(Cliente) : void insertCliente(Cliente) : void insertOrUpdateCliente(Cliente) : void obtenerClientePorId(Integer) : Cliente obtenerClientes(int, int, Object, Object) : List<Cliente> obtenerTotalClientes(Object) : int setClienteDAO(ClienteDAO) : void updateCliente(Cliente) : void
GestionFacadeImpl + + + + + + + + + clienteService: ClienteService deleteCliente(Cliente) : void GestionFacadeImpl() insertCliente(Cliente) : void insertOrUpdateCliente(Cliente) : void obtenerClientePorId(Integer) : Cliente obtenerClientes(int, int, Object, Object) : List<Cliente> obtenerTotalClientes(Object) : int setClienteService(ClienteService) : void updateCliente(Cliente) : void + -clienteService + + + + + + interface services::ClienteService deleteCliente(Cliente) : void insertCliente(Cliente) : void insertOrUpdateCliente(Cliente) : void obtenerClientePorId(Integer) : Cliente obtenerClientes(int, int, Object, Object) : List <Cliente> obtenerTotalClientes(Object) : int updateCliente(Cliente) : void
ATENCION Aunque en este ejemplo se muestra solamente un servicio lo normal es que la fachada acceda a varios servicios.
Los servicios se separarn en bloques funcionales para facilitar el mantenimiento posterior de la aplicacin. Cada bloque funcional estar formado por los objetos de dominio, los DAOs, los servicios y la fachada.
67 de 191
Framework Atlas
Normativa 6.3.1 FACHADA
En primer lugar nos encontramos con la fachada que ser el punto central de acceso a los servicios de negocio de un bloque funcional. Los componentes de la capa de presentacin invocarn por tanto a esta fachada. La fachada constituye el lugar idneo para poder gestionar de forma sencilla los aspectos transversales a la arquitectura, tales como las transacciones, la seguridad, la auditoria de acceso a informacin protegida y las trazas. SNFacade Dentro de una aplicacin en cada bloque funcional se ha de crear un servicio que haga de fachada al resto de servicios de negocio. Las responsabilidades de esta fachada son las siguientes:
2
NORMA
o o
Manejar las peticiones de la capa de presentacin. Recuperar los datos (en forma de objetos de dominio) que requiere la capa de presentacin.
o o
Usar inyeccin de dependencias para crear los servicios de negocio. Delegar la ejecucin a los servicios de negocio.
Cada bloque funcional deber tener una fachada y solo puede haber una fachada por cada bloque funcional.
De esta manera, para acceder a la lgica de negocio de la aplicacin se emplear siempre esta fachada. Esto reduce el nmero de objetos a usar desde el cliente y el acoplamiento con la capa de servicios de negocio, ya que un servicio puede ser reemplazado o modificado sin afectar a la capa de presentacin de la aplicacin. De forma general, la fachada delegar la ejecucin de los mtodos de negocio al correspondiente servicio de negocio (que sern los que gestionen entre otras cosas la transaccionalidad). Aunque no es lo recomendado, en ocasiones especiales se puede definir en la fachada algn mtodo de ms alto nivel que implique el uso de varios servicios de negocio.
El patrn de diseo Facade (fachada) sirve para proveer de una interfaz unificada sencilla que haga de intermediaria entre un cliente y una interfaz o grupo de interfaces ms complejas.
68 de 191
Framework Atlas
Normativa SNFacadeWS
PRACTICA
BUENA
En el caso de mdulos de tipo servicio web la fachada no tiene sentido. Los que se publican como servicios son los propios servicios de negocio. Si intervienen varios servicios de negocio se puede crear un servicio de alto nivel que contenga la lgica de negocio e invoque al resto de servicios.
SNFacadeImpl Para crear una fachada se crearn dos clases, con la siguiente nomenclatura:
NORMA
o o
<nombre>Facade (Interfaz de la fachada) <nombre>FacaceImpl (Implementacin de la interfaz)
Donde <nombre> debe ser sustituido por el nombre del bloque funcional al que pertenece la fachada. Estas clases se incluirn en el paquete services.facade del bloque funcional correspondiente.
class facade interface GestionFacade + + + + + + + deleteCliente(Cliente) : void insertCliente(Cliente) : void insertOrUpdateCliente(Cliente) : void obtenerClientePorId(Integer) : Cliente obtenerClientes(int, int, Object, Object) : List<Cliente> obtenerTotalClientes(Object) : int updateCliente(Cliente) : void
GestionFacadeImpl + + + + + + + + + clienteService: ClienteService deleteCliente(Cliente) : void GestionFacadeImpl() insertCliente(Cliente) : void insertOrUpdateCliente(Cliente) : void obtenerClientePorId(Integer) : Cliente obtenerClientes(int, int, Object, Object) : List<Cliente> obtenerTotalClientes(Object) : int setClienteService(ClienteService) : void updateCliente(Cliente) : void
Una de las implicaciones ms importantes al trabajar con JSF es que de alguna manera lo que se presenta al usuario dentro de un formulario es el propio objeto de dominio, generados por la capa de acceso de datos y obtenidos a travs de la fachada.
69 de 191
Framework Atlas
Normativa
SNDominio
NORMA
Los mtodos de la fachada utilizarn objetos de dominio (esto es, los que representan los datos de la aplicacin) cuando sea necesario. No es necesario crear clases adicionales (los viejos DTO, Data Transfer Objects) para enviar este tipo de datos.
A continuacin se muestra un ejemplo de interfaz e implementacin de una fachada.
Ejemplo de interfaz de una fachada package ejpl.gestion.services.facade; import java.util.List; import ejpl.gestion.domain.Cliente; import atlas.core.exceptions.ServiceException; /** * Esta interfaz representa las operaciones * de la facacha del sistema. * @author ICM * @version 1.0 * @since ATLAS 1.0.0 */ public interface GestionFacade { /** * Este metodo inserta un nuevo cliente en el sistema. * * @param cliente Cliente a insertar. * @throws atlas.core.exceptions.ServiceException * Lanza atlas.core.exceptions.ServiceException ante cualquier error producido. */ void insertCliente(Cliente cliente) throws ServiceException; /** * Este metodo obtiene un Cliente a partir de la PK. * * @param idCliente PK del cliente. * @throws atlas.core.exceptions.ServiceException * Lanza atlas.core.exceptions.ServiceException ante cualquier error * * @return <code>ejpl.gestion.domain.Cliente</code> que representa el Cliente encontrado o null en caso contrario. */ Cliente obtenerClientePorId(Integer idCliente) throws ServiceException;
70 de 191
Framework Atlas
Normativa Ejemplo de implementacin de una fachada package ejpl.gestion.services.facade; import import import import import java.util.List; atlas.core.exceptions.ServiceException; org.springframework.stereotype.Service; ejpl.gestion.domain.Cliente; ejpl.gestion.services.ClienteService;
/* Esta clase representa la fachada del sistema. * @author ICM * @version 1.0 */ @Service public class GestionFacadeImpl implements GestionFacade { /** * El Servicio de Clientes */ private ClienteService clienteService; /** * Constructor sin argumentos. */ public GestionFacadeImpl() { } /** * Este metodo inyecta el servicio ClienteService. * @param clienteService El servicio a inyectar. */ public void setClienteService(ClienteService clienteService) { this.clienteService = clienteService; } /** * {@inheritDoc} * @see ejpl.gestion.services.facade.GestionFacade#insertCliente(ejpl.gestion.domain.Cliente) */ public void insertCliente(Cliente cliente) throws ServiceException { clienteService.insertCliente(cliente); } /** * {@inheritDoc} * * @see ejpl.gestion.services.facade.GestionFacade#obtenerClientePorId(java.lang. * Integer) */ public Cliente obtenerClientePorId(Integer idCliente) throws ServiceException { return clienteService.obtenerClientePorId(idCliente); }
71 de 191
Framework Atlas
Normativa 6.3.2 SERVICIOS
Como ya se ha comentado anteriormente los servicios implementarn la lgica de negocio de la aplicacin. SNServiceImpl Para crear un servicio se crearn dos clases, con la siguiente nomenclatura:
NORMA
o o
<nombre>Service (Interfaz del servicio) <nombre>ServiceImpl (Implementacin del servicio)
Donde <nombre> debe ser sustituido por el nombre del servicio. Estas clases se incluirn en el paquete services del bloque funcional correspondiente.
class serv ices interface ClienteService + + + + + + + deleteCliente(Cliente) : void insertCliente(Cliente) : void insertOrUpdateCliente(Cliente) : void obtenerClientePorId(Integer) : Cliente obtenerClientes(int, int, Object, Object) : List <Cliente> obtenerTotalClientes(Object) : int updateCliente(Cliente) : void
ClienteServ iceImpl + + + + + + + + + clienteDAO: ClienteDAO ClienteServiceImpl() deleteCliente(Cliente) : void insertCliente(Cliente) : void insertOrUpdateCliente(Cliente) : void obtenerClientePorId(Integer) : Cliente obtenerClientes(int, int, Object, Object) : List<Cliente> obtenerTotalClientes(Object) : int setClienteDAO(ClienteDAO) : void updateCliente(Cliente) : void
NORMA
SNAnotacion Todos las implementaciones de los servicios debern ir precedidos de la anotacin @Service.
72 de 191
Framework Atlas
Normativa SNMVC La capa de negocio debe ser totalmente independiente de la capa de presentacin, es decir nunca
NORMA
se acceder de manera directa desde los servicios de negocio a informacin de otras capas (por ejemplo, a la sesin Http). Toda la informacin requerida por los mtodos de un servicio se le ha de pasar como parmetro. Hay que tener en cuenta que cualquier servicio de negocio puede ser transformado en un servicio web en un momento dado, y por tanto debe ser independiente.
Para facilitar la tarea de implementacin de las operaciones CRUD en los Servicios, se proporciona dentro del arquetipo una interfaz llamada BaseService y su correspondiente implementacin, con los mtodos bsicos ya implementados de tal forma que podemos crear nuestros servicios heredando de esta clase e implementando solo aquellos mtodos que sean especficos de nuestro servicio. A continuacin se muestra la interfaz BaseService:
package ejpl.services; import java.io.Serializable; import java.util.List; import java.util.Map; import org.hibernate.criterion.Criterion; import org.hibernate.criterion.Order; import atlas.core.exceptions.ServiceException; import ejpl.dao.BaseDAO; /** * Interfaz de servicio genrico con funcionalidad CRUD * * Extiende esta interfaz si se requiere servicios para los objetos de modelo sin * necesidad de realizar cast de conversin de datos. * * @param <T> el tipo de objeto que manejar este servicio. * @param <PK> la clave primaria del objeto de dominio. * @param <D> el dao que maneja el objeto. */ public interface BaseService <T, PK extends Serializable, D extends BaseDAO<T, PK>> { /** * Establece el valor del DAO * @param dao El DAO */ void setDao(D dao); /** * Devuelve el valor del DAO * @return el DAO */ D getDao(); /** * Mtodo genrico usado para obtener todos los objetos de un tipo * particular. Este mtodo es equivalente a obtener todas las filas * de una tabla. *
73 de 191
Framework Atlas
Normativa
* El nmero total de elementos que correspondera al mtodo * countAll() se puede obtener a travs del mtodo size() del objeto * de lista devuelto. * * @return Lista de los objetos recuperados de BD * @throws ServiceException Error en la invocacin */ List<T> findAll() throws ServiceException; /** * Mtodo genrico usado para obtener el total de objetos de un tipo * particular. * @return nmero de elementos totales en la tabla. * @throws ServiceException Error en la invocacin */ Long countAll() throws ServiceException; /** * Obtiene todos los registros sin duplicados. * Si se utiliza este mtodo, es imperativo que las clases de * modelo implementen correctamente los mtodos hashcode/equals. * * El nmero total de elementos que correspondera al mtodo * countAllDistinct() se puede obtener a travs del mtodo size() del * objeto de lista devuelto. * * @return Lista de los objetos recuperados de BD * @throws ServiceException Error en la invocacin */ List<T> findAllDistinct() throws ServiceException; /** * Obtiene en nmero total de registros sin duplicados. * @return nmero de elementos totales sin duplicados. * @throws ServiceException Error en la invocacin */ Long countAllDistinct() throws ServiceException; /** * Mtodo genrico para obtener un objeto basado en el tipo de clase * y su identificador nico. Si no se encuentra el objeto, este mtodo * devolver null. * * @param id el identificador (clave primaria) del registro a obtener * @return el objeto de base de datos recuperado * @throws ServiceException Error en la invocacin */ T find(PK id) throws ServiceException; /** * Mtodo para obtener una serie de elementos del sistema dados unos ordenes y filtros * @param index Indice de paginacion actual. * @param pageSize Tamao de pagina. * @param orders Criterios de ordenacion * @param filters Filtros de busqueda. * @return <code>java.util.List</code> La lista de objetos encontrados * @throws ServiceException Error en la invocacin */ List<T> find(int index, int pageSize, Order[] orders, Criterion[] filters) throws ServiceException; /** * Mtodo para obtener el numero de elementos dada una serie de filtros * @param filters Filtro de busqueda. * @return <code>int</code> con el numero total de objetos encontrados. * @throws ServiceException Error en la invocacin */ int count(Criterion[] filters) throws ServiceException; /** * Comprueba la existencia de un objeto en base a su clave primaria. * * @param id el identificador de la entidad * @return - true si el objeto existe, false en caso contrario * @throws ServiceException Error en la invocacin */
74 de 191
Framework Atlas
Normativa
boolean exists(PK id) throws ServiceException; /** * Mtodo genrico para grabar un objeto (maneja objetos nuevos y modificados). * Si el objeto es nuevo, este se devolver con la clave primaria generada para * su insercin en base de datos. * * @param object el objeto a guardar * @return el objeto persistente * @throws ServiceException Error en la invocacin */ T insert(T object) throws ServiceException; /** * Mtodo genrico para grabar un objeto (maneja objetos nuevos y modificados). * Si el objeto es nuevo, este se devolver con la clave primaria generada para * su insercin en base de datos. * * @param object el objeto a guardar * @throws ServiceException Error en la invocacin */ void insertOrUpdate(T object) throws ServiceException; /** * Mtodo genrico para grabar actualizar un objeto * * @param object el objeto a guardar * @throws ServiceException Error en la invocacin */ void update(T object) throws ServiceException; /** * Mtodo genrico para eliminar un objeto de la base de datos en base a su * clave primaria. * * @param id el identificador (clave primaria) del registro a obtener * @throws ServiceException Error en la invocacin */ void delete(PK id) throws ServiceException; /** * Mtodo genrico para eliminar un objeto de la base de datos * * @param object el objeto a eliminar * @throws ServiceException Error en la invocacin */ void delete(T object) throws ServiceException; /** * Encuentra una lista de registos usando una 'named query'. * * @param queryName nombre de la consulta a ejecutar * @param queryParams un objeto Map con los nombres de los parmetos y sus valores * @return una lista con los registros encontrados * @throws ServiceException Error en la invocacin */ List<T> findByNamedQuery(String queryName, Map<String, Object> queryParams) throws ServiceException; }
La implementacin de esta clase se puede ver en el paquete dao en la clase BaseServiceImpl.
ADBaseService
PRACTICA
BUENA
En el caso de que en el proyecto se identifiquen otros mtodos comunes a todos los Servicios estos mtodos se incorporaran en la interfaz BaseService y en su correspondiente implementacin.
75 de 191
Framework Atlas
Normativa La creacin de nuevos servicios se realizar utilizando los mecanismos de herencia sobre la clase BaseService. Dentro de los arquetipos se ha incluido un ejemplo de nuevo servicio que accede a la tabla de clientes: ClienteService. A continuacin se muestra un posible cdigo de ejemplo para las clases ClienteService y ClienteServiceImpl, que heredan de BaseService y no aaden funcionalidad a la clase padre (pero podran hacerlo): Ejemplo: ClienteService package ejpl.services; import ejpl.domain.Cliente; import ejpl.dao.ClienteDAO; /** * Interfaz para el Servicio de la clase de dominio Cliente * @see ejpl.Cliente * Fecha: 20-feb-2012 15:43:54 */ public interface ClienteService extends BaseService<Cliente, Integer, ClienteDAO> { }
Ejemplo: ClienteServiceImpl package ejpl.services; import import import import import ejpl.domain.Cliente; ejpl.dao.ClienteDAO; org.springframework.stereotype.Service; org.springframework.transaction.annotation.Propagation; org.springframework.transaction.annotation.Transactional;
/** * Implementacin del servicio para la clase de dominio Cliente * @see ejpl.Cliente * Fecha: 20-feb-2012 15:43:54 */ @Service @Transactional (readOnly = false, propagation = Propagation.REQUIRED) public class ClienteServiceImpl extends BaseServiceImpl<Cliente, Integer, ClienteDAO> implements ClienteService { }
Nota Los servicios se deben inyectar en el contexto de Spring en el fichero applicationContext-services.xml
76 de 191
Framework Atlas
Normativa 6.3.3 INYECCION DE DEPENDENCIAS
La fachada y los servicios se deben incluir en los ficheros de configuracin de Spring. Para homogeneizar los desarrollos se establece que los ficheros de configuracin de Spring se incluyan en la carpeta src/main/resources/conf.
NORMA NORMA
SNSpring Los ficheros de configuracin de Spring se incluirn en la carpeta src/main/resources/conf.
A continuacin se muestra un ejemplo de ficheros de configuracin tal y como los podemos encontrar dentro de alguno de los arquetipos.
En el arquetipo de mdulos de tipo librera en lugar de todos los ficheros anteriores solamente aparece un fichero de configuracin de Spring llamado applicationContext-yyyy.xml donde yyyy se corresponde con el nombre de la librera. Este fichero de contexto ir incluido dentro del jar de la librera y en las aplicaciones que utilicen esta librera, debern referenciarlo dentro del parmetro contextConfigLocation del fichero web.xml de las aplicaciones en las que se utilice la librera.
SNSpringLIB Cuando se desarrolle un mdulo de tipo librera se crear un fichero de contexto con la nomenclatura applicationContext-yyyy.xml donde yyyy se corresponde con el nombre del mdulo. Este fichero se situar en el directorio conf de la librera para que se incluya dentro del jar de esta librera. Este fichero ser el nico de esta librera que se referenciar en el parmetro contextConfigLocation del fichero web.xml de las aplicaciones en las que se utilice la librera.
77 de 191
Framework Atlas
Normativa SNDependencias El fichero de configuracin de Spring donde se definen los servicios y la fachada se debe llamar applicationContext-services.xml. En el caso de que este fichero se haga muy grande se podra
NORMA
dividir en varios ficheros con la nomenclatura applicationContext-services-yyyy.xml donde yyyy es un nombre que identifica a este fichero. No se permite instanciar objetos de fachadas o servicios directamente. Los mdulos de tipo librera en lugar de esta norma les aplica la norma SNSpringLIB.
Los servicios de Spring se pueden construir en base a 5 mbitos distintos de creacin segn las propiedades que se le deseen otorgar, dicho mbitos seran:
Ambito Singleton
Descripcin Solo se crear una instancia del servicio, la cual ser compartida por contenedor Spring. ste ser el mbito por defecto que adoptar Spring cuando no se especifique ningn otro.
Prototype
Este mbito resulta en la creacin de una nueva instancia del servicio cada vez que se realice una peticin sobre el mismo.
Request
El mbito del servicio es el mismo que el ciclo de vida de una peticin HttpRequest. Solo tiene sentido en aplicaciones web. (No se puede utilizar)
Session
El mbito del servicio es el mismo que el ciclo de vida de una sesin Http. Solo tiene sentido en aplicaciones web. (No se puede utilizar)
Global Session
El mbito del servicio es el mismo que el ciclo de vida de una sesin Http Global (mbito de aplicacin). Solo tiene sentido en aplicaciones web. (No se puede utilizar)
78 de 191
Framework Atlas
Normativa
SNAmbitos El mbito de creacin de los servicios en Spring debe ser Singleton, pudiendo crear servicios de
NORMA
mbito Prototype nica y exclusivamente en ciertos casos excepcionales, totalmente justificados y autorizados previamente por ICM. Completando lo anterior, los mbitos de creacin en Spring denominados request, session y global session no se pueden de utilizar bajo ninguna circunstancia.
A continuacin se muestra un ejemplo de fichero de configuracin de Spring de los servicios y la fachada: applicationContext-services.xml <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:p="http://www.springframework.org/schema/p" xmlns:context="http://www.springframework.org/schema/context" xmlns:tx="http://www.springframework.org/schema/tx" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd">  <!-Definicion de todos los servicios de la aplicacion -->  <bean id="facade" class="ejpl.gestion.services.facade.GestionFacadeImpl" p:clienteService-ref="clienteService"/>  <bean id="clienteService" class="ejpl.gestion.services.ClienteServiceImpl" p:clienteDAO-ref="clienteDAO"/> </beans> SNAgrupacion
PRACTICA
BUENA
Para mejor organizacin de los servicios dentro del fichero de contexto de Spring se recomienda organizarlos por bloques funcionales. De forma que por cada bloque funcional se incluya en el fichero de configuracin de Spring lo siguiente: o o o Comentario con el nombre del bloque funcional Definicin del bean de la fachada Definicin de los bean de los distintos servicios.
Esto facilitar tanto el desarrollo como el posterior mantenimiento de la aplicacin.
79 de 191
Framework Atlas
Normativa 6.3.4 MANEJO DE EXCEPCIONES
Uno de los problemas con el manejo de excepciones es saber cundo y cmo utilizarlas. En trminos generales, las aplicaciones desarrolladas con el framework Atlas tendrn que ser capaces de manejar dos tipos de excepciones: Excepciones de negocio: Sern aquellas excepciones creadas a medida por el desarrollador. Estas excepciones permiten representar aquellos errores inherentes al negocio. Sern lanzadas y gestionas por el propio programador, indicando as el incumplimiento de una regla del negocio. Excepciones del sistema: En este grupo se engloban todas aquellas excepciones producidas de forma automtica por el entorno. Sern excepciones propietarias del API, como por ejemplo, un fallo en la conexin a una base de datos, fallo de invocacin a un servicio web, etc. Dentro de Atlas para normalizar el uso de excepciones se ha creado la clase ServiceException. Con esta clase lo que se pretende es que todas las excepciones que se generen en la capa de negocio y se propaguen a la capa de presentacin sean de tipo ServiceException.
NORMA
SNThrowsException Todos los mtodos de los servicios y de la fachada slo pueden lanzar excepciones del tipo ServiceException o clases que hereden de ella.
Ejemplo de excepcin devuelta por un mtodo void deleteCliente(Cliente cliente) throws ServiceException;
Si en nuestra aplicacin queremos crear excepciones propias del negocio las podemos crear heredando de la clase ServiceExcepcion.
SNCustomException
NORMA
Cuando se desee implementar una excepcin propia del negocio, esto es a medida, se deber extender de la clase ServiceException. El nombre de la excepcin ser <nombre>ServiceException y se ubicar en el paquete exceptions del bloque funcional correspondiente.
Ejemplo de excepcin propia del negocio package ejpl.gestion.exceptions;
80 de 191
Framework Atlas
Normativa
public class InvalidAccountServiceException extends ServiceException { private static final long serialVersionUID = -3193946292701856020L; public InvalidAccountServiceException() { super(); } public InvalidAccountServiceException(String message) { super(message); } }
SNExcComunes
PRACTICA
BUENA
Las excepciones que puedan ser comunes a varios bloques funcionales se pueden ubicar en el paquete exceptions de un bloque funcional comn. Estas excepciones podrn ser utilizadas desde los otros bloques funcionales.
NORMA
SNNegocioException Cuando se lance una excepcin propia del negocio, se deber atrapar en el momento de producirse para encapsularla en otra de tipo ServiceException.
Ejemplo de relanzado de excepciones de negocio Public void reserveRoom(Integer customerId, String account, Date expDate) throws InvalidAccountServiceException, RoomAvailabilityServiceException if (customerManager.setReserve(customerId, account, expDate) .booleanValue()) { Room room = hotelManager.getFirstAvailableRoom(); if (room != null) { LOG.debug("getFirstAvailableRoom(): " + room.getRoomNumber()); Customer customer = customerManager.getCustomer(customerId); room.setReserveStatus(Room.OCUPPIED); room.setCustomer(customer); ..... } else { throw new RoomAvailabilityServiceException(); } } else { throw new InvalidAccountServiceException(); } } {
81 de 191
Framework Atlas
Normativa SNSystemException Cuando se lance una excepcin que no sea del negocio, se deber atrapar en el momento de producirse para encapsularla en otra de tipo ServiceException.
NORMA
Ejemplo de relanzado de excepciones de Sistema Public Boolean setReserve(Integer customerId, String sAccount, Date dExpiredDate) throws ServiceException { Boolean reserve = false; try { reserve = webService.checkAccount(customerId, sAccount, dExpiredDate); } catch (AxisFault axisex) { throw new ServiceException(axisex); } catch (JmsException jmsex) { throw new ServiceException(jmsex); } return reserve;
SNDAOException Los servicios que invoquen de forma directa a los componentes de la capa de acceso a datos (formada por Spring-DAOs), debern atrapar y gestionar las excepciones del tipo
NORMA
DataAccessException que se lancen, con objeto de encapsularlas y relanzarlas como excepciones de tipo ServiceException, ya sea a la fachada u otros servicios de ms alto nivel. La capa de acceso a datos no har ningn de tratamiento de las excepciones producidas, simplemente se limitar a lanzarlas a la capa de negocio para que sea esta la encargada de manejarlas.
Ejemplo de captura de excepciones de la capa de acceso a datos public void deleteCliente(Cliente cliente) throws ServiceException { try { this.clienteDAO.deleteCliente(cliente); } catch (DataAccessException dae) { throw new ServiceException(dae); } }
82 de 191
Framework Atlas
Normativa 6.3.5 TRANSACCIONALIDAD
Una de funcionalidades ms importantes aportadas por el framework Spring es la gestin de la transaccionalidad proporcionando una capa de abstraccin hacia el gestor transaccional utilizado, aportando los siguientes beneficios: Proporciona un modelo de programacin consistente entre diferentes APIs transaccionales tales como JTA, JDBC, Hibernate, JPA y JDO. Soporte a gestin declarativa de transaccin. Totalmente integrado con la abstraccin de acceso a datos de Spring. Proporciona un API para la gestin programtica de transacciones ms sencilla que las habituales. Permite gestin de transacciones mediante anotaciones aplicadas a cualquier clase, y no a clases especiales como EJBs. Ofrece reglas de rollback mediante anotaciones, de forma que se puede configurar el rollback automtico de una transaccin en caso de producirse cierto tipo de excepcin. Esta caracterstica no existe en el modelo de EJB. Spring permite adaptar el comportamiento de las transacciones, mediante AOP, por ejemplo para insertar un comportamiento personalizado en rollback de transacciones. A diferencia del modelo de EJB CMT, el cual esta ligado a JTA, la transaccin anotacional de Spring trabaja en cualquier entorno.
El modelo declarativo de Spring se basa en el soporte de proxies AOP y metadatos (XML o anotaciones solo soportadas por entornos J2SE 5 o superiores). Esta combinacin de proxies y metadatos permite tener proxies AOP que usan un TransactionInterceptor en conjuncin con el PlatformTransactionManager apropiado y gestionar las transacciones en la ejecucin de mtodos. El modelo transaccional de Spring se puede resumir en la siguiente figura:
83 de 191
Framework Atlas
Normativa El modelo que se deber seguir es el basado en anotaciones. En los servicios de Spring, se usar @Transaction la cual posee un conjunto de atributos que permitirn definir las reglas y polticas para aplicar sobre mtodos. En concreto, podremos tener uno o ms parmetros como los siguientes: 6.3.5.1 Propagation:
Es utilizado para especificar los lmites de una transaccin. Gracias a esta caracterstica tendremos bastantes opciones para especificar comportamiento si un mtodo transaccional es ejecutado cuando un contexto transaccional ya existe: Por ejemplo, podramos ejecutar algo en la transaccin en ejecucin; suspender la transaccin ejecucin y crear una nueva transaccin, etc. El catlogo de atributos transaccionales disponibles para Spring es: Propagation PROPAGATION_REQUIRED Descripcin Se ejecuta en la actual transaccin. Si no existe, se crea una nueva. PROPAGATION_REQUIRES_NEW Siempre se crear una transaccin nueva. Si existe una transaccin previa se suspende. PROPAGATION_SUPPORTS Si existe una transaccin se ejecuta en la misma transaccin. Si no existe una transaccin se ejecutar sin contexto transaccional. PROPAGATION_NOT_SUPPORTED Se ejecuta sin contexto transaccional. Si existe una transaccin se detiene. PROPAGATION_MANDATORY Se ejecuta en la actual transaccin. Si no existe una transaccin previa, se produce una excepcin. PROPAGATION_NEVER Se ejecuta sin contexto transaccional. Si existe una transaccin previa se produce una excepcin. PROPAGATION_NESTED Se ejecuta en una transaccin anidada si existe una transaccin previa. En caso contrario se comporta exactamente igual que REQUIRED. Se debe tener cuidado al utilizar este atributo transaccional, debido a q solo es soportado por algunos gestores de transacciones.
6.3.5.2
Isolation Level:
Con este atributo podremos indicar el control de concurrencia. Cuando mltiples transacciones se estn ejecutando en paralelo se pueden dar dirty reads, non repeateable reads y phantom reads.
84 de 191
Framework Atlas
Normativa El estndar ANSI/ISO SQL define cuatro niveles de aislamiento transaccional en funcin de tres hechos que deben ser tenidos en cuenta entre transacciones concurrentes. Estos hechos no deseados son: Dirty read (lecturas sucias): Una transaccin lee datos escritos por una transaccin no esperada y no cursada (no ha hecho todava el commit). Non-repeateable read (lecturas no repetibles): Una transaccin vuelve a leer datos que previamente haba ledo y encuentra que han sido modificados por una transaccin cursada. Phantom read (lectura fantasma): Una transaccin vuelve a ejecutar una consulta, devolviendo un conjuto de filas que satisfacen una condicin de bsqueda y encuentra que otras filas que satisfacen la condicin han sido insertadas por otra transaccin cursada. As, el framework Spring nos proporciona un conjunto de niveles de aislamiento que podremos usar en base a la tolerancia del sistema:
Isolation level ISOLATION_DEFAULT
Descripcin Usa la poltica de aislamiento por defecto del sistema persistente.
ISOLATION_READ_UNCOMMITTED
Permite leer datos incluso cuando existan filas sin commit, esto podra causar dirty read, non repeteable read o phantom reads.
ISOLATION_READ_COMMITTED
Previenen lecturas dirty pero todava se pueden dar lecturas non-repeateable o lecturas phantom.
ISOLATION_REPEATABLE_READ
Previene lecturas dirty y non-repeateable pero se pueden dar lecturas phantom.
ISOLATION_SERIALIZABLE
Este nivel consigue ACID (Atomicity, concurrancy, isolation and durability). Pero al ser tan estricto puede causar problemas de rendimiento.
6.3.5.3
Read Only:
En algunas ocasiones hay un requerimiento que es solo leer datos de la base de datos, en dichos casos utilizar este atributo puede proporcionar un buen rendimiento ya que la base de datos aplicar algunas optimizaciones. Esto solo puede ser hecho cuando una nueva transaccin es arrancada en operaciones de tipo select, as este atributo solo tomar sentido si la propiedad de propagacin es PROPAGATION_REQUIRED, PROPAGATION_REQUIRES_NEW, o PROPAGATION_NESTED.
85 de 191
Framework Atlas
Normativa 6.3.5.4 TimeOut:
Se utiliza para prevenir deadlocks o recursos bloqueados en el sistema. Permite especificar un timeout que matar la transaccin despus del periodo especificado. Al igual que en el caso anterior este atributo solo tomar sentido si la propiedad de propagacin es PROPAGATION_REQUIRED, PROPAGATION_REQUIRES_NEW, o PROPAGATION_NESTED. A continuacin se muestra un ejemplo que muestra como se deben implementar las transacciones mediante anotaciones. El servicio que se desea hacer transaccional: Ejemplo de servicio transaccional // La implementacin del servicio transaccional package ejpl.gestion.services; @Transactional(readOnly = true, propagation = Propagation.SUPPORTS) public class RoomServiceImpl implements RoomService { public Room getRoom(String roomName) { throw new ServiceException(); } public Room getRoom(String roomName, Integer idRoom) { throw new ServiceException(); } @Transactional(readOnly = false, propagation = Propagation.REQUIRED) public void insertRoom(Room room) { throw new ServiceException(); } @Transactional(readOnly = false) public void updateRoom(Room room) { throw new ServiceException(); } }
Segn el ejemplo anterior se puede definir atributos transaccionales a nivel de clase, de esta manera modelamos el comportamiento transaccional que por defecto tendr cada uno de los mtodos de la misma. A partir de ah, se podr sobrescribir dicho comportamiento transaccional por defecto, utilizando la anotacin @Transaction sobre el mtodo que se desee modificar. Los mtodos getRoom se ejecutarn en un contexto de solo lectura con soporte a transaccin, el mtodo insertRoom en un contexto de lecturaescritura con transaccin requerida y el mtodo updateRoom en un contexto de lectura-escritura con soporte a transaccin.
86 de 191
Framework Atlas
Normativa SNGenericTransaction
PRACTICA
BUENA
Si bien es cierto que el manejo de transacciones depender del negocio, en la mayora de los casos las transacciones se podrn configurar tal y como se han expuesto en el ejemplo anterior por lo que se recomienda utilizar esta configuracin por defecto a la hora de gestionar transacciones en los servicios de negocio.
La gestin de las transacciones siempre deber realizarse a nivel de la capa de servicios, nunca a nivel de la capa DAO. Se recomienda gestionar transacciones en la fachada por ser el punto de control de la capa de servicios. Desde un punto vista de la configuracin, lo primero que se debe hacer es indicar el gestor transaccional que se quiere utilizar, en el caso del framework Atlas lo configuramos para utilizar Hibernate como gestor transaccional. Esta configuracin ya viene preconfigurada en los arquetipos en el fichero applicationContext-database.xml y no se debe modificar. A continuacin se muestra como se ha configurado el gestor de transacciones en los arquetipos:
Configuracin del gestor de transacciones en applicationContext-database.xml  <bean id="transactionManager" class="org.springframework.orm.hibernate3.HibernateTransactionManager" p:sessionFactory-ref="sessionFactory" p:entityInterceptor-ref="atlasInterceptor"/>  <tx:annotation-driven transaction-manager="transactionManager"/>
NORMA NORMA
SNTransactionAnnotated Para el manejo de transacciones se emplear el modelo de anotaciones propuesto por Spring.
SNTransactionDefault No esta permitido modificar los atributos Isolation Level y TimeOut respecto a sus valores por defecto. En caso de tener que alterarlo solo se podr hacer previa autorizacin por parte de ICM.
87 de 191
Framework Atlas
Normativa La manera ms sencilla de indicar a Spring que una transaccin necesita hacer rollback ser lanzar una excepcin desde el cdigo que se est ejecutando dentro del contexto transaccional. Spring atrapar cualquier excepcin no manejada y marcar la transaccin para rollback.
SNTransactionRollback Se utilizar el mecanismo de rollback de transaccin basado en anotaciones. Esto se conseguir
NORMA
mediante la anotacin @Transaction y los atributos rollbackFor, rollbackForClassName, noRollbackFor, noRollbackForClassName. Esto solo tendr sentido para las excepciones de negocio gestionadas en la capa de servicios ya que las excepciones de tipo DataAccessException a nivel de DAO o RuntimeException se traducirn en un rollback automtico.
Por ejemplo, el cdigo necesario para realizar un rollback de una transaccin cuando se lance una excepcin de negocio de tipo NotRoomFoundServiceException podra ser algo como:
Ejemplo de definicin de rollback @Transactional(readOnly = false, propagation = Propagation.REQUIRED, rollbackForClassName = {"NotRoomFoundServiceException"})
Atencin Si desde un mtodo de un Servicio se invoca a otro mtodo del mismo Servicio el contexto transaccional ser el de la anotacin transaccional del primero, y la anotacin transaccional del segundo mtodo ser ignorada. Por lo tanto la invocacin del segundo mtodo siempre participar en la transaccin del primero, y en ningn caso se crear una nueva transaccin aunque se le indique mediante una anotacin. . FICHEROS TEMPORALES
6.3.6
En algunas aplicaciones es necesario generar ficheros temporales en un directorio del entorno. Actualmente todos los entornos ya tienen preparados estos directorios y estn compartidos por NFS entre las distintas mquinas del cluster. Las aplicaciones podrn acceder a estos directorios para dejar y eliminar ficheros pero no podrn crear carpetas dentro de estos directorios. Existen jobs peridicos que se encargan de limpiar estos directorios, para eliminar los ficheros temporales obsoletos. La ruta de los directorios temporales en los entornos de ICM est configurada utilizando la propiedad del sistema java.io.tmpdir. El framework Atlas ya establece el valor para esta propiedad dependiendo del
88 de 191
Framework Atlas
Normativa entorno en el que nos encontremos (no es responsabilidad de la aplicacin). En entornos locales (la mquina local del desarrollador) la ruta ser la que est establecida por defecto en el sistema operativo. A continuacin se muestran dos ejemplos de creacin de ficheros temporales:
Creacin de un fichero temporal a partir de un byte[] public File guardarFicheroTemporal(byte[] b) throws ServiceException { File temp = null; try { temp = File.createTempFile("EJPL_", ".txt"); temp.deleteOnExit(); //Eliminar fichero al finalizar la ejecucin de la JVM. if (b != null) { FileOutputStream fout = new FileOutputStream(temp); fout.write(b); fout.flush(); fout.close(); } logger.info("--- Nombre fichero: " + temp.getName()); } catch (IOException e) { logger.error("Error al crear el fichero"); throw new ServiceException(e); } return temp; }
Creacin de un fichero temporal rellenando su contenido //crear fichero en el directorio temporal try { //Creacion de fichero temporal // mas info: http://download.oracle.com/javase/1,5.0/docs/api/java/io/File.html#createTempFile(java.lang.String,%20java.lang.String) File temp = File.createTempFile("EJPL_", ".txt"); temp.deleteOnExit(); //Eliminar fichero al finalizar la ejecucin de la JVM. FileOutputStream fout = new FileOutputStream(temp); PrintStream out = new PrintStream(fout); out.println("Ejemplo fichero en el directorio temporal."); //Escribimos dentro del fichero logger.info("--- Nombre fichero: " + temp.getName()); } catch (IOException e) { logger.error("Error al crear el fichero"); throw new ServiceException(e); }
89 de 191
Framework Atlas
Normativa SNFicherosTemporales Si se necesita crear un fichero temporal, se utilizarn los mtodos que proporciona la clase java.io.File para ello (File.createTempFile). Al utilizar estos mtodos, los ficheros temporales se crearn en el directorio definido por la propiedad del sistema java.io.tmpdir. El valor de esta propiedad ya est preestablecido en el framework Atlas dependiendo del entorno en el que se encuentre desplegada la aplicacin, por lo que no se debe modificar su valor desde el cdigo fuente de ninguna aplicacin.
NORMA
SNNomFicheroTemporal
PRACTICA
BUENA
En aquellos casos en los que los ficheros se generan en cada peticin es necesario crear un nombre aleatorio para el nombre del fichero para evitar que una peticin sobreescriba el fichero generado por otra. Dado que el directorio temporal es compartido por todas las aplicaciones se recomienda que el nombre del fichero comience por el nombre del proyecto. Ejemplo; EJPL_<nombrealeatorio>.
6.4
ACCESO A DATOS
El acceso a datos es una de las partes con mayor ndice de criticidad que pueda existir en cualquier aplicacin web. Para el acceso a los distintos sistemas relacionales la tecnologa seleccionada es Hibernate. A continuacin se muestra un diagrama general de la capa de acceso a datos desde el punto de vista de arquitectura del sistema.
POJO Services POJOs
Capa de Acceso a Datos Capa de Acceso a Datos

SPRING
Fachada
POJO Services POJOs
HibernateDaoSupport
SPRING SPRING
SPRING
Hibernate Template
SPRING
HIBERNATE
HibernateDaoSupport DAO Hibernate
BD
HIBERNATE
(Oracle, etc)
Hibernate Template
Arquitectura de la capa de Acceso a Datos
90 de 191
Framework Atlas
Normativa Para el acceso a la informacin se utilizar la solucin ORM (Object-Relational Mapping) de Hibernate, la cual se erige como un potente mapeador objeto/relacional y servicio de consultas para Java. Hibernate permite desarrollar clases persistentes a partir de clases comunes, incluyendo asociacin, herencia, polimorfismo, composicin y colecciones de objetos. El lenguaje de consultas de Hibernate HQL (Hibernate Query Language), diseado como una mnima extensin orientada a objetos de SQL, proporciona un puente elegante entre los mundos de objetos y relacional. Hibernate tambin permite expresar consultas utilizando SQL nativo o consultas basadas en criterios. Soporta todos los sistemas gestores de bases de datos SQL y se integra de manera sencilla y sin restricciones con prcticamente la totalidad de servidores de aplicaciones JEE y contenedores web, adems de poder utilizarse en aplicaciones standalone. Se pueden enumerar las siguientes caractersticas clave: o o o o o o o Persistencia transparente: Hibernate puede operar proporcionando persistencia de una manera transparente para el desarrollador. Modelo de programacin natural: Hibernate soporta el paradigma de orientacin a objetos de una manera natural: herencia, polimorfismo, composicin y el framework de colecciones de Java. Soporte para modelos de objetos con una granularidad muy fina: Permite una gran variedad de mapeos para colecciones y objetos dependientes. Sin necesidad de mejorar el cdigo compilado (bytecode): No es necesaria la generacin de cdigo ni el procesamiento del bytecode en el proceso de compilacin. Escalabilidad extrema: Hibernate posee un alto rendimiento, tiene una cach de dos niveles y puede ser usado en un cluster. Permite inicializacin perezosa (lazy) de objetos y colecciones. Lenguaje de consultas HQL: Este lenguaje proporciona una independencia del SQL de cada base de datos, tanto para el almacenamiento de objetos como para su recuperacin. Soporte para transacciones de aplicacin: Hibernate soporta transacciones largas (aquellas que requieren la interaccin con el usuario durante su ejecucin) y gestiona la poltica optimistic locking automticamente. o Generacin automtica de claves primarias: Soporta los diversos tipos de generacin de identificadores que proporcionan los sistemas gestores de bases de datos (secuencias, columnas autoincrementales,...) as como generacin independiente de la base de datos, incluyendo identificadores asignados por la aplicacin o claves compuestas.
91 de 191
Framework Atlas
Normativa ADHibernate La gestin de persistencia sobre los datos almacenados en bases de datos relacionales se realizar utilizando el motor de persistencia Hibernate. El mecanismo elegido para realizar el mapeo de clases java a tablas de la base de datos ser el
NORMA
basado en anotaciones, dichas anotaciones proporcionarn a Hibernate la informacin suficiente para saber cmo cargar y almacenar clases persistentes y se marcarn a nivel de atributo. Se debern utilizar aquellas anotaciones proporcionadas por Hibernate y que formen parte del estndar JPA. En ocasiones es posible que sea necesario utilizar anotaciones propias de Hibernate no correspondientes al estndar JPA. Slo se podrn utilizar si se ha consensuado previamente con ICM y se ha otorgado una autorizacin excepcional para ello.
92 de 191
Framework Atlas
Normativa 6.4.1 Datasource y Sesiones de Hibernate
Todas las aplicaciones definirn un datasource para conectarse con la base de datos. DAODatasource
NORMA NORMA NORMA
En los arquetipos ya viene configurado el datasource de acceso a base de datos. Deber utilizarse dicho datasource y nunca obtener directamente las conexiones jdbc.
El acceso al datasource siempre se realizar a travs de la sesin de Hibernate. La sesin en Hibernate representa la interfaz entre la aplicacin Java e Hibernate. Dicha sesin permitir realizar operaciones de creacin, modificacin, lectura y eliminacin de instaciones mapeadas con la base de datos. Histricamente, la gestin de sesiones en Hibernate se ha considerado uno de los problemas ms comunes que se encuentran en aplicaciones Web, para evitar esto han surgido un conjunto de buenas prcticas y/o patrones que nos indican como trabajar de forma optima, en base al entorno de trabajo establecido. De tal forma para entornos Web el modelo recomendado siempre ser el patrn session-perview (Sesin por vista). En una sesin por vista, la sesin de Hibernate se mantiene abierta mientras dura el ciclo de vida de una peticin Http.
DAOSession En las aplicaciones Web se deber utilizar el patrn session-per-view, para ello Spring proporciona un filtro que se encargar de tratar toda la problemtica asociada a la gestin de sesiones Hibernate en cada peticin. Este filtro ya se encuentra definido en el fichero web.xml y no se puede modificar.
DAOFlushing Se deber usar el mecanismo de flushing por defecto en Hibernate sobre las sesiones, esto es el denominado FlushMode.AUTO. Este valor por defecto debern ser vlidos para cualquier entorno. Solo se podr optar por otra estrategia, previo consenso con ICM. Se deber usar el mecanismo de fetching por defecto en Hibernate, este es lazy select fetching para colecciones y lazy proxy fetching para asociaciones single-valued. Estos valores por defecto debern ser vlidos para cualquier entorno. Solo se podr optar por otra estrategia, previo consenso con ICM.
93 de 191
Framework Atlas
Normativa 6.4.2 Configuracin
A continuacin se muestran los distintos ficheros donde se encuentra la configuracin de la capa de acceso a datos.
6.4.2.1
enviroment.properties
El fichero enviroment.properties contiene las variables que dependen del entorno por lo tanto aqu es donde se tiene que configurar el datasource. A continuacin se muestra la configuracin del datasource que viene configurada en los arquetipos.
environment.properties ###################################################### # Fichero de variables de configuracin especficas # # para el entorno LOCAL # ###################################################### # Configuracion para acceso a base de datos dataSourceName=${artifactId}-webDS jdbc.driverClassName=oracle.jdbc.OracleDriver jdbc.url=jdbc:oracle:thin:@icm21.icm.es:1521:denivel2 jdbc.username=dba_ejpl jdbc.password=sis hibernate.dialect=org.hibernate.dialect.Oracle9iDialect
Nota Para ms informacin sobre el fichero de configuracin environment.properties consultar el manual de arquetipos. 6.4.2.2 applicationContext-database.xml
El fichero applicationContext-database.xml que incorpora el arquetipo contiene la configuracin de todos los parmetros de conexin a base de datos, incluyendo el sessionFactory y el transactionManager. En este fichero solamente se puede modificar la propiedad packagesToScan para incorporar los paquetes donde residen las distintas clases de dominio que sea necesario crear (solo es necesario incluir los paquetes raz, los subpaquetes sern escaneados automticamente). applicationContext-database.xml <?xml version="1.0" encoding="UTF-8"?>  <!-En este fichero se configuran todos los --> <!-parametros de conexion a la base de datos --> <!-incluyendo el sessionFactory y el transactionManager -->  <beans xmlns="http://www.springframework.org/schema/beans"
94 de 191
Framework Atlas
Normativa xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:p="http://www.springframework.org/schema/p" xmlns:context="http://www.springframework.org/schema/context" xmlns:tx="http://www.springframework.org/schema/tx" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd">    <bean id="dataSource" class="org.springframework.jndi.JndiObjectFactoryBean"> <property name="jndiName" value="jdbc/${dataSourceName}" /> </bean>  <bean id="sessionFactory" class="org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean"> <description> Bean que representa a la factoria de hibernate para crear sesiones con base de datos </description>  <property name="schemaUpdate" value="false"/> <property name="packagesToScan"> <list>  <value>ejpl.bloquefuncionaln.domain</value>  <value>atlas.componentes.domain</value> </list> </property> <property name="hibernateProperties"> <props> <prop key="hibernate.dialect">${hibernate.dialect}</prop> <prop key="hibernate.show_sql">false</prop> <prop key="hibernate.format_sql">false</prop> <prop key="hibernate.use_sql_comments">false</prop>  <prop key="hibernate.cache.use_second_level_cache">false</prop> 
95 de 191
Framework Atlas
Normativa </props> </property> <property name="dataSource" ref="dataSource" /> </bean>  <bean id="transactionManager" class="org.springframework.orm.hibernate3.HibernateTransactionManager" p:sessionFactory-ref="sessionFactory" p:entityInterceptorref="atlasInterceptor"/>  <tx:annotation-driven transaction-manager="transactionManager"/>  <bean id="jdbcExceptionTranslator" class="org.springframework.jdbc.support.SQLErrorCodeSQLExceptionTranslator"> <description> Bean que representa al traductor de codigos de error SQL a excepciones JAVA </description> <property name="dataSource" ref="dataSource" /> </bean>  <bean id="hibernateTemplate" class="org.springframework.orm.hibernate3.HibernateTemplate"> <description> Bean que representa la plantilla de hibernate. A este bean se le inyectan la factoria de sesiones y el traductor de sesiones JDBC </description> <property name="sessionFactory" ref="sessionFactory" /> <property name="jdbcExceptionTranslator" ref="jdbcExceptionTranslator" /> </bean>   </beans> 6.4.2.3 applicationContext-dao.xml
El fichero applicationContext-dao.xml contiene la definicin de los bean de los distintos DAOs en el contexto de Spring.
applicationContext-dao.xml <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:p="http://www.springframework.org/schema/p" xmlns:context="http://www.springframework.org/schema/context" xmlns:tx="http://www.springframework.org/schema/tx"
96 de 191
Framework Atlas
Normativa xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd">  <!-Definicion de todos los DAO`s de la aplicacion -->  <bean id="clienteDAO" class="ejpl.gestion.dao.ClienteDAOImpl" p:sessionFactory-ref="sessionFactory"/> </beans> El mbito de creacin de los DAOs ser siempre el que adopta Spring por defecto, es decir Singleton. (por defecto si no se indica en el fichero de configuracin)
DAODependencias El fichero de configuracin de Spring donde se definen los daos se debe llamar applicationContext-dao.xml. En el caso de que este fichero se haga muy grande se podra
NORMA
dividir en varios ficheros con la nomenclatura applicationContext-dao-yyyy.xml donde yyyy es un nombre que identifica a este fichero. No se permite instanciar objetos de daos directamente. Los mdulos de tipo librera en lugar de esta norma les aplica la norma SNSpringLIB.
97 de 191
Framework Atlas
Normativa 6.4.3 Entidades de dominio
Las entidades de dominio son las clases Java que tienen una correspondencia con tablas del modelo de datos relacional. ADEntityImpl Las clases de dominio se incluirn en el paquete domain del bloque funcional correspondiente. No tendrn una nomenclatura especfica ya que su nombre debe representar al objeto de dominio que implemente. Las clases de dominio deben: o Incluir la anotacin @Entity Implementar la interface Serializable. Incluir atributos privados y sus correspondientes setter y getter Incluir un constructor sin argumentos Implementar los mtodos equals y hashcode para las entidades persistentes, ya que dichos mtodos se harn indispensables en casos como: o o o Se necesitan almacenar instancias en un conjunto (Asociaciones 1-n). Se quieren utilizar las instancias como keys para un map. Se quieren usar mtodos de colecciones como contains(), remove(), etc
NORMA
o o o o
ADRendimiento
PRACTICA
. BUENA
Hibernate puede ser una herramienta muy potente pero a su vez su utilizacin sin tener en cuenta la forma en la que trabaja Hibernate puede provocar problemas de rendimiento. Se debe evitar que el acceso a determinados datos suponga la carga en memoria de estructuras complejas o de demasiada informacin que en la mayora de los casos no se va a necesitar.
A continuacin se muestra un fragmento de la clase denominada Cliente, la cual representa una entidad persistente gestionada por el motor de Hibernate:
Cliente.java package ejpl.gestion.domain; import java.util.Date; import javax.persistence.Column; import javax.persistence.Entity;
98 de 191
Framework Atlas
Normativa import import import import import import import import import javax.persistence.GenerationType; javax.persistence.Id; javax.persistence.JoinColumn; javax.persistence.ManyToOne; javax.persistence.SequenceGenerator; javax.persistence.Table; javax.persistence.Temporal; javax.persistence.TemporalType; javax.persistence.GeneratedValue;
import org.apache.commons.lang.builder.EqualsBuilder; import org.apache.commons.lang.builder.HashCodeBuilder; /** * Cliente * @author ICM * @version 1.0. */ @Entity @Table(name = "EJPL_CLIENTES") public class Cliente implements java.io.Serializable { /** * Identificador del numero de serie para serializacion */ private static final long serialVersionUID = 1L; /** * Representa el identificador/PK del cliente. */ private Integer idCliente; /** * Representa el nombre del cliente. */ private String nombre; /** * Representa el primer apellido del cliente. */ private String apellido1; /** * Representa el segundo apellido del cliente. */ private String apellido2; /** * Representa la direccion del cliente. */ private String direccion; /** * Representa el telefono del cliente. */ private String telefono; /** * Representa la fecha de nacimiento del cliente.
99 de 191
Framework Atlas
Normativa */ private Date fechaNacimiento; /** * Representa el estado civil del cliente. */ private EstadoCivil estadoCivil; /** * Constructor sin argumentos. */ public Cliente() { } /** * Constructor para la entidad Cliente con los parametros minimos. * @param idCliente Identificador * @param nombre Nombre * @param apellido1 Primer Apellido * @param apellido2 Segundo Apelillido */ public Cliente(Integer idCliente, String nombre, String apellido1, String apellido2) { this.idCliente = idCliente; this.nombre = nombre; this.apellido1 = apellido1; this.apellido2 = apellido2; } /** * Constructor para la entidad Cliente con los todos parametros posibles. * @param idCliente Identificador * @param nombre Nombre * @param apellido1 Primer Apellido * @param apellido2 Segundo Apelillido * @param direccion Direccion * @param telefono Telefono * @param fechaNacimiento Fecha de Nacimiento * @param estadoCivil Estado Civil */ public Cliente(Integer idCliente, String nombre, String apellido1, String apellido2, String direccion, String telefono, Date fechaNacimiento, EstadoCivil estadoCivil) { this.idCliente = idCliente; this.nombre = nombre; this.apellido1 = apellido1; this.apellido2 = apellido2; this.direccion = direccion; this.telefono = telefono; this.fechaNacimiento = fechaNacimiento; this.estadoCivil = estadoCivil; } /** * @return <code>java.lang.Integer</code> Devuelve el identificador/PK de la entidad Cliente. */ @Id @GeneratedValue(strategy = GenerationType.AUTO, generator = "EJPL_SECUENCIA_ID_CLIENTE") @SequenceGenerator(name = "EJPL_SECUENCIA_ID_CLIENTE", sequenceName = "EJPL_SECUENCIA_ID_CLIENTE")
100 de 191
Framework Atlas
Normativa @Column(name = "ID_CLIENTE", unique = true, nullable = false, precision = 9, scale = 0) public Integer getIdCliente() { return this.idCliente; } /** * @param idCliente Modifica el identificador/PK del cliente. */ public void setIdCliente(Integer idCliente) { this.idCliente = idCliente; } /** * @return <code>java.lang.String</code> Devuelve el nombre del cliente. */ @Column(name = "NOMBRE", nullable = false, length = 50) public String getNombre() { return this.nombre; } /** * @param nombre Modifica el nombre del cliente. */ public void setNombre(String nombre) { this.nombre = nombre; } /** * @return <code>java.lang.String</code> Devuelve el primer apellido del cliente. */ @Column(name = "APELLIDO1", nullable = false, length = 50) public String getApellido1() { return this.apellido1; } /** * @param apellido1 Modifica el primer apellido del cliente. */ public void setApellido1(String apellido1) { this.apellido1 = apellido1; } /** * @return <code>java.lang.String</code> Devuelve el segundo apellido del cliente. */ @Column(name = "APELLIDO2", nullable = false, length = 50) public String getApellido2() { return this.apellido2; } /** * @param apellido2 Modifica el segundo apellido del cliente. */ public void setApellido2(String apellido2) { this.apellido2 = apellido2; } /**
101 de 191
Framework Atlas
Normativa * @return <code>java.lang.String</code> Devuelve la direccion del cliente. */ @Column(name = "DIRECCION", length = 100) public String getDireccion() { return this.direccion; } /** * @param direccion Modifica la direccion del cliente. */ public void setDireccion(String direccion) { this.direccion = direccion; } /** * @return <code>java.lang.String</code> Devuelve el telefono del cliente. */ @Column(name = "TELEFONO", length = 15) public String getTelefono() { return this.telefono; } /** * @param telefono Modifica el telefono del cliente. */ public void setTelefono(String telefono) { this.telefono = telefono; } /** * @return <code>java.lang.String</code> Devuelve el estado civil del cliente. */ @ManyToOne @JoinColumn(name = "FK_ESTADO_CIVIL") public EstadoCivil getEstadoCivil() { return this.estadoCivil; } /** * @param estadoCivil Modifica el estado civil del cliente. */ public void setEstadoCivil(EstadoCivil estadoCivil) { this.estadoCivil = estadoCivil; } /** * @return <code>java.util.Date</code> Devuelve la fecha de nacimiento del cliente. */ @Temporal(TemporalType.DATE) @Column(name = "FC_NACIMIENTO", length = 7) public Date getFechaNacimiento() { return this.fechaNacimiento; } /** * @param fechaNacimiento Modifica la fecha de nacimiento del cliente. */ public void setFechaNacimiento(Date fechaNacimiento) {
102 de 191
Framework Atlas
Normativa this.fechaNacimiento = fechaNacimiento; } /** * Implementacin de hashCode para uso de Hibernate. La 'business key' en * este caso se compondr por [nombre, apellido1, apellido2 y * fechaNacimiento]. * * Ms info en: {@link http://community.jboss.org/docs/DOC-13933} */ @Override public int hashCode() { return new HashCodeBuilder() .append(this.nombre) .append(this.apellido1) .append(this.apellido2) .append(this.fechaNacimiento) .toHashCode(); } /** * Implementacin de mtodo equals para uso con Hibernate. Se ha definido * la clave de negocio o 'business key' como * [nombre, apellido1, apellido2, fechaNacimiento] * * Ms info en: {@link http://community.jboss.org/docs/DOC-13933} * * @param obj objeto a comparar con esta instancia. * @return true si el objeto pasado es igual a este; * false en caso contrario */ @Override public boolean equals(Object obj) { // Si el objeto a comparar es nulo o no pertenece a la // misma clase, la igualdad no se cumple if (obj == null || obj.getClass() != getClass()) { return false; } // si el objeto pasado es este objeto, la igualdad se cumple if (obj == this) { return true; } // comparacin en base a la 'business key' Cliente rhs = (Cliente) obj; return new EqualsBuilder() .append(this.nombre, rhs.nombre) .append(this.apellido1, rhs.apellido1) .append(this.apellido2, rhs.apellido2) .append(this.fechaNacimiento, rhs.fechaNacimiento) .isEquals(); } /** * Implementacin de toString() pare este objeto de modelo. * Se ha utilizado la clase StringBuilder como base de implementacin. * * NOTA: Hay que tener mucho cuidado con volcar en este mtodo * relaciones con otros objetos (EstadoCivil en este caso)
103 de 191
Framework Atlas
Normativa * porque una linea de log puede provocar la carga de muchos * objetos de base de datos, dependiendo del grado de * enlazamiento entre los objetos de dominio. */ @Override public String toString() { StringBuilder builder = new StringBuilder(); builder.append("Cliente [idCliente=").append(idCliente) .append(", nombre=").append(nombre) .append(", apellido1=").append(apellido1) .append(", apellido2=").append(apellido2) .append(", direccion=").append(direccion) .append(", fechaNacimiento=").append(fechaNacimiento) .append(", telefono=").append(telefono) .append(", estadoCivil=").append(estadoCivil) // relacin 1-1 .append("]"); return builder.toString(); } }
PRACTICA
ADEqualsHashcode La implementacin de equals y hashcode se debe realizar utilizando EqualsBuilder y HashCodeBuilder tal y como se puede ver en el ejemplo de la clase cliente.
. BUENA
Es recomendable que el ndice de granularidad de las entidades persistentes sea el adecuado, intentando representar de forma estricta las entidades de negocio. 6.4.3.1 Mapeo relacional
Las clases de dominio se mapearn mediante las correspondientes anotaciones de Hibernate. A continuacin se muestra una tabla con algunas de las anotaciones de Hibernate ms utilizadas. Aunque aqu solamente se muestran las ms utilizadas se podrn utilizar todas las anotaciones proporcionadas por Hibernate que cumplen con el estndar JPA.
@Table @Id @GeneratedValue @SequenceGenerator
Indica la tabla con la que se va a mapear Indica que este campo es identificador de la tabla Indica que este campo va a ser generado automticamente Indica la secuencia a utilizar para este campo
104 de 191
Framework Atlas
Normativa @Column Indica el campo con el que se va a mapear este atributo
NORMA
ADMapeoTabla Cada clase de dominio ser mapeada a una tabla de la base de datos, esto se har con la anotacin @Table.
Ejemplo de mapeo a tabla @Entity @Table(name = "EJPL_CLIENTES") public class Cliente implements java.io.Serializable {
Nota No hay que olvidarse de que cada clase de domino anotada se debe incluir en el fichero de configuracin applicationContext-database.xml.
ADIdentificador Todas las entidades persistentes debern tener un atributo a modo de identificador nico que permita distinguir un objeto de otro de forma unvoca. Este atributo ser de tipo Integer y estar obligatoriamente generado por una secuencia.
NORMA
En el caso de que el modelo de datos ya exista en produccin y no sea posible cumplir esta norma se utilizar la anotacin @ AtlasLegacy en la clase de dominio. Este atributo se anotar con la anotacin @Id. Al margen de este atributo se podrn crear otros identificadores nicos propios de la gestin funcional de la tabla que no sern anotados con @Id.
Ejemplo de campo Id @Id @GeneratedValue(strategy = GenerationType.AUTO, generator = "EJPL_SECUENCIA_ID_CLIENTE") @SequenceGenerator(name = "EJPL_SECUENCIA_ID_CLIENTE", sequenceName = "EJPL_SECUENCIA_ID_CLIENTE") @Column(name = "ID_CLIENTE", unique = true, nullable = false, precision = 9, scale = 0) public Integer getIdCliente() { return this.idCliente; }
105 de 191
Framework Atlas
Normativa ADRelaciones
NORMA NORMA
6.4.3.2
No se permite el uso de relaciones muchos-a-muchos. Se debern sustituir, siempre que sea posible, por relaciones uno-a-muchos y/o muchos-a-uno. En caso de no poder hacer dicha sustitucin, se deber consultar a ICM el uso de la posible relacin muchos-a-muchos.
ADDinamicos No se permite el uso de modelos dinmicos de Hibernate como sustitutivo de las entidades POJOs de persistencia.
Tipos de datos BLOB y CLOB (LOB)
Los tipos de datos BLOB y CLOB hacen referencia a aquellos elementos utilizados en una bases de datos para almacenar entidades de gran tamao que puedan cambiar de forma dinmica, estando los primeros enfocados a datos binarios (por ejemplo una imagen) y los segundos a datos de tipo carcter (por ejemplo un prrafo de texto con un tamao considerable).
NORMA
ADLobAnot Los atributos de tipo Lob se anotarn con la anotacin @Lob y se le indicar que se traiga bajo demanda con la anotacin @Basic(fetch=FetchType.LAZY)
Ejemplo de definicin de campo LOB /** * * @return Devuelve el contenido del ficherote un campo LOB */ @Lob @Column(name = "CONTENIDO") @Basic(fetch=FetchType.LAZY) public Blob getContenido() { return contenido; }
106 de 191
Framework Atlas
Normativa 6.4.4 Data Access Objects
En una arquitectura Java Enterprise Edition (JEE) es fundamental contar con un elemento propio de acceso a datos que permita a las aplicaciones obtener y manipular los datos de la organizacin de una manera estandarizada y ptima que ofrezca a los desarrolladores una interfaz sencilla y homognea que facilite los desarrollos aumentando la productividad y mejorando los tiempos de mantenimiento, a la vez que ofrezca unas elevadas prestaciones de rendimiento en tiempo de ejecucin. El patrn DAO es uno de los patrones de diseo estndar de JEE. DAO permite encapsular el acceso y manipulacin de datos en una capa separada. Esta capa gestiona la conexin con la fuente de datos (bases de datos relacionales, ficheros planos, sistema de ficheros remotos, etc.) para obtener y almacenar dichos datos, ya que implementa el mecanismo de acceso necesario. Independientemente del tipo de fuente de datos empleada, la capa DAO siempre proporciona un API uniforme a sus clientes, ocultando los detalles de implementacin. La capa DAO se implementa sin estado. No almacena en cach resultados de ninguna consulta, ni datos que el cliente pueda necesitar posteriormente. Esto provoca que los objetos DAO sean simples y evita problemas potenciales de concurrencia Diagrama de clases (extrado de Core J2EE Patterns, Best Practices and Design Strategies por Deepak Alur, John Crupi y Dan Malks):
Spring proporciona un mecanismo adicional que permite integrar herramientas ORM en objetos DAO de una forma mucho ms sencilla, haciendo uso del componente Spring DAO. Los DAOs pueden ser configurados a travs de la inyeccin de dependencias as como participar de los recursos y la gestin automtica de transacciones que aporta Spring. La norma habitual en los desarrollos ser hacer uso de Hibernate Spring DAO, proporcionando funcionalidades adicionales que harn ms sencillo el uso de Hibernate. Las ventajas obtenidas al hacer uso de Spring DAO con Hibernate: Fcil de testear: La aproximacin de inyeccin de dependencias aportada por Spring hace sencillo cambiar implementaciones y configurar la localizacin de instancias del objeto SessionFactory de
107 de 191
Framework Atlas
Normativa Hibernate, recursos JDBC, gestores de transacciones, etc. Esto hace sencillo aislar y testear cada pieza relacionada con la persistencia de forma independiente. Acceso comn a excepciones: Spring puede mapear las excepciones producidas por la Hibernate, convirtindolas de propietarias a una jerarqua comn de manejo de excepciones DataAccessException, permitiendo manejar excepciones no recuperables solo en las capas apropiadas. Gestin general de recursos: Spring maneja de forma automtica la localizacin y configuracin de instancias SessionFactory, Datasources, etc., por lo que Spring ofrece una manera sencilla y segura de poder acceder a los recursos. Por ejemplo, generalmente Hibernate necesita utilizar la misma sesin para hacer un manejo eficiente de las transacciones, Spring de forma transparente crea y enlaza sesiones al actual hilo de ejecucin, etc.
ADHibernateDAOImpl En cada bloque funcional de una aplicacin se han de crear los DAOs que darn cobertura a los accesos a la base de datos. Para crear un DAO se crearn dos clases, con la siguiente nomenclatura:
NORMA
o o
<nombre>DAO (Interfaz del DAO) <nombre>DAOImpl (Implementacin del DAO)
Donde <nombre> debe ser sustituido por el nombre del DAO. Estas clases se incluirn en el paquete dao del bloque funcional correspondiente. Las clases de implementacin deben heredar de la clase HibernateDaoSupport, de esta forma se utiliza el modelo de DAOs proporcionado por Spring.
NORMA
ADDAOAnotacion Las clases de implementacin de DAO tienen que tener la anotacin @Repository. (No incluir la anotacin en las interfaces)
108 de 191
Framework Atlas
Normativa ADDAONomenclatura Cuando los DAOs tengan operaciones de modificacion o alteracin de datos seguirn la siguiente nomenclatura: o Insercin: insertXXX, donde XXX ser un nombre autodescriptivo, generalmente el nombre del objeto de domino.
NORMA
Actualizacin: updateXXX, donde XXX ser un nombre autodescriptivo, generalmente el nombre del objeto de domino.
Eliminacin: deleteXXX, donde XXX ser un nombre autodescriptivo, generalmente el nombre del objeto de domino.
Consultas: findXXX, donde XXX ser un nombre autodescriptivo sobre la consulta a realizar.
El nombre descriptivo XXX siempre ser opcional.
ADDAOHibernateTemplate
NORMA
Todas las operaciones sobre la base de datos como insert, delete, select (equivalente a find en Hibernate), etcse deben realizar a travs de la clase HibernateTemplate proporcionada por Spring, evitando el uso directo de la sesin de Hibernate.
Ejemplo de uso de HibernateTemplate /** * {@inheritDoc} * * @param cliente El cliente * @see ejpl.gestion.dao.ClienteDAO#insertCliente(ejpl.gestion.domain * .Cliente) */ @Transactional(readOnly = false) public void insertCliente(Cliente cliente) { this.getHibernateTemplate().save(cliente); }
Para facilitar la tarea de implementacin de las operaciones CRUD en los DAOs, se proporciona dentro del arquetipo una interfaz llamada BaseDAO y su correspondiente implementacin, con los mtodos bsicos ya implementados de tal forma que podemos crear nuestros DAOs heredando de esta clase DAO e implementando solo aquellos mtodos que sean especficos de nuestro DAO. A continuacin se muestra la interfaz BaseDAO:
109 de 191
Framework Atlas
Normativa
package ejpl.dao; import java.io.Serializable; import java.util.List; import java.util.Map; import org.hibernate.criterion.Criterion; import org.hibernate.criterion.Order; /** * DAO genrico con funcionalidad CRUD * * Extiende esta interfaz si se requiere DAOs para los objetos de modelo sin * necesidad de realizar cast de conversin de datos. * * @param <T> el tipo de objeto que manejar este DAO. * @param <PK> la clave primaria del objeto de dominio. */ public interface BaseDAO <T, PK extends Serializable> { /** * Mtodo genrico usado para obtener todos los objetos de un tipo * particular. Este mtodo es equivalente a obtener todas las filas * de una tabla. * * El nmero total de elementos que correspondera al mtodo * countAll() se puede obtener a travs del mtodo size() del objeto * de lista devuelto. * * @return Lista de los objetos recuperados de BD */ List<T> findAll(); /** * Mtodo genrico usado para obtener el total de objetos de un tipo * particular. * @return nmero de elementos totales en la tabla. */ Long countAll(); /** * Obtiene todos los registros sin duplicados. * Si se utiliza este mtodo, es imperativo que las clases de * modelo implementen correctamente los mtodos hashcode/equals. * * El nmero total de elementos que correspondera al mtodo * countAllDistinct() se puede obtener a travs del mtodo size() del * objeto de lista devuelto. * * @return Lista de los objetos recuperados de BD */ List<T> findAllDistinct(); /** * Obtiene en nmero total de registros sin duplicados. * @return nmero de elementos totales sin duplicados. */ Long countAllDistinct(); /** * Mtodo genrico para obtener un objeto basado en el tipo de clase * y su identificador nico. Si no se encuentra el objeto, este mtodo * devolver null. * * @param id el identificador (clave primaria) del registro a obtener * @return el objeto de base de datos recuperado */ T find(PK id); /** * Mtodo para obtener una serie de elementos del sistema dados unos ordenes y filtros * @param index Indice de paginacion actual.
110 de 191
Framework Atlas
Normativa
* @param pageSize Tamao de pagina. * @param orders Criterios de ordenacion * @param filters Filtros de busqueda. * @return <code>java.util.List</code> La lista de objetos encontrados */ List<T> find(int index, int pageSize, Order[] orders, Criterion[] filters); /** * Mtodo para obtener el numero de elementos dada una serie de filtros * @param filters Filtro de busqueda. * @return <code>int</code> con el numero total de objetos encontrados. */ int count(Criterion[] filters); /** * Comprueba la existencia de un objeto en base a su clave primaria. * * @param id el identificador de la entidad * @return - true si el objeto existe, false en caso contrario */ boolean exists(PK id); /** * Mtodo genrico para grabar un objeto (maneja objetos nuevos y modificados). * Si el objeto es nuevo, este se devolver con la clave primaria generada para * su insercin en base de datos. * * @param object el objeto a guardar * @return el objeto persistente */ T insert(T object); /** * Mtodo genrico para grabar un objeto (maneja objetos nuevos y modificados). * Si el objeto es nuevo, este se devolver con la clave primaria generada para * su insercin en base de datos. * * @param object el objeto a guardar */ void insertOrUpdate(T object); /** * Mtodo genrico para grabar actualizar un objeto * * @param object el objeto a guardar */ void update(T object); /** * Mtodo genrico para eliminar un objeto de la base de datos en base a su * clave primaria. * * @param id el identificador (clave primaria) del registro a obtener */ void delete(PK id); /** * Mtodo genrico para eliminar un objeto de la base de datos * * @param object el objeto a eliminar */ void delete(T object); /** * Encuentra una lista de registos usando una 'named query'. * * @param queryName nombre de la consulta a ejecutar * @param queryParams un objeto Map con los nombres de los parmetos y sus valores * @return una lista con los registros encontrados */ List<T> findByNamedQuery(String queryName, Map<String, Object> queryParams); }
La implementacin de esta clase se puede ver en el paquete dao en la clase BaseDAOImpl.
111 de 191
Framework Atlas
Normativa
ADBaseDAO
PRACTICA
BUENA
En el caso de que en el proyecto se identifiquen otros mtodos comunes a todos los DAOs estos mtodos se incorporaran en la interfaz BaseDAO y en su correspondiente implementacin.
La creacin de nuevos DAOS se realizar utilizando los mecanismos de herencia sobre la clase BaseDAO. Dentro de los arquetipos se ha incluido un ejemplo de nuevo DAO que accede a la tabla de clientes: ClienteDAO. El siguiente diagrama muestra el diagrama de clases con las dependencias de la implementacin de este nuevo DAO.
class dao interface BaseDAO + + + + + + + + + + countAll() : Integer countAllDistinct() : Integer delete(PK) : void exists(PK) : boolean findAll() : List<T> findAllDistinct() : List<T> findByNamedQuery(String, Map<String, Object>) : List<T> get(PK) : T insert(T) : T saveOrUpdate(T) : void
T PK:extends Serializable HibernateDaoSupport BaseDAOImpl interface ClienteDAO + + findClientes(int, int, Object, Object) : List<Cliente> findClientesTotal(Object) : int + + + + + + + + + + # + + log: Log = LogFactory.getL... {readOnly} persistentClass: Class<T> BaseDAOImpl(Class<T>) BaseDAOImpl(Class<T>, SessionFactory) countAll() : Integer countAllDistinct() : Integer delete(PK) : void exists(PK) : boolean findAll() : List<T> findAllDistinct() : List<T> findByNamedQuery(String, Map<String, Object>) : List<T> get(PK) : T getLog() : Log insert(T) : T saveOrUpdate(T) : void
ClienteDAOImpl + + + ClienteDAOImpl() findClientes(int, int, Object, Object) : List<Cliente> findClientesInternal(int, int, Object, Object, String) : Query findClientesTotal(Object) : int
112 de 191
Framework Atlas
Normativa A continuacin se muestra un posible cdigo de ejemplo para las clases ClienteDAO y ClienteDAOImpl, que heredan de BaseDAO y aaden dos mtodos que no existen en la clase padre. Ejemplo: ClienteDAO package ejpl2.dao; import java.util.List; import ejpl2.domain.Cliente; /** * Clase que extiende el CRUD bsico proporcionado por Atlas. Esta clase es * una demostracin de como usar BaseDAO y completar con ms mtodos de * acceso a BBDD. * * Si no hiciesen falta ms mtodos, no sera necesario crear ninguna clase, * simplemente definir ClienteDAO en el contexto de Spring como sigue: * * <pre> * <bean id="clienteDAO" class="ejpl2.dao.BaseDAOImpl"> * <constructor-arg value="ejpl2.domain.Cliente"/> * </bean> * </pre> * * * * @author ICM * */ public interface ClienteDAO extends BaseDAO<Cliente, Integer> { /** * Este metodo recupera todos los clientes del sistema. * * @param index Indice de paginacion actual. * @param pageSize Tamao de pagina. * @param order Criterio de ordenacion. * @param filter Filtro de busqueda. * * @return <code>java.util.List</code> objecto que representa la lista de clientes. */ List<Cliente> findClientes(int index, int pageSize, Object order, Object filter); /** * Este metodo obtiene el numero total de clientes del sistema. * * @param filter Filtro de busqueda. * * @return <code>int</code> con el numero total de cliente encontrados. */ int findClientesTotal(Object filter); }
113 de 191
Framework Atlas
Normativa Ejemplo: ClienteDAOImpl package ejpl2.dao; import java.util.HashMap; import java.util.List; import java.util.Map; import import import import org.hibernate.Query; org.springframework.stereotype.Repository; org.springframework.transaction.annotation.Propagation; org.springframework.transaction.annotation.Transactional;
import ejpl2.domain.Cliente; /** * Objeto DAO de tratamiento en base de datos de la clase Cliente. * * @author ICM */ @Repository @Transactional(readOnly = true, propagation = Propagation.SUPPORTS) public class ClienteDAOImpl extends BaseDAOImpl<Cliente, Integer> implements ClienteDAO { /** * Constructor por defecto. Pasa a BaseDAO el objeto Class de * parametrizacin de la clase. */ public ClienteDAOImpl() { super(Cliente.class); } /** * {@inheritDoc} * * @see ejpl2.dao.ClienteDAO#findClientes(int, int, java.lang.Object, * java.lang.Object) */ @SuppressWarnings("unchecked") public List<Cliente> findClientes(int index, int pageSize, Object order, Object filter) { null); Query query = findClientesInternal(index, pageSize, order, filter, // Ejecuta la query return query.setFirstResult(index).setMaxResults(pageSize).list(); } /** * {@inheritDoc} * * @see ejpl2.dao.ClienteDAO#findClientesTotal(java.lang.Object) */ public int findClientesTotal(Object filter) { Query query = findClientesInternal(0, 0, null, filter, "Select count(c)");
114 de 191
Framework Atlas
Normativa
// Ejecuta la query return ((Long) query.uniqueResult()).intValue(); } /** * Mtodo interno para buscar clientes * * @param index Indice de paginacion actual. * @param pageSize Tamao de pagina. * @param order Criterio de ordenacion. * @param filter Filtro de busqueda. * @param select clausula select para retornar distintos valores * @return objeto Query para entregar a Hibernate */ private Query findClientesInternal(int index, int pageSize, Object order, Object filter, String select) { StringBuffer strQuery = new StringBuffer(); Map<String, String> params = new HashMap<String, String>(); if (select != null) { strQuery.append(select); } strQuery.append(" from Cliente c"); // Concatena la clausula where al filtro si es necesario String strFiltro = (filter == null) ? null : filter.toString(); if (strFiltro != null && !strFiltro.equals("")) { strQuery.append(" where c.nombre like :filtro "); params.put("filtro", "%" + strFiltro + "%"); } // Concatena la clausula order al filtro si es necesario String strOrder = (order == null) ? null : order.toString(); if (strOrder != null && !strOrder.equals("")) { strQuery.append(" order by c.").append(strOrder); } // Selecciona el parmetro del filtro si es necesario Query query = getSession().createQuery(strQuery.toString()); // Incluimos los parametros for (String key : params.keySet()) { query.setString(key, params.get(key)); } // Devolver el objeto query return query; } }
115 de 191
Framework Atlas
Normativa Atencin Puede ocurrir que un DAO no necesite ningn mtodo adicional a los del BaseDAO, en ese caso no es necesario crear ninguna clase, simplemente definir un objeto en el contexto de Spring (applicationContextdao.xml) de la siguiente forma: <bean id="miDAO" class="ejpl.dao.BaseDAOImpl"> <constructor-arg value="ejpl.domain.Cliente"/> <constructor-arg ref=sessionFactory/> </bean>
Nota Los daos se deben inyectar en el contexto de Spring en el fichero applicationContext-dao.xml
NORMA NORMA
ADCatalogos No se permiten realizar actualizaciones en tablas de catlogos generales (SUCA, CATA, etc). Tampoco se podrn realizar borrados en cascada sobre tablas de catlogos.
ADRemoto El acceso a tablas remotas se debe hacer mediante sinnimos remotos y no por database link.
ADHQL Se deber utilizar en la medida de lo posible el lenguaje de acceso a datos HQL, por ser un
PRACTICA
lenguaje ms enfocado a objetos que el propio SQL. An as se podr extender este modelo haciendo uso del lenguaje SQL siempre y cuando sea necesario. Esto ser necesario en casos de querer usar querys SQL no ANSI-Estndar, querys que por su complejidad sea ms adecuado SQL en lugar del mapeo objeto-relacional, operaciones de larga duracin del tipo batch, streaming de BLOBs, operaciones de tipo select complejas, etc.
BUENA
116 de 191
Framework Atlas
Normativa ADSQL En el caso de utilizar SQL se implementar mediante los mecanimos que proporciona Hibernate para la ejecucin de queries SQL nativas. (createSQLQuery)
NORMA
Ejemplo de uso de SQL public List getQueryData() { SQLQuery query = getHibernateTemplate().getSession().createSQLQuery(sql); query.setResultTransformer(Transformers.ALIAS_TO_ENTITY_MAP); return query.list(); }
ADSQLUso En el caso de utilizar SQL se deberan tener en cuenta las siguientes restricciones: No se podrn utilizar sentencias SQL-DML ni SQL-DDL desde el cdigo ni utilizar los mecanismos de Hibernate que permitan realizar ese tipo de operaciones desde el cdigo. No se deben utilizar las sentencias SELECT * en su lugar se incluirn los nombre de los campos que en realidad se van a consultar. En el caso de utilizar una sentencia SELECT FOR UPDATE se har con la clausula NO WAIT.
6.4.4.1
NORMA
Ejecucin de consultas
Es normal en todos los DAOs la ejecucin de consultas en la base de datos. Por motivos de optimizacin de las consultas es necesario que los parmetros utilizados como criterios no se adjunten en el String de la consulta y sean pasados como named parameters. A continuacin se muestra un ejemplo incorrecto y otro correcto de creacin de consultas: Creacin INCORRECTA de consultas String strQuery = "from Cliente where nombre = '" + nombre + "'"; // MAL Query query = getSession().createQuery(strQuery); return query.list();
Creacin CORRECTA de consultas String strQuery = "from Cliente where nombre = :nombre"; // BIEN Query query = getSession().createQuery(strQuery); query.setString("nombre", nombre); return query.list();
117 de 191
Framework Atlas
Normativa ADNamedParameter El uso de criterios en las consultas de los DAOs ha de hacerse siempre a travs de named parameters.
NORMA
118 de 191
Framework Atlas
Normativa 6.4.4.2 Manejo de excepciones
Un DAO deber esforzarse en aislar el manejo de excepciones gracias a Spring, por lo que solo podr lanzar DataAccessException, de manera que el tratamiento de las excepciones que se pudiesen provocar a este nivel seria gestionadas en capas superiores (capa de negocio). Esto se justifica ya que por ejemplo carece de sentido lanzar java.lang.Exception, ya que es demasiado genrica y no transmite ninguna informacin acerca de la raz del problema. Tampoco tendr sentido lanzar excepciones de tipo java.sql.SQLException, ya que es una excepcin JDBC de bajo nivel.
NORMA
6.4.4.3
DAOExcepciones Todos los mtodos de los DAOs slo podrn lanzar excepciones de tipo DataAccessException.
Transaccionalidad
El uso del modelo de anotaciones que propone Spring permite gestionar de forma automtica y sencilla la semntica transaccional, esto se pronuncia en un cdigo portable con respecto al gestor transaccional utilizado, por ejemplo se podra alterar el uso del gestor transaccional de Hibernate por el de otro sistema de persistencia que soporte el estndar JTA.
ADTransaccion La gestin de las transacciones se har mediante anotaciones. Los DAOs tendrn por defecto todos los mtodos como de lectura y propagacin supports, esto se definir con una anotacin @Transaction a nivel de clase. (@Transactional(readOnly = true, propagation = Propagation.SUPPORTS)
NORMA
Los mtodo de los DAOs que alteren datos (insert, update, delete) modificarn el comportamiento por defecto, mediante el atributo readOnly=false. (@Transactional(readOnly = false)) De forma excepcional, se permite modificar el comportamiento por defecto de un mtodo con respecto al atributo propagacin Propagation.SUPPORTS por uno de tipo Propagation.REQUIRES_NEW. El uso de cualquier atributo de propagacin que no sea Propagation.SUPPORTS o Propagation.REQUIRES_NEW deber de justificarse y consesuarse con ICM.
En el ejemplo de implementacin de un DAO que podemos ver mas arriba podemos observar el uso de las anotaciones tal y como se indica en la norma.
119 de 191
Framework Atlas
Normativa
Aunque se coment en la seccin de servicios, recalcar que sern las capas superiores (servicios) la encargadas de gestionar el contexto transaccional y no la capa de acceso a datos, por lo que los DAOs se limitarn a ejecutar un mtodo en un contexto transaccional (si al invocar dicho mtodo el contexto ya est creado), o a ejecutar el mtodo sin transaccin (en caso de invocar al DAO sin un contexto transaccional). Esto se cumplir en la mayora de los casos, ya que al permitir (eventualmente) Propagation.REQUIRES_NEW, se permite que el propio DAO cree un contexto transaccional solo para la ejecucin de un mtodo concreto.
ADRollback Un DAO no puede gestionar rollback de transaccin, es decir, se prohbe el uso de o o

rollbackFor = xxxException.class, rollbackForClassName = {"xxxException"}, noRollbackFor = xxxException.class , noRollbackForClassName = {"xxxException"}.
NORMA
o o
Cuando los DAOs generen un error de tipo DataAccessException o RuntimeException se traducir en un rollback automtico. Segn se comenta en el apartado de servicios de negocio, los atributos rollbackFor, rollbackForClassName,noRollbackFor y noRollbackForClassName solo tendrn sentido en la capa de servicios con objeto de poder realizar rollback para las excepciones de negocio.
120 de 191
Framework Atlas
Normativa 6.4.5 Llamada a Procedimientos Almacenados desde Hibernate
La llamada a procedimientos almacenados de Oracle desde Hibernate se puede realizar utilizando Named Queries segn se muestra en el ejemplo de este apartado.
NORMA
ADStoredProc La llamada a procedimientos almacenados de Oracle desde Hibernate se realizar utilizando Named Queries, y no accediendo directamente a la conexin JDBC.
A continuacin se muestra un ejemplo de procedimiento almacenado que devuelve un cliente (el ejemplo puede implementarse en un arquetipo recien creado). 1) Creacin de procedimiento almacenado:
Ejemplo de procedimiento almacenado create or replace procedure EJPL_PROC_BUSCAR_POR_ID ( z_resultado out SYS_REFCURSOR, w_id IN integer) is begin OPEN z_resultado FOR SELECT ID_CLIENTE,NOMBRE,APELLIDO1,APELLIDO2, DIRECCION,TELEFONO,FC_NACIMIENTO,FK_ESTADO_CIVIL FROM EJPL_CLIENTES WHERE ID_CLIENTE = w_id; end EJPL_PROC_BUSCAR_POR_ID; 2) Modificacin de la entidad de dominio para incluir la named query (Cliente.java): Ejemplo de entidad que define la Named Query @Entity @org.hibernate.annotations.NamedNativeQuery(name = "buscarClientePorId", query = "call EJPL_PROC_BUSCAR_POR_ID(?,:w_id)", callable = true, resultClass = Cliente.class) @Table(name = "EJPL_CLIENTES") public class Cliente implements java.io.Serializable { } 3) Modificacin del DAO de Clientes para obtener un cliente por su identificador utilizando el procedimiento almacenado creado (ClienteDAOImpl): Ejemplo de DAO que utiliza la Named Query
public Cliente findById(final Integer idCliente) { // Implementacin de ejemplo utilizando procedimiento almacenado List<Cliente> clientes = (List<Cliente>) getHibernateTemplate().execute(new HibernateCallback() {
121 de 191
Framework Atlas
Normativa public Object doInHibernate(final Session session) throws HibernateException, SQLException { return session.getNamedQuery("buscarClientePorId") // .setParameter("w_id", idCliente) // .list(); } }); if(clientes != null && clientes.size() > 0) { return clientes.get(0); } return null; // Implementacin sin utilizar procedimiento almacenado // return (Cliente) getHibernateTemplate().get( // "xxxx.bloquefuncionaln.domain.Cliente", idCliente); }
122 de 191
Framework Atlas
Normativa 6.4.6 Cachs en Hibernate
El uso adecuado de mecanismos de cach permitir aumentar el rendimiento de aplicaciones que accedan a entornos persistentes de informacin al almacenar las estructuras de objetos en memoria, evitando volver a buscar dichos objetos en bases de datos, ahorrando multitud de accesos y por consiguiente grandes cantidades de tiempo. Los pasos comunes que se siguen en el acceso a datos mediante caches podran resumirse como: Se realiza una consulta de acceso a datos. Se comprueba si los objetos requeridos se encuentran en cach. Si los objetos estn en cach se devuelven directamente. Si los objetos no se encuentran en cach, se recuperan desde un almacn de datos persistente y se almacenan en cach para un uso futuro. 6.4.6.1 Las cachs de primer y segundo nivel
Hibernate cuenta con dos tipos de cachs, la denominada cach de primer nivel y la de segundo nivel:
Figura 1 : Cach de primer y segundo nivel en Hibernate La cache de primer nivel se corresponde al objeto sesin que se obtiene de la factora de sesiones de Hibernate. Esta cach de primer nivel se encargar de almacenar los objetos que se recuperan de la base de datos. Otra ventaja obtenida en paralelo es que el objeto sesin acta como fachada y situaciones como accesos, lazos circulares, etc. solo afecta a la propia sesin sin causar efectos colaterales al resto de sesiones abiertas.
123 de 191
Framework Atlas
Normativa Una norma fundamental cuando se utilizan cachs, es almacenar slo lo que estamos seguros que se reutilizar. En otro caso, lo mejor es no utilizar la cach. Cuando se trabaje con una sesin y se mantenga activa en memoria, se debe tener en cuenta que es una cach de primer nivel, y se debe eliminar todo aquello que carezca de sentido su almacenaje en la misma. Se recomienda que cuando se desee eliminar objetos de la cach se invoque al mtodo evict() para que se elimine de cach el objeto pasado como parmetro. Existe tambin un mtodo clear() que permite eliminar todos los objetos que se encuentren en ese momento en la cach, limpindola as por completo. Ambos mtodos, son tiles para polticas de sincronizacin entre cachs. La cach de segundo nivel se acoplar a la sesin de Hibernate absorbiendo todos los fallos que se produzcan en sta. La gran ventaja de utilizar una cach de segundo nivel es que desaparecen los problemas de actualizaciones concurrentes entre sesiones. La cach de segundo nivel se sita al mismo nivel que el objeto SessionFactory de Hibernate, recogiendo y coordinando los objetos con los que trabajan las diferentes sesiones. El problema de las actualizaciones concurrentes supone un grave quebradero de cabeza para cualquier sistema de cach. Sea cual sea el modelo que se desee utilizar siempre se tendr algn problema en relacin con las actualizaciones concurrentes, ya sea en mayor o menor medida. La gran ventaja de una cach de segundo nivel, es que ayuda a mitigar estos problemas, al tiempo que alivia de la responsabilidad de almacenar datos temporales, a la cach de primer nivel. La recomendacin general con una cach de segundo nivel es utilizar una aproximacin de sesin por transaccin de aplicacin (Sesin por vista). Con una cach de segundo nivel, el gran problema de no aprovechamiento de la cach de primer nivel del que adolecen algunos modelos, desaparece parcialmente. Si un objeto no se encuentra en la cach de primer nivel, Hibernate tratar de obtenerlo de la cach de segundo nivel, de modo que en caso de encontrarse ah se consigue el ahorro de un hit en la base de datos. Cerrar las sesiones pues, ya no es un problema tan grave (a nivel de rendimiento), ya que aunque se tengan que realizar cientos y cientos de consultas recurrentes, los datos estarn en la cach de segundo nivel, y la prdida de rendimiento ya no ser tan grande. Hibernate permite habilitar individualmente la cach para cada una las entidades. De este modo, se podr indicar que clases se beneficiarn del uso de una cach, ya que como segn lo comentado anteriormente, puede que no todas las clases del sistema se beneficien. Adems de esto, al habilitar la cach es necesario establecer la estrategia de concurrencia que Hibernate utilizar para sincronizar la cach de primer nivel con la cach de segundo nivel, y sta ltima con la base de datos. Hay cuatro estrategias de concurrencia predefinidas. A continuacin aparecen listadas por orden en base a restricciones expresadas en trminos de aislamiento transaccional:
124 de 191
Framework Atlas
Normativa Transactional: Garantiza un nivel de aislamiento hasta repeatable read, si se necesita. Es el nivel ms estricto. Se recomienda su uso cuando no se pueda permitir datos que queden desfasados. Esta estrategia slo se puede utilizar en entornos basados en clusters, es decir, con cachs distribuidas. Read-write: Mantiene un aislamiento hasta el nivel de commited, utilizando un sistema de marcas de tiempo (timestamps). El caso de uso recomendable es el mismo que para la estrategia transactional pero con la diferencia de que esta estrategia no se puede utilizar en entornos basados en clusters. Nonstrict read-write: No ofrece ninguna garanta de consistencia entre la cach y la base de datos. Para sincronizar los objetos de la cach con la base de datos se utilizan timeouts, de modo que cuando caduca el timeout se recargan los datos. Con esta estrategia se tiene un intervalo en el cual existe el riesgo de obtener objetos desfasados. Cuando Hibernate realiza una operacin de flush() en una sesin, se invalidan los objetos de la cach de segundo nivel. An as, esta es una operacin asncrona y nunca se tienen garantas de que otro usuario no pueda leer datos errneos. A pesar de todo esto, esta estrategia es ideal para almacenar datos que no sean demasiado crticos. Read-only: Es la estrategia de concurrencia menos estricta. Ideal para datos que nunca cambian.
NORMA
6.4.6.2
ADCache2nivel No se permite el uso de cachs de segundo nivel en Hibernate. En el caso de que se justifique su uso se solicitar una autorizacin excepcional a ICM.
Las cachs distribuidas
Las aplicaciones con decenas de miles de usuarios probablemente necesiten ejecutarse en un entorno distribuido, es decir, en cluster. Llegado este momento, el nico elemento de Hibernate que necesitara configurarse es la cach de segundo nivel. Hay dos modos de configurar una cach de segundo nivel de Hibernate en un cluster: El ms sencillo, sin ninguna duda, es colocar en cada nodo del cluster una instancia del proveedor de cach, por ejemplo EHCache, y confiar en los timeout para la sincronizacin de los proveedores de cach de los diferentes nodos. Este sistema es muy simple, y no presenta retardos de sincronizacin entre los nodos, ya que no existe sincronizacin alguna. El segundo modo, es instalar un proveedor de cach ms avanzado que soporte la sincronizacin de las cachs de los diferentes nodos. El proveedor recomendado por Hibernate para esta tarea es JBossCache, un proveedor totalmente transaccional basado en la librera de multicasting, JGroups, si bien no deja de ser una recomendacin por lo que llegado el caso podr optarse por otro proveedor certificado en Hibernate.
125 de 191
Framework Atlas
Normativa
DAOCacheDistribuida En concordancia con el apartado anterior, se debe justificar el uso de cachs distribuidas en entornos basados en cluster, especificando que ventajas aporta con respecto a otro tipo de
NORMA
6.4.6.3
soluciones que nos proporcione el entorno ya sea a nivel de bases de datos, servidores de aplicaciones, etc. Adems el volumen de informacin a manejar crecer sustancialmente (replicacin) por lo que se tendr que justificar su uso en contraposicin con otros requisitos no funcionales (como alta disponibilidad), ausentes en el entorno de desarrollo/preproduccin.
La cach de consultas
La cach de consultas de Hibernate permite almacenar las consultas realizadas recientemente, de modo que si se vuelven a realizar posteriormente, se recuperen los resultados de un modo mucho ms gil (sin volver a ejecutar la select a base de datos). ADRendimiento Se desaconseja el uso de la cach de consultas de hibernate, excepto en aplicaciones que slo realicen consultas (no realicen operacin de insercin/borrado/actualizacin), y realmente hagan uso intensivo de esta cach.
PRACTICA
BUENA
126 de 191
Framework Atlas
Normativa 7 CONFIGURACION
En todas las aplicaciones es necesario establecer ciertos parmetros que permitan modificar el estado o la configuracin del sistema. As, por ejemplo, a la hora de desarrollar una aplicacin se suelen definir constantes y valores predeterminados que quizs interese cambiar a lo largo del tiempo, por lo que incluirlos en el cdigo sera un grave error ya que cada modificacin implicara una recompilacin del cdigo. Dentro de la configuracin de una aplicacin vamos a distinguir distintos tipos de configuraciones: o o Configuracin particular de la aplicacin Configuracin de componentes comunes del framework
Adems dentro de estas configuraciones nos podemos encontrar con configuracin que depende del entorno en el que se ejecute la aplicacin (local, desarrollo, validacin y produccin) y la que no depende de dicho entorno. Las variables de configuracin de una aplicacin pueden estar situadas en distinto lugar, en funcin de la naturaleza de la variable: Librera de configuracin comn por entorno: Toda la configuracin de componentes comunes del framework que es dependiente del entorno y no se necesita personalizar en las aplicaciones (por tanto slo depende del entorno y no de la aplicacin) se ubica en la librera atlascomunes-configuracion-lib. En los entornos de ICM (desarrollo, validacin y produccin) esta librera ya se encuentra configurada para dicho entorno y publicada en el servidor de aplicaciones para que todas las aplicaciones puedan acceder a ella, de manera que el proveedor no necesita realizar ninguna accin con esta librera. o Un ejemplo de configuracin de este tipo podra ser las polticas de seguridad aplicadas en cada entorno, o la configuracin del servidor de planificacin ControlM. Fichero application.properties: Este fichero de configuracin se encuentra incluido en el directorio src/main/resources/conf de las aplicaciones. En l se deben incluir todas las variables de configuracin de la aplicacin que NO dependan del entorno en el que est desplegada (no dependen de que la aplicacin se desplegue en local, desarrollo, validacin o produccin). o Un ejemplo de variable de configuracin de este tipo es la que indica el nombre del fichero de mens de la aplicacin (menu.xml). Si se trata de variables de configuracin referentes a queries (tanto las queries del componente de lista de valores, como queries para la integracin con documentum), estas variables se incluirn en el fichero queries.properties. Fichero environment.properties: Este fichero de configuracin se encuentra incluido en el directorio src/main/resources de las aplicaciones. En l se deben incluir todas las variables de
127 de 191
Framework Atlas
Normativa configuracin de la aplicacin SI no dependan del entorno en el que est desplegada (dependen de que la aplicacin se desplegue en local, desarrollo, validacin o produccin). Durante el despliegue de una aplicacin en los entornos de ICM, este fichero ser sustituido por su homlogo correspondiente al entorno en el que se desea desplegar. o Un ejemplo de variable de configuracin de este tipo es la que indica la ubicacin fsica del fichero de log de la aplicacin.
CONFEntorno El fichero enviroment.properties deber incluir todas las variables que son dependientes del
NORMA NORMA
entorno y que se definan a nivel de aplicacin. Este es el nico fichero que se actualizar a sus valores correspondientes en el despliegue del aplicativo a los distintos entornos. (local, desarrollo, validacin, produccin, etc). Por lo tanto cada vez que se incluya una variable en el fichero enviroment.properties de la carpeta src/main/resources se debe incluir dicha variable en todos los ficheros enviromnet.properties de todos los entornos.
CONFParticular El fichero application.properties deber incluir las variables que se definan a nivel de aplicacin y que no dependan el entorno en el que est desplegada (local, desarrollo, validacin, produccin, etc.). Tambin deber incluir aquellas variables de componentes o servicios del framework que se necesite personalizar para la aplicacin y que no dependan del entorno. Si se trata de variables de configuracin referentes a queries (tanto las queries SQL/HQL del componente de lista de valores, como queries para la integracin con documentum en DQL), estas variables se incluirn en el fichero queries.properties. Las variables de este fichero debern empezar por queryCode. y estarn agrupadas dentro del fichero de manera que se facilite su lectura. Los mdulos de tipo librera en lugar de esta norma les aplica la norma CONFLIB.
Los mdulos de tipo librera han de definir su configuracin de forma distinta para que puedan convivir varias libreras y sus configuraciones dentro de un proyecto. Por ello han de seguirse las siguientes instrucciones: Fichero application-yyyy.properties: En el caso de que una librera incluya variables de configuracin cuyos valores son los mismos para todos los proyectos que usen estas libreras y estos valores no dependan del entorno se crear un fichero llamado application-yyyy.properties
128 de 191
Framework Atlas
Normativa ,donde yyyy es el nombre de la librera, Este fichero se situar en el directorio src/main/resources/conf de la librera para que se incluya dentro del jar de la misma. Si se trata de variables de configuracin referentes a queries, estas variables se incluirn en el fichero queries-yyyy.properties donde yyyy es el nombre de la librera. El fichero ir situado en el mismo directorio que el anterior. Las aplicaciones que utilicen la librera debern referenciar estos ficheros de configuracin dentro del fichero de contexto de Spring applicationContext-general.xml en el bean propertyConfigurer. Fichero environment.properties: Las libreras NO pueden incluir este fichero de configuracin ya que sino sera necesario generar distintas versiones de la librera una por cada entorno. Cuando una librera requiera de variables de configuracin que dependen del entorno estas se incluirn en el fichero de configuracin de la aplicacin que use esta librera (nunca dentro de la librera). Es muy importante que las variables sigan la nomenclatura adecuada para reconocer dentro de una aplicacin a quin pertenecen esas variables de configuracin. CONFParticularLIB En los mdulos de tipo librera el fichero de configuracin se llamar applicationyyyy.properties donde yyyy se corresponde con el nombre de la librera. Este fichero deber incluir las variables que se definan a nivel de aplicacin y que no dependan el entorno en el que
NORMA NORMA
est desplegada (local, desarrollo, validacin, produccin, etc.). Este fichero ir incluido dentro del jar de la librera. Si se trata de variables de configuracin referentes a queries estas variables se incluirn en el fichero queries-yyyy.properties donde yyyy se correponde con el nombre de la librera. Las variables de este fichero debern empezar por queryCode. y estarn agrupadas dentro del fichero de manera que se facilite su lectura.
CONFEntornoLIB Los mdulos de tipo librera NO pueden incluir el fichero enviroment.properties en el directorio src/main/resources. En el caso de que la librera necesite variables que son dependientes del entorno, estas se incluirn en el fichero enviroment.properties de la aplicacin que utilice la librera.
129 de 191
Framework Atlas
Normativa CONFNomenclatura La nomenclatura de las variables propias de la aplicacin ser: xxxx.nombre Donde xxxx es el nombre del mdulo y nombre el nombre de la variable.
NORMA
NORMA
Estas variables debern incluir un comentario con la descripcin de las mismas. Los comentarios deben aportar claridad, no abusar de ellos intentando que el propio fichero sea autodescriptivo. Para ello ayudar la seleccin adecuada de los nombres de los parmetros. Los parmetros que hacen referencia a una misma funcionalidad deben ser incluidas en un grupo de elementos adecuadamente comentados. Cuando existan grupos funcionales deben indicarse introduciendo un nivel de anidamiento ms en esa estructura para agrupar claramente los valores propios para cada instancia. Esta situacin se puede presentar cuando por ejemplo se trabaje con servidores de correo electrnico, donde los datos de conexin y cuentas pueden ser diferentes.
CONFSEG Los ficheros de configuracin no contendrn informacin que supongan riesgo de seguridad segn lo establecido por la LOPD, como por ejemplo contraseas no cifradas.
A continuacin se muestra un ejemplo de cmo obtener el valor de una variable de configuracin definida en el fichero application.properites o environment.properties, desde un fichero de Spring:
Ejemplo de fichero application.properties environment.properties politicas.url=http://localhost:9080/index.jsf
Ejemplo de cmo obtener el valor de una variable de configuracin desde Spring <bean id="miBean" class="paquete.MiClase"> <property name="url" value="${politicas.url}"/> </bean>
Para obtener el valor de una variable de configuracin desde Java, se recomienda inyectar el valor en la clase Java a travs de un bean de Spring (segn se muestra en el ejemplo anterior). Aunque menos recomendada para los casos habituales, existe otra forma alternativa que consiste en cargar el fichero de propiedades del que se desea obtener la variable y obteniendo su valor de este, segn se muestra en el siguiente ejemplo:
130 de 191
Framework Atlas
Normativa Ejemplo de cmo obtener el valor de una variable de configuracin desde Java import java.util.Properties; import atlas.core.general.PropertiesLoader; public class EjemploProperties { /** singleton para cargar properties de fichero */ private static final Properties PROPS = PropertiesLoader.getInstance( new String[] {"conf/application.properties"}).getProperties(); /** Variable obtenida del fichero application.properties */ public static final String POLITICAS_URL = PROPS.getProperty("politicas.url"); /** * Devuelve el valor de la URL * @return El valor de la URL leda del fichero application.properties */ public String getURLPoliticas() { return POLITICAS_URL; } }
131 de 191
Framework Atlas
Normativa 8 SERVICIOS BASICOS
El framework Atlas ofrece un conjunto de servicios bsicos para cubrir aquellos requisitos comunes a la mayora de las aplicaciones. Los arquetipos ya vienen preconfigurados para poder utilizar estos servicios bsicos. A continuacin se muestran con ms detalle cada uno de estos servicios bsicos. 8.1 SERVICIO DE AUTENTICACION Y AUTORIZACION
La Comunidad de Madrid dispone de aplicaciones de carcter pblico y privado, dependiendo, tanto del tipo de funcin que desempean como del tipo de usuarios al que van dirigidas. En el framework Atlas se ha desarrollado el Servicio de Autenticacin y Autorizacin para cubrir este requisito de gestin de accesos. Las aplicaciones de carcter privado limitaran su acceso a determinados usuarios. La forma de acceder a este tipo de aplicaciones puede ser mediante dos mecanismos: certificado digital y/o login/password. Los usuarios que tienen su acceso permitido a determinadas aplicaciones estarn dados de alta en alguno de los repositorios que la Comunidad de Madrid dispone. En estos repositorios de usuarios se encuentra toda la informacin de los usuarios y sus perfiles o roles de trabajo para cada aplicacin. Estos repositorios son los que se muestran a continuacin:
Poltica LDAP USU USUI
Repositorio a validar y acciones Almacena los datos de login de los usuarios de la intranet. Se utiliza para la autenticacin de los usuarios. Repositorio de usuarios y perfiles de la Comunidad de Madrid. Se utiliza para la autorizacin de los usuarios. Repositorio de usuarios y perfiles de la Comunidad de Madrid con acceso desde Internet. Se utiliza para la autenticacin y autorizacin de los usuarios. Repositorio de usuarios y perfiles de la Comunidad de Madrid para aplicaciones de Justicia. Se utiliza para la autenticacin y autorizacin de los usuarios.
USUJ
132 de 191
Framework Atlas
Normativa
Para el framework Atlas se han definido unas polticas de acceso para las aplicaciones que consisten en la definicin de unas reglas de validacin de acceso de los usuarios. Estas polticas indican cual es el mecanismo de acceso, contra que repositorios se deben llevar a cabo el proceso de autenticacin, as como otras medidas a adoptar. A continuacin se muestra una tabla con la lista de polticas de acceso que se han definido para Atlas y que se pueden utilizar en las aplicaciones web.
Poltica Pblico Pblico Certificado Usuario Intranet Usuario Internet Usuario Justicia Demo
Repositorio a validar y acciones (no se realizar ninguna accin) Validar Certificado contra la plataforma multipki de ASF Validar el usuario contra LDAP y recoger el rol de USU Validar Certificado (multiPKI) o validar el usuario y recoger su rol en USUI Validar Certificado (multiPKI) o validar el usuario y recoger su rol en USUJ Poltica para desarrollo en la cual no es necesario disponer de ningn repositorio. Los usuarios de pruebas se definen en un fichero xml.
133 de 191
Framework Atlas
Normativa En algunas aplicaciones se puede dar el caso de que, dependiendo del entorno desde donde se acceda a la aplicacin, la forma de autenticacin sea distinta. Por ejemplo: una autenticacin con certificado si la aplicacin es accedida desde internet y permitir acceso mediante usuario/contrasea para los accesos desde la intranet. El Servicio de Autenticacin y Autorizacin de usuarios permite que dependiendo del dominio/host al que se conecte el usuario se presente una poltica de acceso u otra, segn se haya definido en la aplicacin a la que se est accediendo.
SBAutenAuto
NORMA NORMA
Aquellas aplicaciones web que tengan que restringir el acceso a determinados usuarios debern utilizar el Servicio de Autenticacin y Autorizacin del framework Atlas y siempre utilizando alguna de las polticas ya definidas en el mismo.
Por otra parte dentro de una aplicacin determinados usuarios tendrn acceso a unas opciones y otros usuarios a otras opciones. Esto se va a gestionar creando distintos perfiles o roles segn el tipo de usuarios y limitando el acceso a las opciones de men y a las rutas de acceso segn los perfiles creados.
SBAutoPerfiles Si la aplicacin tiene distintos perfiles de acceso, la seguridad se debe implementar a nivel de men y a nivel de urls de acceso.
Para ms informacin sobre el Servicio de Autenticacin y Autorizacin consultar el manual Error! No se encuentra el origen de la referencia. El Real Decreto 3/2010, 8 de enero, por el que se regula el Esquema Nacional de Seguridad en el mbito de Administracin Electrnica, previsto en el artculo 42 de la Ley 11/2007, establece la poltica de seguridad en la utilizacin de medios electrnicos por las Administraciones Pblicas y ests constituido por principos bsicos y requisitos mnimos que permitan una proteccin adecuada en la informacin. Para asegurar estos requisitos mnimos del Esquema Nacional de Seguridad en las aplicaciones desarrolladas con el framework Atlas se han implementado los siguientes mecanismos: En la pantalla de acceso al sistema, se informa, mediante un enlace a las condiciones de acceso, al usuario de las obligaciones que implica la tenencia de un autenticador, en particular el deber de custodia diligente, proteccin de su confidencialidad e informacin inmediata en caso de prdida y ha de indicar que ha leido y acepta las condiciones de acceso.
134 de 191
Framework Atlas
Normativa
No se ofrecen mensajes de ayuda en la ventana de conexin al sistema o durante la conexin que den pistas. Por ejemplo: Password incorrecta. El mensaje cuando el usuario no existe, la password es incorrecta o no est asociado a la aplicacin es: Las credenciales introducidas son errneas.
No se autorellena el identificador de usuario en el sistema La informacin de logn se validar slo tras rellenar todos los datos de entrada El sistema presenta al usuario el ltimo acceso realizado con su identidad.
135 de 191
Framework Atlas
Normativa El sistema registra los intentos de acceso exitosos y errneos al sistema (Fecha, hora e identificador de usuario) en un modelo de datos centralizado que permita su posterior explotacin. Una vez que se ha obtenido el acceso al sistema en la zona de informacin sobre el usuario se muestra un enlace a un Aviso de Seguridad a partir del cual se muestra una ventana informativa con sus obligaciones principales tras obtener el acceso (uso permitido, uso no permitido, supervisin de la actividad, etc.)
No se pueden realizar modificaciones en las aplicaciones que impliquen la modificacin o anulacin de estos mecanismos. SBENS
NORMA
No se pueden realizar modificaciones en el control de acceso que impliquen las modificacin o anulacin de los mecanismos implementados para cubrir los requisitos mnimos del Esquema Nacional de Seguridad.
136 de 191
Framework Atlas
Normativa 8.2 COMPONENTES DE PRESENTACION
El framework Atlas ofrece un conjunto de componentes visuales para el desarrollo de las interfaces grficas de usuario de las aplicaciones web. Estos componentes estn basados en los siguientes productos: JSF estndar RichFaces Ajax4JSF Facelets
Los componentes que ofrece el framework Atlas son: Componente Layouts Componentes de Men Descripcin Plantillas para organizar la informacin dentro de la pgina Componentes para la construccin de mens en una aplicacin. Existen 3 tipos de mens: Men Vertical Men Horizontal Men Visual Indicador de navegacin para situar al usuario en la estructura de contenidos Facilita al usuario introducir una fecha en un formulario mostrando en un panel emergente un calendario mensual. Facilita al usuario la introduccin de un valor que est asociado a un catlogo Muestra una lista de datos de forma tabulada en una serie de pginas Panel para mostrar un mensaje de error Ofrece el mecanismo de prueba necesario para determinar cuando un usuario es humano o no. La prueba consiste en introducir por parte del usuario una serie de caracteres los cuales son mostrados de forma distorsionada por pantalla. Tiene por objetivo el validar identificadores legales (DNI, CIF, Pasaporte y Tarjeta de Residencia). Permite incrustar en una pgina un cdigo de barras en diferentes formatos. Permite mostrar un conjunto de datos organizados jerrquicamente en forma de rbol Permite mostrar un conjunto de datos organizados jerrquicamente en forma de rbol cumpliendo con la accesibilidad de las aplicaciones Permite mostrar una barra de solapas para organizar formularios que incluyen muchos datos
Rastro de Migas Calendario Lista de Valores Lista Paginada Mensaje de Error Captcha
Nmero de documento Cdigo de Barras Arbol Jerrquico Arbol Accesible Solapas
137 de 191
Framework Atlas
Normativa Para ms informacin se puede consultar cada uno de los manuales de cada componente. Estos manuales se llaman ATLAS_MUS_Componente_xxxxx
8.3
SERVICIO DE TRAZAS
El Servicio de Trazas de Atlas proporciona a todas las aplicaciones una serie de logs automticos (Inicio /Fin de mtodos que deban ser traceados, Transacciones, SQL de las consultas, etc) durante la ejecucin de la aplicacin adems de formatear todos los logs (tanto generados automticamente por el componente como los definidos por la propia aplicacin) para su posterior uso en la Herramienta de Monitorizacin. SBTrazas Las aplicaciones debern generar un nico log de aplicacin utilizando el Servicio de Trazas que el framework Atlas ofrece. Se deber hacer un uso adecuado de los niveles de prioridad para los mensajes de logs. Las prioridades predefinidas ofrecidas son (ordenadas de mayor a menor detalle): DEBUG > INFO > WARN > ERROR > FATAL. Estableceremos los siguientes criterios para la explotacin de los niveles de log desde nuestro cdigo: DEBUG: Mensajes de depuracin. Se puede utilizar para mostrar el valor de variables, parmetros de configuracin, etc. Son mensajes que deberan ser entendidos y tratados por alguien que conoce el cdigo de la aplicacin. Incorporarn informacin sobre checkpoints que ayudarn a seguir el curso de la ejecucin del algoritmo implementado. INFO: Mensajes de informacin. Se utilizan para anunciar el progreso en el flujo de la aplicacin. Marcarn inicios y finalizacin de bloques de actividades con cmputos de tiempo empleado en realizarlas, etc. WARN: Mensajes de advertencia, usado dentro de la aplicacin para dar aviso de excepciones esperadas y que nuestro cdigo sepa tratarlas para evitar que la aplicacin se interrumpa. ERROR: Mensajes de error, para dar aviso de errores inesperados que no lleguen a detener o afectar la ejecucin de la aplicacin, como por ejemplo que algn parmetro de configuracin no sea correcto y se cargue el valor por defecto del mismo. FATAL: Mensajes de error, para dar aviso de errores inesperados que afectan o detienen la ejecucin de la aplicacin.
NORMA
138 de 191
Framework Atlas
Normativa A continuacin se muestra una figura que representa de forma piramidal la jerarqua de niveles de trazas as como la informacin a mostrar.
INFO: Mensajes de informacin

Inicio-fin de acciones y uso de componentes/servicios. Fecha, Hora, Nombre de clase, Nombre de mtodo, tiempo de ejecucin del mtodo. Si la clase o el mtodo accede a base de datos :
Sentencia HQL/SQL con sus parmetros . Tiempos de preparacin y/o ejecucin de las consultas. Ciclo de vida de las transacciones: inicio y fin (commit y rollback), etc. Actividad del pool de conexiones
FATAL: Mensajes de error crticos

Implementar un sistema de alertas que avise de la cada del sistema y dejar notificacin del envo en el fichero de log.
Siempre que sea posible, almacenar informacin detallada sobre el error producido. Deber integrarse con los sistemas de alertas ICM
ERROR: Mensajes de error

Aadir un indicador de prioridad junto a informacin relevante que ayude a comprender el alcance del error: Nivel 1 : El proceso puede finalizar correctamente a pesar de las inconsistencias producidas. Nivel 2: Se desconoce si la finalizacin del proceso puede darse por vlida. Nivel 3: El carcter del error es severo.
WARN: Mensajes de advertencia

Punto del sistema donde se produzca.
Nombre del usuario que invoca al mtodo. Volcado de errores con nivel, nmero y descripcin. Volcado de los parmetros de configuracin (al arrancar)
FATAL ERROR
Informacin relacionada sobre el posible impacto Las trazas debern reflejar los datos de la operacin que ha generado la excepcin. Valores del fichero de configuracin con la que se est realizando la operacin.
NIVEL MNIMO DE TRAZAS
WARN INFO DEBUG
DEBUG: Mensajes de depuracin

Informacin detallada de la ejecucin de mtodos: Entrada y salida de un mtodo Valor de parmetros Hechos relevantes producidos dentro de un mtodo: Construccin y destruccin de objetos relevantes Accesos a objetos locales y remotos Cualquier otra informacin que permita determinar que se esta realizando en un instante determinado El proceso detallado del flujo de invocaciones sobre toda la infraestructura Informacin de llamadas entre distintas capas y componentes del sistema
Figura 2 : Niveles de trazas SBTrazasSeg
NORMA
El fichero de log no contendr informacin que suponga riesgo de seguridad segn lo establecido por la LOPD, como por ejemplo contraseas no cifradas, datos que identifiquen a menores, minusvalas, etc.
139 de 191
Framework Atlas
Normativa 8.4 SERVICIO DE AUDITORIA DE SEGURIDAD
Los Sistemas de Informacin de la Comunidad de Madrid en algunos casos tratan datos personales de nivel alto que son especialmente protegidos segn el Real Decreto 1720/2007 - Reglamento desarrollo de la LOPD. Algunos ejemplos de datos personales de nivel alto son: Ideologa, afiliacin sindical, religin, creencias, origen racial, salud o vida sexual. Recabados con fines policiales sin consentimiento. Derivados de actos de violencia de gnero. Trfico y localizacin en operadores que prestan servicios de comunicaciones electrnicas.
En estos casos es obligado que se recoja informacin sobre los accesos realizados a dichos datos. El Servicio de Auditoria de Atlas se encarga de auditar los accesos mencionados anteriormente. Para ello es necesario que la aplicacin indique cules son aquellos datos susceptibles de ser auditados, basndose en los mecanismos que ofrecen los frameworks Spring e Hibernate. El Servicio de Auditoria intercepta todas las operaciones de base de datos que se realizan a travs de Hibernate y deja el registro de la auditoria en el esquema TRAZ a travs del paquete de base de datos ATLAS.PACK.LOG. Para ms informacin sobre la utilizacin de este servicio consultar el manual Error! No se encuentra el origen de la referencia.
NORMA
SBAudit Las aplicaciones que precisen auditar los accesos a los datos protegidos lo harn a travs del Servicio de Auditoria del framework Atlas.
140 de 191
Framework Atlas
Normativa 9 INTEGRACION
El framework Atlas para cubrir los requisitos de integracin con otros productos ofrece una serie de servicios adicionales que vamos a denominar servicios de integracin. A continuacin se muestran los distintos servicios que ofrece el framework. En el caso de que un proyecto tenga un requisito de integracin con otro producto o tecnologa se debe comunicar al Area de Aplicaciones Especiales y Arquitectura de Software para que se valore la mejor forma de realizar dicha integracin.
141 de 191
Framework Atlas
Normativa 9.1 SERVICIO DE GESTIN DOCUMENTAL
La solucin de gestin documental para las aplicaciones de la Comunidad de Madrid es el gestor de documental de EMC Documentum. La plataforma EMC Documentum es una extensa suite de productos para la gestin documental que proporciona servicios para la creacin, gestin, distribucin y archivo de cualquier tipo de contenido documental. Sobre este producto se ha construido un servicio dentro del framework Atlas que permite un acceso a la plataforma de gestin documental independiente de la solucin elegida. La integracin con el gestor documental se realiza en dos ambitos: Acceso al core de documentum mediante programacin Componentes visuales que acceden al gestor documental
Para facilitar la configuracin y uso de este servicio se ha creado el arquetipo web documental por lo tanto los mdulos web que necesiten acceder a este servicio deberan partir de este arquetipo. Por otra parte en los proyectos que incluyen gestin documental es necesario crear un mdulo que las definiciones de los tipos documentales y dems elementos necesarios. Para ms informacin sobre este tipo de mdulos consultar el manual Error! No se encuentra el origen de la referencia., y Error! No se encuentra el origen de la referencia..
SIGDOC
NORMA
Las aplicaciones que necesiten acceder a un gestor documental lo harn a travs del Servicio de Gestin Documental y accediendo a travs de los servicios web implementados dentro de este servicio. Actualmente este Servicio de Gestin Documental se ha implementado sobre Documentum.
142 de 191
Framework Atlas
Normativa 9.2 SERVICIO DE PLANIFICACION
En ocasiones es necesario ejecutar ciertas tareas a una hora concreta, en base a una planificacin preestablecida. Tal es el caso de la ejecucin de informes peridicos, o la generacin de estadsticas. Este tipo de tareas suele conllevar una carga importante para la base de datos, cosa que puede empeorar el rendimiento de la aplicacin (y de otros sistemas). Para este tipo de tareas normalmente pesadas, existe una solucin simple: planificar la creacin del informe para las horas cuando el sistema tiene menor carga de trabajo. La solucin elegida para realizar la planificacin de las tareas mencionadas anteriormente es el producto de BMC CONTROL-M.
Figura 3 : Planificacin de tareas con Control-M Para poder invocar a este tipo de tareas necesitamos crear un mdulo batch que implementa la tarea a ejecutar y utilizar el Servicio de planificacin para ejecutar o planificar la tarea. El Servicio de Planificacin ofrece os siguientes elementos: Acceso al api de ControlM mediante programacin Componentes visuales que muestran informacin obtenida de ControlM
NORMA
SIPLAN Las aplicaciones que necesiten invocar una tarea batch lo harn a travs del Servicio de Planificacin del framework Atlas.
143 de 191
Framework Atlas
Normativa 9.3 SERVICIO DE CRIPTOGRAFIA
Las aplicaciones de la Comunidad de Madrid muchas veces requieren de la utilizacin de certificados digitales y/o operaciones criptogrficas que posibilitan la tramitacin electrnica. El Servicio de Critografa, provee las siguientes funcionalidades: Cifrado y descifrado de datos Firma electrnica en servidor Verificacin de firmas electrnicas Validacin de certificados digitales Obtencin de datos de un certificado
NORMA
SICert Las aplicaciones que necesiten realizar operaciones con certificados digitales y/o criptogrficas lo harn a travs del Servicio de Criptografa que ofrece el framework Atlas.
Para ms informacin sobre el uso del servicio de certificados digitales consultar el manual ATLAS_MUS_Servicio_Criptografia.
144 de 191
Framework Atlas
Normativa 9.4 SERVICIO DE BUSSINESS INTELLIGENT
La solucin de Bussiness Intelligent para los proyectos de la Comunidad de Madrid es Bussiness Objects de SAP. Sobre este producto se han definido dentro del framework Atlas una serie de componentes visuales que permite un acceso directo a la plataforma de Bussiness Objects. Business Objects XI ofrece, en una nica solucin, funciones de gestin de rendimiento, generacin de informes, consulta y anlisis e integracin de datos, apoyando a una correcta toma de decisiones tanto a nivel ejecutivo y directivo como a nivel estratgico. Integra distintas fuentes de datos, abstrayendo dichas fuentes, as como los modelos subyacentes, creando una capa semntica con entidades entendibles para el usuario ejecutor y consumidor de los informes, sin necesidad de conocer los modelos de datos relacionales. Esta capa semntica es lo que se conoce en Business Objects XI por el concepto de Universo. Business Objects XI es un producto completamente autnomo y completo que unifica todo el ciclo de gestin y produccin de informes. Las principales caractersticas aportadas por Business Objects XI son:
l l l
Acceso y presentacin de datos en diversos formatos. Integracin de mltiples fuentes de datos. Abstraccin de las fuentes de datos en un conjunto de entidades entendibles por parte del usuario que realiza los informes. Esta abstraccin permite que los usuarios que realmente tienen necesidad de extraer informacin, puedan realizar informes sin necesidad de tener los conocimientos tcnicos necesarios para comprender el modelo de datos subyacentes.
l l l l l l l
Modificacin y creacin de reportes en tiempo de ejecucin. Gestin eficiente y segura de reportes crticos para el negocio. Entrega de la informacin requerida a la gente adecuada en un momento determinado. Basado en un tecnologa fuertemente probada. Escalabilidad y rendimiento adaptables en base al crecimiento del negocio. Soporte a distintos lenguajes de programacin. Gestin de la seguridad en todos los niveles.
Las siguientes tareas del ciclo de vida de generacin de informes se deben realizar con las aplicaciones aportadas por el producto Business Objects XI:
l l l l l l
Tareas de extraccin, transformacin y carga (ETL). Definicin de Universos. Organizacin en carpetas y subcarpetas. Definicin de usuarios y permisos a nivel de datos, de carpetas y de informes. Creacin de informes. Planificicacin de informes.
La integracin con Business Objects XI de las aplicaciones desarrolladas con Atlas se limitar a las siguientes tareas:
145 de 191
Framework Atlas
Normativa
l l l l
Conexin al servidor Business Objects XI con las credenciales definidas en la implantacin BO. Recorrido de carpetas autorizadas. Visionado de los informes de esas carpetas. Planificacin de informes
En proyectos que integren una solucin completa de Business Objects XI, el ciclo de vida de la extraccin de informacin se gestionar por medio de las aplicaciones que proporciona la plataforma Business Objects XI, y no desde la integracin con Atlas. La integracin con Atlas se limitar a la presentacin, visionado y planificacin de los informes generados por la plataforma Business Objects XI.
NORMA
SIBI Las aplicaciones que necesiten acceder a la plataforma de Bussiness Objects lo harn a travs de los componentes establecidos en el framework Atlas.
146 de 191
Framework Atlas
Normativa 9.5 SERVICIO DE INVOCACIN DE SERVICIOS WEB
Muchas de las aplicaciones que se desarrollan para la Comunidad de Madrid necesitan acceder a servicios web tanto servicios que se han desarrollado especficamente para la tramitacin electrnica como otros servicios web que incluso pueden estar fuera de nuestros entornos. Dada la amplia variedad de tipos de servicios web que nos podemos encontrar y los distintos tipos de seguridad que nos pueden requerir los citados servicios web se ha desarrollado el Servicio Invocador de Servicios. En el caso de que el servicio a utilizar se haya desarrollado con Atlas se ha de acceder utilizar el cliente Atlas que proporciene el servicio web. Para ms informacin sobre este servicio consultar el manual Error! No se encuentra el origen de la referencia.Web. INTWS Para invocar a un servicio web se har mediante la utilizacin del Servicio de Invocacin de Servicios Web de Atlas.
NORMA NORMA
INTNomClient Para facilitar su localizacin el nombre del paquete donde se incluyan las clases generadas por el invocador de servicios debe contener la palabra client.
147 de 191
Framework Atlas
Normativa 9.6 SERVICIO DE PROCESOS DE NEGOCIO
Un proceso de negocio es la representacin del trabajo realizado por las personas y los sistemas de una organizacin, con el objetivo de ofrecer un servicio a sus clientes. Business Process Management (BPM) es el arte de formalizar la automatizacin de los procesos de negocio. Un BPM simplifica el desarrollo de aplicaciones que tengan alguno de los siguientes requerimientos: Orquestacin de servicios de negocio: es la secuenciacin de las diferentes tareas y servicios que forman parte de un proceso. La orquestacin permite crear lgica dentro del proceso, ofreciendo funcionalidades tales como: o o o o Invocacin sincrnica y asincrnica a servicios. Manejo de transacciones. Mecanismos de compensacin y manejo de excepciones. Transformacin de mensajes para adaptar la salida de un servicio a la entrada de otro (mapeo de datos). o o Manejo de condicionales, loops, etc. Orientacin a flujos de trabajo: los BPM ofrecen herramientas para definir los procesos de negocio que comprenden un sistema. Los procesos de negocio pueden comprender tareas desempeadas por personas, y tareas que se ejecutan de forma automtica. Integracin de personas dentro de los flujos de trabajo: cuando la ejecucin de un proceso requiere que ciertas personas en la organizacin realicen funciones relacionadas con el proceso (aprobaciones, revisiones, etc.), el uso de un BPM simplifica la interaccin con las mismas. Necesidades de integracin con diferentes sistemas y fuentes de datos: los BPM disponen de conectores para acceder a diferentes sistemas comerciales existentes en grandes organizaciones (SAP, PeopleSoft, CICS, etc.), de forma que la creacin de tareas en las que intervenga este tipo de productos se simplifica enormemente. Capacidades de seguimiento y gestin de las tareas definidas en los procesos de negocio: un BPM ofrece herramientas administrativas que permiten a ciertas personas poder hacer un seguimiento de los procesos y tareas que los comprenden. Medicin, auditora, control y reportes: asociado a un producto de este tipo se ofrecen herramientas para realizar mtricas y anlisis del funcionamiento global del sistema. Aplicacin de reglas de negocio. Ejecucin de procesos con estado.
148 de 191
Framework Atlas
Normativa La solucin de BPM (procesos de negocio) para las aplicaciones de la Comunidad de Madrid es producto Oracle BPM. Sobre este producto se ha construido un servicio dentro del framework Atlas que permite un acceso a la plataforma de BPM independiente de la solucin elegida, este servicio se denomina Servicio de Procesos de Negocio. La integracin con el motor de procesos se realiza en dos ambitos: Acceso al core de Oracle BPM mediante programacin Componentes visuales que muestran informacin obtenida del motor de procesos
SIBPM
NORMA
9.7
Las aplicaciones que necesiten acceder a un motor de procesos lo harn a travs del Servicio de Procesos de Negocio de Atlas. Actualmente este Servicio de Procesos de Negocio se ha implementado sobre el producto Oracle BPM.
OTRAS SOLUCIONES
Por otra parte dentro del framework Atlas se ha seleccionado una serie de soluciones o libreras de terceros que nos cubren otras funcionalidades o requisitos que podamos tener a la hora de desarrollar nuestra aplicacin.
NORMA
SOLLIB El uso de cualquier librera, producto de terceros o tecnologa no incluido dentro del framework deber ser previamente consensuado y autorizado por ICM.
149 de 191
Framework Atlas
Normativa 9.7.1 REPORTING
La solucin de generacin de listados e informes para las aplicaciones de la Comunidad de Madrid es Crystal Reports 2008. Para utilizar informes de Crystal Reports 2008 en las distintas aplicaciones de la Comunidad de Madrid, se ha optado por una solucin centralizada que libera a la aplicacin que va a utilizar los informes de la complejidad de su generacin e interpretacin. Para obtener ms informacin sobre el uso de informes con Crystal Reports consultar el manual Error! No se encuentra el origen de la referencia.. Para incluir informes en nuestra aplicacin en primer lugar debemos disear o crear dichos informes con la herramienta Crystal Reports 2008.
SOLRpt La herramienta de creacin de los informes de las aplicaciones ser Crystal Reports 2008.
NORMA
El nombre del informe tendr la siguiente nomenclatura: XXXXNombreDelInforme.rpt Donde xxxx es el nombre del proyecto y NombreDelInforme el nombre del informe que debe estar escrito en minsculas, excepto la primera letra de cada palabra que estar en maysculas. Este nombre no puede contener espacios en blanco. La extensin debe ser rpt.
La conexin con la base de datos deber ser JDBC y desde la propia herramienta se puede ejecutar el informe para ver el resultado del mismo.
SOLRptConex El tipo de conexin con la base de datos debe ser JDBC. Los informes se desarrollarn integrando las sentencias SQL dentro del informe, no estando
NORMA
permitidas las opciones de ResultSet, RecordSet ni colecciones de objetos, a no ser que as se acuerde explcitamente con ICM. El nombre de las tablas de base de datos dentro del informe rpt desarrollado no debern incluir el nombre de la instancia de base de datos. De esta forma ser posible ejecutar los informes sobre distintas instancias (desarrollo, test, produccin...) sin necesidad de modificar el fichero rpt.
Una vez que tengamos los informes completados se debern publicar en la plataforma de BO. En la entrega se agruparan los distintos informes dentro de un nuevo mdulo de tipo reports.
150 de 191
Framework Atlas
Normativa
SOLRptModulo
NORMA
Todos los informes se entregaran en un mdulo con la siguiente nomenclatura: xxxx_crbo Donde xxxx es el nombre del proyecto. Dentro se crear una carpeta llamada reports donde se incluirn todos los reports.
SOLRptConf El fichero de configuracin environment.properties debe incluir las siguientes variables:
NORMA
bo_ws.webservice Apunta a la url del servicio web bo_ws para autenticacin bo_ws.rutabo Servidor de la plataforma BO (Ej: http://icmdesbi01:8080) bo_ws.usuario Usuario con el que nos conectaremos a la plataforma de Bussiness Objects.
bo_ws.clave Clave del usuario encriptada.
151 de 191
Framework Atlas
Normativa 9.7.2 COMPOSICION DE DOCUMENTOS
Este punto tiene por objetivo explicar como se realizar la generacin dinmica de documentos Word y RTF, a partir de plantillas previamente definidas en este mismo formato. Para el relleno de las plantillas as como la transformacin dinmica de las mismas se utilizar Velocity. Velocity es un motor de plantillas basado en Java que incluye un lenguaje de script, el Lenguaje de Plantillas de Velocity (VTL por sus siglas en ingls). El Lenguaje de Plantillas de Velocity (VTL) nos permite incorporar contenido dinmico dentro de un documento de tipo texto de una manera fcil y sencilla. Este lenguaje se utilizar para la creacin de las plantillas. Desde la parte del negocio de la aplicacin es dnde se va a realizar la fusin de las plantillas utilizando el API Java de Velocity. Se trata de que la fusin del documento se realice en el lado del servidor. El uso del API en java bsicamente consiste en definir un contexto con las variables a mapear en el documento, aplicar este contexto a la plantilla y generar el nuevo documento.
Documentos RTF
Contenedor Web
.doc, .rtf
.doc, .rtf
Peticin JSF Respuesta JSF
Documento generado
Motor de plantillas velocity

Plantilla Velocity
DOCUMENTUM
Documento generado
VTL
.html, txt, etc

Documento origen
Figura 4 : Generacin de documentos RTF
SOLCompositor
NORMA BUENAS PRACTICAS
Para la composicin de documentos en Atlas se utilizar la solucin de Velocity. Las plantillas se crearn en formato RTF y los documentos generados tendrn tambin formato RTF. Las plantillas se incluirn en la carpeta plantillas del proyecto.
SOLCompositor Se recomienda utilizar nombres significativos en las variables, y notaciones sencillas al hacer uso de las etiquetas que dote de claridad a la plantilla y sea fcilmente inteligible mediante una lectura rpida. Esto ayudar a realizar un buen mantenimiento de la misma cuando sea necesario aplicarla modificaciones. Se recomienda utilizar sintaxis de etiquetas simple, escapando de notaciones ms complejas a no ser que est justificada claramente su utilizacin. Se recomienda no anidar bucles en la medida de lo posible. Estos procesos interactivos
152 de 191
Framework Atlas
Normativa complican los procesos de renderizado. Se recomienda hacer uso de las estructura de datos estndar: string, list y map. Su procesado es rpido y eficaz. Se recomienda incorporar macros a las plantillas cuando se prevea una reutilizacin del mismo en varios puntos del documento o cuando la operacin de renderizado se presuponga compleja. En este ltimo caso el macro deber mostrar una interfaz clara en su llamada que aporte la mxima claridad a la plantilla. Se recomienda escapar de utilizar llamadas a macros de manera recursiva. Se recomienda delegar el menor trabajo posible al generador de documentos. A pesar de que incorporan cierta potencia de calculo, operaciones y operadores, manejo avanzado de estructuras de datos, etc prescindir cuando sea posible de ello, delegando esos clculos a nuestra aplicacin y dejando que el compositor de documentos slo realice la tarea de renderizado, la de dibujar el documento, es decir los datos que alimentan la plantilla, deben de ir adecuadamente tratados y formateados.
153 de 191
Framework Atlas
Normativa 9.7.3 GESTION DE DOCUMENTOS EXCEL
La solucin del framework Atlas para la generacin o modificacin de ficheros Excel es Jakarta POI.
NORMA
SOLExcel Para la gestin de documentos Excel en las aplicaciones del framework Atlas se utilizar la librera Jakarta POI.
Desde las aplicaciones se usuar directamente este API desde la capa de negocio.
154 de 191
Framework Atlas
Normativa 9.7.4 GESTION DE DOCUMENTOS PDF
Para la generacin y manipulacin dinmica de PDFs se deber utilizar la librera iText. Se debera utilizar esta librera en casos como: Generacin dinmica de documentos PDF mediante APIs de desarrollo en base a varias alternativas de fuentes de datos como bases de datos, ficheros XML, etc. Crear mapas, libros electrnicos, dotar de interactividad a documentos PDF. Aadir bookmarks, nmeros de pgina, filigranas, etc. Dividir y concatenar documentos pdf.
NORMA
SOLPDF Para la generacin de documentos PDF desde las aplicaciones del framework Atlas se utilizar la librera IText.
A pesar de que iText permite la generacin de documento RTF, para esta finalidad ha de emplearse Velocity, ya que es un mecanismo ms flexible y potente.
155 de 191
Framework Atlas
Normativa 9.7.5 GENERACION DE GRAFICOS
Para la generacin de grficos se utilizar la librera JFreeChart, una librera 100% Java que permite desarrollar grficos, para poder incluirlos en aplicaciones, documentos e informes. Con JFreeChart podremos hacer diferentes tipos de grficos que van desde los tipos comunes tales como grficos circulares , grficos de barras , reas , grficos de lnea , histogramas , diagramas de Gantt y ms especficos y menos frecuentemente utilizados como tipos Candlestick, Viento y Wafer Map. Tambin se puede usar la familia Chart de Jenia4faces, que ofrece componentes JSF para la inclusin de grficas realizadas mediante JFreeChart en una aplicacin JSF.
NORMA
SOLGraficos La generacin de grficos de las aplicaciones del framework Atlas se har con la librera JFreeChart y los componentes visuales Jenia4Faces.
SOLGraficosGrandes
PRACTICA
BUENA
Como norma general se recomienda tener especial cuidado con imgenes de JFreeChart que ocupen mucho espacio y puedan saturar el ancho de banda en aplicaciones con interfaz Web.
156 de 191
Framework Atlas
Normativa 9.7.6 MANIPULACION DE ARCHIVOS MULTIMEDIA
En muchas ocasiones surge la necesidad de utilizar un API que permita la incorporacin de archivos audio, video, sonido u otro tipo de archivos multimedia en aplicaciones Java, extendiendo las capacidades multimedia por defecto de la plataforma Java 2 Standard Edition. La tecnologa Java Media FrameWork API (JMF) permite manipular y gestionar ficheros de audio, video u otros archivos multimedia que formen parte integral de aplicaciones y applets. Este paquete opcional acta sobre mltiples formatos, proporcionando a desarrolladores un control adicional escalable e independiente de la plataforma de proceso y renderizado de archivos multimedia. JMF esta diseada en base a plugins proporcionando acceso directo a recursos multimedia y aportando a JMF las caracterticas necesarias para personalizarlo y extenderlo en base a necesidades especficas.
SOLMultimedia El API JMF 2.X ser la tecnologa a utilizar para cualquier manipulacin sobre archivos multimedia. Este API no esta incluida por defecto en la plataforma Java 2 Standard Edition.
NORMA
Cuando se necesite extender las capacidades de la tecnologa JMF en referencia a la manipulacin de ficheros de imagen se podr recurrir a las APIs Java 2D, Java advanced Image (JAI) y JAI Image I/O. Se deber utilizar el API Java 3D cuando se requieran capacidades adicionales sobre manipulaciones y renderizados de imgenes en tres dimensiones.
157 de 191
Framework Atlas
Normativa 9.7.7 Acceso a plataforma y dispositivos locales
La plataforma local define los elementos, herramientas, servicios y productos residentes en la mquina de cada usuario para dar soporte a la ejecucin de las aplicaciones de la organizacin cubriendo la extensin de las aplicaciones web de cara a interactuar con elementos residentes en la plataforma local, como pueden ser dispositivos y aplicaciones.
NORMA
SOLAccesoLocal Para la integracin con los dispositivos y aplicaciones de la plataforma local se utilizarn y desarrollarn componentes de tipo Applet.
158 de 191
Framework Atlas
Normativa 9.7.8 XML
Algunas aplicaciones necesitan gestionar ficheros XML. Para facilitar la gestin de los mismos se utilizar la librera JAXB. JAXB aporta una forma sencilla de asociar un esquema XML a su representacin en cdigo Java. Esto hace simple el manejo de datos XML desde Java, sin necesidad de conocer mucho acerca de XML. JAXB consta de 3 componentes principales: El compilador de esquema, que transforma el esquema en una serie de elementos requeridos para el proceso de lectura ( unmarshalling) y escritura (marshalling) de un XML. El generador de esquema, que convierte estos elementos (descritos mediante anotaciones Java) a un esquema XML. El framework de asociacin (binding), que ofrece las operaciones de lectura (unmarshalling) y escritura (marshalling) para el acceso, manipulacin y validacin de contenido XML usando los elementos generados mediante las herramientas anteriores. El siguiente esquema muestra un diagrama de funcionamiento de estos elementos:
SOLXML
NORMA
Cuando las aplicaciones necesiten trabajar con ficheros XML, tanto para generarlos como para leerlos, se utilizar la implementacin de referencia de JAXB (Java Architecture for XML Binding). Para facilitar su localizacin y que la herramienta de validacin no de errores las clases generadas por jaxb se incluirn en un subpaquete llamado jaxb.
Los pasos para realizar la asociacin entre un documento XML y un objeto Java con JAXB son los siguientes:
159 de 191
Framework Atlas
Normativa 1. Generar las clases Java (a partir del esquema XML). Recordar que se deben incluir en un subpaquete llamado jaxb de alguno de los paquetes de nuestra aplicacin. 2. Compilar las clases. 3. Leer el documento origen (unmarshall). 4. Generar el rbol de contenido. El proceso de lectura genera un rbol de contenido a partir de las clases generadas. 5. Validar: antes de generar el rbol de contenido a partir del XML origen se puede validar dicho documento. Tambin se puede validar el documento a generar (cuando sea el caso). 6. Procesar el contenido. La aplicacin cliente puede modificar los datos del documento XML que representa el rbol de contenido a travs de los interfaces generados por el compilador 7. Escritura (marshall), esto es, generar uno o ms documentos XML a partir del rbol de contenidos. Como se dijo anteriormente, el contenido puede ser validado antes de este proceso.
La siguiente imagen muestra de forma grfica el proceso descrito:
Figura 5 : Asociacin de un documento XML con un objeto Java
160 de 191
Framework Atlas
Normativa 9.7.9 ENVIO DE CORREO
El framework Spring ofrece una librera de utilidad para enviar correos electrnicos abstrayendo al usuario de la configuracin especfica para cada sistema de mensajera, responsable del manejo de recursos a bajo nivel que normalmente ha de implementar el cliente.
SOLCorreo
NORMA
Para el envo de correo desde las aplicaciones se emplear la utilidad de envo de correo que aporta el framework de Spring. Dicha utilidad permite el envo de correo de una forma sencilla mediante JavaMail, realizando la configuracin mediante inyeccin de dependencias.
En primer lugar hay que definir un bean de Spring para enviar correos.
Bean encargado del envio de correos <bean id="mailSender" class="org.springframework.mail.javamail.JavaMailSenderImpl"> <property name="host"> <value>${mail.host}</value> </property> </bean>
Se crearn plantillas para las distintas tipologas de correo electrnico que la aplicacin enve. De esta forma no ser necesario escribir en el cdigo aspectos como el destinatario, el asunto, etc. Ejemplo de bean de mensaje <bean id="cursosMailMessage" class="org.springframework.mail.SimpleMailMessage"> <property name="from"> <value>${xxxx.cursomail.from}</value> </property> <property name="subject"> <value>Listado de cursos</value> </property> </bean>
161 de 191
Framework Atlas
Normativa Ejemplo de bean de servicio que enva correo <bean id="cursosService" class="ejpl.gestion.services.CursosServiceImpl"> <property name="mailSender"><ref bean="mailSender"/></property> <property name="message"><ref bean="cursomailMessage"/></property> <bean>
Para hacer uso de los beans inyectados anteriormente, simplemente se declararn los atributos respectivos en el servicio, con sus mtodos set correspondientes.
Ejemplo de envio de correo ..... private MailSender mailSender; private SimpleMailMessage mailMessage; public void setMailSender(MailSender mailSender) { this.mailSender = mailSender; } public void setMailMessage(SimpleMailMessage mailMessage) { this.mailMessage = mailMessage; } public void sendCourseEnrollmentReport() { Set courseList = courseDao.findAll(); SimpleMailMessage message = new SimpleMailMessage(this.mailMessage); StringBuffer messageText = new StringBuffer(); messageText.append("Los cursos son los siguientes:\n\n"); for(Iterator iter = courseList.iterator(); iter.hasNext(); ) { Course course = (Course) iter.next(); messageText.append(course.getId() + " "); messageText.append(course.getName() + " "); int enrollment = courseDao.getEnrollment(course); messageText.append(enrollment); } message.setText(messageText.toString()); msg.setTo(); try { mailSender.send(message); } catch (MailException e) { .
162 de 191
Framework Atlas
Normativa } } .....
Cuando el contenido de los correos electrnicos manejados por la aplicacin sea complejo, se emplear el mecanismo de plantillas que ofrece Velocity para crear plantillas avanzadas para envo de correo electrnico. Estas plantillas se podrn crear en formato HTML y se almacenaran en la carpeta plantillas.
Ejemplo de plantilla de correo <html> <body> <h3>Hi ${user.userName}, welcome to the Chipping Sodbury On-the-Hill message boards!</h3> <div>Your email address is <a href="mailto:${user.emailAddress}">${user.emailAddress}</a>. </div> </body> </html>
De esta forma se pueden crear plantillas de correo mediante cualquier editor (por ejemplo, con un editor de HTML), y definir variables que se establecern en tiempo de ejecucin para el mensaje de correo.
Para usar Velocity desde un servicio Spring, simplemente se le ha de pasar mediante inyeccin de control el bean de Spring que maneja el motor de Velocity, y usarlo en el cdigo de envo de correo de la forma tradicional:
Bean de Spring para Velocity <bean id="velocityEngine" class="org.springframework.ui.velocity.VelocityEngineFactoryBean"> <property name="velocityProperties"> <value>resource.loader=class class.resource.loader.class= org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader </value> </property> </bean>
163 de 191
Framework Atlas
Normativa Para enviar el mensaje, ahora es necesario hacer uso de un mensaje MIME (estamos enviando un mail en HTML), para lo cual usamos el interfaz de MimeMessagePreparator de Spring: Ejemplo de envio de correo con plantilla personalizada private void sendConfirmationEmail(final User user) { MimeMessagePreparator preparator = new MimeMessagePreparator() { public void prepare(MimeMessage mimeMessage) throws Exception { MimeMessageHelper message = new MimeMessageHelper(mimeMessage); message.setTo(user.getEmailAddress()); message.setFrom("from@email.com"); // Se establecen los campos a mapear en el correo Map model = new HashMap(); model.put("user", user); String text = VelocityEngineUtils.mergeTemplateIntoString( velocityEngine, "plantillas/correo.vm", model); message.setText(text, true); } }; this.mailSender.send(preparator); } }
164 de 191
Framework Atlas
Normativa 9.7.10 ENVIO DE SMS La Comunidad de Madrid dispone de una plataforma desarrollada por Telefnica Soluciones para el envo y recepcin de mensajes SMS, que recibe el nombre de MenTeS (Mensajera de Telefnica Soluciones). Sobre esta plataforma se ha desarrollado un servicio web que ofrecer una interfaz estndar para el acceso a estas funcionalidades desde cualquier tipo de aplicativo. El siguiente diagrama muestra la arquitectura del sistema:
Figura 6 : Arquitectura de la plataforma de SMS Para el envo de mensajes SMS se utilizar el servicio de envo de SMS que invoca a los servicios web . Para ms informacin consultar el manual ATLAS_MUS_Servicio_Envio_SMS.
165 de 191
Framework Atlas
Normativa 9.7.11 VISOR DE MAPAS Dentro del framework Atlas se ha incorporado un componente visor de mapas permite mostrar mapas de GIS y operar con ellos en aplicaciones Atlas. Tiene las siguientes caractersticas: Permite personalizar el tamao del marco en el que se muestra el mapa. Dos modos de renderizado: en un marco en pantalla o en un panel popup. Personalizacin del mapa y los componentes que lo forman mediante la modificacin de los ficheros de configuracin de GIS. A continuacin se muestra un ejemplo del componente en modo popup:
Para ms informacin consultar el manual ATLAS_MUS_Componente_Visor_Mapas.
166 de 191
Framework Atlas
Normativa 9.7.12 SERVICIOS WEB La invocacin y generacin de servicios web de ATLAS se basa en los siguientes elementos: Axis2 Mdulo de seguridad Rampart Mdulo de seguridad para webservices de ATLAS Plataforma multipki ASF
Para la creacin de nuevos servicios web se partir de un arquetipo especfico para servicios web. Los servicios web desarrollados implementaran adems del propio servicio web una librera cliente para dicho servicio que facilitar la integracin de este servicio web en otros proyectos Atlas. Para ms informacin consultar el manual ATLAS_MUS_Servicios_Web.doc. Los servicios web que tengan que implementar seguridad lo harn segn el estandar de WS Security que incluye la seguridad en el propio mensaje SOAP. Dentro de este modelo de seguridad existen las siguientes posibilidades: Ambas posibilidades se pueden combinar. Firmado digital del mensaje SOAP Garantiza la procedencia del mensaje, integridad de los datos y no repudio. Cifrado del mensaje SOAP Garantiza la confidencialidad del mensaje.
Se puede realizar el control de acceso sobre el cliente que ha firmado el mensaje. Al cifrar el mensaje no es necesario cifrar el canal de comunicacin.
WSSECURITY
NORMA
Cuando el servicio web que se desarrolle tengan que implementar seguridad lo har con WS Security con los mecanismos de firma y/o cifrado de mensaje SOAP. Cualquier otro tipo de seguridad ha de ser autorizado previamente por la Unidad de Arquitectura de Aplicaciones.
167 de 191
Framework Atlas
Normativa 10 HERRAMIENTAS
El framework ATLAS ofrece principalmente dos herramientas de apoyo al desarrollo de aplicaciones que aseguran la calidad de los desarrollos realizados, y que se describen en los siguientes apartados. 10.1 VALIDACION DE NORMATIVA La Herramienta de Validacin tiene como objetivo principal la comprobacin del cumplimiento de la normativa Atlas sobre un proyecto o mdulo. Esta herramienta valida los siguientes tipos de recursos de un proyecto: Valida las clases java. Valida los ficheros de configuracin. Valida la estructura de directorios.
Dicha herramienta est implementada como un plugin que ya viene preinstalado y correctamente configurado con los arquetipos de Atlas para su ejecucin directa a travs de ciertas etiquetas de Maven.
VALFrecuente
PRACTICA
BUENA
Se deber ejecutar la herramienta de validacin de la normativa frecuentemente desde el inicio del proyecto (no slo al final del proyecto) con el fin de evitar que los incumplimientos de la normativa se vayan acumulando a lo largo del desarrollo y esto suponga carga adicional de trabajo.
La herramienta de validacin se distribuye como versin snapshot de maven ya que no todas las normas incluidas en este documento se han implementado en su totalidad. Por otro lado no es posible automatizar la comprobacin de todas las normas, lo que no significa que el proveedor no deba cumplirlas. Por lo tanto es posible que durante el desarrollo de la aplicacin aparezcan nuevas versiones de la herramienta de validacin. Estas nuevas versiones en ningn caso incluirn validacin de nuevas normas sino que podrn validar normas ya definidas en la versin del framework pero que anteriormente no se estaban validando (y por tanto el proveedor ya debera estar cumpliendo, independientemente de que anteriormente la herramienta las validase o no). Por todo lo anteriormente indicado, el hecho de que la herramienta de validacin de la normativa no indique errores en un proyecto no implica que dicho proyecto cumpla al 100% con todas las normas de la normativa del framework, aunque s asegura un porcentaje alto de cumplimiento.
168 de 191
Framework Atlas
Normativa Existen casos excepcionales en los que ICM autoriza previamente que no se le aplique alguna de las normas. Estos casos deben ser autorizados utilizando la solicitud correspondiente que firmar el rea de Aplicaciones Especiales y Arquitectura de software. Esta autorizacin deber ser incluida en la entrega e informado en la ficha de entrega. El plugin permite la opcin de excluir normas, de modo que no se comprueben en la ejecucin de la herramienta. El arquetipo ya viene preparado para excluir una norma. La exclusin de normas se hace desde el fichero pom.xml. Los arquetipos incorporan la configuracin de exclusin de normas comentada. Se debe activar dicho cdigo y en la propiedad excluidas aadir los nombres de las normas que se quieran excluir separados por comas. Solo se incluirn aqu las normas que haya autorizado ICM. A continuacin se muestra el ejemplo en el arquetipo web.
pom.xml <plugin> <groupId>atlasfrm</groupId> <artifactId>atlasfrm-validacion-pluginreglas</artifactId> <version>${atlasfrm-validacion-pluginreglas.version}</version> <executions> <execution> <phase>site</phase> <goals> <goal>check</goal> </goals> </execution> </executions> <configuration> <moduleType>web</moduleType> <excluidas>ADLob</excluidas> </configuration> </plugin>
VALEXCLUDE Toda autorizacin excepcional a alguna norma de la normativa debe estar previamente autorizada por ICM.
NORMA
La solicitud de autorizacin se har mediante el formulario de autorizacin correspondiente y una vez firmado por el rea de Aplicaciones Especiales y Arquitectura de Software ser incluido en la documentacin del proyecto. En las entregas se deber informar en la ficha de entrega sobre la autorizacin. El fichero pom.xml de la aplicacin deber contemplar la exclusin de esta regla.
169 de 191
Framework Atlas
Normativa
Para ms informacin sobre el uso de la herramienta consultar el manual Error! No se encuentra el origen de la referencia. 10.2 VALIDACION DE CODIFICACION JAVA Un estndar de codificacin adecuado y buen diseo orientado a objetos son prcticas que deben estar presentes en todos los proyectos. Es necesario imponer una normalizacin a la hora de desarrollar cdigo debido a diferentes factores que facilitarn el mantenimiento posterior y costes econmicos derivados de tal actividad. Un porcentaje elevado del coste del software va asociado a su mantenimiento. Las aplicaciones son dinmicas, crecen y se modifican, requieren de mantenimiento y evolucin. Las convenciones de cdigo nos facilitarn la interpretacin fcil de nuestro cdigo, ms rpida y ms clara. Debemos pues garantizar el cumplimiento con estas convenciones. Para todos los desarrollos en Java con el framework Atlas se deben utilizar las convenciones de cdigo para el lenguaje de programacin Java de SUN Microsystems. Estas convenciones estn disponibles en la url: http://java.sun.com/docs/codeconv/ El uso de convenciones de cdigo se debe realizar desde la primera linea de cdigo que se implemente y no esperar a que se haya finalizado el desarrollo ya que en este caso el coste del cambio es muy elevado. La herramienta Eclipse nos permite mediante determinados plugins validar que se estan cumpliendo estas convenciones. Dentro del framework Atlas se han personalizado los ficheros de reglas para que se realicen las validaciones que el framework requiere. La validacin se debe realizar segn se van codificando las clases. En el caso de que ya tengamos cdigo desarrollado y queramos ajustarlo a esta codificacin Eclipse dispone de utilidades que nos permiten formatear el cdigo para que se cumplan muchas de las reglas que se validan. Las herramientas que se van a utilizar para la validacin son:
Herramientas Code Style Formatter de Eclipse Code Style Clean up de Eclipse Plugin de Checkstyle Incluido en eclipse Incluido en eclipse
URL
http://eclipse-cs.sourceforge.net/
170 de 191
Framework Atlas
Normativa Plugin de PMD http://pmd.sourceforge.net/
PMD: Conjunto de reglas basadas en el anlisis de cdigo Java que identifica problemas como cdigo muerto, posibles bugs, etc... Checkstyle: Herramienta para el anlisis esttico de cdigo usado para chequear que el cdigo fuente Java cumple con unas reglas de codificacin determinadas. El framework proporciona los siguientes ficheros de reglas:
Fichero ATLAS_JAVA_CC_CS.xml
Descripcin Fichero con las reglas de checkstyle del framework Atlas
ATLAS_JAVA_CC_PMD.xml
Fichero con las reglas de pmd del framework Atlas
ATLAS_JAVA_CC_ECLIPSE_CLEANUP_PROFILE.xml
Fichero con las opciones para la utilidad de cleanup de Eclipse
ATLAS_JAVA_CC_ECLIPSE_FORMATTER_PROFILE.xml Fichero con las opciones para la utilidad de formatter de Eclipse.
Para ms informacin sobre el uso de estas utilidades consultar el manual Error! No se encuentra el origen de la referencia..
NORMA
CSPMD Los mdulos desarrollados debern cumplir las reglas de checkstyle y pmd especficas del framework Atlas.
CODFrecuente Se recomienda ejecutar frecuentemente las herramientas proporcionadas por el framework
PRACTICA
BUENA
Atlas para validar que se cumplen las normas de codificiacin Java (herramientas Checkstyle y PMD), con el fin de evitar que los incumplimientos de la normativa se vayan acumulando a lo largo del desarrollo y esto suponga carga adicional de trabajo. Puede configurarse el entorno de desarrollo Eclipse para que compruebe las normas de Checkstyle y PMD en caliente, al tiempo que el programador va desarrollando la aplicacin.
171 de 191
Framework Atlas
Normativa 10.3 GENERACION AUTOMTICA DE CODIGO A partir de la versin 1.2.0 del framework de desarrollo de aplicaciones ATLAS, se incluye una herramienta de generacin automtica de cdigo. Esta herramienta permite, a partir de un modelo de datos, generar cdigo para gestionar las operaciones bsicas (alta, baja, modificacin y consulta) de ese modelo de datos de acuerdo a la normativa del framework Atlas en las distintas capas de la aplicacin. La herramienta nos permite seleccionar las tablas de las que queremos generar el cdigo, y a partir de ellas realiza una ingeniera inversa del modelo de datos y genera el cdigo en la aplicacin. Para el desarrollo de la herramienta se ha tomado como punto de partida el plugin JBoss Hibernate Tools, y se ha personalizado su configuracin para adaptarlo a las necesidades propias de ATLAS.
GENCOD Se recomienda al inicio del desarrollo utilizar la herramienta de generacin automtica de codigo del framework Atlas. El cdigo generado por la herramienta va a reducir el coste/tiempo de desarrollo del proyecto ya que nos va a generar el cdigo requerido por el framework Atlas para el acceso a base de datos en las operaciones bsicas de alta, baja, modificacin y consulta y en el caso de mantenimiento de catlogos nos va a generar tambin las pantallas de usuario que permiten la gestin del catlogo en las operaciones bsicas tal y como se ha indicado.
PRACTICA
BUENA
Atencin El cdigo fuente generado es un punto de partida para el desarrollo. Lo generado se debe evolucionar para adaptarlo a las necesidades y requisitos especficos del proyecto.
A continuacin se muestran, para cada una de las capas del framework Atlas, los diagramas de clases del cdigo que se genera. Se ha tomado como ejemplo una entidad de base de datos llamada Expediente. Para una descripcin ms detallada de este cdigo y conocer como utilizar la herramienta se debe consultar el manual ATLAS_MUS_Generador_Codigo que se puede encontrar en la seccin Desarrollos Atlas->Herramientas del portal de arquitectura.
172 de 191
Framework Atlas
Normativa 10.3.1 ACCESO A DATOS En la capa de acceso a datos la herramienta va a generar las clases que la normativa del framework Atlas determina (Clases de dominio y DAOS) para las operaciones bsicas de consulta, alta, baja y modificacin. Adems se van a realizar las correspondientes actualizaciones en los ficheros de configuracin de Spring para que estas clases puedan ser usadas desde los servicios de negocio.
Clases generadas para la capa de acceso a datos

class Acceso a Datos interface dao::BaseDAO + + + + + + + + + + + + + + findAll() : List<T> countAll() : Long findAllDistinct() : List<T> countAllDistinct() : Long find(PK) : T find(int, int, AtlasOrder[], AtlasQuery) : List<T> count(AtlasQuery) : int exists(PK) : boolean insert(T) : T insertOrUpdate(T ) : void update(T ) : void delete(PK) : void delete(T ) : void findByNamedQuery(String, Map<String, Object>) : List<T> java.io.Serializable interface dao:: ExpedienteDAO domain::Expediente + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + serialVersionUID: long = 1L {readOnly} idExpediente: Integer oficina: Oficina cdExpediente: String dsExpediente: String itEstado: String fcAlta: Date fcModif: Date clDsExtendida: Clob nmCdUadmin: Integer expeInteresados: Set<ExpeInteresado> = new HashSet<Exp... expeArchivos: Set<ExpeArchivo> = new HashSet<Exp... Expediente() Expediente(Integer) Expediente(Integer, Oficina, String, String, String, Date, Date, Clob, Integer, Set<ExpeInteresado>, Set<ExpeArchivo>) getIdExpediente() : Integer setIdExpediente(Integer) : void getPKAsString() : String getPKFromString(String) : Integer getOficina() : Oficina setOficina(Oficina) : void getCdExpediente() : String setCdExpediente(String) : void getT extoListaValores() : String getDsExpediente() : String setDsExpediente(String) : void getItEstado() : String setItEstado(String) : void getFcAlta() : Date setFcAlta(Date) : void getFcModif() : Date setFcModif(Date) : void getClDsExtendida() : Clob setClDsExtendida(Clob) : void getNmCdUadmin() : Integer setNmCdUadmin(Integer) : void getExpeInteresados() : Set<ExpeInteresado> setExpeInteresados(Set<ExpeInteresado>) : void getExpeArchivos() : Set<ExpeArchivo> setExpeArchivos(Set<ExpeArchivo>) : void toString() : String equals(Object) : boolean hashCode() : int
T PK:extends Serializable HibernateDaoSupport dao::BaseDAOImpl + + + + + + + + + + + + + + + + # logger: Log = LogFactory.getL... {readOnly} persistentClass: Class<T> BaseDAOImpl(Class<T>) BaseDAOImpl(Class<T>, SessionFactory) findAll() : List<T > countAll() : Long findAllDistinct() : List<T > countAllDistinct() : Long find(PK) : T find(int, int, AtlasOrder[], AtlasQuery) : List<T> count(AtlasQuery) : int findInternal(AtlasOrder[], AtlasQuery, boolean) : Criteria exists(PK) : boolean insert(T ) : T insertOrUpdate(T) : void update(T) : void delete(PK) : void delete(T ) : void findByNamedQuery(String, Map<String, Object>) : List<T> getLog() : Log
dao::ExpedienteDAOImpl + ExpedienteDAOImpl()
expedienteDAO : ExpedienteDAOImpl
Bean de Spring para utilizar desde los servicios de negocio.
173 de 191
Framework Atlas
Normativa 10.3.2 SERVICIOS DE NEGOCIO En la capa de servicios de negocio la herramienta va a generar las clases que la normativa del framework Atlas determina (Fachada y Servicios) para las operaciones bsicas de consulta, alta, baja y modificacin invocando para su ejecucin a los DAOs de la capa de acceso a datos. Adems va a realizar las correspondientes configuraciones para incluir objetos de estos servicios en el contexto de Spring..
Cdigo generado para la capa de servicio de negocio

class Serv icio interface serv ices::BaseServ ice + + + + + + + + + + + + + + + + setDao(D) : void getDao() : D findAll() : List<T > countAll() : Long findAllDistinct() : List<T > countAllDistinct() : Long find(PK) : T find(int, int, AtlasOrder[], AtlasQuery) : List<T > count(AtlasQuery) : int exists(PK) : boolean insert(T) : T insertOrUpdate(T) : void update(T ) : void delete(PK) : void delete(T) : void findByNamedQuery(String, Map<String, Object>) : List<T>
facade::PruebasFacadeImpl interface serv ices:: ExpedienteServ ice -expedienteService + + + + + + + + + expedienteService: ExpedienteService setExpedienteService(ExpedienteService) : void findExpediente(int, int, AtlasOrder[], AtlasQuery) : List<Expediente> findExpediente(Integer) : Expediente countExpediente(AtlasQuery) : int insertExpediente(Expediente) : void updateExpediente(Expediente) : void insertOrUpdateExpediente(Expediente) : void deleteExpediente(Expediente) : void deleteExpediente(Integer) : void
T PK:extends Serializable D:extends BaseDAO<T, PK> serv ices::BaseServ iceImpl + + + + + + + + + + + + + + + + logger: Log = LogFactory.getL... {readOnly} dao: D setDao(D) : void getDao() : D findAll() : List<T > countAll() : Long findAllDistinct() : List<T> countAllDistinct() : Long find(PK) : T find(int, int, AtlasOrder[], AtlasQuery) : List<T > count(AtlasQuery) : int exists(PK) : boolean insert(T ) : T insertOrUpdate(T ) : void update(T) : void delete(PK) : void delete(T) : void findByNamedQuery(String, Map<String, Object>) : List<T > expedienteDAO : ExpedienteDAOImpl expediente : Expediente
interface facade::PruebasFacade + + + + + + + + findExpediente(int, int, AtlasOrder[], AtlasQuery) : List<Expediente> findExpediente(Integer) : Expediente countExpediente(AtlasQuery) : int insertExpediente(Expediente) : void updateExpediente(Expediente) : void insertOrUpdateExpediente(Expediente) : void deleteExpediente(Expediente) : void deleteExpediente(Integer) : void
serv ices:: ExpedienteServ iceImpl
expedienteServ ice : ExpedienteServ iceImpl
pruebasFacade : PruebasFacadeImpl
Bean de Spring para ser usado desde los beans de respaldo de JSF
174 de 191
Framework Atlas
Normativa 10.3.3 PRESENTACION En la capa de presentacin se generan para cada una de las entidades/tablas unas pantallas que nos permitan realizar el mantenimiento bsico de dicha tabla. La generacin de la parte de presentacin est pensada como una solucin para generar el cdigo asociado al mantenimiento de ctalogos que tipicamente podemos encontrar en las aplicaciones. A continuacin se muestra el cdigo generado en la capa de presentacin: Cdigo generado: Presentacin
class Presentacion listaExpediente.xhtml formularioExpediente.xhtml
expedienteBean : ExpedienteBean
expedienteBean : ExpedienteBean Managed Bean para ser usado desde las pginas JSF
j sf::ExpedienteBean + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + serialVersionUID: long = 1L {readOnly} facade: PruebasFacade orderAndFilter: OrderAndFilterBean = null entidad: Expediente = null listaValoresOficina: ListaValores textoOficina: String oficinaFilter: String cdExpedienteFilter: String dsExpedienteFilter: String itEstadoFilter: String fcAltaFilter: Date fcModifFilter: Date scroller: UIDataScroller = new UIDataScroller() ExpedienteBean() getEntidad() : Expediente setEntidad(Expediente) : void getFacade() : PruebasFacade setFacade(PruebasFacade) : void getTimeZone() : TimeZone getOrderAndFilter() : OrderAndFilterBean setOrderAndFilter(OrderAndFilterBean) : void obtener(int, int, Object, Object) : List<Expediente> obtenerTotal(Object) : int cargar() : String cargar(ActionEvent) : void eliminar() : String eliminar(ActionEvent) : void confirmarEliminar() : String confirmarEliminar(AjaxBehaviorEvent) : void guardar() : String nuevo() : String volver() : String getListaValoresOficina() : ListaValores setListaValoresOficina(ListaValores) : void setTextoOficina(String) : void getTextoOficina() : String obtenerListaOficina(int, int, Object, Object) : List<AtlasHashMap> obtenerTotalOficina(Object) : int getOficinaFilter() : String setOficinaFilter(String) : void getCdExpedienteFilter() : String setCdExpedienteFilter(String) : void getDsExpedienteFilter() : String setDsExpedienteFilter(String) : void getItEstadoFilter() : String setItEstadoFilter(String) : void getFcAltaFilter() : Date setFcAltaFilter(Date) : void getFcModifFilter() : Date setFcModifFilter(Date) : void getScroller() : UIDataScroller setScroller(UIDataScroller) : void filtrar() : String setIdOficina(String) : void getRequiredMessage() : String
interface facade::PruebasFacade + + -facade + + + + + + countExpediente(AtlasQuery) : int insertExpediente(Expediente) : void updateExpediente(Expediente) : void findExpediente(int, int, AtlasOrder[], AtlasQuery) : List<Expediente> findExpediente(Integer) : Expediente insertOrUpdateExpediente(Expediente) : void deleteExpediente(Expediente) : void deleteExpediente(Integer) : void
-entidad
java.io.Serializable domain::Expediente
175 de 191
Framework Atlas
Normativa
A continuacin se muestran ejemplos de pantallas generadas para el mantenimiento de la entidad Expediente.
Ejemplo de pgina xhtml generada Listado: listaExpediente.xhtml
Desde esta pantalla nos permite realizar las siguientes operaciones: Bsqueda basada en filtros Nuevo elemento: Accede a la pantalla de alta Eliminacin Edicin: Accede a la pantalla de edicin
Caractersticas de esta pantalla: Filtros: o o Para cada campo de la tabla de tipo Textual se genera un <inputText> para buscar en ese campo. En el caso de que un campo sea una foreign key de una tabla se genera un <inputText> para buscar en el primer campo de tipo texto de la tabla fornea. Tabla de resultados: o o Ordenacin por columnas Paginacin
176 de 191
Framework Atlas
Normativa
Ejemplo de pgina xhtml generada Pgina de alta y edicin: formularioExpediente.xhtml
Caractersticas de esta pantalla: Para los campos que son foreign key de otra tabla se genera un <inputText> asociado a una lista de valores. Para los campos de tipo Date se genera un campo de tipo Calendario Resto de campos se genera un <inputText> de tamao fijo Cada campo lleva asociado un enlace a una ayuda de contexto Los campos generados de tipo <inputText> cuyo valor es obligatorio (en la tabla de base de datos tienen la propiedad NOT NULL) se marcan en amarillo, y si no se rellenan se muestra un mensaje de error indicndolo.
177 de 191
Framework Atlas
Normativa
11
PRUEBAS
El desarrollo de software requiere e implica la construccin de aplicaciones de forma robusta, extensible y escalable. Conseguir dichos objetivos requiere la aplicacin de una metodologa de desarrollo que incluya la realizacin de pruebas de software precisas. El objetivo de las pruebas de software es asegurar que el producto final cumple todas las funcionalidades requeridas por los usuarios. Para conseguir dicho objetivo, los encargados de realizar las pruebas tendrn que revisar el producto final y concluir si los requisitos iniciales son completamente satisfechos. La ejecucin de pruebas es tan importante que se debe hacer durante todo el tiempo y a lo largo del ciclo de vida de desarrollo del software. Mediante las pruebas de software es posible demostrar formalmente que las especificaciones funcionales y tcnicas se cumplen. Un software probado contendr menos errores y ser ms seguro. Por otro lado, la demora en la correccin de errores software hace que sea ms costosa su deteccin y eliminacin. Si un error es detectado en el mismo momento en el cual el desarrollador hace un cambio, ser probable que pueda arreglarlo en ese instante. Por el contrario si un error no es detectado hasta despus de la entrega parcial o final el coste de su deteccin se dispara, adems de la consiguiente prdida de confianza generada. Por ltimo comentar que la realizacin de pruebas permite poder refactorizar el cdigo con la seguridad de que el comportamiento seguir siendo correcto. La refactorizacin ayuda a resaltar o recuperar la claridad de un diseo que se ha ido complicando a causa de modificaciones o implementaciones posteriores. 11.1 TIPOS DE PRUEBAS Los tipos de pruebas a desarrollar en el momento de probar el software pueden ser categorizadas de diferente forma: Pruebas unitarias: Las pruebas unitarias ejercitan el funcionamiento de una unidad de cdigo, normalmente una clase aislada del resto de la aplicacin. Su objetivo es comprobar que su estructura es correcta y que se ajusta a la funcionalidad establecida previamente y aprobada en la fase de anlisis. Es muy importante incorporar la implementacin de pruebas unitarias a la metodologa de desarrollo, de modo que las pruebas unitarias se desarrollen a la vez que se implementa el cdigo, probando cada parte del cdigo que se desarrolla (test-driven development, o desarrollo guiado por las pruebas).
178 de 191
Framework Atlas
Normativa
TESTUnitarios Todos los bloques funcionales de la aplicacin debern contener Tests que realicen las pruebas unitarias de dicho bloque funcional. Para implementar las pruebas unitarias se utilizar como herramienta principal JUnit (los arquetipos ya vienen preparados para trabajar con esta herramienta). Se podrn utilizar objetos mock como los pertenecientes a las libreras JMock, Spring Mock, EasyMock y PowerMock.
NORMA
Se podrn utilizar herramientas a modo de extensin de JUnit como pueda ser DBUnit que mejoren y faciliten el proceso de pruebas unitarias. Las clases de testeo se deben incluir en la carpeta src/test/java. Desde de esta carpeta se crearan con la misma estructura de paquetes que se ha definido en el proyecto. Los recursos necesarios para ejecutar las pruebas (ficheros de configuracin, etc) se incluirn en la carpeta src/test/resources. Esta batera de pruebas nunca se deber incluir en el proyecto final que se despliegue en el entorno de produccin (esto ser controlado por maven en empaquetacin de la aplicacin).
Pruebas de integracin: Las pruebas integrales o pruebas de integracin son aquellas que se realizan en el mbito del desarrollo de software una vez que se han aprobado las pruebas unitarias. nicamente se refieren a la prueba o pruebas de todos los elementos unitarios que componen un proceso, hecha en conjunto, de una sola vez. Estas pruebas permiten comprobar que la unin de partes de software funcionan juntos y de forma correcta.
179 de 191
Framework Atlas
Normativa TESTIntegracion Para realizar los test de integracin se recomienda la utilizacin del paquete org.springframework.test spring-mock.jar que permite realizar pruebas de integracin mediante el contenedor Spring. Tambin se permite el uso de las libreras JMock, EasyMock y PowerMock
NORMA
Las clases de testeo se deben incluir en la carpeta src/test/java. Desde de esta carpeta se crearan con la misma estructura de paquetes que se ha definido en el proyecto. Los recursos necesarios para ejecutar las pruebas (ficheros de configuracin, etc) se incluirn en la carpeta src/test/resources. Esta batera de pruebas nunca se deber incluir en el proyecto final que se despliegue en el entorno de produccin (esto ser controlado por maven en empaquetacin de la aplicacin).
Pruebas funcionales (aceptacin): Las pruebas funcionales y de aceptacin permiten a los usuarios finales comprobar que toda la funcionalidad de la aplicacin est implementada. Puede involucrar procesos de pruebas automticas y parte manual aunque esto ltimo debe limitarse al mnimo. TESTAceptacion Para automatizar pruebas de aceptacin de mdulos web se utilizar la herramienta Selenium. Cuando las pruebas a realizar sean sobre servicios web, se utilizar la herramienta SoapUI.
NORMA
Los tests de Selenium deben ir incluidos en un mdulo del proyecto aparte llamado test, que se crea al generar el proyecto partiendo del arquetipo. Las clases de testeo se deben incluir en la carpeta src/test/java del mdulo test. Los recursos necesarios para ejecutar las pruebas con Selenium (ficheros de configuracin, etc) se incluirn en la carpeta src/test/resources del mdulo test.
Pruebas de servicios web: Las pruebas de los servicios web permiten a los clientes finales de los servicios web comprobar el correcto funcionamiento de los mismos adems de poder automatizarla
180 de 191
Framework Atlas
Normativa y repetir dichas pruebas en cualquier momento. Estas pruebas se realizan utilizando la herramienta SoapUI. TESTServiciosWeb Se implementarn pruebas en los mdulos de tipo webservice para cubrir los distintos mtodos expuestos en las interfaces de los distintos servicios web del mdulo.
NORMA
Para implementar las pruebas de servicios web se utilizar la herramienta SoapUI. Los tests de SoapUI deben ir incluidos en el submdulo del proyecto llamado test, que se crea al generar el proyecto partiendo del arquetipo. Los tests se deben incluir en la carpeta src/test/soapui del mdulo test.
Pruebas de carga y stress: Las pruebas de carga y stress evalan el rendimiento del sistema en base a los requisitos. Permite verificar el comportamiento del sistema en situaciones extremas, tanto en carga como en tiempo, donde los usuarios y peticiones se producen de forma concurrente.
TESTRendimiento Se implementarn pruebas de carga y estrs para las funcionalidades de la aplicacin en las que el rendimiento sea un factor a tener en cuenta.
NORMA
Para implementar las pruebas de carga y estrs se utilizar JMeter. Los tests de JMeter deben ir incluidos en un mdulo del proyecto aparte llamado test, que se crea al generar el proyecto partiendo del arquetipo. Los tests se deben incluir en la carpeta src/test/jmeter del mdulo test.
Pruebas de usabilidad: Las pruebas de usabilidad permiten comprobar que la aplicacin no solo cumple funcionalmente su cometido, sino que adems, es fcil e intuitivo su uso.
Revisiones de cdigo esttico: Una va de deteccin de muchos errores y de mejora de los diseos es la realizacin de revisiones de cdigo. Las revisiones de cdigo se realizan por el propio desarrollador y por otros desarrolladores. Es altamente recomendable realizar revisiones de cdigo peridicas, ya que mejoran la calidad del software tanto en diseo como en robustez. Este tipo de revisiones ya se han indicado en el apartado Validacin de codificacin Java.
181 de 191
Framework Atlas
Normativa
A continuacin se definen algunas normas generales para la ejecucin de pruebas:
NORMA NORMA
TESTAutomatizacion Se emplear Maven como herramienta para la ejecucin automtica de las pruebas y los informes de resultados de las mismas.
TESTCobertura La cobertura del cdigo debe incluir las ramas principales y de ms importancia en la aplicacin.
182 de 191
Framework Atlas
Normativa 11.2 PLAN DE PRUEBAS Un plan de pruebas debe ser interpretado como la piedra angular y en consecuencia el principal factor crtico de xito para la puesta en prctica de un proceso de pruebas que permita entregar un software de calidad ya que resumir, entre otras cosas, las actividades de prueba que se debern realizar. De tal forma, se puede definir el plan de pruebas como un documento que describe el alcance, enfoque, recursos y calendario de las actividades de prueba. Adems identificar elementos a evaluar, caractersticas, tareas, responsabilidades y prevendr de riesgos que quizs requieran un plan de contingencia. Identifica tems de prueba, caractersticas a ser probadas, tareas de prueba, quien realizar cada tarea y riesgos que quizs requieran un plan de contingencia. Adems, los planes de pruebas son especialmente tiles al tratarse de documentos sencillos de revisar, lo que confiere la posibilidad a individuos que pertenecen a roles distintos (equipo de ingenieros, responsables de proyecto, etc.) poder inspeccionarlo y adaptarlo a sus necesidades concretas.
TESTPlanPruebas Como parte de los entregables de los proyectos ser necesario entregar los planes de pruebas, los resultados de los mismos y un informe de evaluacin de dichos resultados. El plan de pruebas entregado por el proveedor tendr que incorporar (como mnimo) los siguientes elementos Identificador del plan de pruebas: El identificador ser de alguna forma mnemnica que permita relacionarlo con su alcance, por ejemplo: PP-Global (plan de pruebas global), PP-Aceptacion (plan de pruebas para pruebas de aceptacin), etc.
NORMA
Versin y la fecha del plan de pruebas. Alcance del plan de pruebas: Se deber especificar los requisitos que se van a probar con este plan. Por otra parte se debern indicar igualmente aquellos requisitos excluidos justificando los motivos por los cuales no se van a probar.
Configuracin necesaria Para cada uno de los siguientes tipos de pruebas incluir un apartado donde se especifiquen los casos de prueba, el instrumento o herramienta usada, donde pueden ser encontrados, cmo sern ejecutados y los datos que sern usados. Pruebas unitarias Pruebas de integracin Pruebas de aceptacin Pruebas de carga y estrs
183 de 191
Framework Atlas
Normativa 11.3 DOCUMENTACION DEL CODIGO La documentacin del cdigo debe explicar claramente que funcin realiza dicho cdigo y debe exponer toda funcionalidad interna que afecte a su comportamiento externo. Adems debe incluir informacin que permita identificar el autor del cdigo (el proveedor) para permitir una rpida resolucin del problema. Por otra parte, es necesario que se incluya informacin sobre la versin en la que se incluyeron nuevos mtodos o la etiqueta deprecated si el mtodo est obsoleto.
JAVADOC Todas las clases Java de las aplicaciones debern incluir tanto en sus mtodos como en sus
NORMA
}
propiedades las correspondientes etiquetas de Javadoc que permitan generar la documentacin correspondiente. Asimismo, todas las clases java deben incluir una cabecera en la que se muestre una descripcin de la clase, y en la que se incluya la etiqueta @author indicando el proveedor que realiza el desarrollo. El porcentaje de javadoc que se debe incluir es del 100%.
A continuacin se muestra un ejemplo de clase Java con la documentacin completa: package ejpl.comunes.general; import java.util.Properties; /** * Clase de ejemplo correctamente documentada con javadoc * @author ICM */ public class EjemploJavaDoc { /** identificador de serializacin */ private static final long serialVersionUID = 30460628734587345L; /** Ejemplo de variable */ public static final String CONSTANTE = "prueba"; /** * Ejemplo de mtodo documentado * @return un objeto de tipo {@link String} */ public String getValor() { return CONSTANTE; }
184 de 191
Framework Atlas
Normativa 12 ENTREGA
El proveedor desarrollar los distintos mdulos en sus instalaciones y posteriormente realizar la entrega al Responsable de Proyecto para que solicite a la Unidad de de Paso a Produccin el despliegue de la misma en el entorno de desarrollo. La Unidad de Paso a Produccin desempea actualmente las tareas de despliegue en el entorno de desarrollo durante la fase de construccin y hasta la puesta en produccin de la aplicacin.
La Unidad de Paso a Produccin dispone de un servidor SFTP para que los proveedores puedan realizar las entregas.
La entrega del proyecto de un proveedor externo al responsable de proyecto deber efectuarse mediante alguno de los siguientes mecanismos: Entrega de un CD/DVD al jefe de proyecto Entrega en el directorio del proveedor en el SFTP destinado a tal efecto
En cada entrega el proveedor deber cumplimentar una ficha de instalacin (disponible en la web) que deber enviar al responsable de proyecto para que la revise antes de solicitar la instalacin. La Unidad de Paso a Produccin se encargar de la compilacin y despliegue de los distintos mdulos entregados sin la asistencia del proveedor, por lo tanto la entrega deber tener la estructura de directorios exigida y todo el cdigo fuente, librerias, etc necesarios para la compilacin del proyecto. Pudiendo desestimarse la instalacin si no se cumple lo anterior.
ENTREGAParcial
PRACTICA
BUENA
A lo largo del ciclo de vida del desarrollo del proyecto es recomendable realizar al menos dos entregas intermedias a ICM, al 30% y 70% del desarrollo, no realizando una nica entrega final con todo el proyecto slo cuando est finalizado.
La Unidad de Paso a Produccin emitir un resumen de la realizacin de la instalacin al jefe de proyecto. Tras la primera instalacin de un proyecto la Unidad de Paso a Produccin crear el repositorio de subversion para el control de versiones de este proyecto. A partir de este momento las solicitudes a la Unidad de Paso a Produccin pueden hacerse bien con una nueva entrega en el servidor FTP o bien creando subiendo la entrega a subversin tal y como se indica en
185 de 191
Framework Atlas
Normativa el siguiente manual: http://www.madrid.org/arquitecturasw/images/documentacion/portal/actual/Guia_Uso_Subversion.pdf
NORMA NORMA NORMA

13
ENTREGABUILD Es obligatorio que la aplicacin entregada compile correctamente sin errores.
ENTREGATARGET La entrega slo debe contener los ficheros fuente del proyecto, no se incluir el directorio target generado por Maven. Dentro de la entrega no se incluir ninguna librera jar ya que stas se descargarn automticamente del repositorio artifactory.
ENTREGALIB Las aplicaciones no podrn utilizar libreras externas que no estn incluidas en el repositorio artifactory de ICM, a no ser que sean autorizadas por ICM.
ENLACES RELACIONADOS Producto URL
Portal para el desarrollo http://gestiona.madrid.org/arquitecturasw de aplicaciones Artifactory de Atlas http://gestiona.madrid.org/artifactory
186 de 191
Framework Atlas
Normativa
A1.1
NORMAS
ENTORNO .................................................................................................................................................................... 17 ENTORNOEJECUCION ............................................................................................................................................. 17 ARQUETIPOS .............................................................................................................................................................. 19 NOMARCHIVO ............................................................................................................................................................ 20 NOMPAQUETES ......................................................................................................................................................... 20 VERSIONADO .............................................................................................................................................................. 20 IMPLWEB ..................................................................................................................................................................... 21 LIBCOMUN .................................................................................................................................................................. 22 IMPLLIB ....................................................................................................................................................................... 22 IMPLWS ........................................................................................................................................................................ 23 WSLIBCLIENTE .......................................................................................................................................................... 23 IMPLBATCH ................................................................................................................................................................ 24 REFLEXION ................................................................................................................................................................. 25 GARBAGE .................................................................................................................................................................... 25 MULTIHILO ................................................................................................................................................................. 25 CLASESIGUALES ....................................................................................................................................................... 25 JSFCOMPONENTES ................................................................................................................................................... 27 JSFXHTML ................................................................................................................................................................... 28 JSFPOB .......................................................................................................................................................................... 28 JSFNEGOCIO ............................................................................................................................................................... 31 JSFVALIDACION ........................................................................................................................................................ 36 JSFCUSTOMVALIDATOR ........................................................................................................................................ 37 JSFCUSTOMCONVERSOR ....................................................................................................................................... 37 JSFINTERNALIZACION............................................................................................................................................ 38 JSFLAYOUT ................................................................................................................................................................. 42 JSFPANEL .................................................................................................................................................................... 43 JSFJAVASCRIPT ......................................................................................................................................................... 44 JSFJQUERY.................................................................................................................................................................. 44 JSFACCESIBLIDAD ................................................................................................................................................... 46 JSFIMAGENES ............................................................................................................................................................ 46 JSFCSS ........................................................................................................................................................................... 46 JSFIFRAMES................................................................................................................................................................ 47 JSFAJAX ....................................................................................................................................................................... 47 JSFAJAXINTERAC ..................................................................................................................................................... 48 JSFMBEANSIMPL....................................................................................................................................................... 51 JSFANOTACION ......................................................................................................................................................... 53 JSFMBATRIBUTOS .................................................................................................................................................... 53
187 de 191
Framework Atlas
Normativa JSFFACADE ................................................................................................................................................................. 54 JSFEXCEPTION .......................................................................................................................................................... 55 JSFNAVEGACION ...................................................................................................................................................... 56 JSFFACESCONFIGXML ............................................................................................................................................ 58 JSFREQUEST ............................................................................................................................................................... 60 JSFNAVDES.................................................................................................................................................................. 62 JSFCONFADICIONAL................................................................................................................................................ 63 JSFWEBXML ............................................................................................................................................................... 63 JSFSESION ................................................................................................................................................................... 65 JSFHTTPSESSION ...................................................................................................................................................... 65 JSFTIEMPOSESION ................................................................................................................................................... 65 JSFUSOSESION ........................................................................................................................................................... 65 JSFCREACIONSESION .............................................................................................................................................. 66 SNFACADE ................................................................................................................................................................... 68 SNFACADEIMPL......................................................................................................................................................... 69 SNDOMINIO ................................................................................................................................................................. 70 SNSERVICEIMPL ....................................................................................................................................................... 72 SNANOTACION ........................................................................................................................................................... 72 SNMVC .......................................................................................................................................................................... 73 SNSPRING .................................................................................................................................................................... 77 SNSPRINGLIB .............................................................................................................................................................. 77 SNDEPENDENCIAS .................................................................................................................................................... 78 SNAMBITOS ................................................................................................................................................................. 79 SNTHROWSEXCEPTION .......................................................................................................................................... 80 SNCUSTOMEXCEPTION .......................................................................................................................................... 80 SNNEGOCIOEXCEPTION ......................................................................................................................................... 81 SNSYSTEMEXCEPTION............................................................................................................................................ 82 SNDAOEXCEPTION ................................................................................................................................................... 82 SNTRANSACTIONANNOTATED ............................................................................................................................. 87 SNTRANSACTIONDEFAULT ................................................................................................................................... 87 SNTRANSACTIONROLLBACK ............................................................................................................................... 88 SNFICHEROSTEMPORALES ................................................................................................................................... 90 ADHIBERNATE ........................................................................................................................................................... 92 DAODATASOURCE .................................................................................................................................................... 93 DAOSESSION ............................................................................................................................................................... 93 DAOFLUSHING ........................................................................................................................................................... 93 DAODEPENDENCIAS ................................................................................................................................................ 97 ADENTITYIMPL ......................................................................................................................................................... 98 ADRENDIMIENTO ..................................................................................................................................................... 98 ADEQUALSHASHCODE .......................................................................................................................................... 104
188 de 191
Framework Atlas
Normativa ADMAPEOTABLA .................................................................................................................................................... 105 ADIDENTIFICADOR ................................................................................................................................................ 105 ADRELACIONES....................................................................................................................................................... 106 ADDINAMICOS ......................................................................................................................................................... 106 ADLOBANOT ............................................................................................................................................................. 106 ADHIBERNATEDAOIMPL ...................................................................................................................................... 108 ADDAOANOTACION ............................................................................................................................................... 108 ADDAONOMENCLATURA ..................................................................................................................................... 109 ADDAOHIBERNATETEMPLATE .......................................................................................................................... 109 ADCATALOGOS ....................................................................................................................................................... 116 ADREMOTO ............................................................................................................................................................... 116 ADSQL ......................................................................................................................................................................... 117 ADSQLUSO ................................................................................................................................................................. 117 ADNAMEDPARAMETER ........................................................................................................................................ 118 DAOEXCEPCIONES ................................................................................................................................................. 119 ADTRANSACCION ................................................................................................................................................... 119 ADROLLBACK .......................................................................................................................................................... 120 ADSTOREDPROC ..................................................................................................................................................... 121 ADCACHE2NIVEL .................................................................................................................................................... 125 DAOCACHEDISTRIBUIDA ..................................................................................................................................... 126 ADRENDIMIENTO ................................................................................................................................................... 126 CONFENTORNO ....................................................................................................................................................... 128 CONFPARTICULAR ................................................................................................................................................. 128 CONFPARTICULARLIB .......................................................................................................................................... 129 CONFENTORNOLIB ................................................................................................................................................ 129 CONFNOMENCLATURA ........................................................................................................................................ 130 CONFSEG ................................................................................................................................................................... 130 SBAUTENAUTO ........................................................................................................................................................ 134 SBAUTOPERFILES ................................................................................................................................................... 134 SBENS .......................................................................................................................................................................... 136 SBTRAZAS.................................................................................................................................................................. 138 SBTRAZASSEG .......................................................................................................................................................... 139 SBAUDIT ..................................................................................................................................................................... 140 SIPLAN ........................................................................................................................................................................ 143 SICERT ........................................................................................................................................................................ 144 SIBI............................................................................................................................................................................... 146 INTWS ......................................................................................................................................................................... 147 INTNOMCLIENT....................................................................................................................................................... 147 SIBPM .......................................................................................................................................................................... 149 SOLLIB ........................................................................................................................................................................ 149
189 de 191
Framework Atlas
Normativa SOLRPT ....................................................................................................................................................................... 150 SOLRPTCONEX ........................................................................................................................................................ 150 SOLRPTMODULO .................................................................................................................................................... 151 SOLRPTCONF ........................................................................................................................................................... 151 SOLCOMPOSITOR ................................................................................................................................................... 152 SOLEXCEL ................................................................................................................................................................. 154 SOLPDF ....................................................................................................................................................................... 155 SOLGRAFICOS .......................................................................................................................................................... 156 SOLMULTIMEDIA ................................................................................................................................................... 157 SOLACCESOLOCAL ................................................................................................................................................ 158 SOLXML ..................................................................................................................................................................... 159 SOLCORREO ............................................................................................................................................................. 161 WSSECURITY ............................................................................................................................................................ 167 VALEXCLUDE ........................................................................................................................................................... 169 CSPMD ........................................................................................................................................................................ 171 TESTINTEGRACION ............................................................................................................................................... 180 TESTACEPTACION .................................................................................................................................................. 180 TESTSERVICIOSWEB ............................................................................................................................................. 181 TESTRENDIMIENTO ............................................................................................................................................... 181 TESTAUTOMATIZACION ...................................................................................................................................... 182 TESTCOBERTURA ................................................................................................................................................... 182 TESTPLANPRUEBAS ............................................................................................................................................... 183 JAVADOC ................................................................................................................................................................... 184 ENTREGABUILD ...................................................................................................................................................... 186 ENTREGATARGET .................................................................................................................................................. 186 ENTREGALIB ............................................................................................................................................................ 186
190 de 191
Framework Atlas
Normativa
A1.2 BUENAS PRACTICAS

JSFMANAGEDBEAN .................................................................................................................................................. 30 JSFGET.......................................................................................................................................................................... 30 JSFTAMANO ................................................................................................................................................................ 31 JSFEL ............................................................................................................................................................................. 31 JSFACCIONES ............................................................................................................................................................. 33 JSFMESSAGES ............................................................................................................................................................ 36 JSFACCESOMESSAGES ............................................................................................................................................ 39 JSFAJAXLIMITE......................................................................................................................................................... 48 JSFAYUDA.................................................................................................................................................................... 50 JSFMBUNICO .............................................................................................................................................................. 53 JSFSTOREERROR ...................................................................................................................................................... 56 JSFSAVESTATE .......................................................................................................................................................... 60 JSFATLASFACESUTILS ............................................................................................................................................ 66 SNFACADEWS ............................................................................................................................................................. 69 ADBASESERVICE ....................................................................................................................................................... 75 SNAGRUPACION ........................................................................................................................................................ 79 SNEXCCOMUNES ....................................................................................................................................................... 81 SNGENERICTRANSACTION .................................................................................................................................... 87 SNNOMFICHEROTEMPORAL ................................................................................................................................ 90 ADBASEDAO .............................................................................................................................................................. 112 ADHQL ........................................................................................................................................................................ 116 SOLCOMPOSITOR ................................................................................................................................................... 152 SOLGRAFICOSGRANDES ...................................................................................................................................... 156 VALFRECUENTE ...................................................................................................................................................... 168 CODFRECUENTE ..................................................................................................................................................... 171 GENCOD ..................................................................................................................................................................... 172 ENTREGAPARCIAL ................................................................................................................................................. 185
191 de 191

Atlas Normativa

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Atlas Normativa

Uploaded by

Copyright:

Available Formats

ATLAS

Ttulo Documento de Referencia Responsable Versin

Arquitectura de Software 1.13 Fecha Versin 11/07/2013

Causa del Cambio

rea de Aplicaciones Especiales y Arquitectura de Software 02/07/2010

rea de Aplicaciones Especiales y Arquitectura de Software 2/11/2010

rea de Aplicaciones Especiales y Arquitectura de Software 10/01/2011

rea de Aplicaciones Especiales y Arquitectura de Software 24/02/2012

Buena Prctica JSFStoreError: Se cambia el uso de t:message a h:message.

Nuevo apartado 6.2.1.10: Ayuda contextual.

Nueva buena practica JSFAYUDA Modificado apartado 6.2.1.7 Uso de

Causa del Cambio Javascript para hablar de Jquery.

Nueva regla JSFJQuery Nuevo apartado 10.3 Generacin automtica de cdigo

Apartado 9.7.11: Visor Mapas. Nuevo componente.

Apartado 12: Entrega. Se cambia Unidad

Apartado 6.4.3.2: Se elimina la regla ADLOB.

MANAGED BEANS .............................................................................................................................. 50 CONFIGURACIN DE JSF ................................................................................................................... 57

DATA ACCESS OBJECTS .................................................................................................................. 107

HERRAMIENTAS .......................................................................................................................................... 168

NombreDeNorma Contenido de la norma.

NombreDeBuenaPractica Contenido de la Buena Prctica.

Las siguientes imagenes muestran los elementos a grandes rasgos

Entorno Desarrollo Proveedor

Eclipse + plugin Maven (+ plugin subversion)

Base de Datos (Oracle)

Servidor de Aplicaciones (WebLogic)

Portal para el desarrollo Subversion

Actualmente se dispone de los siguientes arquetipos dentro del framework Atlas:

Tipo de mdulo Proyecto de inicio

Genera un proyecto Maven de tipo web listo para desplegar un servicio

Mdulo servicio web

NORMA NORMA NORMA

NORMA NORMA NORMA NORMA

En la JSF <h:commandLink action="#{miBean.accion}" actionListener="#{miBean.escuchadorAccion}"> <h:outputText value="#{bundle['texto_del_link']}"/> </h:commandLink>

En la pgina JSF <h:selectBooleanCheckbox id="changeColorMode" valueChangeListener="#{resumeBean.changeColorMode}" onchange="submit()" /> immediate="true"

Validator, con la siguiente nomenclatura: o <nombre>Validator

Converter, con la siguiente nomenclatura: o <nombre>Converter

Estructura y decoracin de la pgina

Los layouts que ofrece el framework son:

(Horizontal+Contenido). Incluye un men horizontal, y en el resto de la pgina se muestra el contenido.

(Vertical + Contenido). Incluye un men vertical, y en el resto de la pgina se muestra el contenido.

(Contenido) Incluye solamente la cabecera y el pie.

Para ms informacin y ejemplos de layout acceder a la aplicacin de componentes.

Localizacin de elementos por Id

NORMA NORMA NORMA

Interfaces ricas de usuario (RIA)

Ejemplo de uso de rich:toolTip en un campo de un formulario

Al pulsar sobre el icono nos mostrar el panel de la ayuda de la siguiente forma:

NORMA NORMA NORMA NORMA

<nombre>Facade (Interfaz de la fachada) <nombre>FacaceImpl (Implementacin de la interfaz)

A continuacin se muestra un ejemplo de interfaz e implementacin de una fachada.

<nombre>Service (Interfaz del servicio) <nombre>ServiceImpl (Implementacin del servicio)

La implementacin de esta clase se puede ver en el paquete dao en la clase BaseServiceImpl.

Nota Los servicios se deben inyectar en el contexto de Spring en el fichero applicationContext-services.xml

SNSpring Los ficheros de configuracin de Spring se incluirn en la carpeta src/main/resources/conf.

Esto facilitar tanto el desarrollo como el posterior mantenimiento de la aplicacin.

Ejemplo de excepcin propia del negocio package ejpl.gestion.exceptions;

Isolation level ISOLATION_DEFAULT

Descripcin Usa la poltica de aislamiento por defecto del sistema persistente.

Previene lecturas dirty y non-repeateable pero se pueden dar lecturas phantom.

SNTransactionRollback Se utilizar el mecanismo de rollback de transaccin basado en anotaciones. Esto se conseguir

Ejemplo de definicin de rollback @Transactional(readOnly = false, propagation = Propagation.REQUIRED, rollbackForClassName = {"NotRoomFoundServiceException"})

POJO Services POJOs

Capa de Acceso a Datos Capa de Acceso a Datos