net.sf.jasperreports.engine

## Interface JRVariable

- All Superinterfaces:
    java.lang.Cloneable, JRCloneable
  All Known Implementing Classes:
    JRBaseVariable, JRDesignVariable, JRFillVariable

      public interface JRVariable
      extends JRCloneable

  An interface for implementing classes that deal with report variables. This interface defines constants for names of built-in variables and for reset, increment and calculation types.

  ### Report Variables

  Report variables are special objects built on top of a report expression. They can simplify the report template by isolating in one place an expression that is heavily used throughout the report template, and they can perform various calculations based on the corresponding expression.

  In its expression, a variable can reference other report variables, fields, or parameters. With every iteration through the data source, variables are evaluated/incremented in the same order as they are declared. Therefore, the order of variables as they appear in the report template is very important.

  ### Variable Name

  Just as for parameters and fields, the name attribute of the `<variable>` element is mandatory and allows referencing the variable by its declared name in report expressions.

  ### Variable Class

  The class attribute contains the name of the class to which the variable values belong. The default is `java.lang.String`, but you can declare report variables of any class as long as the class is available in the classpath, both at report-compilation time and report-filling time.

  ### Reset Type

  The value of a report variable can change with every iteration, but it can be brought back to the value returned by its initial value expression at specified times during the report filling process. This behavior is controlled using the resetType attribute, which indicates when the variable should be reinitialized during the report-filling process. There are five reset types for a variable:
  - `None` - The variable will never be initialized using its initial value expression and will only contain values obtained by evaluating the variable's expression
  - `Report` - The variable is initialized only once, at the beginning of the report-filling process, with the value returned by the variable's initial value expression
  - `Page` - The variable is reinitialized at the beginning of each new page.
  - `Column` - The variable is reinitialized at the beginning of each new column
  - `Group` - The variable is reinitialized every time the group specified by the `resetGroup` attributes breaks

  ### Reset Group

  If present, the `resetGroup` attribute contains the name of a report group and works only in conjunction with the `resetType` attribute, whose value must be `resetType="Group"`.

  ### Increment Type

  This property lets you choose the exact moment to increment the variable. By default, variables are incremented with each record in the data source, but in reports with multiple levels of data grouping, some variables might calculate higher-level totals and would need to be incremented only occasionally, not with every iteration through the data source.

  This attribute uses the same values as the resetType attribute, as follows:
  - `None` - The variable is incremented with every record during the iteration through the data source
  - `Report` - The variable never gets incremented during the report filling process.
  - `Page` - The variable is incremented with each new page.
  - `Column` - The variable is incremented with each new column.
  - `Group` - The variable is incremented every time the group specified by the `incrementGroup` attributes breaks

  ### Increment Group

  If present, the `incrementGroup` attribute contains the name of a report group. It works only in conjunction with the `incrementType` attribute, whose value must be `incrementType="Group"`.

  ### Calculations

  As mentioned, variables can perform built-in types of calculations on their corresponding expression values. Following are described all the possible values for the `calculation` attribute of the `<variable>` element.
  `Nothing`
    This is the default calculation type that a variable performs. It means that the variable's value is recalculated with every iteration in the data source and that the value returned is obtained by simply evaluating the variable's expression.
  `Count`
    A count variable includes in the count the non-null values returned after evaluating the variable's main expression, with every iteration in the data source. Count variables must always be of a numeric type. However, they can have non-numeric expressions as their main expression since the engine does not care about the expression type, but only counts for the non-null values returned, regardless of their type.
    Only the variable's initial value expression should be numeric and compatible with the variable's type, since this value will be directly assigned to the count variable when initialized.
  `DistinctCount`
    This type of calculation works just like the `Count` calculation, the only difference being that it ignores repeating values and counts only for distinct non-null values.
  `Sum`
    The reporting engine can sum up the values returned by the variable's main expression if this type of calculation is chosen; but make sure the variable has a numeric type. One cannot calculate the sum of a `java.lang.String` or `java.util.Date` type of report variable unless a customized variable incrementer is used.
  `Average`
    The reporting engine can also calculate the average for the series of values obtained by evaluating the variable's expression for each record in the data source. This type of calculation can be performed only for numeric variables.
  `Lowest` and `Highest`
    Choose this type of calculation when you want to obtain the lowest or highest value in the series of values obtained by evaluating the variable's expression for each data source record.
  `StandardDeviation` and `Variance`
    In some special reports, you might want to perform more advanced types of calculations on numeric expressions. JasperReports has built-in algorithms to obtain the standard deviation and the variance for the series of values returned by evaluation of a report variable's expression.
  `System`
    This type of calculation can be chosen only when you don't want the engine to calculate any value for the variable. That means you are calculating the value for that variable yourself, almost certainly using the scriptlets functionality of JasperReports. For this type of calculation, the only thing the engine does is to conserve the calculated value from one iteration in the data source to the next.
  `First`
    When using the calculation type `First`, the variable will keep the value obtained after the first incrementation and will not change it until the reset event occurs.
  Here is a simple report variable declaration that calculates the sum for a numeric report field called `Quantity`:

         <variable name="QuantitySum" class="java.lang.Double" calculation="Sum">
           <variableExpression>$F{Quantity}</variableExpression>
         </variable>

  If you want the sum of this field for each page, here's the complete variable declaration:

         <variable name="QuantitySum" class="java.lang.Double" resetType="Page" calculation="Sum">
           <variableExpression>$F{Quantity}</variableExpression>
           <initialValueExpression>new Double(0)</initialValueExpression>
         </variable>

  In this example, the page sum variable will be initialized with zero at the beginning of each new page.

  ### Incrementers

  All calculations in the JasperReports engine are performed incrementally. This is obvious for variables that calculate counts, sums, or the highest and lowest value of a series, but is also true for more complex calculations like average or standard deviation. There are formulas that allow updating the average value of a series when a new element is added, so the average is updated with each iteration through the data source.

  JasperReports provides a built-in set of calculations that depend on the type of the data involved. You can also create custom calculation capabilities using simple interfaces.

  If a variable needs to perform a certain type of calculation on some special data, implement the `JRIncrementer` interface and associate that implementation with a report variable that shows the JasperReports engine how to handle that custom calculation.

  To associate custom types of calculations with a given report variable, set the `incrementerFactoryClass` attribute to the name of a class that implements the `JRIncrementerFactory` interface. The factory class will be used by the engine to instantiate incrementer objects at runtime depending on the calculation attribute set for the variable.

  Such customized calculations could be useful for making JasperReports sum up `java.lang.String` values or for teaching it how to calculate the average value of some custom-made numeric data (third-party optimized implementations of big decimal numbers, for instance).

  ### GroupName_COUNT Built-In Variable

  When declaring a report group, the engine will automatically create a count variable that will calculate the number of records that make up the current group (number of records processed between group ruptures).

  The name for this variable comes from the name of the group it corresponds to, suffixed with the "`_COUNT`" sequence. It can be used like any other report variable, in any report expression (even in the current group expression like you can see done in the "BreakGroup" of the jasper sample).
  Version:
    $Id: JRVariable.java 7045 2014-04-24 14:20:46Z shertage $
  Author:
    Teodor Danciu (teodord@users.sourceforge.net)

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `COLUMN_COUNT` This variable contains the number of records that were processed when generating the current column.
    `static java.lang.String` | `COLUMN_NUMBER` Built-in variable containing the current column number.
    `static java.lang.String` | `PAGE_COUNT` Built-in variable containing the number of records that were processed when generating the current page.
    `static java.lang.String` | `PAGE_NUMBER` Built-in variable containing the current page number.
    `static java.lang.String` | `REPORT_COUNT` Built-in variable that contains the total number of records read from the datasource.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `CalculationEnum` | `getCalculationValue()` Gets the variable calculation type.
    `JRExpression` | `getExpression()` Returns the main expression for this variable.
    `java.lang.Class<?>` | `getIncrementerFactoryClass()` Returns the class of the incrementer factory used for choosing the right incrementer for the variable value.
    `java.lang.String` | `getIncrementerFactoryClassName()` Returns the string name of the variable value class.
    `JRGroup` | `getIncrementGroup()` Returns the group whose break triggers the variable increment.
    `IncrementTypeEnum` | `getIncrementTypeValue()` Gets the variable increment type.
    `JRExpression` | `getInitialValueExpression()` Returns the initial value expression for this variable.
    `java.lang.String` | `getName()` Returns the name of the variable.
    `JRGroup` | `getResetGroup()` Returns the group whose break triggers the variable reset.
    `ResetTypeEnum` | `getResetTypeValue()` Gets the variable reset type.
    `java.lang.Class<?>` | `getValueClass()` Returns the class of the variable value.
    `java.lang.String` | `getValueClassName()` Returns the string name of the variable value class.
    `boolean` | `isSystemDefined()` Returns `true` if the variable calculation type is system defined.

    - ### Methods inherited from interface net.sf.jasperreports.engine.JRCloneable

      `clone`

