El servei de Reporting de Canigó permet integrar d'una manera senzilla dades des de fonts heterogènies i mostrar-les en diferents formats: PDF, XLS, CSV, RTF i HTML, dins d'un marc homogeni de desenvolupament.

Context i Escenaris d'Ús

El servei de Reporting es troba dins dels serveis de presentació de Canigó.
El seu ús és necessari en cas de voler presentar informació en format report (ja sigui PDF o els formats que suporta el servei).

Versions i Dependències

Les dependències descrites a la següent url són requerides per tal de compilar i fer funcionar el projecte:
Dependències Servei de Reporting

A qui va dirigit

Aquest document va dirigit als següents perfils:

Programador. Per conèixer l'ús del servei.
Arquitecte. Per conèixer quins són els components i la configuració del servei.

Documents i Fonts de Referència

[1]	JasperReports	http://jasperreports.sourceforge.net/
[2]	iReport	http://ireport.sourceforge.net

Glossari

JasperReports
Es tracta d'una eina de reporting open source que és capaç de gestionar les dades obtingudes (d'una -o més- connexions JDBC, TableModels, JavaBeans, XML, etc.) i mostrar-les segons un disseny definit en XML.

Descripció Detallada

Arquitectura i Components

Canigó ofereix una arquitectura del servei de reporting totalment deslligada de qualsevol implementació.

Els components podem classificar-los en:

Interfícies i Components Genèrics. Interfícies del servei i components d'ús general amb independència de la implementació escollida.
Implementació de les interfícies basada en JasperReports.
Es pot trobar tota la documentació JavaDoc i el codi font referent aquests components a les següents urls:

JavaDoc: http://canigo.ctti.gencat.net/confluence/canigodocs/site/canigo2_0/canigo-services-reporting/apidocs/index.html
Codi Font: http://canigo.ctti.gencat.net/confluence/canigodocs/site/canigo2_0/canigo-services-reporting/xref/index.html

Instal.lació i Configuració

Instal.lació

La instal.lació del servei requereix de la utilització de la llibreria 'canigo-services-reporting' i les dependències indicades a l'apartat 'Introducció - Versions i Dependències'.

Configuració

La configuració del Servei de Reporting implica realitzar els següents pasos:

Definir la configuració bàsica del servei (abans de generar qualsevol vista)
Definir la localització dels reports i el seu tipus de visualització

Definició de la Configuració Bàsica

La configuració bàsica implica:

Definir el mapeig de les urls amb sufix '.report' al Servlet principal

Fitxer de configuració: web.xml
Ubicació proposada: <PROJECT_ROOT>/src/main/webapp/WEB-INF

Definir que totes les URIs que finalitzin amb ".report" les tractarà Canigó amb el servlet 'org.springframework.web.servlet.DispatcherServlet':

Usar el següent codi:

...

<servlet>

<servlet-name>application</servlet-name>

<servlet-class>

org.springframework.web.servlet.DispatcherServlet

</servlet-class>

<load-on-startup>2</load-on-startup>

</servlet>

...

<servlet-mapping>

<servlet-name>application</servlet-name>

<url-pattern>*.report</url-pattern>

</servlet-mapping>

...

Definir la localització de les definicions de les vistes

Fitxer de configuració: canigo-services-reporting.xml
Ubicació proposada: <PROJECT_ROOT>/src/main/resources/spring

Configurar un bean amb un identificador (es recomana usar 'viewResolver' ) i els següents atributs:

Atribut	Requerit	Descripció
class	Sí	Defineix el tipus de resolver de Spring utilitzarem per indicar on trobar el fitxer amb la definició dels reports. Es recomana utilitzar la notació XML: # org.springframework.web.servlet.view.XmlViewResolver

Configurar les següents propietats:

Propietat	Requerit	Descripció
location	Sí	Referència a la localització del fitxer amb la definició dels reports.

Exemple:

...

<!-- REPORTING service -->

<bean id="viewResolver"  class="org.springframework.web.servlet.view.XmlViewResolver"  >

<property name="location" value="classpath:reports/views.xml"  />

</bean>

...

Declaració dels forwards globals per poder usar el servei des d'un Action

Fitxer de configuració: canigo-services-reporting.xml
Ubicació proposada: <PROJECT_ROOT>/src/main/resources/spring

Definir un forward per cada format de renderització emprat, seguint el següent patró:

<forward name="report*<FORMAT>*"

path="/view.report?contentType=<format>"

redirect="true" />

Usar el següent codi:

...

<global-forwards>

...

<!-- Forward to report -->

<forward name="reportPDF"  path="/view.report?contentType=pdf" redirect="true" />

<forward  name="reportXLS" path="/view.report?contentType=xls" redirect="true"  />

<forward name="reportCSV" path="/view.report?contentType=csv"  redirect="true" />

<forward name="reportHTML"  path="/view.report?contentType=html" redirect="true" />

<forward name="reportRTF"  path="/view.report?contentType=rtf" redirect="true" />
...

