public interface JRParameter extends JRPropertiesHolder, JRCloneable
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.
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.
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.
This is why we have the Boolean isForPrompting
attribute in the parameter
declaration sequence and the inner <parameterDescription>
element.
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.
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 |
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) |
getParentProperties, getPropertiesMap, hasProperties
clone
static final String REPORT_PARAMETERS_MAP
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.
static final String JASPER_REPORTS_CONTEXT
static final String JASPER_REPORT
JasperReport
template object that is being filled.static final String REPORT_CONNECTION
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.
static final String REPORT_MAX_COUNT
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.
static final String REPORT_DATA_SOURCE
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.
static final String REPORT_SCRIPTLET
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.
static final String REPORT_LOCALE
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.
static final String REPORT_RESOURCE_BUNDLE
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.
static final String REPORT_TIME_ZONE
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.
static final String REPORT_VIRTUALIZER
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.
static final String REPORT_CLASS_LOADER
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.
static final String REPORT_URL_HANDLER_FACTORY
JasperReportsContext
.static final String REPORT_FILE_RESOLVER
JasperReportsContext
.FileResolver
instance to be used during the report filling process to
handle locate files on disk using relative paths.static final String REPORT_FORMAT_FACTORY
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.
static final String IS_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.
static final String REPORT_TEMPLATES
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.static final String SORT_FIELDS
static final String REPORT_CONTEXT
static final String FILTER
DatasetFilter
to be used in addition to JRDataset.getFilterExpression()
for filtering dataset rows.String getName()
String getDescription()
void setDescription(String description)
Class<?> getValueClass()
String getValueClassName()
boolean isSystemDefined()
boolean isForPrompting()
JRExpression getDefaultValueExpression()
Class<?> getNestedType()
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.
null
if none setgetValueClass()
String getNestedTypeName()
null
if none setgetNestedType()
Copyright © 2017. All rights reserved.