* 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. * * @author Teodor Danciu (teodord@users.sourceforge.net) * @version $Id: JRParameter.java 7045 2014-04-24 14:20:46Z shertage $ */ public interface JRParameter extends JRPropertiesHolder, JRCloneable { /** * 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.
*/
public static final String REPORT_PARAMETERS_MAP = "REPORT_PARAMETERS_MAP";
/**
* A net.sf.jasperreports.engine.JasperReportsContext instance representing the current report filling context.
*/
public static final String JASPER_REPORTS_CONTEXT = "JASPER_REPORTS_CONTEXT";
/**
* This parameter gives access to the current {@link net.sf.jasperreports.engine.JasperReport}
* template object that is being filled.
*/
public static final String JASPER_REPORT = "JASPER_REPORT";
/**
* 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
* {@link net.sf.jasperreports.engine.JRDataSource} instance.
*
* This parameter is also useful for passing the same JDBC connection object that was used * by the master report to its subreports. */ public static final String REPORT_CONNECTION = "REPORT_CONNECTION"; /** * 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.
*
*/
public static final String REPORT_MAX_COUNT = "REPORT_MAX_COUNT";
/**
* A {@link net.sf.jasperreports.engine.JRDataSource} instance representing the report data source.
* JasperReports defines some convenience implementations
* of {@link net.sf.jasperreports.engine.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. * */ public static final String REPORT_DATA_SOURCE = "REPORT_DATA_SOURCE"; /** * A {@link 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 * {@link net.sf.jasperreports.engine.JRAbstractScriptlet} instance, which in this case * is a {@link net.sf.jasperreports.engine.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. */ public static final String REPORT_SCRIPTLET = "REPORT_SCRIPTLET"; /** * A java.util.Locale instance containing the resource bundle desired locale. This parameter should be used in * conjunction with {@link #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.
*/
public static final String REPORT_LOCALE = "REPORT_LOCALE";
/**
* 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.
*/
public static final String REPORT_RESOURCE_BUNDLE = "REPORT_RESOURCE_BUNDLE";
/**
* 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.
*/
public static final String REPORT_TIME_ZONE = "REPORT_TIME_ZONE";
/**
* The {@link net.sf.jasperreports.engine.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
* {@link net.sf.jasperreports.engine.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.
*/
public static final String REPORT_VIRTUALIZER = "REPORT_VIRTUALIZER";
/**
* 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.
*/
public static final String REPORT_CLASS_LOADER = "REPORT_CLASS_LOADER";
/**
* 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.
* @deprecated Replaced by {@link JasperReportsContext}.
*/
public static final String REPORT_URL_HANDLER_FACTORY = "REPORT_URL_HANDLER_FACTORY";
/**
* A {@link FileResolver} instance to be used during the report filling process to
* handle locate files on disk using relative paths.
* @deprecated Replaced by {@link JasperReportsContext}.
*/
public static final String REPORT_FILE_RESOLVER = "REPORT_FILE_RESOLVER";
/**
* A {@link net.sf.jasperreports.engine.util.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
* {@link net.sf.jasperreports.engine.util.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.
*/
public static final String REPORT_FORMAT_FACTORY = "REPORT_FORMAT_FACTORY";
/**
* 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. */ public static final String IS_IGNORE_PAGINATION = "IS_IGNORE_PAGINATION"; /** * A {@link java.util.Collection collection} of {@link JRTemplate templates} passed to the * report at fill time. *
* These templates add to the ones specified in the report (see {@link 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. */ public static final String REPORT_TEMPLATES = "REPORT_TEMPLATES"; /** * */ public static final String SORT_FIELDS = "SORT_FIELDS"; /** * */ public static final String REPORT_CONTEXT = "REPORT_CONTEXT"; /** * A {@link DatasetFilter} to be used in addition to {@link JRDataset#getFilterExpression()} * for filtering dataset rows. */ public static final String FILTER = "FILTER"; /** * */ public String getName(); /** * */ public String getDescription(); /** * */ public void setDescription(String description); /** * */ public Class getValueClass(); /** * */ public String getValueClassName(); /** * */ public boolean isSystemDefined(); /** * */ public boolean isForPrompting(); /** * */ public JRExpression getDefaultValueExpression(); /** * 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
* {@link java.util.Collection} or a derived class, in which case the nested
* type specifies the type of values which are to be placed inside the collection.
*
* @return the nested value type for this parameter,
* or null if none set
*
* @see #getValueClass()
*/
public Class getNestedType();
/**
* Returns the name of the parameter nested value type.
*
* @return the name of the nested value type for this parameter,
* or null if none set
*
* @see #getNestedType()
*/
public String getNestedTypeName();
}