(Parte 1 de 2)

Grupo de Usuários Java http://www.guj.com.br

Geração de Relatório com JasperReports e iReport

Carlos Feliz Paixão

Este documento descreve a instalação, configuração e utilização de duas ferramentas open-source para a geração de relatórios em Java: JasperReports e iReport. É realizado um exemplo de geração de relatório no formato PDF, utilizando uma base de dados em Firebird, demonstrando assim o poder dessas ferramentas.

Introdução

Dentre as tarefas de um sistema, a mais comum é a geração de relatório. Presente na maioria dos sistemas, mas muitas vezes não suficientemente reconhecida, esta tarefa constitui um importante módulo do sistema.

Basicamente, o processo de geração de relatório resume-se na definição do design e mapeamento de dados para campos dentro de um layout definido. Nesse contexto, surgiram ferramentas comerciais com intuito de auxiliar neste processo. No passado, essa área foi completamente dominada por produtos comerciais, como o Crystal Reports, que com o passar do tempo tornaram-se cada vez mais robustos no que diz respeito a novas funcionalidades, como o suporte a diferentes tipos de fontes de dados. Porém, o que se vê hoje é o surgimento de ferramentas open-source com o mesmo objetivo, e tão ou mais robustas que as comerciais, com a grande conveniência de serem gratuitas. É o caso das ferramentas foco deste documento: JasperReports e iReport..

Link’s:

JasperReports: http://jasperreports.sourceforge.net iReport: http://ireport.sourceforge.net

JasperReports

JasperReports é um poderoso framework open-source para geração de relatórios. Escrito em Java, essa biblioteca apresenta grande habilidade na organização e apresentação de conteúdo, permitindo a geração dinâmica de relatórios em diversos formatos, como PDF, HTML, XLS, CSV e XML, podendo ainda ser utilizada em qualquer aplicação Java, incluindo aplicações desktop, Web e distribuídas.

Funcionamento

Antes de iniciar a utilizar a biblioteca JasperReports, é necessário a compreensão de seu funcionamento (Veja a fig. 1).

O design do relatório, incluindo a localização dos campos a serem preenchidos e seus respectivos nomes, para futuro mapeamento, são definidos em um arquivo XML através de tags XML que obedecem a uma estrutura, vocabulário e restrições declarados em um arquivo DTD (jasperreports.dtd). Usando XML, o designer pode definir textos estáticos, imagens, linhas, formas geométricas, como retângulos e elipses, e suas localizações dentro do relatório. Pode-se, ainda, e principalmente, definir os campos que serão preenchidos dinamicamente a partir de uma base de dados. O arquivo XML precisa ser compilado, gerando um arquivo .jasper, isto é, contendo a versão compilada do código XML. Isto implica na compilação de todas as expressões Java definidas no arquivo XML, sendo realizadas várias verificações em tempo de compilação.

Diferentes objetos JasperReports são usados para representar as etapas do processo de geração de relatório:

JasperDesign: Representa a definição do relatório. A partir do template XML é criado um JasperDesign.

JasperReport: Representa o JasperDesign compilado. O processo de compilação verifica o design do relatório e compila o design em um objeto JasperReport.

JasperPrint: Representa o relatório gerado. É criado um JasperPrint a partir de um JasperReport, contendo o relatório preenchido.

Dados

Para produzir um relatório precisamos fornecer dados ao Jasper. Estes dados podem ser recuperados de diferentes lugares, como de uma base de dados em um SGBD ou em um arquivo XML. Para recuperarmos informações de um banco de dados relacional, precisamos realizar uma consulta (query)

Grupo de Usuários Java – http://www.guj.com.br – Página 1

Grupo de Usuários Java http://www.guj.com.br em linguagem SQL. Essa query pode ser inserida ao código XML ou ser realizada por uma classe Java, gerando um objeto ResulSet, que será passado às classes do Jasper para o preenchimento do relatório.

O JasperReports suporta vários tipos de datasources (fonte de dados) através de uma interface específica chamada JRDataSource. Há uma implementação padrão desta interface para objetos ResultSet, chamada JRResultSetDataSource, ou seja, é possível realizar consultas, gerando objetos ResultSet e passando ao JasperReports para o preenchimento do relatório. Quando a fonte de dados é um ResultSet, este objeto deve conter todas as colunas a serem mapeadas para seus campos correspondentes no relatório.

A figura 1 ilustra o funcionamento do JasperReports:

Fig. 1: Etapas para a geração de relatório com JasperReports.

No linguajar “Jasper", um datasource somado a um arquivo .jasper gera um "print", que pode ser "exportado" para os formatos PDF, HTML, XML, CVS ou XLS.

Campos, Parâmetros, Variáveis e Expressões

Campos (Fields) são “áreas específicas” que receberão diretamente os dados das respectivas colunas referenciadas. O relatório deve conter um campo com o mesmo nome da coluna a qual faz referência. Por exemplo, para os dados da coluna Nome do tipo VARCHAR, da tabela Cliente, serem mapeados para o relatório, um campo Nome deve ser definido no arquivo XML da seguinte forma:

<field name=”Nome” class=”java.lang.String”/>

