As Variáveis

Visão geral

( français english )

As variáveis podem ser usadas para armazenar resultados parciais e fazer cálculos complexos com os dados extraídos da fonte de dados. Esses valores podem ser usados em outras partes do relatório, incluindo outras variáveis. Este tutorial mostra como criar e configurar uma variável e explica os campos que a definem.

Definindo uma nova variável ou editando uma existente

Como com muitos outros elementos, todas as variáveis definidas são visíveis no menu Contorno sob o item chamado "Variáveis". A partir daí você pode criar uma nova variável (clique direito no item "Variáveis" e depois "Criar variável") e, uma vez selecionada, uma variável suas propriedades são visíveis na guia Propriedades. Existem algumas variáveis internas no Jaspersoft Stuido, que estão presentes em todos os relatórios. Você pode identificar essas variáveis porque seu nome tem uma cor cinza claro, em vez de uma cor preta, e as propriedades dessas variáveis não podem ser editadas.

Propriedades de base de uma variável

No mínimo, todas as variáveis devem ter o seguinte definido:

• Name: uma string usada para se referir à variável, é necessário usar esta variável dentro de outras expressões (como a valorização de um Campo de Texto ou a computação de outra variável). Para se referir a uma variável é utilizada a seguinte sintaxe: $ V {variable_name}.
• Tipo: necessário porque uma variável é um objeto que provavelmente será usado em outras expressões, portanto, seu tipo deve ser conhecido por ser manipulado corretamente.
• Expressão: a função usada para definir o valor da variável, pode ser composta de mais campos e variáveis, e poderia ser usado operadores lógicos, operadores de matemática e assim por diante. Para definir easly a expressão de um editor de expressão é fornecido na Jaspersoft Studio, isso pode ser aberto usando o botão à direita do campo de texto usado para escrever a expressão. A expressão é avaliada em cada iteração, sempre que um registro é lido da fonte de dados. Se não houver uma função de cálculo definida (isto será explicado abaixo) o resultado da expressão será atribuído à variável, por isso é importante que o resultado tenha um tipo compatível com o da variável.
• Valor inicial: o valor assiumed da variável no início, antes da primeira computação de sua expressão. O valor inicial é uma expressão em si, portanto, pode ser definido através do editor de expressão. Não é obrigatório, mas isso depende da expressão em si e deve ser uma boa prática definir um valor inicial. Suponha que haja uma variável chamada variable1 com a expressão "new Integer (5)". Em cada registro de leitura será atribuir à variável o valor inteiro 5, então o valor inicial não é importante neste contexto. Mas suponha que para mudar a expressão para "$ V {variable1} +5", isto significa que a cada iteração a variável é incrementada por 5. Neste caso, um valor inicial é necessário de outra forma na primeira iteração a variável1 é indefinida e isso quebra Todas as avaliações futuras. Portanto, um valor inicial não é obrigatório, mas as variáveis não inicializadas podem ser perigosas, então é uma boa prática defini-lo.

Outras propriedades de uma variável

A propriedade mais complexa de uma variável é seu valor temporal. Uma vez que sua expressão é avaliada em cada iteração, é importante entender qual valor tem uma variável e em que momento. Isso pode ser complicado, considerando que uma variável pode usar outras variáveis dentro de sua expressão. Por estas razões existem mecanismos que podem ser utilizados para simplificar a avaliação ou a leitura do valor da variável durante as iterações.

Tempo de Avaliação

O tempo de avaliação não é um atributo da variável, mas dos elementos que podem usar variáveis em suas expressões (como um Campo de Texto) e definir o "tempo" quando o valor da variável deve ser lido. Uma variável pode potencialmente alterar o valor em cada iteração, portanto, um valor readat uma vez pode ser diferente do obtido durante outro tempo. Assim, para cada elemento que pode definir uma expressão é possível dizer quando avaliá-lo. E uma vez que na expressão poderia ser definida uma ou mais variáveis este parâmetro também influencia também quando estas variáveis são lidas. Os valores possíveis são:

