ReportMaker

O BISReports é o sistema do BIS para a geração de relatórios do sistema. A função deste serviço é oferecer funções e suporte para que a aplicação possa desenvolver relatórios em PDF de forma rápida e centralizada. Outra função bem clara do BISReports é centralizar a aparência dos relatórios em todo o sistema, oferecendo templates de cabeçalhos, rodapés, e blocos de conteúdos para serem usados pelas relatórios dos plugins/módulos.

iText O BISReports funciona em cima da biblioteca [iText]. Verifique o Guia Rápido do iText para uma visão rápida do seu funcionamento e exemplos sucintos de como escrever no diretamente no documento.

BISReport

BISReport é a classe principal do serviço. Esta classe é abstrata e deve ser estendida diretamente pela classe do relatório, ou por alguma classe "intermediária" usada para criar um template específico de relatório.

Os serviços oferecidos por esta classe são:

Conjunto de Fontes

Entre as características que devem ser uniformes em todos os relatórios do sistema estão as "Fontes" usadas para escrever as informações. Por isso a classe pai oferece um conjunto de fontes para ser utilizado nos relatórios. Os conjuntos definem o tipo de letra (fonte), e sua aparência (bold, italic, etc.). Essas fontes são obtidas pelos métodos:

• getBaseFontPlain() - Retorna a fonte padrão para relatório do sistema.
• getBaseFontItalic() - Retorna a fonte padrão com o formato itálico ativado.
• getBaseFontBold() - Retorna a fonte padrão com formato negrito ativado.
• getBaseFontBoldItalic() - Retorna a fonte padrão com o formato negrito e itálico ativado.

Fontes Alternativas Embora nada impeça a criação de novas fontes nos relatórios, ou mesmo fontes específicas para relatórios específicos, deve-se analisar com cuidado a troca da fonte padrão do relatório por alguma personalizada, justamente para não remover o padrão ou dificultar a leitura do relatório.

Cabeçalhos e Rodapés

Outra característica do BISReport é a centralização dos cabeçalhos e rodapés disponíveis para serem utilizados nos relatórios. Há alguns modelos distintos de acordo com as informações que precisam ser exibidas, como títulos e subtítulos, datas de períodos, etc.

Abaixo estão listados os modelos existentes atualmente:

Métodos Utilitários

A classe oferece alguns métodos que facilitam a escrita dos relatórios. São funções e blocos de códigos que costumam se repetir em vários momentos/relatórios.

createClippedTextField

Este método cria um template para escrita de um texto e aplica um clip no tamanho desejado.

É usado (ou deve ser usado) durante a escrita de campos de texto que podem ter tamanho variável, e algumas vezes até maior do que o espaço destinado à ele. Utilizando esta técnica o campo será "cortado" no seu limite, evitando que a informação atropele outro conteúdo, ou mesmo desobedeça as margens do papel.

Mais detalhes sobre o funcionamento no javadoc do método.

getWritableWidth & getWritableHeight

Ambos os métodos servem para retornar o espaço livre da folha, retornando respectivamente a largura (eixo X) e a altura (eixo Y). Este método leva em consideração apenas 2 coisas: O tamanho da folha em uso e as margens definidas. Este método não considera cabeçalhos, rodapés ou qualquer outro conteúdo já "impresso" no relatório.

getCoord*

Os métodos getCoord são responsáveis por calcular as coordenadas a partir dos limites "writable" do documento, sendo a origem (0,0) no canto superior esquerdo. Por exemplo, ao solicitar a posição 100 a partir da esquerda, o sistema calculará 100 + a borda da esquerda para achar o valor de x correto para ser usado no PDF. Dessa maneira facilita o posicionamento dos campos no espaço "writable".

Os métodos disponíveis são:

• getCoordFromTop(c) - Obtém a coordenada Y que representa a distância "c" em relação à borda superior do espaço "writable" do documento.
• getCoordFromBottom(c) - Obtém a coordenada Y que representa a distância "c" em relação à borda inferior do espaço "writable" do documento.
• getCoordFromRight(c) - Obtém a coordenada X que representa a distância "c" em relação à borda direita do espaço "writable" do documento.
• getCoordFromLeft(c) - Obtém a coordenada X que representa a distância "c" em relação à borda esquerda do espaço "writable" do documento.
• getCoordFromMiddleX(c) - Obtém a coordenada X que representa a distância "c" em relação ao centro da largura "writable" do documento.

Distância Negativas Embora não faça muito sentido para a maioria dos métodos citados, os valores "c" podem ser passados negativos. O que fará com que o valor retornado seja no "sentido contrário". Isto é, valores positivos em geral retornam uma posição dentro do espaço "writable" da folha. O valor negativo faz mais sentido se pensar no método getCoordFromMiddleX(). Se o valor for positivo ele retornará a coordenada que fica à distância "c" do centro da página para a direita. Caso o valor seja negativo, a coordenada ficará a mesma distância "c", só que a esquerda do centro da página.

Além disso, os métodos automaticamente invertem as origens do documento conforme solicitado.

Executando um Relatório

Uma vez que o relatório foi implementado, gera-lo pode ser descrito em três passos básicos:

1. instancie a classe do relatório (que estende e implementa os métodos abstratos da BISReport);
2. chame o método writeReport();
3. por fim, obtenha o arquivo do PDF através do método getOut();

Obviamente que há passos anteriores aos 3 citados acima, como por exemplo captar e definir eventuais configurações do relatório.

BISReportBean

O BISReportBean é um objeto que "carrega" todas as configurações necessárias para a geração do relatório. Ao invés de um construtor complexo com inúmeros atributos, optamos por receber este único objeto com todas as configurações necessárias internamente.

O BISReportBean tem alguns atributos usados no relatório, e todos os atributos já são instanciados com valores que definem o relatório, como por exemplo, que a folha é A4 no formato 'Retrato', e algumas margens padrões para impressão.

Locale Embora o relatório seja classe do Core, muitos dados precisam ser tratados de acordo com o Locale do usuário, afinal, relatório é como uma "interface que exibe dados para o usuário", e precisa ser legível à maneira que ele é acostumado a ver a informação: decimais com "," ou ".", datas com "dd/mm/aaaa" ou "mmm dd,aaa", etc.. Ao iniciar o Bean procure sempre passar o Locale do usuário, provavelmente enviando-o junto durante a requisição da interface. Caso o relatório esteja sendo executado de outro "ator", como uma integração de outro sistema, ou uma tarefa agendada é preciso tomar o cuidado de definir o locale que será usado. O locale pode vir de diversos lugares, é preciso analisar cado a caso. Por fim, se nenhum Locale for especificado o BISReportBean usará como valor padrão o Locale retornado como padrão na JVM.

É sugerido que os relatório sigam o mesmo padrão. Que recebam em seu construtor a mesma classe BISReportBean ou outro Bean específico para o relatório. Neste caso, também é sugerido que o Bean específico para o relatório estenda o BISReportBean. Desta forma um único objeto carregará todas as informações necessárias, tanto para o BISReport quando para a classe de Relatório.

Entre os atributos específicos de cada relatório podem estar o "MO" que o relatório usará para obter os dados no CRUD, ou mesmo a coleção de dados/objeto que ele deverá usar para montar o relatório. Sendo obviamente livre e de definição de cada relatório definir seus atributos e informações necessárias.