Parâmetros são dados passados para a operação de preenchimento, que não podem ser encontrados normalmente na fonte de dados. São declarados, por exemplo, da seguinte forma:

<parameter name=”TituloDoRelatorio” class=”java.lang.String”/>

E passados via código Java, através da classe HashMap:

Map parametros = new HashMap( ); parametros.put( “Cliente”, “Carlos Paixão” );

Outra importante utilização de parâmetros é na query do relatório. Por exemplo: Select * FROM CLIENTE WHERE CLIENTE=$P{Cliente}

O relatório será gerado apenas para o cliente passado por parâmetro.

Variáveis são utilizadas para simplificar o projeto do relatório. Através de uma variável podemos definir somente uma vez uma expressão, que seja usada freqüentemente durante o design do relatório, chamando-a quando precisarmos daquela funcionalidade. Elas podem referenciar tipos internos de cálculos, como contagem (count), soma (sum), média (average), menor (lowest), maior (highest), etc. Por exemplo, o cálculo do valor total da compra:

<variable name=”ValorTotalCompraSum” class=”java.lang.Double” calculation=”Sum”> <variable expression> ${ValorProduto} </variable expression>

</variable>

Em uma expressão, uma variável pode referenciar outras variáveis do relatório, mas somente se aquelas variáveis foram definidas previamente no projeto do relatório. Assim, a ordem em que as variáveis são declaradas no relatório é importante.

Grupo de Usuários Java – http://www.guj.com.br – Página 2

Grupo de Usuários Java http://www.guj.com.br

Para as variáveis que executam o cálculo nós podemos especificar o nível em que devem ser reinicializadas. O nível Report (de relatório) significa que a variável será inicializada somente uma vez, no começo do relatório, e que executa o cálculo especificado até que o fim do relatório seja alcançado. Mas nós podemos escolher executar o cálculo em nível de página, coluna ou de grupo. O exemplo abaixo demonstra o mesmo cálculo anterior em nível de página. Nossa variável será inicializada com zero no começo de cada nova página:

<variable name=”ValorTotalCompraSum” class=”java.lang.Double” resetType=”Page” calculation=”Sum”>

<variable expression> ${ValorProduto} </variable expression>

<initialValueExpression> new Double( 0 ) </initialValueExpression>

</variable>

Existem também variáveis internas da ferramenta, com nomes “auto-explicativos”, prontas para o uso nas expressões: PAGE_NUMBER, COLUMN_NUMBER, REPORT_COUNT, PAGE_COUNT, COLUMN_COUNT, GroupName_COUNT.

Expressões (Expressions) são utilizadas para especificar o conteúdo de campos de texto, na realização de cálculos freqüentes, por exemplo. Todas elas são expressões Java que podem conter em sua sintaxe: campos, parâmetros e variáveis de relatório. Por exemplo:

<textFieldExpression>

“Sr.(a) ” + $F{Cliente} + " realizou um total de compras no valor de " + $V{ValorTotalCompraSum} + " no dia "

+ (new SimpleDateFormat("d/M/y")).format($F{DataCompra}) + "."

</textFieldExpression>

Layout

Para a melhor organização e definição do design do relatório, o JasperReports divide o layout em áreas “pré-definidas”, chamadas seções. Ao projetar um relatório nós necessitamos definir a posição do conteúdo dentro de uma seção, levando em consideração o que ela representa na estrutura visual de um relatório. A seguir estão as seções em que é baseado o layout de relatório: title, pageHeader, columnHeader, groupHeader, detail, groupFooter, columnFoter, pageFooter, summary.

Mais detalhes

Enquanto escrevia, o JasperReports encontrava-se em sua versão 0.5.x, na qual se baseia este documento. Maiores informações em:

http://jasperreports.sourceforge.net.

iReport

Criar o design do relatório diretamente em XML pode ser uma tarefa custosa. Necessitava-se, então, de uma ferramenta que automatizasse esse processo. O iReport veio preencher essa lacuna, permitindo definir o design do relatório dentro de um ambiente gráfico, contento “todos” os recursos que a biblioteca Jasper oferece. É possível definir relatórios com designs modernos e complexos sem se quer escrever uma linha de código XML, que é todo gerado automaticamente. O ambiente ainda oferece atalhos para tarefas de compilação e visualização do relatório, permitindo a realização de testes, acelerando assim o processo de design.

É importante salientar que existem outras ferramentas com o mesmo objetivo que o iReport, mas que não são suficientemente maduras, no que diz respeito a facilidade de uso, e principalmente, no suporte as tags XML do JasperReports.

Mais detalhes

