Package net.sf.jasperreports.engine

Interface JRField

  • All Superinterfaces:
    Cloneable, JRCloneable, JRPropertiesHolder
    All Known Implementing Classes:
    JRBaseField, JRDesignField, JRFillField
    public interface JRField
extends JRPropertiesHolder, JRCloneable
    An abstract representation of a data source field. Each row in a dataset consists of one or more fields with unique names. These names can be used in report expressions.

    Report Fields

    The report fields represent the only way to map data from the data source into the report template and to use this data in report expressions to obtain the desired output.

    When declaring report fields, make sure that the data source supplied at report-filling time can provide values for all those fields.

    For example, if a JRResultSetDataSource implementation is used along with the report's SQL query, make sure that there is a column for each field in the result set obtained after the execution of the query. The corresponding column must bear the same name and have the same data type as the field that maps it.

    If a field is declared without a corresponding column in the result set, an exception will be thrown at runtime. The columns in the result set produced by the execution of the SQL query that do not have corresponding fields in the report template will not affect the report-filling operations, but they also won't be accessible for display on the report.

    Following are described the components of a report field definition.

    Field Name

    The name attribute of the <field> element is mandatory. It lets you reference the field in report expressions by name.

    Field Class

    The second attribute for a report field specifies the class name for the field values. Its default value is java.lang.String, but it can be changed to any class available at runtime. Regardless of the type of a report field, the engine makes the appropriate cast in report expressions in which the $F{} token is used, making manual casts unnecessary.

    Field Description

    This additional text chunk can prove very useful when implementing a custom data source, for example. You could store in it a key, or whatever information you might need in order to retrieve the field's value from the custom data source at runtime.

    By using the optional <fieldDesciption> element instead of the field name, you can easily overcome restrictions of field-naming conventions when retrieving the field values from the data source: 

       <field name="PersonName" class="java.lang.String"
     <fieldDesciption>PERSON NAME</fieldDesciption>
   </field>
    The field description is less important than in previous versions of the library because now even the field's name accepts dots, spaces, and other special characters.

    Custom Field Properties

    Just like the report template and report parameters, report fields can have custom-defined properties, too. This comes in addition to the field description, which can be considered a built-in report field property. Custom properties are useful in some cases where more information or meta data needs to be associated with the report field definition. This additional information can be leveraged by query executer or data source implementations.
    Author:
    Teodor Danciu (teodord@users.sourceforge.net)

    • Method Detail

      • getName

        String getName()
        Gets the field unique name.

      • getDescription

        String getDescription()
        Gets the field optional description.

      • setDescription

        void setDescription​(String description)
        Sets the field description.

      • getValueClass

        Class<?> getValueClass()
        Gets the field value class. Field types cannot be primitives.

      • getValueClassName

        String getValueClassName()
        Gets the field value class name.

      • getPropertyExpressions

        JRPropertyExpression[] getPropertyExpressions()
        Returns the list of dynamic/expression-based properties for this field.
        Returns:
        an array containing the expression-based properties of this field