net.sf.jasperreports.engine

## Interface JRParameter

- All Superinterfaces:
    java.lang.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.
  Version:
    $Id: JRParameter.java 7045 2014-04-24 14:20:46Z shertage $
  Author:
    Teodor Danciu (teodord@users.sourceforge.net)

- - ### Field Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `JRExpression` | `getDefaultValueExpression()`
    `java.lang.String` | `getDescription()`
    `java.lang.String` | `getName()`
    `java.lang.Class<?>` | `getNestedType()` Returns the parameter nested value type.
    `java.lang.String` | `getNestedTypeName()` Returns the name of the parameter nested value type.
    `java.lang.Class<?>` | `getValueClass()`
    `java.lang.String` | `getValueClassName()`
    `boolean` | `isForPrompting()`
    `boolean` | `isSystemDefined()`
    `void` | `setDescription(java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String SORT_FIELDS

      See Also:
        Constant Field Values

    - #### REPORT_CONTEXT

          static final java.lang.String REPORT_CONTEXT

      See Also:
        Constant Field Values

    - #### FILTER

          static final java.lang.String FILTER

      A `DatasetFilter` to be used in addition to `JRDataset.getFilterExpression()` for filtering dataset rows.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getName

          java.lang.String getName()

    - #### getDescription

          java.lang.String getDescription()

    - #### setDescription

          void setDescription(java.lang.String description)

    - #### getValueClass

          java.lang.Class<?> getValueClass()

    - #### getValueClassName

          java.lang.String getValueClassName()

    - #### isSystemDefined

          boolean isSystemDefined()

    - #### isForPrompting

          boolean isForPrompting()

    - #### getDefaultValueExpression

          JRExpression getDefaultValueExpression()

    - #### getNestedType

          java.lang.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

          java.lang.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()`

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com