ATLAS MANUAL DE USUARIO SERVICIO DE FUSIÓN

Transcripción

1 ATLAS MANUAL DE USUARIO SERVICIO DE FUSIÓN Versión 1.2 Área de Aplicaciones Especiales y Arquitectura de Software 3

2 Hoja de Control Título Documento de Referencia Responsable Manual de Usuario NORMATIVA ATLAS Área de Aplicaciones Especiales y Arquitectura de Software Versión 1.2 Fecha Versión 26/10/2012 Registro de Cambios Versión Causa del Cambio Responsable del Cambio Fecha del Cambio 1.0 Versión inicial del documento Las preguntas frecuentes se consultarán en el portal de arquitectura. 1.1 Se modifica el nombre del área Se actualizan los métodos obtenerfusionrtf del servicio de fusión Instalación: Ampliado dónde debe ponerse la dependencia. Área de Integración y Arquitectura de 04/08/2010 Aplicaciones Área de Aplicaciones Especiales y 26/09/2011 Arquitectura de Software Paso 2: Configuración del Área de Aplicaciones Especiales y 1.2 entorno de Spring: corregido el Arquitectura de Software 27/08/2012 valor del out.directory del ejemplo. 2 de 20

3 Índice 1. INTRODUCCIÓN AUDIENCIA OBJETIVO CONOCIMIENTOS PREVIOS DESCRIPCIÓN INSTALACIÓN Y CONFIGURACIÓN INSTALACIÓN CONFIGURACIÓN Paso 1: Modificación del fichero web.xml Paso 2: Configuración del entorno de Spring USO PASO 1: GENERACIÓN PLANTILLA RTF PASO 2: INCLUSIÓN DE DATOS EN EL CONTEXTO PASO 3: MÉTODOS DE GENERACIÓN EN EL SERVICIO Método obtenerfusionrtf(string plantilla, DatosFusion datos) Método obtenerfusionrtf(inputstream plantilla, DatosFusion datos) Método obtenerfusionrtf(string plantilla, DatosFusion datos, OutputStream fusion) Método obtenerfusionrtf(inputstream plantilla, DatosFusion datos, OutputStream fusion) RECOMENDACIONES Y BUENAS PRÁCTICAS PREGUNTAS MÁS FRECUENTES ENLACES RELACIONADOS de 20

4 1. INTRODUCCIÓN Este documento contiene el manual de uso del de documentos del Framework Atlas. En él se incluye información sobre cómo utilizar dicho servicio en una aplicación, así como información acerca de la configuración de los parámetros fundamentales del servicio Audiencia objetivo El lector objetivo de este documento es toda aquella persona que esté desarrollando una aplicación basada en el framework Atlas y desee usar el de Atlas Conocimientos Previos Para un completo entendimiento del documento, el lector deberá tener conocimientos previos sobre las siguientes tecnologías: - Lenguaje Java - Spring Framework. - Velocity - Diseño de plantillas RTF Para saber más sobre dichas tecnologías, consultar los accesos referenciados en el apartado 6 de este documento, Enlaces Relacionados. 4 de 20

5 2. DESCRIPCIÓN El servicio de fusión proporciona un mecanismo de generación de documentos a través de un documento plantilla y una serie de datos a enlazar en los espacios habilitados para tal efecto en el documento inicial. El formato de documentos admitido es formato RTF (siglas en inglés para Rich Text Format o 'Formato de texto enriquecido') que incluirán campos de combinación (MERGEFIELD), campos de hipervínculo (HIPERLINK), campo de formulario con texto o marcadores (BOOKMARK, para gestionar el inicio/fin de bucles). Los datos se harán llegar a través de POJO s como veremos más adelante. Actualmente toda esta fusión se realiza aprovechándose de la versatilidad para la generación de páginas que ofrece Velocity y los campos de combinación de correspondencia de Word. 5 de 20

