manual de usuario del arquetipo jar

ATLAS
MANUAL DE USUARIO DEL
ARQUETIPO JAR
Versión 1.7
Área de Aplicaciones Especiales y Arquitectura de
Software
Framework Atlas
Arquetipo Jar
Hoja de Control
Título
Manual de usuario del Arquetipo Jar
Documento de Referencia
NORMATIVA ATLAS
Responsable
Área de Aplicaciones Especiales y Arquitectura de Software
Versión
1.7
Fecha Versión
30/04/2014
Registro de Cambios
Versión
Causa del Cambio
Responsable del Cambio
Fecha del Cambio
Área de Integración y Arquitectura de
1.0
1.1
1.2
Versión inicial del documento
Se modifica la nomenclatura de los
ficheros de Spring. En vez de incluir
el nombre del proyecto se tiene que
incluir el nombre del módulo
- Nueva configuración de Arquetipo
Jar
- Incluida creación previa del
arquetipo de proyecto
Aplicaciones
25/05/2010
Área de Integración y Arquitectura de
Aplicaciones
Área de Integración y Arquitectura de
15/06/2010
16/09/2010
Aplicaciones
- Nueva nomenclatura de paquetes
Se modifica el apartado 2.1
Creación
de un módulo de tipo librería
partiendo del arquetipo ya que la
nomenclatura del artifactId no era la
correcta según la normativa.
1.3
Se modifica el apartado 2.3
Estructura de directorios y archivos
para indicar que el fichero
environment.properties solo se
puede utilizar para los test.
Área de Aplicaciones Especiales y
Arquitectura de Software
10/02/2011
Se incluyen los siguientes apartados:
· Apartado 3 Inyección de
dependencias de Spring
· Apartado 4 Configuración
· Apartado 5 Versionado
· Apartado 6 Uso de la
librería dentro de una
aplicación.
Área de Aplicaciones Especiales y
1.4
Cambio del nombre del Área
Arquitectura de Software
2 de 16
16/09/2011
Framework Atlas
Arquetipo Jar
Versión
1.5
1.6
1.7
Causa del Cambio
- Se añaden las clases BaseService
y BaseServiceImpl, así como los
servicios y DAOs para EstadoCivil
- Se añaden las clases de test
agrupadas por servicio
- Quitado directorio “jar” del
arquetipo, y todos los
environment.properties de los
entornos
Se actualiza el apartado 3 para
eliminar referencias a la herramienta
de validación
Responsable del Cambio
Fecha del Cambio
Área de Aplicaciones Especiales y
Arquitectura de Software
24/02/2012
Área de Aplicaciones Especiales y
Arquitectura de Software
05/03/2012
Área de Aplicaciones Especiales y
Arquitectura de Software
3 de 16
12/03/2014
Framework Atlas
Arquetipo Jar
Índice
1.
INTRODUCCIÓN ................................................................................................................................................................ 5
1.1.
1.2.
2.
AUDIENCIA OBJETIVO .............................................................................................................................................. 5
CONOCIMIENTOS PREVIOS ...................................................................................................................................... 5
INFORMACIÓN SOBRE EL ARQUETIPO ..................................................................................................................... 6
2.1.
2.2.
2.3.
2.4.
CREACIÓN DE UNA APLICACIÓN PARTIENDO DEL ARQUETIPO .......................................................................................... 6
ESTRUCTURA DEL ARQUETIPO ......................................................................................................................................... 7
ESTRUCTURA DE DIRECTORIOS Y ARCHIVOS .................................................................................................................... 8
EJECUCIÓN DE LA APLICACIÓN ........................................................................................................................................ 9
3.
INYECCION DE DEPENDENCIAS DE SPRING .......................................................................................................... 11
4.
CONFIGURACION ........................................................................................................................................................... 11
5.
VERSIONADO ................................................................................................................................................................... 12
6.
USO DE LA LIBRERÍA DENTRO DE UNA APLICACIÓN ........................................................................................ 12
6.1.
6.2.
6.3.
6.4.
INCLUIR DEPENDENCIA DE LA LIBRERÍA......................................................................................................................... 13
AÑADIR INFORMACIÓN DE CONTEXTO ........................................................................................................................... 13
REFERENCIAR A LOS FICHEROS DE PROPIEDADES ........................................................................................................... 14
INCLUIR VARIABLES DE ENTORNO EN ENVIRONMENT.PROPERTIES ................................................................................. 14
7.
GENERACIÓN DEL SITE ................................................................................................................................................ 15
8.
ENLACES RELACIONADOS .......................................................................................................................................... 16
4 de 16
Framework Atlas
Arquetipo Jar
1. INTRODUCCIÓN
Los arquetipos son las plantillas para la generación de los distintos proyectos dentro del Framework Atlas. Estos
arquetipos utilizan el plugin archetype de maven para generar la estructura de ficheros y directorios necesarios
para nuestro proyecto, gestionando las librerías que le indiquemos así como las dependencias. Todas las librerías
serán incluidas durante el empaquetado del proyecto, por lo que para generar y compilar un arquetipo debe estar
conectado al repositorio de artefactos de la Comunidad de Madrid (Artifactory). El framework Atlas consta de los
siguientes arquetipos:
-
Arquetipo para inicio de proyecto
-
Arquetipo para módulos de tipo web
-
Arquetipo para módulos de tipo jar.
-
Arquetipo para módulos de tipo webservice o servicios web
-
Arquetipo para módulos de tipo batch
-
Arquetipo para módulos de gestión documental (documentum)
El Arquetipo Jar se debe utilizar para generar módulos de tipo librería con la estructura de directorios preparada
para comenzar a desarrollar. Al tratarse de un arquetipo de tipo jar solo contiene las configuraciones básicas de
cualquier proyecto (Spring, Hibernate, etc.).
1.1.
AUDIENCIA OBJETIVO
Este documento está dirigido a desarrolladores de proyectos java para ICM en los que se desee crear una librería
java utilizando el framework de desarrollo Atlas.
1.2.
CONOCIMIENTOS PREVIOS
Para un completo entendimiento del documento, el lector deberá tener conocimientos previos sobre las siguientes
tecnologías:
-
Java
-
Eclipse
-
Maven
-
Spring Framework.
-
Hibernate
Además, es necesario haber leído y seguido los pasos del documento
ATLAS_MUS_Preparacion_Entorno_Desarrollo para tener el entorno de desarrollo preparado para comenzar a
trabajar con los arquetipos.
5 de 16
Framework Atlas
Arquetipo Jar
2. INFORMACIÓN SOBRE EL ARQUETIPO
2.1.
Creación de una aplicación partiendo del arquetipo
NOTA IMPORTANTE
Antes de generar un arquetipo es IMPRESCINDIBLE haber generado un
arquetipo para albergar el proyecto (consultar el documento
“ATLAS_MUS_Preparacion_Entorno_Desarrollo” para ver cómo crear un
arquetipo de proyecto).
Cualquier arquetipo posterior será incluido como un módulo de éste.
Crear un proyecto Jar (librería) a partir de un arquetipo es similar a la creación de un proyecto Web, lo único que
cambia es el nombre del arquetipo a utilizar.
Para crear un proyecto a partir de un arquetipo maven puede consultar la guía paso a paso que se indica en el
documento ATLAS_MUS_Preparacion_Entorno_Desarrollo, según se indica en el apartado “Creación de una
aplicación Web desde cero”, sustituyendo “atlas-arquetipos-generador-web” por “atlas-arquetiposgenerador-jar”.
Desde Eclipse, seleccionamos el arquetipo correspondiente (la versión que aparece en la segunda columna puede
variar dependiendo de la versión actual de ATLAS):
6 de 16
Framework Atlas
Arquetipo Jar
A continuación se nos mostrará una pantalla para indicar cuales son los parámetros con los que vamos a crear
nuestro proyecto.
ATENCION – NOMENCLATURA
Es muy importante utilizar en esta
pantalla los valores que cumplan la
normativa de Atlas:
groupId: Nombre del proyecto.
Normalmente es de 4 caracteres y es
un código que se le dá a un proyecto.
Todos los módulos de un proyecto
tendrán el mismo groupId y se
corresponderá con el nombre del
proyecto.
artifactId: Nombre del módulo. (En el
caso de librerías el nombre del módulo
será: xxxx_lib_yyyy donde xxxx se
corresponde con el groupId indicado y
yyyy el texto que identifique a este
modulo y lo diferencie de otros:
Ejemplo: ejpl_lib_sample.
El carácter de separación utilizado en
el nombre debe ser el guión bajo.
Version: La primera versión será 1.0.0
package: El nombre del paquete java
será el groupId, seguido de un punto y
el nombre del bloque funcional dentro
de la aplicación (para aplicaciones
grandes se crearán varios bloques
funcionales).
Todos los nombres deben ir en
minúsculas.
Al pulsar Finish se crea el nuevo proyecto.
ATENCION
Las clases que se incluyen de ejemplo son simplemente eso y deben ser
eliminadas del proyecto cuando no se necesiten.
2.2.
Estructura del arquetipo
Este arquetipo genera un proyecto de tipo jar en el que se incluye la configuración más simple posible de software
desarrollado en Altas.
7 de 16
Framework Atlas
Arquetipo Jar
Esta aplicación además viene preconfigurada para utilizar los módulos de trazas y monitorización (e incluye las
dependencias de Spring e Hibernate para utilizarlos dentro de la librería).
2.3.
Estructura de directorios y archivos
Una vez generado el proyecto nos generará una serie de directorios a estilo maven, donde ubicaremos los fuentes
y recursos de las partes de java y test.
Se generará la siguiente estructura:
Fichero
de
configuración de
maven
del
módulo core.
De esta ruta cuelga la estructura de paquetes con el código fuente de la
aplicación El paquete raíz va a llamarse igual que el nombre del módulo que
se está desarrollando.
El paquete raíz será el especificado al crear el proyecto. No debe olvidarse
que el paquete raíz debe coincidir con el groupid.
Adicionalmente, para cada bloque funcional de nuestra aplicación debe
crearse un subpaquete. En el ejemplo inferior, se ha tomado ejpl como
paquete raíz y un único bloque funcional cuyo paquete se denomina
bloquefuncionaln.
Interfaces de las clases de
acceso a datos y sus
implementaciones
Entidades anotadas de hibernate
Interfaz de la fachada de acceso
a los servicios y su
correspondiente implementación.
Interfaces de los servicios de
negocio y sus implementaciones
8 de 16
Framework Atlas
Arquetipo Jar
Ruta donde se generarán los recursos del proyecto, normalmente son ficheros
de configuración y ficheros de propiedades. En nuestro caso contiene los
siguientes ficheros:
Contiene la configuración los beans de la
librería. {artifactId} será el nombre
especificado en el artifactId del fichero
pom.xml.
Ruta donde se generarán el código fuente para los tests unitarios de nuestro
proyecto. Este código no será incluido en el paquete jar final.
Ejemplo de test unitario
Ruta donde se generarán los recursos para realizar las pruebas de test,
normalmente son ficheros de configuración y ficheros de propiedades. En
nuestro caso contiene los siguientes ficheros:
Fichero de propiedades que contiene
mediante clave y valor todos los valores
susceptibles de ser modificados o
configurados entre diferentes entornos de
ejecución. Este fichero solamente es para
la ejecución de los test.
Fichero de configuración de log4j; lleva
además configuración de los módulos de
trazas y monitorización.
Contiene la configuración básica de un
bean de Spring de ejemplo para ejecutar el
test de JUnit que viene preconfigurado.
Fichero de propiedades que contiene
mediante clave y valor todos los valores
particulares de la aplicación que no son
susceptibles de ser modificados o
configurados entre diferentes entornos de
ejecución.
2.4.
Ejecución de la aplicación
Este arquetipo no viene preparado para su ejecución, sino para empaquetarlo como librería a ser utilizada en otras
aplicaciones. Con las pruebas unitarias debe ser suficiente para probar su ejecución.
Para realizar solo las pruebas de test:
mvn test
9 de 16
Framework Atlas
Arquetipo Jar
Para construir el proyecto generando el fichero jar podemos ejecutar maven con las tareas “clean install”. Puede
hacerse desde eclipse, o por línea de comandos:
mvn clean install
10 de 16
Framework Atlas
Arquetipo Jar
3. INYECCION DE DEPENDENCIAS DE SPRING
Los beans de contexto de Spring se incluirán en el fichero applicationContext-yyyy.xml, donde yyyy es el nombre
de la librería. Este fichero ya se encuentra incluido dentro del arquetipo.
De esta forma solamente hay que incluir un único fichero de contexto dentro de las aplicaciones que utilicen esta
librería.
En el caso de que el tamaño de este fichero sea muy grande se podrá dividir en otros ficheros que serán
importados dentro del fichero applicationContext-yyyy.xml. La nomenclatura de estos ficheros siempre será
applicationContext-yyyy-zzzz.xml donde zzzz puede ser dao, services, etc.
A continuación se muestra un ejemplo de importación de ficheros de contexto.
applicationContext-ejpl_lib.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">
<import resource="classpath:/conf/applicationContext-ejpl_lib-dao.xml" />
<import resource="classpath:/conf/applicationContext-ejpl_lib-services.xml" />
</beans>
4. CONFIGURACION
Los módulos de tipo librería han de definir su configuración de forma distinta para que puedan convivir varias
librerías 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 librería incluya variables de configuración
cuyos valores son los mismos para todos los proyectos que usen estas librerías y estos valores no
dependan del entorno se creará un fichero llamado application-yyyy.properties , donde yyyy es el nombre
de la librería, Este fichero se situará en el directorio src/main/resources/conf de la librería para que se
incluya dentro del jar de la misma.
11 de 16
Framework Atlas
Arquetipo Jar
Si se trata de variables de configuración referentes a queries, estas variables se incluirán en el fichero
queries-yyyy.properties donde yyyy es el nombre de la librería. El fichero irá situado en el mismo
directorio que el anterior.
Las aplicaciones que utilicen la librería deberán referenciar estos ficheros de configuración dentro del
fichero de contexto de Spring applicationContext-general.xml en el bean propertyConfigurer.
·
Fichero environment.properties: Las librerías NO pueden incluir este fichero de configuración (en
src/main/resources) ya que no deben existir distintas versiones de la librería por cada entorno (hay una
librería única). Cuando una librería requiera de variables de configuración que dependen del entorno estas
se incluirán en el fichero de configuración de la aplicación que use esta librería (nunca dentro de la
librería). Es muy importante que las variables sigan la nomenclatura adecuada para reconocer dentro de
una aplicación a quién pertenecen esas variables de configuración.
En el apartado 6 USO DE LA LIBRERÍA DENTRO DE UNA APLICACIÓN se muestran los distintos pasos
necesarios con ejemplos de los mismos.
5. VERSIONADO
Al tratarse de un módulo de tipo librería es muy importante el versionado de la misma cuando se realicen cambios.
El versionado se realizará dentro del fichero pom.xml en el atributo <version>.
Fichero pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/mavenv4_0_0.xsd">
<parent>
<artifactId>atlasfrm-arquetipos-padre-jar</artifactId>
<groupId>atlasfrm</groupId>
<version>1.0.4</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<groupId>atlasfrm</groupId>
<artifactId>ejpl_lib</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging>
<name>ejpl_lib</name>
<description>Librería jar ejpl_lib</description>
Cada vez que se genere una nueva versión de la librería se ha de modificar el número de versión.
6. USO DE LA LIBRERÍA DENTRO DE UNA APLICACIÓN
Para utilizar la librería dentro de una aplicación será necesario realizar los siguientes pasos.
12 de 16
Framework Atlas
Arquetipo Jar
Atención
Estos pasos deben estar claramente indicados en la documentación de uso de la librería implementada.
6.1.
Incluir dependencia de la librería
La dependencia a la librería se incluirá en el fichero pom.xml de la aplicación que la utiliza.
Primero hay que definir una propiedad que es el número de versión de la librería. Este número de versión se
corresponde con el número de versión que aparece en el pom.xml de la librería. Esta propiedad se definirá en el
elemento <properties> del fichero pom.xml. Si el elemento <properties> no existe hay que incluirlo tal y como se
puede ver en el ejemplo.
Después hay que incluir la dependencia dentro del elemento dependencias del fichero pom.xml. El atributo
<version> de la librería apuntará a la propiedad definida anteriormente.
A continuación se muestra un ejemplo de inclusión de librería en el fichero pom.xml.
Fichero pom.xml
<properties>
<ejpl_lib.version>1.0.0</ejpl_lib.version>
</properties>
<dependencies>
…
<dependency>
<groupId>ejpl</groupId>
<artifactId>ejpl_lib</artifactId>
<version>${ejpl_lib.version}</version>
</dependency>
…
<dependencies>
6.2.
Añadir información de contexto
Es necesario referenciar el fichero de contexto de Spring de la librería (applicationContext-yyyy.xml) dentro del
fichero web.xml de la aplicación en el parámetro de contexto contextConfigLocation, según se muestra en el
siguiente ejemplo:
Fichero web.xml
13 de 16
Framework Atlas
Arquetipo Jar
<!-- ============================================================== -->
<!-PARAMETROS DE CONFIGURACION SPRING
-->
<!-- ============================================================== -->
<context-param>
<description>
Este parámetro indica la localización exacta de los ficheros de configuración
de SPRING
</description>
<param-name>contextConfigLocation</param-name>
<param-value>classpath:/conf/applicationContext-general.xml;
classpath:/conf/applicationContext-database.xml;
classpath:/conf/applicationContext-dao.xml;
classpath:/conf/applicationContext-services.xml;
classpath:/conf/applicationContext-security.xml;
classpath:/conf/applicationContext-security-hostPolitica.xml;
classpath:/atlas/atlas-comp-control-m.xml;
classpath:/conf/atlas-trazas-application-context.xml;
classpath:/conf/atlas-monitorizacion-application-context.xml;
classpath:/conf/applicationContext-componentes.xml;
classpath:/conf/applicationContext-ejpl_lib.xml;
</param-value>
</context-param>
6.3.
Referenciar a los ficheros de propiedades
Es necesario referenciar el fichero o los ficheros de propiedades de la librería (application_yyyy.properties y
queries.properties) dentro del fichero applicationContext-general.xml en el bean propertyConfigurer, según se
muestra en el siguiente ejemplo:
Fichero applicationContext-general.xml
<bean id="propertyConfigurer"
class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
<property name="locations">
<list>
<value>classpath:/conf/application.properties</value>
<value>classpath:/environment.properties</value>
<value>classpath:/conf/queries.properties</value>
<value>classpath:/conf/application-ejpl_lib.properties</value>
</list>
</property>
</bean>
6.4.
Incluir variables de entorno en environment.properties
Si la librería ha definido variables que dependen del entorno estas se deberán incluir en el fichero
environment.properties de la aplicación (situado en src/main/resources).
Fichero environment.properties
14 de 16
Framework Atlas
Arquetipo Jar
….
# Configuración de ejpl_lib
ejpl_lib.webservice=http://desarrollo.madrid.org/ejpl_ws/services/ServicioWS
ejpl_lib.server=http://icmdesbi01:8080
ejpl_lib.usuario=EJPL_Usu
ejpl_lib.clave=C7FFB972B34AB66E
…
7. GENERACIÓN DEL SITE
Los arquetipos vienen preparados para automáticamente generar un web-site con la información de la aplicación,
incluyendo lava javadoc, información de dependencias, etc. Para más información sobre como generarlo consultar
el documento ATLAS_MUS_Preparacion_Entorno_Desarrollo
15 de 16
Framework Atlas
Arquetipo Jar
8. ENLACES RELACIONADOS
Producto
URL
Apache Maven
http://maven.apache.org/
Ajax4JSF
http://www.jboss.org/jbossrichfaces/
Barbecue
http://barbecue.sourceforge.net/
Commons BeanUtils
commons.apache.org/beanutils/
Commons Configurations
http://commons.apache.org/configuration/
Facelets
https://facelets.dev.java.net/
Hibernate
http://www.hibernate.org/
Hibernate Annotations
http://www.hibernate.org/hib_docs/annotations/reference/en/html_single/
JAXB
http://java.sun.com/webservices/jaxb/
Jcaptcha
jcaptcha.sourceforge.net/
JPA
http://java.sun.com/developer/technicalArticles/J2EE/jpa/
JSF
http://java.sun.com/javaee/javaserverfaces/
JSFUnit
http://www.jboss.org/jsfunit/
Log4J
http://logging.apache.org/log4j/
MyFaces Core
http://myfaces.apache.org/
RichFaces
http://www.jboss.org/jbossrichfaces/
Spring
http://www.springframework.org/
Spring Security
http://www.springframework.org/
Tomahawk
http://myfaces.apache.org/tomahawk/
Velocity
http://velocity.apache.org/
16 de 16