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 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.
String	getName() Returns the dataset name.
JRParameter[]	getParameters() Returns the dataset's parameters.
JRQuery	getQuery() Returns the query of the dataset.
String	getResourceBundle() Returns the resource bundle base name.
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

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

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

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