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 ([email protected])

Method Summary

Modifier and Type	Method and Description
String	getDescription() Gets the field optional description.
String	getName() Gets the field unique name.
JRPropertyExpression[]	getPropertyExpressions() Returns the list of dynamic/expression-based properties for this field.
Class<?>	getValueClass() Gets the field value class.
String	getValueClassName() Gets the field value class name.
void	setDescription(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

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