Eclipse BIRT Report Object Model (ROM)

DataSet Element

Element Overview

The data set element represents a result set retrieved from an external data provider.

Details

Display Name: Data Set
Since: 1.0
XML Element: None
Extends: ReportElement
Extendable: No
Abstract: Yes
Name Space: Data Sets
Name Requirement: Required
Allows User Properties: Yes
Has Style: No

Property Summary

cachedMetaData
Cached derived data attributes of a data set.
cachedRowCount
Number of rows that will be cached when the data rows are retrived from DB.
columnHints
Defines the report-related data attributes of the result set’s columns.
computedColumns
User-defined columns in the result set.
dataSource
The database connection that the data set is used.
filter
An optional set of filters to apply to the result set before any other data transforms.
paramBindings
A list of data set parameter binding elements that bind data set input parameters to BIRT expressions.
parameters
Defines the data access attributes of the list of input and/or output parameters.
refTemplateParameter
Name of the template parameter definition.
resultSet
Defines the columns of the expected result set.

Method Summary

afterClose
Called just after BIRT closes the data set. Allows the application to perform code-based cleanup.
afterOpen
Called just after BIRT opens the data set. Allows the application to perform any code-based initialization required for the data set.
beforeClose
Called just before BIRT closes the data set. Allows the application to perform code-based cleanup.
beforeOpen
Called just before BIRT opens the data set. Allows the application to customize the data set properties.
onFetch
Called just after fetching each row before applying filters or calculating computed columns.

Inherited Properties

comments, customXml, displayName, displayNameID, eventHandlerClass, extends, name, propertyMasks, userProperties

Inherited Property Notes

name
The name is required to identify a data set.

Description

The Data Set element is an abstract element that includes data-access and report-related properties and other content common to all kinds of data sets.

Its script methods execute as methods of a JavaScript object that represents the data set. See the Data Scripting Objects section for a description of the DataSet scripting object.

See Also

DataSet scripting object

Property Detail

cachedMetaData Property

Cached derived data attributes of a data set.

Details

Type: CachedMetaData Structure
Since: 1.0
Required: No
Display Name: Cached metadata
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

Defines the cached derived data attributes of a data set. The BIRT designer uses the cached information until the user initiates refresh and reconciles with the latest derived data attributes provided by the connected data source. This property is used during report design time only; its content is maintained by the BIRT designer tool.

See Also

CachedMetaData structure


cachedRowCount Property

Number of rows that will be cached when the data rows are retrived from DB.

Details

Type: integer
Since: 2.0
Required: No
Display Name: Cached row count
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

Number of rows that will be cached when the data rows are first time retrieved from DB, the cached data will be used after that unless user choose to flush the cache. This will speed up the report developing.


columnHints Property

Defines the report-related data attributes of the result set’s columns.

Details

Type: List of ColumnHint Structures
Since: 1.0
Required: No
Display Name: Column hints
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

In BIRT, a result set column can be defined with an alias.  Aliases are useful in cases where a column name is awkward, or is used by multiple columns in a result set.

BIRT reports provide a rich viewing experience. The user can search the report, extract data to a file, export data to an OLAP system, and more. Such operations work on the actual data set’s result set instead of on the presentation of the data. Column hints let the report developer customize the search and data extract experience.

The column hint element provides a number of "hints" about result set columns. The hints override BIRT defaults for how columns are handled during viewing. Hints can be provided for both retrieved and computed columns.

Column hints are keyed to the data set’s primary result set using names. The user must understand how to keep the hints in sync with the data set when either the data set definition, or underlying data source, changes.

BIRT uses the column hints in the following cases:

  • The report references a column using the alias defined in the column hint.
  • The report references a column (retrieved or computed) that is also referenced by the column hint.
  • The column hint has the Export attribute set to "always".

In each case, BIRT checks whether the data set provides the requested column. If so, it continues processing the report.  If not, it issues a fatal runtime error.

See Also

ColumnHint structure


computedColumns Property

User-defined columns in the result set.

Details

Type: List of ComputedColumn Structures
Since: 1.0
Required: No
Display Name: Computed columns
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

A computed column is a user-defined column produced as an expression of other columns within the data set’s primary result set. It is not of the columns retrieved directly from the underlying data provider.

See Also

ComputedColumn structure


dataSource Property

The database connection that the data set is used.

Details

Type: DataSource Reference
Since: 1.0
Required: Yes
Display Name: Data source
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

Name of the data source, that is the database connection this data set is using.


filter Property

An optional set of filters to apply to the result set before any other data transforms.

Details

Type: List of FilterCondition Structures
Since: 1.0
Required: No
Display Name: Filter
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