• Relatório: o valor da expressão é avaliado no final do relatório.
• Página: o valor da expressão é avaliado no final de cada página do relatório.
• Coluna: o valor da expressão é avaliado no final de cada coluna (se o relatório for composto apenas de uma coluna equivalente a Página).
• Grupo : O valor da expressão é avaliado após a quebra do grupo especificado. Esta opção é visível somente se pelo menos um grupo estiver definido.
• Banda: o valor da expressão é avaliado após o fim da banda onde o elemento com este tempo de avaliação é colocado. Este é um caso muito particular, introduzido para esperar que os outros elementos na banda são completamente criados. Normalmente, o valor das variáveis é lido no início da banda, mas, por exemplo, suponha que haja um sub-relatório com um parâmetro de saída para imprimir no relatório principal. Para imprimir este parâmetro, ele deve ser lido quando o sub-relatório já foi computado, portanto o valor pode ser impresso quando a banda é completamente criada, neste caso o tempo de avaliação da Banda é necessário.
• Auto: é usado quando na expressão do elemento há mais variáveis e campos, que precisam ser avaliados em momentos diferentes. As variáveis são avaliadas em um momento correspondente ao seu Tipo de Reset (veja abaixo para mais informações), insted os campos são sempre avaliados em tempo-agora. Esse tipo é útil quando os elementos do relatório possuem expressões que combinam valores avaliados em momentos diferentes (por exemplo, porcentagem de um total).
• Agora: o valor da expressão é avaliado após a leitura de cada registro, portanto, em cada iteração, esse é o comportamento padrão.

Função Cálculo

Uma função de cálculo é um atributo de uma variável que define quando a variável pode ser usada em associação com a expressão para determinar o valor da variável. Ao usar uma função de cálculo, o valor da variável não é determinado diretamente pela sua expressão. Em vez disso, é passado para a função de cálculo que irá usá-lo (dependendo da função) para calcular o valor da variável. Existem muitas funções incorporadas no Jaspersoft Studio:

• Soma: em cada iteração o valor da expressão é tomado ele será somado no valor da variável. Este é um dos casos em que o valor inicial é realmente importante.
• Contagem: em cada iteração o valor da variável é incrementado em uma unidade. Isso somente se a expressão for diferente de null, nesse caso o valor da variável será deixado inalterado.
• Contagem distinta: em cada iteração o valor da variável é incrementado em uma unidade, mas somente se o valor da expressão nunca foi retornado antes.
• Média: o valor da variável é a média aritmética de todos os valores recebidos na entrada da expressão.
• Menor: a variável toma o valor do elemento mais baixo recebido da expressão.
• Maior: a variável toma o valor do elemento mais alto recebido da expressão.
• Desvio padrão: o desvio padrão de todo o valor recebido da expressão.
• Primeiro: a variável toma o valor do primeiro valor retornado pela expressão.
• Sistema: nenhum cálculo é feito ea expressão não é avaliada, o valor desta variável será o último valor definido nele. Útil para armazenar resultados parciais ou o resultado final de uma computação.

Tipo de incremento

Como indicado acima, quando uma função de cálculo é definida, o valor da expressão é passado para a função que fará o cálculo para a variável. O comportamento padrão é fazer isso para cada registro lido, mas às vezes um comportamento diferente é desejado. Utilizando o parâmetro de tipo de incremento é possível alterar o "tempo" no qual a função de cálculo é usada. Os valores possíveis para este atributo são:

• Relatório: a Função de Cálculo é chamada apenas no final do relatório, passando para ela o valor da expressão naquele momento.
• Página: a Função de Cálculo é chamada no final de cada página, passando para ela o valor da expressão nesses momentos.
• Coluna: a Função de Cálculo é chamada no final de cada coluna (se o relatório é composto apenas de uma coluna isto é equivalente a Página).
• Grupo : A função de cálculo é chamada no início de cada ocorrência do grupo especificado. Esta opção é visível somente se pelo menos um grupo estiver definido.
• Nenhum: a função de cálculo é chamada após a leitura de cada registro, este é o comportamento padrão.

Lembre-se que a expressão é avaliada em cada registro lido, independentemente do tipo de incremento selecionado, mas a função de cálculo será usada somente quando os tempos coincidirem com aqueles definidos no tipo de incremento.

Tipo de reposição

O tipo de redefinição define quando uma variável deve ser redefinida para o valor inicial, ou para null se um valor inicial for indefinido. Isso é útil quando a variável é usada para calcular um valor parcial, tal uma soma ou uma média de apenas alguns dos registros lidos. Os valores possíveis para este atributo são:

• Relatório: a variável é inicializada apenas uma vez no início da criação do relatório.
• Página: a variável é inicializada em cada página.
• Coluna: a variável é inicializada novamente em cada nova coluna (se o relatório for composto apenas de uma coluna, isso é equivalente a Página).
• Grupo : A variável é inicializada no início de cada ocorrência do grupo especificado. Esta opção é visível somente se pelo menos um grupo estiver definido.
• Nenhum: a variável nunca será inicializada, portanto, a expressão de valor inicial será ignorada.

Nome da classe de fábrica Incrementer

As funções de cálculo são úteis, mas também são genéricas e limitadas aos tipos numéricos. Você pode ter um caso em que algo mais específico é necessário. Suponha que você tenha um campo do tipo String e queira concatenar o valor lido. Você pode fazer isso definindo um novo Incrementer. Um incremento é um pedaço de código java que estende a interface JRIncrementerFactory e pode criar uma função de cálculo personalizada para fazer o que você precisa. Cada função de cálculo recebe o valor da expressão e o valor da variável e retorna o resultado do incremento, então há tudo o que é necessário para fazer o cálculo e retornar o valor correto.

As variáveis embutidas

Essas são as variáveis padrão incorporadas ao Jaspersoft Studio e que estão presentes em todos os relatórios definidos. Eles representam informações muito gerais. Essas variáveis são:

• PAGE_NUMBER: Em cada iteração, contém o número de páginas que compõem o relatório. Se esta variável for lida com o tempo de avaliação "Relatório" conterá o número de todas as páginas no relatório;
• COLUMN_NUMER: contém o número atual de colunas; 
• REPORT_COUNT: Contém o número total de registros processados;
• PAGE_COUNT: Contém o número de registros processados na página atual;
• COLUMN_COUNT: contém o número de registros processados durante a criação da coluna atual.

dicas e truques

1. Preste atenção no tipo de variável, muitas vezes um mau resultado é devido a isso. Por exemplo, se sua expressão retorna um número, mas a variável é tipo string (que também é o tipo padrão), então seu valor será sempre zero.
2. A forma da expressão é realmente importante para a computação de um valor, especialmente quando na expressão é usada a própria variável. Considere o seguinte exemplo com

• Um campo com o nome "Money_Gained", lido a partir da origem de dados, que tem um valor inteiro e poderia ser nulo
• A variável "Total1" com a expressão IF (Equals ($ F {Money_Gained}, null), $ V {Total1}, $ V {Total1} + $ F {Money_Gained}),  valor inicial de zero, e nenhuma função de cálculo;
• Uma variável "Total2" com a expressão $ V {Money_Gained} == null? $ V {Total2}: $ V {Total2} + $ F {Money_Gained} ,  valor inicial zero, e nenhuma função de cálculo;

As duas expressões podem parecer equivalentes: ambos somam o dinheiro ganho à variável quando não é nulo (lembre-se que se não houver uma função de cálculo, então o valor da expressão é atribuído à variável). A verificação se o Money Gained tem valor null é necessário porque a soma de um número com o valor null é nulo. Portanto, adicionar nulo a Total1 ou Total2 mudará a variável para nulo. Mas mesmo com essa verificação quando Money_Gained se tornará nulo pela primeira vez mesmo Total1 será nulo, em vez de Total2 terá o valor correto. 

Isto acontece porque estas duas expressões têm 2 interpretes diferentes, o primeiro é interpretado por Groovy, o segundo por Java. O comportamento java é avaliar a condição e, em seguida, selecionar o ramo correto. Em vez Groovy calcular os dois ramos, em seguida, avaliar a expressão e, finalmente, retornar o ramo já avaliado correto. Fazendo isso, ele vai adicionar o valor nulo para Total1 antes de fazer o check-in, e este testamento feito Total1 para se tornou null.A truque para evitar isso é usar a variável apenas no ramo principal, por exemplo Total1 poderia ser reescrito como:   $ V {Total1} + IF (EQUALS ($ F {Money_Gained}, nulo), 0, F {Money_Gained}).

A sintaxe ainda é interpretada pelo Groovy, mas agora a variável está fora dos ramos IF, portanto, mesmo que ambos sejam avaliados, a variável mantém seu valor.