net.sf.jasperreports.engine

## Interface JRExpression

- All Superinterfaces:
    java.lang.Cloneable, JRCloneable
  All Known Implementing Classes:
    JRBaseExpression, JRDesignExpression

      public interface JRExpression
      extends JRCloneable

  Provides the JasperReports expressions functionality.

  ### Expressions in JasperReports

  Expressions are a powerful feature of JasperReports. They can be used to declare report variables that perform various calculations, group data on the report, specify report text field content, or further customize the appearance of report objects.

  By default, the Java language is used for writing report expressions, but other scripting languages can be used if a corresponding report compiler able to produce the information needed for expression evaluation at runtime is available. Currently, JasperReports ships with report compilers that can compile report templates using the Groovy scripting language, JavaScript or BeanShell script, inside report expressions.

  For simplicity's sake, in the next paragraphs we'll assume that expressions have been written using the Java language.

  Since all JasperReports expressions are (or are assumed to be) real Java expressions, then any valid java class can be used inside them, as long as they are referred to by using the complete class name (including the package), or are adding the proper imports to your report template. We also have to make sure that the classes we are using in the report expressions are available in the classpath when the report is compiled and filled with data.

  In a JRXML report template, there are several elements that define expressions, including `<variableExpression>`, `<initialValueExpression>`, `<groupExpression>`, `<printWhenExpression>`, `<imageExpression>`, `<textFieldExpression>`...

  ### Expression Syntax

  Report expressions would be useless if there were no way to reference in them the report parameters, report fields, or declared report variables. For this reason, a special JasperReports syntax on top of the scripting language allows introducing such references in the report expressions created in the JRXML report template.

  Report parameter references are introduced using the `$P{}` character sequence, as in the following example:

         <textFieldExpression>
           $P{ReportTitle}
         </textFieldExpression>

  This example assumes that the report design declares a report parameter named ReportTitle, whose class is `java.lang.String`. The text field will display the value of this parameter when the report is filled.

  To use a report field reference in an expression, one must put the name of the field between the `$F{` and `}` character sequences. For example, to display the concatenated values of two data source fields in a text field, define an expression like this one:

         <textFieldExpression>
           $F{FirstName} + " " + $F{LastName}
         </textFieldExpression>

  The expression can be even more complex, as in the following example:

         <textFieldExpression>
           $F{FirstName} + " " + $F{LastName} + " was hired on " +
           (new SimpleDateFormat("MM/dd/yyyy")).format($F{HireDate}) + "."
         </textFieldExpression>

  To reference a report variable in an expression, you must put the name of the variable between `$V{` and `}`, as in this example:

         <textFieldExpression>
           "Total quantity : " + $V{QuantitySum} + " kg."
         </textFieldExpression>

  As you can see, the parameter, field, and variable references introduced by the special JasperReports syntax are in fact real Java objects. Knowing their class from the parameter, field or variable declaration made in the report template, you can even call methods on those object references in your expressions.

  Here's one way to extract and display the first letter from a java.lang.String report field:

         <textFieldExpression>
           $F{FirstName}.substring(0, 1)
         </textFieldExpression>

  When support for internationalization was added to JasperReports, a new token was introduced in the JasperReports syntax to allow access to the locale-specific resources inside the report's associated resource bundle. The `$R{}` character syntax extracts the locale-specific resource from the resource bundle based on the key that must be put between the brackets:

         <textFieldExpression>
           $R{report.title}
         </textFieldExpression>

  The preceding text field displays the title of the report by extracting the String value from the resource bundle associated with the report template based on the runtime supplied locale and the `report.title` key.

  In some rare cases (for example, debugging), there is the need to escape an expression token like the ones described previously. The escape syntax for the tokens requires duplicating the `$` character. Escaping a `$P{paramName}` token is achieved by writing `$$P{paramName}` in the expression. When escaped, an expression token is preserved as-is in the resulting expression, and no attempt to parse the token is made.

  ### Conditional Expressions

  As the Java language documentation states, an expression is a series of variables, operators, and method calls (constructed according to the syntax of the language) that evaluate to a single value.

  So even if we rely on the Java language for writing report expressions, we cannot use Java statements like `if else`, `for`, or `while`.

  However, quite often an expression must return a value that is calculated based on a condition or even multiple conditions. To accomplish this, use the conditional operator `?:`. One can even nest this operator inside a Java expression to obtain the desired output based on multiple conditions.

  The following text field displays No data if the value for the quantity field is null:

         <textFieldExpression>
           $F{quantity} == null ? "No data" : String.valueOf($F{quantity})
         </textFieldExpression>

  ### Expressions Calculator

  The expressions calculator is the entity inside JasperReports that evaluates expressions and increments variables or datasets at report-filling time. When a report template is compiled, the report compiler produces and stores in the compiled report template (`JasperReport` object) information that it will use at report-filling time to build an instance of the `JRCalculator` class.
  Version:
    $Id: JRExpression.java 7045 2014-04-24 14:20:46Z shertage $
  Author:
    Teodor Danciu (teodord@users.sourceforge.net)
  See Also:
    `JRCalculator`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static byte` | `EVALUATION_DEFAULT`
    `static byte` | `EVALUATION_ESTIMATED`
    `static byte` | `EVALUATION_OLD`
    `static java.lang.Integer` | `NOT_USED_ID` Dummy ID that is assigned to expression that are not used (and not collected).

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `JRExpressionChunk[]` | `getChunks()`
    `int` | `getId()`
    `java.lang.String` | `getText()`
    `java.lang.Class<?>` | `getValueClass()` Deprecated. To be removed.
    `java.lang.String` | `getValueClassName()` Deprecated. To be removed.

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

      `clone`

- - ### Field Detail

    - #### EVALUATION_OLD

          static final byte EVALUATION_OLD

      See Also:
        Constant Field Values

    - #### EVALUATION_ESTIMATED

          static final byte EVALUATION_ESTIMATED

      See Also:
        Constant Field Values

    - #### EVALUATION_DEFAULT

          static final byte EVALUATION_DEFAULT

      See Also:
        Constant Field Values

    - #### NOT_USED_ID

          static final java.lang.Integer NOT_USED_ID

      Dummy ID that is assigned to expression that are not used (and not collected).

  - ### Method Detail

    - #### getValueClass

          java.lang.Class<?> getValueClass()

      Deprecated. To be removed.
      Returns the expression return value class.

    - #### getValueClassName

          java.lang.String getValueClassName()

      Deprecated. To be removed.
      Returns the expression return value class.

    - #### getId

          int getId()

    - #### getChunks

          JRExpressionChunk[] getChunks()

    - #### getText

          java.lang.String getText()

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com