</global-forwards>

...

Declaració del controlador assignat als reports

Fitxer de configuració: canigo-services-reporting.xml
Ubicació proposada: <PROJECT_ROOT>/src/main/resources/spring

Definir el controlador a utilitzar en la renderització dels reports, per això s'ha de definir el següent bean:

En la definició del bean "ExportInterceptor", a la propietat "redirections" s'ha d'afegir l'entrada:

<entry key="//.report" value="/view.report" />

En la definició del bean "urlMapping", a la propietat "mappings" s'ha d'afegir l'entrada:

<prop key="view.report">reportingController</prop>

Exemple:

...

<bean id="ExportInterceptor" class="net.gencat.ctti.canigo.services.web.spring.
BufferedResponseSpringInterceptor">
    <property name="redirections">
        <map>
        ...
            <entry key="//.report" value="/view.report" />*
        </map>
    </property>
</bean>

<bean id="urlMapping" class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
    ...
    <property name="mappings">
        <props>
            ...
            <prop key="view.report">reportingController</prop>
            </props>
          </property>
</bean>

...
<bean id="reportingController" class="net.gencat.ctti.canigo.services.reporting.ReportingController"/>

Localització dels reports i el seu tipus de visualització

Fitxer de configuració: views.xml
Ubicació proposada: <PROJECT_ROOT>/src/main/resources/reports

La definició de cada report requereix configurar un bean amb un identificador (es recomana usar '<nom_report>Report' ) i els següents atributs:
Atributs:
|| Atribut || Requerit || Descripció ||

class

Sí

Defineix la classe que s'emprarà per realitzar el renderitzat del report.

Exemple: net.gencat.ctti.canigo.services.reporting.impl.WrapperJasperMultiFormatView

També es poden configurar les següents propietats:

Propietat	Requerit	Descripció
url	Sí	Localització del fitxer jrxml amb el disseny del report.
contentType	Sí	Format del fitxer a mostrar (pdf, xls, html, csv, rtf)
contentDispositionMappings	No	Nom del fitxer a mostrar

Exemple:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
"http://www.springframework.org/dtd/spring-beans.dtd?">

<beans>

    ...
    <bean id="RotationReport" class="net.gencat.ctti.canigo.services.reporting.impl.
    WrapperJasperMultiFormatView" >
        <property name="url" value="classpath:reports/rotation/RotationReport.jrxml" />
    </bean>
    <bean id="CustomersReport" class="net.gencat.ctti.canigo.services.reporting.impl.
    WrapperJasperMultiFormatView" >
        <property name="url" value="classpath:reports/customers/CustomersReport.jrxml" />
        <property name="contentDispositionMappings" >
            <props>
                <prop key="rtf">inline; filename=report.rtf</prop>
                <prop key="html">inline; filename=report.html</prop>
                <prop key="pdf">inline; filename=report.pdf</prop>
                <prop key="xls">inline; filename=report.xls</prop>
            </props>
        </property>
    </bean>
    ...

</beans>

Utilització del Servei

Canigó defineix 2 maneres d'integrar les dades d'un report:

Utilitzant el "data source" específic proporcionat per JasperReports
Injectant les dades des del model de l'aplicació (obtingudes mitjançant el servei de persistència, fitxers de properties, etc.)

Com exemple d'utilització del servei de Reporting s'inclou un exemple en el que es visualitza un report senzill. A continuació es mostren els pasos a seguir per integrar un report dins d'una aplicació:

Realitzar el disseny del report

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jasperReport PUBLIC "-//JasperReports//DTD Report Design//EN"
"http://jasperreports.sourceforge.net/dtds/jasperreport.dtd">

