Package net.sf.jasperreports.engine

Interface JRDataset

  • All Superinterfaces:
    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.

    Author:
    Lucian Chirita (lucianc@users.sourceforge.net)
    See Also:
    JRDatasetRun, JRReport.getMainDataset(), JRReport.getDatasets()

    • Method Detail

      • getName

        String getName()
        Returns the dataset name.
        Returns:
        the name of the dataset

      • getScriptletClass

        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

      • getPropertyExpressions

        DatasetPropertyExpression[] getPropertyExpressions()
        Returns the list of dynamic/expression-based properties for this dataset.
        Returns:
        an array containing the expression-based properties of this dataset

      • 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

        String getResourceBundle()
        Returns the resource bundle base name.

        The resource bundle is used when evaluating expressions.

        Returns:
        the resource bundle base name

      • getWhenResourceMissingType

        WhenResourceMissingTypeEnum getWhenResourceMissingType()
        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