net.sf.jasperreports.engine

## Interface JRField

- All Superinterfaces:
    java.lang.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" isForPrompting="true">
           <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.
  Version:
    $Id: JRField.java 7045 2014-04-24 14:20:46Z shertage $
  Author:
    Teodor Danciu (teodord@users.sourceforge.net)

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `getDescription()` Gets the field optional description.
    `java.lang.String` | `getName()` Gets the field unique name.
    `java.lang.Class<?>` | `getValueClass()` Gets the field value class.
    `java.lang.String` | `getValueClassName()` Gets the field value class name.
    `void` | `setDescription(java.lang.String description)` Sets the field description.

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

      `getParentProperties, getPropertiesMap, hasProperties`

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

      `clone`

- - ### Method Detail

    - #### getName

          java.lang.String getName()

      Gets the field unique name.

    - #### getDescription

          java.lang.String getDescription()

      Gets the field optional description.

    - #### setDescription

          void setDescription(java.lang.String description)

      Sets the field description.

    - #### getValueClass

          java.lang.Class<?> getValueClass()

      Gets the field value class. Field types cannot be primitives.

    - #### getValueClassName

          java.lang.String getValueClassName()

      Gets the field value class name.

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com