<jasperReport name="RotationReport" pageWidth="595" pageHeight="842" columnWidth="555"
leftMargin="20" rightMargin="20" topMargin="30" bottomMargin="30">
    <title>
    <band height="782">
    <staticText>
    <reportElement mode="Opaque" x="0" y="0" width="90" height="350" backcolor="#c0c0c0"/>
    <textElement rotation="Left">
    <font size="14"/>
    </textElement>
    <text><![CDATA[rotation="Left"
    textAlignment="Left"
    verticalAlignment="Top"]]></text>
    </staticText>
    <staticText>
    <reportElement mode="Opaque" x="100" y="0" width="90" height="350" backcolor="#c0c0c0"/>
    <textElement textAlignment="Center" verticalAlignment="Bottom" rotation="Left">
    <font size="14"/>
    </textElement>
    <text><![CDATA[rotation="Left"
    textAlignment="Center"
    verticalAlignment="Bottom"]]></text>
    </staticText>
    <staticText>
    <reportElement mode="Opaque" x="200" y="0" width="90" height="350" backcolor="#c0c0c0"/>
    <textElement textAlignment="Right" verticalAlignment="Middle" rotation="Left">
    <font size="14"/>
    </textElement>
    <text><![CDATA[rotation="Left"
    textAlignment="RIght"
    verticalAlignment="Middle"]]></text>
    </staticText>
    <staticText>
    <reportElement mode="Opaque" x="255" y="410" width="90" height="350"
    forecolor="#ffffff" backcolor="#404040"/>
    <textElement textAlignment="Right" verticalAlignment="Middle" rotation="Right">
    <font size="14"/>
    </textElement>
    <text><![CDATA[rotation="Right"
    textAlignment="RIght"
    verticalAlignment="Middle"]]></text>
    </staticText>
    <staticText>
    <reportElement mode="Opaque" x="355" y="410" width="90" height="350"
    forecolor="#ffffff" backcolor="#404040"/>
    <textElement textAlignment="Center" verticalAlignment="Bottom" rotation="Right">
    <font size="14"/>
    </textElement>
    <text><![CDATA[rotation="Right"
    textAlignment="Center"
    verticalAlignment="Bottom"]]></text>
    </staticText>
    <staticText>
    <reportElement mode="Opaque" x="455" y="410" width="90" height="350"
    forecolor="#ffffff" backcolor="#404040"/>
    <textElement rotation="Right">
    <font size="14"/>
    </textElement>
    <text><![CDATA[rotation="Right"
    textAlignment="Left"
    verticalAlignment="Top"]]></text>
    </staticText>
    </band>
    </title>
</jasperReport>

Nota: Per realitzar el disseny del report es recomana la utilizació d'una eina visual tipus iReport. Veure l'apartat "Eines de Suport".

Registrar el report en el servei (fitxer views.xml)

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
"http://www.springframework.org/dtd/spring-beans.dtd">

<beans>
...
    <bean id="RotationReport" class="net.gencat.ctti.canigo.services.reporting.impl.
    WrapperJasperMultiFormatView" >
        <property name="url" value="classpath:reports/rotation/RotationReport.jrxml" />
        <property name="contentDispositionMappings" >
            <props>
                <prop key="rtf">inline; filename=rotationReport.rtf</prop>
                <prop key="html">inline; filename=rotationReport.html</prop>
                <prop key="pdf">inline; filename=rotationReport.pdf</prop>
                <prop key="xls">inline; filename=rotationReport.xls</prop>
            </props>
        </property>        
    </bean>
...

</beans>

Modelar les dades a mostrar (opcional)

Per renderitzar el report amb dades modelades per un Action, s'ha de definir específicament un Map i informar-lo amb parells "nom/valor" que el servei de reporting utilitzarà per omplir el report al visualitzar-lo.

/**
* Modeling data for report
*/
public ActionForward reportRotation(Category vo, StrutsContext context) {
    // Get data for render report
    Map model = getModel();

    // Save data in session
    context.getRequest().getSession().setAttribute(ReportingController.
    REPORTING_CONTROLLER_MODEL,model);

    // Set view name to render
    context.getRequest().getSession().setAttribute(ReportingController.
    REPORTING_CONTROLLER_REPORTID,"RotationReport");

    // Forward to report Controller
    return context.getActionMapping().findForward("reportPDF");
}

private Map getModel() {
    Map model = new HashMap();
    Collection beanData = getData();
    model.put("myBeanData", beanData);
    return model;
}

protected List getData() {
    List list = new ArrayList();
    for (int x = 0; x < 10; x++) {
        Category bean = new Category();
        bean.setId(""+x);
        bean.setName("canigo");
        list.add(bean);
    }
    return list;
}

Nota: Si el report utilitza el seu propi "data source" (o no mostra dades dinàmiques) no serà necessari realitzar aquest pas.

Invocar el report

Per invocar el report dins de l'aplicació es pot realitzar mitjançant:

Un Action (si s'ha de modelar les dades):
http://localhost:8080/canigo-samples\Petstore/categories.do?reqCode=reportRotation
Un servlet (només si el report utilitza el seu propi "data source"). S'han d'especificar els següents paràmetres:

reportId+: identificador del report segons s'hagi definit en el fitxer views.xml
contentType+: tipus de format a visualitzar (csv, pdf, xls o html)

http://localhost:8080/canigo-samples-Petstore/view.report?contentType=pdf&reportId=RotationReport

Eines de Suport

iReport

El disseny d'un report representa una plantilla que serà utilitzada pel servei per mostrar contingut dinàmic en el format escollit. Està definit en fitxers XML que han de tenir una estructura predefinida. Aquests XML s'han de compilar per poder realitzar les operacions d'omplir dades, aquesta tasca de compilació la realitza el servei de manera "on the fly".

És aconsellable utilitzar una eina visual per realitzar el disseny dels reports, aquesta eina ha de facilitar l'edició de reports complexes amb gràfics, imatges, subreports, etc. Una eina que compleix tots aquests requisits és iReport http://ireport.sourceforge.net.

Algunes de les característiques que proporciona iReport són:

Suport per gràfics:

Agrupacions i seccions

Diferents tipus de connexions

Formateig del document