An optional set of filters that apply to the data set’s primary result set.  A data set’s filter is applied to each row of the retrieved result set before any other data transforms.  The filter expression should thus not contain any aggregation functions.  It usually references at least one column from a data row, and may also reference a report parameter or other scripting variable.

See Also

Filter Criteria structure

Listing filter property

ListingGroup filter property


paramBindings Property

A list of data set parameter binding elements that bind data set input parameters to BIRT expressions.

Details

Type: List of ParamBinding Structures
Since: 1.0
Required: No
Display Name: Parameter bindings
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

A list of data set parameter binding elements that bind data set input parameters to BIRT expressions.  Each ParamBinding structure associates a parameter name with an expression.

BIRT differentiates between data set parameters and report parameters. Data set input parameters are not automatically exposed as report parameters. However, the report developer can define report parameters that match data set input parameters. In this case, data set input parameter binding associates data set input parameters with the values of report parameters.

The Data Set element provides a list of parameter binding elements that bind a value to each query parameter.

The bind expression frequently includes a reference to a report parameter, configuration variable, or a row in an outer query. However, the expression can include any valid JavaScript expression.

See Also

ParamBinding structure

Report Item paramBindings property


parameters Property

Defines the data access attributes of the list of input and/or output parameters.

Details

Type: List of DataSetParam Structures
Since: 1.0
Required: No
Display Name: Parameters
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

Many data sets allow parameters, which can be of input and/or output modes. For some, the user must define the parameters as part of the data set definition. For other data sets, the driver itself can provide the set of parameter definitions from the information available in a data set query. In the latter case, parameter definitions are derived data and are not stored in the parameter definition.

Some drivers refer to a parameter by position. Others can refer to a parameter by name. Also, for some data sets, the data set definition can omit parameter definitions for optional parameters not used within the report.  Not all parameter properties are required. If a property is omitted. BIRT assumes that the data set implementation can provide it at run time. If the driver cannot provide the information, then a runtime error occurs.  This is an optional list of data set parameter definitions, used only when the underlying data provider cannot provide this information.  When contradicting meta-data are found between those provided dynamically by a data provider and  those specified in a data set definition, the data provider’s meta-data takes precedence.

See Also

DataSetParam structure

ParamBinding structure


refTemplateParameter Property

Name of the template parameter definition.

Details

Type: TemplateParameterDefinition Reference
Since: 2.0
Required: No
Display Name: Referred Template Parameter Definition
JavaScript Type:
Default Value: None
Inherited: No
Runtime Settable: No
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

when a data set is created from an template data set, this property will reference to the base data set.


resultSet Property

Defines the columns of the expected result set.

Details

Type: List of ResultSetColumn Structures
Since: 1.0
Required: No
Display Name: Result set
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

Defines the data access attributes of  the list of columns in the expected primary result set. This is an optional list of result set column definitions, used only when the underlying data provider cannot provide this information.  When contradicting meta-data are found between those provided dynamically by a data provider and  those specified in a data set definition, the data provider’s meta-data takes precedence.

See Also

ResultSetColumn structure

Method Detail

afterClose Method

Called just after BIRT closes the data set. Allows the application to perform code-based cleanup.

Synopsis

None obj.afterClose( )

Details

Since: 1.0
Context: factory
Arguments: None
Return Type: None

Description

Called just after BIRT closes the data set. Allows the application to perform code-based cleanup.

See Also

beforeClose method


afterOpen Method

Called just after BIRT opens the data set. Allows the application to perform any code-based initialization required for the data set.

Synopsis

None obj.afterOpen( )

Details

Since: 1.0
Context: factory
Arguments: None
Return Type: None

Description

Called just after BIRT opens the data set. Allows the application to perform any code-based initialization required for the data set.

See Also

beforeOpen method


beforeClose Method

Called just before BIRT closes the data set. Allows the application to perform code-based cleanup.

Synopsis

None obj.beforeClose( )

Details

Since: 1.0
Context: factory
Arguments: None
Return Type: None

Description

Called just before BIRT closes the data set. Allows the application to perform code-based cleanup.

See Also

afterClose method


beforeOpen Method

Called just before BIRT opens the data set. Allows the application to customize the data set properties.

Synopsis

None obj.beforeOpen( )

Details

Since: 1.0
Context: factory
Arguments: None
Return Type: None

Description

Called just before BIRT opens the data set. Allows the application to customize the data set properties.

See Also

afterOpen method


onFetch Method

Called just after fetching each row before applying filters or calculating computed columns.

Synopsis

None obj.onFetch( )

Details

Since: 1.0
Context: factory
Arguments: None
Return Type: None

Description

Called just after fetching each row before applying filters or calculating computed columns.

See Also

DataRow scripting object