Abaixo estão outras alternativas para o design gráfico do relatório: - JasperDesign (http://sourceforge.net/projects/jasperdesign)

- JasperEdit (http://sourceforge.net/projects/jasperedit)

- OpenReports (http://sourceforge.net/projects/oreports)

- JasperJEdit http://www.sourceillustrated.com/jasperjedit

- JasperPal (http://sourceforge.net/projects/jasperpal)

Grupo de Usuários Java – http://www.guj.com.br – Página 3

Grupo de Usuários Java http://www.guj.com.br

Fonte de Dados

O iReport dá suporte a conexões JDBC, ODBC, e à 4 tipos de datasources:

1 – Empty data source (JREmptyDatasource): é um especial datasource usado para preencher relatórios que não possuem registros ou dados recuperados. Este datasource é usado quando é pressionado o botão “run”:

2 – XML DataSource: é um datasource capaz de empacotar um arquivo XML e normalizar seu conteúdo. As únicas informações necessárias para criar este tipo de datasource são: o nome do datasource e o nome do arquivo XML.

3 – JavaBeans Set Datasource: é um datasource capaz de empacotar uma Collection ou um Array de JavaBeans. É necessário uma classe especial de fábrica (factory) que forneça um método estático para gerar a coleção ou um array de JavaBeans. Para criar este datasource você precisa de um nome para o datasource, o nome da classe que fornece o método estático para recuperar o Array/Collection de objetos e o nome deste método, que terá uma definição como esta:

public static Collection createMyCollection( ) ou public static Object[ ] createMyArray( )

É necessário setar o tipo de resultado (Collection ou Array).

4 – Custom Datasource: este tipo de datasource é genérico. O iReport não sabe como a interface JRDataSource é implementada por esta conexão particular, mas isto não é importante. É necessário uma classe especial de fábrica (factory) que forneça um método estático que retorne um JRDataSource. Para criar este datasource você precisa do nome do datasource, do nome da classe que fornece o método estático para recuperar o JRDataSource, e do nome deste método que terá uma definição como esta:

public static JRDataSource createMyJRDataSource( )

Mais detalhes

Enquanto escrevia, o iReport encontrava-se em sua versão 0.2.x, na qual se baseia este documento. Maiores informações em: http://ireport.sourceforge.net.

Requisitos

Ambas as ferramentas possuem requisitos para o seu funcionamento, os quais são em sua maioria bibliotecas de terceiros, também gratuitas. Ao realizar o download opte pelos arquivos completos, pois estes possuem todas as bibliotecas necessárias. Não é necessário baixar o jasperreports, pois o iReport já o traz em sua pasta lib, entretanto, é interessante ver os exemplos e o javadoc fornecidos pelo JasperReports.

Mais detalhes

Você pode ver a lista completa de requisitos para o JasperReports e iReport nos link’s abaixo: JasperReports: http://jasperreports.sourceforge.net/requirements.html iReport: http://ireport.sourceforge.net/cap2.html#2.1

Instalando e configurando

1. Descompacte os arquivos do iReport no diretório de sua preferência. Cheque nesse momento se serão criadas as pastas referentes.

2. Cheque se o JDK e o Ant estão devidamente configurados, ou seja, se as variáveis de ambiente JAVA_HOME e ANT_HOME foram criadas e estão apontando para os diretórios corretos. Lembre-se de setar o PATH com JAVA_HOME\bin e ANT_HOME\bin, e o CLASSPATH com JAVA_HOME\lib e ANT_HOME\lib. No caso dos dados a serem usados forem recuperados de um banco de dados você deve também setar no CLASSPATH o driver JDBC do banco.

3. Copie o arquivo tools.jar, localizado na pasta lib de seu JDK instalado, para os diretório ...\iReport\lib

4. Copie o driver JDBC de seu banco para a pasta “lib” do iReport.

5. Para testar a instalação do iReport, abra o prompt, vá ao diretório do iReport e digite ant iReport. Outra opção é editar o arquivo iReport.bat (para Windows) ou iReport.sh (para Linux), localizados na

Grupo de Usuários Java – http://www.guj.com.br – Página 4

Grupo de Usuários Java http://www.guj.com.br pasta iReport-0.2.x. Corrija as variáveis para apontarem para os diretórios corretos, executando o arquivo de lote. Se tudo ocorreu bem o iReport irá inicializar. Há também uma forma de iniciar o iReport sem ter o Ant instalado. Para isso, execute o arquivo de lote chamado startup.bat (Windows) e statrtup.sh (Linux) localizados na pasta noAnt do diretório principal do iReport.

6. Ao iniciar, vá ao menu Tools >> Options, irá surgir uma janela (vide Fig. 2) onde você deve localizar a aba External Programs, setando ali todos os programas externos a serem utilizados como visualizadores de relatório. Após isso clique em Save.

Fig. 2: Setando programas externos.

Exemplo

O exemplo a seguir utiliza como fonte de dados uma base simples no SGBD open source Firebird, mas você pode adaptar o exemplo para uma base e um SGBD qualquer, desde que este possua um driver JDBC ou ODBC, devidamente configurado. O driver JDBC tipo 4 (conexão direta com o banco) do Firebird é chamado de Jaybird.

Mais detalhes

Abaixo estão os link’s para realizar o download dos arquivos e ferramentas necessárias para o exemplo: Firebird - http://firebird.sourceforge.net Jaybird - http://www.ibphoenix.com/main.nfs?a=ibphoenix&page=ibp_download Base de dados – acervo.fdb

Obs.: Este documento não descreve como utilizar outros tipos de datasources, isto será feito em outra oportunidade.

(Parte 1 de 2)

Comentários