6 3. INSTALACIÓN Y CONFIGURACIÓN 3.1. INSTALACIÓN Añadir la siguiente dependencia en el fichero pom.xml (en el caso de arquetipos web, en el pom.xml del proyecto raíz, no del web): pom.xml <dependency> <groupid>atlasfrm</groupid> <artifactid>atlasfrm-fusion-lib</artifactid> <version>${atlasfrm-fusion-lib.version</version> </dependency> 3.2. CONFIGURACIÓN La configuración del servicio afecta a los siguientes ficheros: - web.xml: Fichero de configuración de la aplicación web en el que se incluirá la llamada a un xml de contexto de Spring distribuido en el propio jar de atlasfrm-fusion-lib jar. - applicationcontext-services.xml: Fichero de configuración del contexto de Spring en el que se incluirá la definición del servicio y el origen de datos. Para la configuración del servicio deben realizarse los pasos descritos en los siguientes apartados: Paso 1: Modificación del fichero web.xml Deben incluirse las siguientes líneas en el fichero web.xml, justamente donde se indican los ficheros de configuración de contexto de Spring, debe indicarse que se va a utilizar el fichero applicationcontext-fusion.xml de configuración de la aplicación: web.xml <context-param> <param-name>contextconfiglocation</param-name> <param-value> classpath:/conf/applicationcontext-fusion.xml; </param-value> </context-param> Paso 2: Configuración del entorno de Spring 6 de 20

7 Debe incluirse en el fichero applicationcontext-services.xml, la definición del servicio y el origen de datos, en este último caso puede variarse el nombre adecuándolo al propio de la aplicación. Y el caso del servicio los parámetros configurados dependerán de la opción de servicio elegida previamente, como explicaremos a continuación. Un ejemplo de configuración a incluir dentro del fichero de contexto es el siguiente: applicationcontext-services.xml <!-- ============== DEFINICION DEL ELEMENTO DE FUSION ==================== --> <bean id="datosfusion" class="atlas.fusion.domain.datosfusiontest" /> <bean id="fusionservice" class="atlas.fusion.services.fusionserviceimpl"> <property name="savetransformeddocument" value="true"/> <property name="groupbyperpagebreak" value="-1" /> <property name="circularreferences" value="false" /> <property name="outdirectory" value="${java.io.tmpdir" /> </bean> Los parámetros posibles para el servicio son los siguientes: Propiedad (*) Propiedad Obligatoria Descripción Valor rtftemplateimpl transformerconfig savetransformeddocument groupbyperpagebreak circularreferences outdirectory Definición del Template de generación utilizado por la herramienta de fusión, en la actual versión el valor obligatorio de este bean es el expresado a continuación. Nombre del fichero a través del que se indica la relación entre las etiquetas de velocity y los campos de combinación Valor booleano para indicar si se desea guardar a disco la plantilla transformada con las especificaciones de Velocity. Sólo se guardará en el caso que la salida de la fusión sea a disco. Valor que indica que cada cuantos elementos durante una iteración debe generar una nueva página. Booleano para indicar si entre los elementos del contexto existe referencias circulares Ruta de salida de los documentos en el caso que se desee que se genere un fichero. Es obligatoria en caso de utilizar esa operación del servicio. vmrtftemplate transformer-config.xml true/false defecto: true Entero defecto: -1 true/false defecto: false ${dir.temp 7 de 20

8 4. USO Una vez configurado el entorno para el uso del servicio, puede procederse a su utilización Paso 1: Generación plantilla RTF Primeramente para la fusión se debe confeccionar una plantilla en formato RTF con los campos de combinación deseados, por ejemplo: Cuya vista en campos de combinación es la que sigue: 8 de 20

9 Cada uno de los campos a incluir se deben anteceder en su nombre por el carácter $ y seguir la nomenclatura que sigue: $[nombre de Objeto en contexto].[atributo] En la imagen anterior podemos ver tres ejemplos claros: $header_developer_name: Se busca en el contexto un String con ese nombre para sustituir el valor. $project.name: Se busca en el contexto un POJO con el nombre project que tenga un método get para obtener el atributo Name. $developers.roles.name: Se busca en el contexto un POJO con nombre developers que tenga un método get para obtener el atributo Roles, que a su vez es un POJO que tiene otro método para obtener el atributo Name. Para crear un campo de combinación dentro de un RTF se debe ir a la opción de menú Insertar Campo, seleccionar en Nombres de campo MergeField, rellenar el Nombre del campo con las indicaciones de nomenclatura citadas anteriormente y se pulsa Aceptar. 9 de 20

10 Para crear un campo de hipervínculo se debe ir a la opción de menú Insertar Hipervínculo. Se rellenan el Texto y la Dirección con las indicaciones de nomenclatura citadas anteriormente y se pulsa Aceptar. Para crear un campo de formulario de texto en la plantilla RTF se abre la barra de herramientas Formularios y se pulsa sobre el icono Campo de texto. Se hace doble click sobre el campo insertado y se rellena el Texto predeterminado con las indicaciones de nomenclatura citadas anteriormente y se pulsa Aceptar. 10 de 20

11 Los bookmark se incluirán para gestionar el inicio/fin de bucles. Para ver los marcadores incluidos en la plantilla hay que seleccionar en menú Herramientas Opciones en la pestaña Ver seleccionar en el apartado Mostrar la opción Marcadores. Para incluir un marcador se debe ir a la opción de menú Insertar Marcador, darle un nombre y pulsar Agregar. Ejemplo de un POJO que representa el objeto Project: Project.java 11 de 20

12 public class Project { /** The name. */ private String name; /** The logo. */ private InputStream logo = null; /** * Instantiates a new project. * name the name */ public Project(String name) { this.name = name; /** * Gets the name. * the name */ public String getname() { return name; /** * Sets the name. * name the new name */ public void setname(string name) { this.name = name; /** * Sets the logo. * logo the new logo */ public void setlogo(inputstream logo) { this.logo = logo; /** * Gets the logo. * the logo */ public InputStream getlogo() { return logo; 4.2. Paso 2: Inclusión de datos en el contexto 12 de 20

13 Dentro de nuestro proyecto una vez configurado se debe crear una clase que implemente el interface atlas.fusion.domain.datosfusion, como por ejemplo: DatosFusionTest.java public class DatosFusionTest implements DatosFusion { /** * {@inheritdoc * atlas.fusion.domain.datosfusion#putcontext(atlas.fusion.core.rtf.template.icontext) public void putcontext(icontext context) throws ServiceException { /* * Context of simply POJO */ context.put("date", new Date()); context.put("project", new Project("ATLAS FUSION")); context.put("header_developer_name", "Name"); context.put("header_developer_ ", " "); context.put("header_developer_roles", "Roles"); /* * Context of list of POJO (Developers and Dependencies) */ List developers = new ArrayList(); Developer developer = new Developer("Juan Español", "jespañol@madrid.org"); developer.addrole("java Developer"); developer.addrole("release Manager"); developers.add(developer); developer = new Developer("Geir Magnusson Jr.", "geirm@madrid.org"); developer.addrole("java Developer"); developer.addrole("release Manager"); developers.add(developer); developer = new Developer("Daniel L. Rall", "dlra@madrid.org"); developer.addrole("java Developer"); developer.addrole("release Manager"); developers.add(developer); context.put("developers", developers); List dependencies = new ArrayList(); Dependency dependency = new Dependency("commons-collection", "jar", "1.0", " dependencies.add(dependency); dependency = new Dependency("logkit", "jar", "1.0.1", " dependencies.add(dependency); dependency = new Dependency("oro", "jar", "2.0.8", " dependencies.add(dependency); context.put("dependencies", dependencies); 13 de 20

14 Esta clase, como puede observarse, contiene el método putcontext a través del cual se deben incluir dentro del contexto los datos que deseamos fusionar con nuestra plantilla RTF. En el caso del ejemplo, se incluyen unos String que se sustituirán por su valor correspondiente en la fusión y una serie de ArrayList de Beans que serán entendidos como una repetitiva dentro del documento. Tras estos pasos la fusión obtenida es como sigue: 14 de 20

15 4.3. Paso 3: Métodos de generación en el servicio Dentro del servicio se proporciona 4 métodos para obtener la fusión, estos son los siguientes: Método obtenerfusionrtf(string plantilla, DatosFusion datos) Este método espera por parámetro la ruta relativa a la plantilla con respecto al classloader y los datos a fusionar. Devuelve el path del fichero fusionado, este fichero se encuentra en el directorio de salida indicado en el parámetro outdirectory del bean DatosFusion. La signatura del método obtenerfusionrtf es la siguiente: public String obtenerfusionrtf(string plantilla, DatosFusion datos) throws ServiceException; Posibles parámetros: Nombre Descripción plantilla datos Ruta relativa de la plantilla de fusión con respecto al classloader. Datos a representar en la fusión Ejemplo de código de fusión de documento import atlas.fusion.services.fusionservice; public void testfusionrtf1() throws Exception { DatosFusionTest datos = new DatosFusionTest(); Assert.assertNotNull(fusionService); String salida = fusionservice.obtenerfusionrtf(plantillartf, datos); Assert.assertNotNull(salida); Método obtenerfusionrtf(inputstream plantilla, DatosFusion datos) Este método espera por parámetro un InputStream con el contenido de la plantilla y los datos a fusionar. Devuelve el path del fichero fusionado, este fichero se encuentra en el directorio de salida indicado en el parámetro outdirectory del bean DatosFusion. 15 de 20

16 La signatura del método obtenerfusionrtf es la siguiente: public String obtenerfusionrtf(inputstream plantilla, DatosFusion datos) throws ServiceException; Posibles parámetros: Nombre Descripción plantilla datos Contenido de la plantilla de fusión. Datos a representar en la fusión Ejemplo de código de fusión de documento import atlas.fusion.services.fusionservice; public void testfusionrtf2() throws Exception { DatosFusionTest datos = new DatosFusionTest(); Assert.assertNotNull(fusionService); InputStream plantilla = new FileInputStream(ficheroRTF); String salida = fusionservice.obtenerfusionrtf(plantilla, datos); Assert.assertNotNull(salida); Método obtenerfusionrtf(string plantilla, DatosFusion datos, OutputStream fusion) La fusión espera por parámetro la ruta relativa a la plantilla con respecto al classloader, los datos a fusionar y un OutputStream donde escribe el resultado de la fusión. La signatura del método obtenerfusionrtf es la siguiente: public String obtenerfusionrtf(string plantilla, DatosFusion datos, OutputStream fusion) throws ServiceException; Posibles parámetros: Nombre plantilla datos Descripción Ruta relativa de la plantilla de fusión con respecto al classloader. Datos a representar en la fusión 16 de 20

17 fusion Resultado de la fusión. Ejemplo de código de fusión de documento import atlas.fusion.services.fusionservice; public void testfusionrtf3() throws Exception { DatosFusionTest datos = new DatosFusionTest(); Assert.assertNotNull(fusionService); ByteArrayOutputStream baos = new ByteArrayOutputStream(); fusionservice.obtenerfusionrtf(plantillartf, datos, baos); Assert.assertNotNull(baos); FileOutputStream fileout = new FileOutputStream("salida.rtf"); fileout.write(baos.tobytearray()); fileout.flush(); fileout.close(); baos.reset(); baos.close(); Método obtenerfusionrtf(inputstream plantilla, DatosFusion datos, OutputStream fusion) La fusión espera por parámetro un InputStream con el contenido de la plantilla, los datos a fusionar OutputStream donde escribe el resultado de la fusión. y un La signatura del método obtenerfusionrtf es la siguiente: public String obtenerfusionrtf(inputstream plantilla, DatosFusion datos, OutputStream fusion) throws ServiceException; Posibles parámetros: Nombre Descripción plantilla datos fusion Contenido de la plantilla de fusión. Datos a representar en la fusión Resultado de la fusión. Ejemplo de código de fusión de documento 17 de 20

18 import atlas.fusion.services.fusionservice; public void testfusionrtf4() throws Exception { DatosFusionTest datos = new DatosFusionTest(); Assert.assertNotNull(fusionService); InputStream plantilla = new FileInputStream(ficheroRTF); ByteArrayOutputStream baos = new ByteArrayOutputStream(); fusionservice.obtenerfusionrtf(plantilla, datos, baos); Assert.assertNotNull(baos); FileOutputStream fileout = new FileOutputStream("salida2.rtf"); fileout.write(baos.tobytearray()); fileout.flush(); fileout.close(); baos.reset(); baos.close(); 4.4. Recomendaciones y buenas prácticas No existen buenas prácticas definidas actualmente. 18 de 20

19 5. PREGUNTAS MÁS FRECUENTES La lista de preguntas frecuentes se encuentra en el portal de arquitectura. 19 de 20

20 6. ENLACES RELACIONADOS Producto URL Versión Ajax4JSF GA Barbecue d Commons BeanUtils commons.apache.org/beanutils/ Commons Configurations Facelets Hibernate ga Hibernate Annotations ga JAXB Jcaptcha jcaptcha.sourceforge.net/ 1.0-RC5 JPA JSF JSFUnit Beta3 Log4J MyFaces Core RichFaces GA Spring Spring Security Tomahawk Velocity de 20