net.sf.jasperreports.engine

Interface JRParameter

All Superinterfaces:

Cloneable, JRCloneable, JRPropertiesHolder

All Known Subinterfaces:

JRCrosstabParameter, JRValueParameter

All Known Implementing Classes:

JRBaseCrosstabParameter, JRBaseParameter, JRDesignCrosstabParameter, JRDesignParameter, JRFillCrosstabParameter, JRFillParameter

public interface JRParameter
extends JRPropertiesHolder, JRCloneable

Provides functionality for report parameters.

Parameters are object references that are passed into the report-filling operations. They are very useful for passing to the report engine data that it cannot normally find in its data source.

For example, one could pass to the report engine the name of the user who launched the report-filling operation if this name have to appear on the report. Or, if the report title depends on various conditions, it can be passed as parameter to the report during the report execution.

Declaring a parameter in a report template is very simple. Simply specify only its name and its class:

   <parameter name="ReportTitle" class="java.lang.String"/>
   <parameter name="MaxOrderID" class="java.lang.Integer"/>
   <parameter name="SummaryImage" class="java.awt.Image"/>

The supplied values for the report parameters can be used in the various report expressions, in the report SQL query, or even in a report scriptlet class.

Below are described the components that make a report parameter definition complete.

Parameter Name

The name attribute of the <parameter> element is mandatory and allows referencing the parameter by its declared name. The naming conventions of JasperReports are similar to those of the Java language regarding variable declaration. That means that the parameter name should be a single word containing no special characters like a dot or a comma.

Parameter Class

The second mandatory attribute for a report parameter specifies the class name for the parameter values. The class attribute can have any value as long it represents a class name that is available in the classpath both at report-compilation time and report-filling time.

Prompting for Parameter Values

In some GUI applications, it is useful to establish the set of report parameters for which the application should request user input, before launching the report-filling process. It is also useful to specify the text description that will prompt for the user input for each of those parameters.

This is why we have the Boolean isForPrompting attribute in the parameter declaration sequence and the inner <parameterDescription> element.

Parameter Custom Properties

In addition to the parameter description and the prompting flag mentioned previously, some applications might need to attach more information or metadata to a report parameter definition. This is why report parameters can have any number of custom-defined name/value property pairs, just like the report template itself could have at the top level.

Parameter Default Value

Parameter values are supplied to the report-filling process packed in a java.util.Map object with the parameter names as the keys. This way, there is no more need to supply a value for each parameter every time.

If there is no value supplied for a parameter, its value is considered to be null, unless a default value expression is specified in the report template for this particular report parameter. This expression is only evaluated if there is no value supplied for the given parameter.

Here's a java.util.Date parameter whose value will be the current date if you do not supply a specific date value when filling the report:

   <parameter name="MyDate" class="java.util.Date">
     <defaultValueExpression>
       new java.util.Date()
     </defaultValueExpression>
   </parameter>

In the default value expression of a parameter, one can only use previously defined report parameters.

Author:

Teodor Danciu (teodord@users.sourceforge.net)

Field Summary

Fields

Modifier and Type	Field and Description
static String	FILTER A DatasetFilter to be used in addition to JRDataset.getFilterExpression() for filtering dataset rows.
static String	IS_IGNORE_PAGINATION This built-in flag parameter specifies whether to ignore pagination.
static String	JASPER_REPORT This parameter gives access to the current JasperReport template object that is being filled.
static String	JASPER_REPORTS_CONTEXT A net.sf.jasperreports.engine.JasperReportsContext instance representing the current report filling context.
static String	REPORT_CLASS_LOADER A java.lang.ClassLoader instance to be used during the report filling process to load resources.
static String	REPORT_CONNECTION A java.sql.Connection needed to run the default report query.
static String	REPORT_CONTEXT
static String	REPORT_DATA_SOURCE A JRDataSource instance representing the report data source.
static String	REPORT_FILE_RESOLVER Deprecated. Replaced by JasperReportsContext.
static String	REPORT_FORMAT_FACTORY A FormatFactory instance to be used during the report filling process to create instances of java.text.DateFormat to format date text fields and instances of java.text.NumberFormat to format numeric text fields.
static String	REPORT_LOCALE A java.util.Locale instance containing the resource bundle desired locale.
static String	REPORT_MAX_COUNT An integer allowing users to limit the datasource size.
static String	REPORT_PARAMETERS_MAP A Map containing report parameters passed by users at fill time.
static String	REPORT_RESOURCE_BUNDLE The java.util.ResourceBundle containing localized messages.
static String	REPORT_SCRIPTLET A JRAbstractScriptlet containing an instance of the report scriptlet provided by the user.
static String	REPORT_TEMPLATES A collection of templates passed to the report at fill time.
static String	REPORT_TIME_ZONE A java.util.TimeZone instance to use for date formatting.
static String	REPORT_URL_HANDLER_FACTORY Deprecated. Replaced by JasperReportsContext.
static String	REPORT_VIRTUALIZER The JRVirtualizer to be used for page virtualization.
static String	SORT_FIELDS

