net.sf.jasperreports.engine

## Interface JRDataset

- All Superinterfaces:
    java.lang.Cloneable, JRCloneable, JRIdentifiable, JRPropertiesHolder
  All Known Implementing Classes:
    JRBaseDataset, JRDesignDataset, JRFillDataset, TableReportDataset

      public interface JRDataset
      extends JRPropertiesHolder, JRCloneable, JRIdentifiable

  Interface representing a data set that can be used in a report.

  A dataset is a concept that lies somewhere between a data source and a subreport. Datasets allow the engine to iterate through some virtual records, just as data sources do, but they also enable calculations and data grouping during this iteration using variables and groups. Because dataset declarations contain parameters, fields, variables, and groups, they closely resemble subreports, but they completely lack any visual content (that is, they have no sections or layout information at the dataset level).

  Datasets are useful for chart, crosstab and other components generation when you need to iterate through data that is not the main report data source itself, in order to gather data for the component or perform data bucketing for the crosstab. Before datasets, the use of subreports was the only way to iterate through virtual records that were nested collections of virtual records rather than part of the current report data source. However, subreports come with unwanted visual settings and tend to complicate layout and report template structure.

  A data set consists of parameters, fields, variables, groups and an optional query. When a data set gets instantiated, parameter values and a data source is passed to it.

  ### Main Dataset

  The report data source, along with the parameters, fields, variables, and groups declared at the report level, represent the building blocks of the main dataset for the report. All report templates implicitly declare and use this main dataset.

  The main dataset is responsible for iterating through the data source records, calculating variables, filtering out records, and estimating group breaks during the report-filling process.

  A report has one main dataset and multiple subdatasets that can be instantiated by charts, crosstabs and other components.

  ### Subdatasets

  User-defined datasets (or subdatasets) are declared in JRXML using the `<subDataset>` tag.

  The engine does not necessarily use a subdataset, once defined in the report. Subdatasets are instantiated and iterate through the supplied data source to calculate dataset variable values only if they are referenced by a chart, crosstab or other component's dataset run.

  Just like subreports, datasets, when instantiated, expect to receive parameter values and a data source to iterate through. As a convenience, datasets can have an associated SQL query that is executed by the engine if a java.sql.Connection object is supplied to them instead of the usual data source.

  Datasets can also have scriptlets associated with them to allow making callbacks to userdefined business logic during the dataset iteration, if further data manipulation is needed.
  Version:
    $Id: JRDataset.java 7051 2014-04-25 13:46:34Z shertage $
  Author:
    Lucian Chirita (lucianc@users.sourceforge.net)
  See Also:
    `JRDatasetRun`, `JRReport.getMainDataset()`, `JRReport.getDatasets()`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `JRField[]` | `getFields()` Returns the dataset's fields.
    `JRExpression` | `getFilterExpression()` Returns the dataset filter expression.
    `JRGroup[]` | `getGroups()` Returns the dataset's groups.
    `java.lang.String` | `getName()` Returns the dataset name.
    `JRParameter[]` | `getParameters()` Returns the dataset's parameters.
    `JRQuery` | `getQuery()` Returns the query of the dataset.
    `java.lang.String` | `getResourceBundle()` Returns the resource bundle base name.
    `java.lang.String` | `getScriptletClass()` The name of the scriptlet class to be used when iterating this dataset.
    `JRScriptlet[]` | `getScriptlets()` Returns the dataset's scriptlets.
    `JRSortField[]` | `getSortFields()` Returns the dataset's sort fields.
    `JRVariable[]` | `getVariables()` Returns the dataset's variables.
    `WhenResourceMissingTypeEnum` | `getWhenResourceMissingTypeValue()` Returns the resource missing handling type.
    `boolean` | `isMainDataset()` Decides whether this dataset is the main report dataset or a sub dataset.
    `void` | `setWhenResourceMissingType(WhenResourceMissingTypeEnum whenResourceMissingType)` Sets the resource missing handling type.

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

      `getParentProperties, getPropertiesMap, hasProperties`

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

      `clone`

    - ### Methods inherited from interface net.sf.jasperreports.engine.JRIdentifiable

      `getUUID`

- - ### Method Detail

    - #### getName

          java.lang.String getName()

      Returns the dataset name.
      Returns:
        the name of the dataset

    - #### getScriptletClass

          java.lang.String getScriptletClass()

      The name of the scriptlet class to be used when iterating this dataset.
      Returns:
        the scriplet class name

    - #### getScriptlets

          JRScriptlet[] getScriptlets()

      Returns the dataset's scriptlets.
      Returns:
        the dataset's scriptlets

    - #### getParameters

          JRParameter[] getParameters()

      Returns the dataset's parameters.
      Returns:
        the dataset's parameters

    - #### getQuery

          JRQuery getQuery()

      Returns the query of the dataset.

      The query is used by passing a connection is passed to the dataset when instantiating.

      Returns:
        the query of the dataset

    - #### getFields

          JRField[] getFields()

      Returns the dataset's fields.
      Returns:
        the dataset's fields

    - #### getSortFields

          JRSortField[] getSortFields()

      Returns the dataset's sort fields.
      Returns:
        the dataset's sort fields

    - #### getVariables

          JRVariable[] getVariables()

      Returns the dataset's variables.
      Returns:
        the dataset's variables

    - #### getGroups

          JRGroup[] getGroups()

      Returns the dataset's groups.
      Returns:
        the dataset's groups

    - #### isMainDataset

          boolean isMainDataset()

      Decides whether this dataset is the main report dataset or a sub dataset.
      Returns:
        `true` if and only if this dataset is the main report dataset

    - #### getResourceBundle

          java.lang.String getResourceBundle()

      Returns the resource bundle base name.

      The resource bundle is used when evaluating expressions.

      Returns:
        the resource bundle base name

    - #### getWhenResourceMissingTypeValue

          WhenResourceMissingTypeEnum getWhenResourceMissingTypeValue()

      Returns the resource missing handling type.
      Returns:
        the resource missing handling type

    - #### setWhenResourceMissingType

          void setWhenResourceMissingType(WhenResourceMissingTypeEnum whenResourceMissingType)

      Sets the resource missing handling type.
      Parameters:
        `whenResourceMissingType` - the resource missing handling type

    - #### getFilterExpression

          JRExpression getFilterExpression()

      Returns the dataset filter expression.

      This expression is used to filter the rows of the `data source` that this dataset will iterate on.

      This expression (if not null) is evaluated immediately after a new row is `produced` by the data source. The evaluation is performed using field and variable values corresponding to the new row. When the result of the evaluation is `Boolean.TRUE` the row gets processed by the report filling engine. When the result is null or `Boolean.FALSE`, the current row will be skipped and the datasource will be asked for the next row.

      Returns:
        the dataset filter expression

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com