- - ### Field Detail

    - #### REPORT_COUNT

          static final java.lang.String REPORT_COUNT

      Built-in variable that contains the total number of records read from the datasource. After finishing iterating throught the datasource, it will contain the total number of records that were processed.
      See Also:
        Constant Field Values

    - #### PAGE_COUNT

          static final java.lang.String PAGE_COUNT

      Built-in variable containing the number of records that were processed when generating the current page.
      See Also:
        Constant Field Values

    - #### COLUMN_COUNT

          static final java.lang.String COLUMN_COUNT

      This variable contains the number of records that were processed when generating the current column.
      See Also:
        Constant Field Values

    - #### PAGE_NUMBER

          static final java.lang.String PAGE_NUMBER

      Built-in variable containing the current page number. At the end of the report filling process, it will contain the total number of pages for the resulting document.
      See Also:
        Constant Field Values

    - #### COLUMN_NUMBER

          static final java.lang.String COLUMN_NUMBER

      Built-in variable containing the current column number.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getName

          java.lang.String getName()

      Returns the name of the variable. Since all variables are stored in a map, the variable names are the keys in the map.
      Returns:
        a string containing the variable name

    - #### getValueClass

          java.lang.Class<?> getValueClass()

      Returns the class of the variable value. Any class is allowed as long as it is in the classpath at compile and run time.
      Returns:
        a `Class` instance representing the variable value class

    - #### getValueClassName

          java.lang.String getValueClassName()

      Returns the string name of the variable value class.

    - #### getIncrementerFactoryClass

          java.lang.Class<?> getIncrementerFactoryClass()

      Returns the class of the incrementer factory used for choosing the right incrementer for the variable value.
      Returns:
        the `Class` instance of the incrementer factory
      See Also:
        `JRIncrementer`, `JRIncrementerFactory`

    - #### getIncrementerFactoryClassName

          java.lang.String getIncrementerFactoryClassName()

      Returns the string name of the variable value class.

    - #### getResetTypeValue

          ResetTypeEnum getResetTypeValue()

      Gets the variable reset type.
      Returns:
        a value representing one of the reset type constants in `ResetTypeEnum`

    - #### getIncrementTypeValue

          IncrementTypeEnum getIncrementTypeValue()

      Gets the variable increment type.
      Returns:
        a value representing one of the reset type constants in `IncrementTypeEnum`

    - #### getCalculationValue

          CalculationEnum getCalculationValue()

      Gets the variable calculation type.
      Returns:
        a value representing one of the calculation type constants in `CalculationEnum`

    - #### isSystemDefined

          boolean isSystemDefined()

      Returns `true` if the variable calculation type is system defined.
      See Also:
        `CalculationEnum.SYSTEM`

    - #### getExpression

          JRExpression getExpression()

      Returns the main expression for this variable. The expression must be numeric for certain calculation types.
      Returns:
        a `JRExpression` instance containing the expression.

    - #### getInitialValueExpression

          JRExpression getInitialValueExpression()

      Returns the initial value expression for this variable. The expression must be numeric for certain calculation types.
      Returns:
        a `JRExpression` instance containing the initial expression.

    - #### getResetGroup

          JRGroup getResetGroup()

      Returns the group whose break triggers the variable reset. Only used when `getResetTypeValue()` returns `ResetTypeEnum.GROUP`.

    - #### getIncrementGroup

          JRGroup getIncrementGroup()

      Returns the group whose break triggers the variable increment. Only used when `getIncrementTypeValue()` returns `ResetTypeEnum.GROUP`.

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com