Method Summary

Methods

Modifier and Type	Method and Description
JRExpression	getDefaultValueExpression()
String	getDescription()
String	getName()
Class<?>	getNestedType() Returns the parameter nested value type.
String	getNestedTypeName() Returns the name of the parameter nested value type.
Class<?>	getValueClass()
String	getValueClassName()
boolean	isForPrompting()
boolean	isSystemDefined()
void	setDescription(String description)

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

getParentProperties, getPropertiesMap, hasProperties

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

clone

Field Detail

REPORT_PARAMETERS_MAP

static final String REPORT_PARAMETERS_MAP

A Map containing report parameters passed by users at fill time.

This parameter is especially useful when you want to pass to the subreports the same set of report parameters that the master report has received.

See Also:

Constant Field Values

JASPER_REPORTS_CONTEXT

static final String JASPER_REPORTS_CONTEXT

A net.sf.jasperreports.engine.JasperReportsContext instance representing the current report filling context.

See Also:

Constant Field Values

JASPER_REPORT

static final String JASPER_REPORT

This parameter gives access to the current JasperReport template object that is being filled.

See Also:

Constant Field Values

REPORT_CONNECTION

static final String REPORT_CONNECTION

A java.sql.Connection needed to run the default report query.

This report parameter points to the java.sql.Connection object that was supplied to the engine for execution of the SQL report query through JDBC, if it is the case. It has a value different than null only if the report (or subreport) has received a java.sql.Connection when the report-filling process was launched, and not a JRDataSource instance.

This parameter is also useful for passing the same JDBC connection object that was used by the master report to its subreports.

See Also:

Constant Field Values

REPORT_MAX_COUNT

static final String REPORT_MAX_COUNT

An integer allowing users to limit the datasource size.

Some users may want to limit the number of records from the report data source during the report-filling process. This built-in parameter accepts java.lang.Integer values representing the number of records from the data source that the engine will process during the report filling. When the internal record counter reaches the specified value, the engine will assume that it has reached the last record from the data source and will stop the iteration through the rest of the data source.

See Also:

Constant Field Values

REPORT_DATA_SOURCE

static final String REPORT_DATA_SOURCE

A JRDataSource instance representing the report data source. JasperReports defines some convenience implementations of JRDataSource, but users may create their own data sources for specific needs.

When filling a report, a data source object is either directly supplied by the parent application or created behind the scenes by the reporting engine when a JDBC connection is supplied. This built-in parameter allows you access to the report's data source in the report expressions or in the scriptlets.

See Also:

Constant Field Values

REPORT_SCRIPTLET

static final String REPORT_SCRIPTLET

A JRAbstractScriptlet containing an instance of the report scriptlet provided by the user.

This built-in parameter points to the report scriptlet specified using the scriptletClass attribute available at report or dataset level.

Even if the report or dataset does not declare any scriptlet, this built-in parameter will point to a JRAbstractScriptlet instance, which in this case is a JRDefaultScriptlet object. When using scriptlets, the scriptlet built-in parameters referencing the scriptlet instances that are created when filling the report, allow specific methods to be called on them. This is so the data that the scriptlet objects have prepared during the filling process can be used or manipulated.

See Also:

Constant Field Values

REPORT_LOCALE

static final String REPORT_LOCALE

A java.util.Locale instance containing the resource bundle desired locale. This parameter should be used in conjunction with REPORT_RESOURCE_BUNDLE.

Report templates can be reused to generate documents in different languages. The target language used during report filling is specified by the java.util.Locale object supplied as the value for this built-in parameter. The engine uses Locale.getDefault() if no value is explicitly supplied for this parameter at runtime.

See Also:

Constant Field Values

REPORT_RESOURCE_BUNDLE

static final String REPORT_RESOURCE_BUNDLE

The java.util.ResourceBundle containing localized messages. If the resource bundle base name is specified at design time, the engine will try to load the resource bundle using specified name and locale.

This parameter points to the java.util.ResourceBundle object that contains localized information associated with the report template. This object can be supplied directly by the caller application or created by the engine using the resource bundle base name specified in the resourceBundle attribute of the report template. The engine tries to read locale-specific information from this object based on the report-supplied locale and the key used inside the report expressions.

See Also:

Constant Field Values

REPORT_TIME_ZONE

static final String REPORT_TIME_ZONE

A java.util.TimeZone instance to use for date formatting.

