Package 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 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

      • 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_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

    • Method Detail

      • getDescription

        String getDescription()

      • setDescription

        void setDescription​(String description)

      • getValueClass

        Class<?> getValueClass()

      • getValueClassName

        String getValueClassName()

      • isSystemDefined

        boolean isSystemDefined()

      • isForPrompting

        boolean isForPrompting()

      • getEvaluationTime

        ParameterEvaluationTimeEnum getEvaluationTime()
        Specifies when the default value expression of a parameter is evaluated.

      • 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()