Escolar Documentos
Profissional Documentos
Cultura Documentos
http://www.guj.com.br
Introduo
Dentre as tarefas de um sistema, a mais comum a gerao de relatrio. Presente na maioria dos
sistemas, mas muitas vezes no suficientemente reconhecida, esta tarefa constitui um importante
mdulo do sistema.
Basicamente, o processo de gerao de relatrio resume-se na definio 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. Porm, o
que se v hoje o surgimento de ferramentas open-source com o mesmo objetivo, e to ou mais
robustas que as comerciais, com a grande convenincia de serem gratuitas. o caso das ferramentas
foco deste documento: JasperReports e iReport..
Links:
JasperReports: http://jasperreports.sourceforge.net
iReport: http://ireport.sourceforge.net
JasperReports
JasperReports um poderoso framework open-source para gerao de relatrios. Escrito em Java, essa
biblioteca apresenta grande habilidade na organizao e apresentao de contedo, permitindo a gerao
dinmica de relatrios em diversos formatos, como PDF, HTML, XLS, CSV e XML, podendo ainda ser
utilizada em qualquer aplicao Java, incluindo aplicaes desktop, Web e distribudas.
Funcionamento
Antes de iniciar a utilizar a biblioteca JasperReports, necessrio a compreenso de seu
funcionamento (Veja a fig. 1).
O design do relatrio, incluindo a localizao dos campos a serem preenchidos e seus respectivos
nomes, para futuro mapeamento, so definidos em um arquivo XML atravs de tags XML que obedecem
a uma estrutura, vocabulrio e restries declarados em um arquivo DTD (jasperreports.dtd). Usando
XML, o designer pode definir textos estticos, imagens, linhas, formas geomtricas, como retngulos e
elipses, e suas localizaes dentro do relatrio. Pode-se, ainda, e principalmente, definir os campos que
sero preenchidos dinamicamente a partir de uma base de dados. O arquivo XML precisa ser compilado,
gerando um arquivo .jasper, isto , contendo a verso compilada do cdigo XML. Isto implica na
compilao de todas as expresses Java definidas no arquivo XML, sendo realizadas vrias verificaes
em tempo de compilao.
Diferentes objetos JasperReports so usados para representar as etapas do processo de gerao de
relatrio:
JasperDesign: Representa a definio do relatrio. A partir do template XML criado um
JasperDesign.
JasperReport: Representa o JasperDesign compilado. O processo de compilao verifica o design do
relatrio e compila o design em um objeto JasperReport.
JasperPrint: Representa o relatrio gerado. criado um JasperPrint a partir de um JasperReport,
contendo o relatrio preenchido.
Dados
Para produzir um relatrio 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 informaes de um banco de dados relacional, precisamos realizar uma consulta (query)
Grupo de Usurios Java
http://www.guj.com.br
em linguagem SQL. Essa query pode ser inserida ao cdigo XML ou ser realizada por uma classe Java,
gerando um objeto ResulSet, que ser passado s classes do Jasper para o preenchimento do relatrio.
O JasperReports suporta vrios tipos de datasources (fonte de dados) atravs de uma interface
especfica chamada JRDataSource. H uma implementao padro desta interface para objetos
ResultSet, chamada JRResultSetDataSource, ou seja, possvel realizar consultas, gerando objetos
ResultSet e passando ao JasperReports para o preenchimento do relatrio. Quando a fonte de dados
um ResultSet, este objeto deve conter todas as colunas a serem mapeadas para seus campos
correspondentes no relatrio.
A figura 1 ilustra o funcionamento do JasperReports:
Parmetros so dados passados para a operao de preenchimento, que no podem ser encontrados
normalmente na fonte de dados. So declarados, por exemplo, da seguinte forma:
<parameter name=TituloDoRelatorio class=java.lang.String/>
Variveis so utilizadas para simplificar o projeto do relatrio. Atravs de uma varivel podemos
definir somente uma vez uma expresso, que seja usada freqentemente durante o design do relatrio,
chamando-a quando precisarmos daquela funcionalidade. Elas podem referenciar tipos internos de
clculos, como contagem (count), soma (sum), mdia (average), menor (lowest), maior (highest), etc.
Por exemplo, o clculo do valor total da compra:
<variable name=ValorTotalCompraSum class=java.lang.Double calculation=Sum>
<variable expression> ${ValorProduto} </variable expression>
</variable>
Em uma expresso, uma varivel pode referenciar outras variveis do relatrio, mas somente se
aquelas variveis foram definidas previamente no projeto do relatrio. Assim, a ordem em que as
variveis so declaradas no relatrio importante.
Grupo de Usurios Java
http://www.guj.com.br
Para as variveis que executam o clculo ns podemos especificar o nvel em que devem ser
reinicializadas. O nvel Report (de relatrio) significa que a varivel ser inicializada somente uma vez,
no comeo do relatrio, e que executa o clculo especificado at que o fim do relatrio seja alcanado.
Mas ns podemos escolher executar o clculo em nvel de pgina, coluna ou de grupo. O exemplo
abaixo demonstra o mesmo clculo anterior em nvel de pgina. Nossa varivel ser inicializada com zero
no comeo de cada nova pgina:
<variable name=ValorTotalCompraSum class=java.lang.Double
resetType=Page calculation=Sum>
<variable expression> ${ValorProduto} </variable expression>
<initialValueExpression> new Double( 0 ) </initialValueExpression>
</variable>
Existem tambm variveis internas da ferramenta, com nomes auto-explicativos, prontas para o uso
nas expresses: PAGE_NUMBER, COLUMN_NUMBER, REPORT_COUNT, PAGE_COUNT, COLUMN_COUNT,
GroupName_COUNT.
Expresses (Expressions) so utilizadas para especificar o contedo de campos de texto, na
realizao de clculos freqentes, por exemplo. Todas elas so expresses Java que podem conter em
sua sintaxe: campos, parmetros e variveis de relatrio. Por exemplo:
<textFieldExpression>
Sr.(a) + $F{Cliente} + " realizou um total de compras no valor de "
+ $V{ValorTotalCompraSum} + " no dia "
+ (new SimpleDateFormat("dd/MM/yyyy")).format($F{DataCompra}) + "."
</textFieldExpression>
Layout
Para a melhor organizao e definio do design do relatrio, o JasperReports divide o layout em reas
pr-definidas, chamadas sees. Ao projetar um relatrio ns necessitamos definir a posio do
contedo dentro de uma seo, levando em considerao o que ela representa na estrutura visual de um
relatrio. A seguir esto as sees em que baseado o layout de relatrio: title, pageHeader,
columnHeader, groupHeader, detail, groupFooter, columnFoter, pageFooter, summary.
Mais detalhes
Enquanto escrevia, o JasperReports encontrava-se em sua verso 0.5.x, na qual
se baseia este documento. Maiores informaes em:
http://jasperreports.sourceforge.net.
iReport
Criar o design do relatrio diretamente em XML pode ser uma tarefa custosa. Necessitava-se, ento,
de uma ferramenta que automatizasse esse processo. O iReport veio preencher essa lacuna, permitindo
definir o design do relatrio dentro de um ambiente grfico, contento todos os recursos que a biblioteca
Jasper oferece. possvel definir relatrios com designs modernos e complexos sem se quer escrever
uma linha de cdigo XML, que todo gerado automaticamente. O ambiente ainda oferece atalhos para
tarefas de compilao e visualizao do relatrio, permitindo a realizao de testes, acelerando assim o
processo de design.
importante salientar que existem outras ferramentas com o mesmo objetivo que o iReport, mas que
no so suficientemente maduras, no que diz respeito a facilidade de uso, e principalmente, no suporte
as tags XML do JasperReports.
Mais detalhes
Abaixo esto outras alternativas para o design grfico do relatrio:
- 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 Usurios Java
http://www.guj.com.br
Fonte de Dados
O iReport d suporte a conexes JDBC, ODBC, e 4 tipos de datasources:
1 Empty data source (JREmptyDatasource): um especial datasource usado para preencher
relatrios que no possuem registros ou dados recuperados. Este datasource usado quando
pressionado o boto run:
2 XML DataSource: um datasource capaz de empacotar um arquivo XML e normalizar seu contedo.
As nicas informaes necessrias para criar este tipo de datasource so: 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. necessrio uma classe especial de fbrica (factory) que fornea um mtodo esttico para
gerar a coleo ou um array de JavaBeans. Para criar este datasource voc precisa de um nome para o
datasource, o nome da classe que fornece o mtodo esttico para recuperar o Array/Collection de objetos
e o nome deste mtodo, que ter uma definio como esta:
public static Collection createMyCollection( )
ou
public static Object[ ] createMyArray( )
necessrio setar o tipo de resultado (Collection ou Array).
4 Custom Datasource: este tipo de datasource genrico. O iReport no sabe como a interface
JRDataSource implementada por esta conexo particular, mas isto no importante. necessrio uma
classe especial de fbrica (factory) que fornea um mtodo esttico que retorne um JRDataSource. Para
criar este datasource voc precisa do nome do datasource, do nome da classe que fornece o mtodo
esttico para recuperar o JRDataSource, e do nome deste mtodo que ter uma definio como esta:
public static JRDataSource createMyJRDataSource( )
Mais detalhes
Enquanto escrevia, o iReport encontrava-se em sua verso 0.2.x, na qual se baseia este
documento. Maiores informaes em: http://ireport.sourceforge.net.
Requisitos
Ambas as ferramentas possuem requisitos para o seu funcionamento, os quais so em sua maioria
bibliotecas de terceiros, tambm gratuitas. Ao realizar o download opte pelos arquivos completos, pois
estes possuem todas as bibliotecas necessrias. No necessrio 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 links
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 diretrio de sua preferncia. Cheque nesse momento se sero
criadas as pastas referentes.
2. Cheque se o JDK e o Ant esto devidamente configurados, ou seja, se as variveis de ambiente
JAVA_HOME e ANT_HOME foram criadas e esto apontando para os diretrios 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 tambm setar no CLASSPATH o driver JDBC do banco.
3. Copie o arquivo tools.jar, localizado na pasta lib de seu JDK instalado, para os diretrio
...\iReport\lib
4. Copie o driver JDBC de seu banco para a pasta lib do iReport.
5. Para testar a instalao do iReport, abra o prompt, v ao diretrio do iReport e digite ant iReport.
Outra opo editar o arquivo iReport.bat (para Windows) ou iReport.sh (para Linux), localizados na
Grupo de Usurios Java
http://www.guj.com.br
pasta iReport-0.2.x. Corrija as variveis para apontarem para os diretrios corretos, executando o
arquivo de lote. Se tudo ocorreu bem o iReport ir inicializar. H tambm 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 diretrio 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 relatrio. Aps isso clique em Save.
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 (conexo direta com o banco) do Firebird
chamado de Jaybird.
Mais detalhes
Abaixo esto os links para realizar o download dos arquivos e ferramentas necessrias
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 no descreve como utilizar outros tipos de datasources, isto ser feito em outra
oportunidade.
2. Na janela que aparece escolha o tipo de conexo (no nosso caso Database JDBC Connection). Na
mesma janela d um nome conexo. Por exemplo, BibliotecaPessoal FB.
3. No campo JDBC Driver, selecione o driver do seu banco. Caso no esteja listado, como no nosso
caso, especifique um de acordo com o seu SGBD. Para o Firebird, digite
org.firebirdsql.jdbc.FBDriver, lembrando que o driver deve estar no classpath.
4. Em JDBC URL digitamos o caminho para a nossa base de dados:
jdbc:firebirdsql:localhost/3050:c://db//Acervo.fdb
Obs.: A sintaxe da URL difere de SGBD para SGBD, consulte a documentao de seu banco para saber a
sintaxe exata. Repare tambm no caminho para a base de dados.
5. Em Server Address digite o caminho para servidor de banco de dados, no nosso caso localhost.
Em Database, entre com o nome do banco (Acervo.fdb) ou do alias. Entramos, ento, com o user
sysdba e password masterkey. Temos a possibilidade de salvar a senha marcando a opo Save
password.
Java. Porm, conveniente, at mesmo para a realizao dos testes, termos um nico ambiente que
alm de permitir a definio do layout, tambm permita visualizarmos, em diversos formatos, o resultado
do design e preenchimento do relatrio atravs de um simples boto (Run): . Para isso, neces-srio
que a conexo JDBC esteja funcionando.
Considerando que o teste de conexo com o banco foi bem-sucedido iniciamos a etapa de design do
relatrio.
1. V ao menu File >> New Document ou clique no boto:
2. Ir aparecer a janela Report Properties onde damos um nome ao nosso relatrio (Report Name)
chamando-o de RelatorioBibliotecaPessoal (no pode haver espao entre as palavras). Ainda na
mesma janela podemos configurar o tamanho da pgina, a sua orientao, as margens, o comprimento,
largura e o espao entre as colunas, alm de outras opes mais avanadas.
Inserimos os elementos do relatrio, bastando clicarmos uma vez sobre o respectivo boto e logo aps
no relatrio. O contedo dos elementos de texto e as configuraes de fonte esto disponveis atravs de
um duplo clique sobre o elemento, assim como as configuraes para os elementos geomtricos.
Na figura 8, os textos Relatrio Biblioteca Pessoal, Data:, Cdigo, Ttulo, Volume,
Edio, Editora, Autor e Adquirido em so campos de texto esttico:
4. Para definir os campos (fields) para preenchimento , precisamos conhecer os nomes das colunas
das tabelas de onde recuperaremos os dados. O iReport permite a insero do SQL no cdigo XML
atravs do menu Datasource >> Report query ou clicando no boto:
5. No campo da janela que aparece, na aba Report SQL Query, digitamos nossa query. Levando em
considerao que o resultado dessa consulta deve conter os dados que preenchero o relatrio, o SQL
deve ser bem estruturado. A mesma janela nos permite visualizar os nomes dos campos que fazem parte
do resultado da consulta. Por exemplo, se digitarmos a consulta SELECT * FROM LIVRO e em seguida
clicarmos no boto Read Fields visualizaremos todas as colunas da tabela LIVRO de nosso banco, e
seus respectivos tipos. Para inserir esta consulta no cdigo XML devemos clicar no boto Save query to
report.
Obs.: Em nosso exemplo no iremos inserir o SQL no cdigo XML. Realizaremos a conexo com o
banco e a consulta em nossa classe Java, passando o objeto ResultSet gerado para o JasperReports.
6. Agora que conhecemos os nomes das colunas e seus tipos, podemos definir nossos campos (fields)
no relatrio, registrando-os para o mapeamento dos dados. Para tanto, na mesma janela selecione o
primeiro campo (coluna) que aparece e, segurando a tecla Shift, clique no ltimo campo, pressionando
o boto Register fields to report. A mesma tarefa pode ser realizada indo ao menu View >>
Report fields ou clicando no boto:
A janela que aparece permite o registro de campos, parmetros e a criao de variveis no relatrio:
7. Aps registrarmos as colunas a serem mapeadas, devemos inserir elementos fields que faro
referncia a elas para serem preenchidos. Para isso, depois de inserir um field, damos um duplo clique
nele, surgindo assim uma janela onde, na aba Text Field, em TextField Expression Class,
configuraremos a classe referente ao tipo da coluna que queremos mapear; e em Textfield
expression, o nome desta coluna entre $F{ e }. Por exemplo, para mapear a coluna CODIGO que do
tipo INTEGER, selecionamos em TextField Expression Class, a classe java.lang.Integer, e em
Textfield expression digitamos $F{CODIGO}. Realize o mesmo processo para as outras colunas
(TITULO, AUTOR, VOLUME, EDICAO, EDITORA, DATA_ADQUIRIDO), atentando para o tipo da coluna.
8. Podemos tambm criar expresses para efetuar clculos ou formataes sobre os dados provenientes
das colunas mapeadas, assim como, optar a que nvel executar esta expresso. (veja Variveis e
Expresses)
Em nosso exemplo inserimos a dada atual de impresso do relatrio, formatando-a de acordo com o
padro brasileiro. Para isso, inserimos um field, damos um duplo clique sobre ele, e na janela que
aparece, na aba Text Field, digitamos a seguinte expresso Java no campo TextField Expression:
new SimpleDateFormat( "dd/MM/yyyy" ).format( new Date( ) )
Outro exemplo pode ser visto ao inserirmos o nmero das pginas de nosso relatrio. Para isso,
utilizamos a varivel interna $V{PAGE_NUMBER}.
Grupo de Usurios Java
http://www.guj.com.br
Inserimos dois fields no relatrio. No primeiro, no campo Evaluation time, escolhemos o nvel de
execuo Now, que considerar a pgina atual e para o segundo field, o nvel Report, que significa
que a varivel ser inicializada somente uma vez, no comeo do relatrio, e que executa o clculo
especificado at que o fim do relatrio seja alcanado, ou seja, a quantidade de total de pginas.
Fig. 13: Nmero da pgina atual. Fig. 14: Nmero total de pginas.
9. Para informarmos ao iReport em que formato desejamos visualizar o relatrio, vamos ao menu
Build, escolhendo uma das opes de visualizao ali existentes.
Vimos at o momento como configurar e utilizar o iReport para montar o layout de nosso relatrio, e
tambm visualiz-lo para fins de teste. Nesta seo, veremos na prtica como gerar um relatrio em
formato pdf a partir de uma classe simples. A classe RelatorioBibliotecaPessoal ser apresentada e
descrita posteriormente.
Supe-se que voc j utilizou o iReport para criar o design do relatrio e definir os campos a serem
preenchidos, que estas informaes foram salvas em um arquivo XML, e que este foi compilado neste
mesmo ambiente, gerando um arquivo .jasper. Este ltimo arquivo (.jasper) ser utilizado pela classe a
seguir:
/* pacotes necessrios */
import dori.jasper.engine.*;
import dori.jasper.view.JasperViewer;
import java.sql.*;
import java.util.*;
Grupo de Usurios Java
http://www.guj.com.br
Class.forName(driver);
Connection con = DriverManager.getConnection( url, user, password );
return con;
}
Obs.: O HashMap de parmetros deve ser instanciado, mesmo no havendo a utilizao destes no
relatrio. So exigidos por todos os mtodos de preenchimento do JasperReports.
4. O arquivo .jrprint (BibliotecaPessoal.jrprint) passado como parmetro para o mtodo
exportReportToPdfFile() da classe dori.jasper.engine.JasperExportManager para exportar o
relatrio para o formato pdf.
Mais detalhes
Outros formatos suportados pelo JasperReports podem ser obtidos a partir da
utilizao de seus mtodos referentes. Consulte a documentao (javadoc) do
JasperReports para conhec-los: http://jasperreports.sourceforge.net/api/index.html
Obs.: A classe dori.jasper.engine.JasperRunManager pode substituir a utilizao das classes
JasperFillManager e JasperExportManager nos passos 3 e 4. Seu mtodo runReportToPdfFile(), por
exemplo, recebe como parmetros o arquivo .jasper referente ao relatrio compilado, possveis
parmetros (parameters) e o objeto JRResultSetDataSource.
5. Finalizando, utilizada a classe dori.jasper.viewer.JasperViewer, uma GUI para a visualizao do
relatrio em pdf. Seu mtodo viewReport() recebe como parmetro o nome do arquivo de relatrio e
um boolean referente ao formato do arquivo de relatrio, ou seja, true para arquivos XML e false para
outro.
Concluso
Demonstramos a interao do JasperReports com o iReport, para a gerao de relatrios. Vimos como
instalar e configurar o iReport, assim como utiliz-lo para desenhar relatrios estruturados que sero
processados pelo JasperReports.
Ambas as ferramentas demonstradas aqui, se completam e mostram-se poderosas, oferecendo ao
desenvolvedor um amplo conjunto de recursos na organizao e apresentao de contedo de um
relatrio. A utilizao destas, permite o rpido desenvolvimento de um relatrio estruturado e complexo
de modo gil e facilitado.