The java.util.TimeZone instance supplied as value for this built-in parameter is used during the report-filling process to format all date and time values. If no value is supplied for this parameter at runtime, the default time zone of the host machine is used.

See Also:

Constant Field Values

REPORT_VIRTUALIZER

static final String REPORT_VIRTUALIZER

The JRVirtualizer to be used for page virtualization. This parameter is optional.

When very large reports are generated and memory becomes insufficient, the engine can rely on the report virtualization mechanism to optimize memory consumption during report filling. Report virtualization is activated by supplying an instance of the JRVirtualizer interface as the value for this built-in parameter. By doing this, the engine will store temporary data in a serialized form in order to minimize the amount of memory needed during report filling.

See Also:

Constant Field Values

REPORT_CLASS_LOADER

static final String REPORT_CLASS_LOADER

A java.lang.ClassLoader instance to be used during the report filling process to load resources.

Resources such as images, fonts, and subreport templates can be referenced using their relative classpath location. By default, JasperReports uses the current thread's context class loader to locate the resource. If that fails, it then falls back to the class loader that loads the library's classes themselves. To extend the resource-lookup mechanism and give greater flexibility to the library, one can pass a custom-made class loader implementation as the value for this built-in fill-time parameter. This would allow applications to load resources from repository locations that are not normally part of the overall application classpath.

See Also:

Constant Field Values

REPORT_URL_HANDLER_FACTORY

static final String REPORT_URL_HANDLER_FACTORY

Deprecated. Replaced by JasperReportsContext.

A java.net.URLStreamHandlerFactory instance to be used during the report filling process to handle custom URL protocols for loading resources such as images, fonts and subreport templates.

See Also:

Constant Field Values

REPORT_FILE_RESOLVER

static final String REPORT_FILE_RESOLVER

Deprecated. Replaced by JasperReportsContext.

A FileResolver instance to be used during the report filling process to handle locate files on disk using relative paths.

See Also:

Constant Field Values

REPORT_FORMAT_FACTORY

static final String REPORT_FORMAT_FACTORY

A FormatFactory instance to be used during the report filling process to create instances of java.text.DateFormat to format date text fields and instances of java.text.NumberFormat to format numeric text fields.

The value for this parameter is an instance of the FormatFactory interface, which is either provided directly by the calling program or created internally by the reporting engine, using the formatFactoryClass attribute of the report template. If this parameter is provided with a value by the report-filling process caller, it takes precedence over the attribute in the report template.

See Also:

Constant Field Values

IS_IGNORE_PAGINATION

static final String IS_IGNORE_PAGINATION

This built-in flag parameter specifies whether to ignore pagination.

By default, JasperReports produces page-oriented documents that are ready for printing.

Sometimes, especially in Web applications, pagination is irrelevant. One way to avoid breaking documents into multiple pages and to obtain a more flow-oriented document layout is to set this built-in parameter to Boolean.TRUE at runtime. By doing this, the engine will ignore all the report settings that are related to page breaking and will produce a document that contains a single very large page.

When used, this fill-time parameter overrides the value of the isIgnorePagination property of the report template.

See Also:

Constant Field Values

REPORT_TEMPLATES

static final String REPORT_TEMPLATES

A collection of templates passed to the report at fill time.

These templates add to the ones specified in the report (see JRReport.getTemplates()). In the final templates list they are placed after the report templates; therefore styles from these templates can use and override styles in the report templates. They are, however, placed before the report styles hence report styles can use and override styles from these templates.

See Also:

Constant Field Values

SORT_FIELDS

static final String SORT_FIELDS

See Also:

Constant Field Values

REPORT_CONTEXT

static final String REPORT_CONTEXT

See Also:

Constant Field Values

FILTER

static final String FILTER

A DatasetFilter to be used in addition to JRDataset.getFilterExpression() for filtering dataset rows.

See Also:

Constant Field Values

Method Detail

getName

String getName()

getDescription

String getDescription()

setDescription

void setDescription(String description)

getValueClass

Class<?> getValueClass()

getValueClassName

String getValueClassName()

isSystemDefined

boolean isSystemDefined()

isForPrompting

boolean isForPrompting()

getDefaultValueExpression

JRExpression getDefaultValueExpression()

getNestedType

Class<?> getNestedType()

Returns the parameter nested value type.

The parameter nested value type is used when the parameter value class is not sufficient in determining the expected type of the parameter values. The most common such scenario is when the parameter value class is Collection or a derived class, in which case the nested type specifies the type of values which are to be placed inside the collection.

Returns:

the nested value type for this parameter, or null if none set

See Also:

getValueClass()

getNestedTypeName

String getNestedTypeName()

Returns the name of the parameter nested value type.

Returns:

the name of the nested value type for this parameter, or null if none set

See Also:

getNestedType()