net.sf.jasperreports.engine.JRField Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of jasperreports Show documentation
Free Java Reporting Library
There is a newer version: 6.21.3
/*
 * JasperReports - Free Java Reporting Library.
 * Copyright (C) 2001 - 2019 TIBCO Software Inc. All rights reserved.
 * http://www.jaspersoft.com
 *
 * Unless you have purchased a commercial license agreement from Jaspersoft,
 * the following license terms apply:
 *
 * This program is part of JasperReports.
 *
 * JasperReports is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * JasperReports is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with JasperReports. If not, see .
 */
package net.sf.jasperreports.engine;


/**
 * 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
 * {@link net.sf.jasperreports.engine.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])
 */
public interface JRField extends JRPropertiesHolder, JRCloneable
{


	/**
	 * Gets the field unique name.
	 */
	public String getName();
		
	/**
	 * Gets the field optional description.
	 */
	public String getDescription();
		
	/**
	 * Sets the field description.
	 */
	public void setDescription(String description);
		
	/**
	 * Gets the field value class. Field types cannot be primitives.
	 */
	public Class getValueClass();
		
	/**
	 * Gets the field value class name.
	 */
	public String getValueClassName();
		
	/**
	 * Returns the list of dynamic/expression-based properties for this field.
	 * 
	 * @return an array containing the expression-based properties of this field
	 */
	public JRPropertyExpression[] getPropertyExpressions();


}