Chapter 6. Understanding the Report Object Model
This chapter provides an overview of the BIRT Report Object Model (ROM) and the primary elements that comprise the model. ROM defines the rules for constructing a valid report design file in much the same way that HTML defines the rules for constructing a valid web page. ROM, therefore, is the model for the BIRT report design, template, or library file in the same way that HTML is the model for the web page. For information about every component of ROM, see the online help entry Report Object Model (ROM) Definitions Reference in BIRT Programmer Reference.
About the ROM specification
The ROM specification defines a set of XML elements that describe the visual and non-visual components of a report. The XML file that BIRT Report Designer generates to describe a report design, library, or template consists entirely of ROM elements. Visual components, known as report items, include data items, labels, and tables. ROM also provides the framework for extended report items such as charts and cross tabs. Non-visual components, for example, data cubes, data sets, data sources, report parameters, and styles, support report items, but do not appear in a report. The ROM specification defines elements, their properties, and an element’s relationship to other elements. The ROM specification describes elements by their methods, properties, slots, and styles. ROM elements describe:
• The data source and query with which to populate a report
• The placement, size, style, and structure of report items
• The report page layout
The report design, template, or library file contains XML elements that describe the ROM elements in the file. The BIRT design engine interprets the ROM elements using the ROM specification and the ROM schema. The ROM specification describes the content of each report element type. The ROM schema describes the supported structure of the XML in a file. Each BIRT file type appears in the ROM schema. Examining the XML in a BIRT file and the ROM schema shows that a template’s structure is identical to a report design.
BIRT Report Designer displays the elements that the design engine interprets. Visual report items appear in the layout window. Data-related items such as cubes, data sets, and report parameters appear in the data explorer. All elements in the report design appear in the Outline view.
ROM methods
A ROM element can have one or more methods, called event handlers. BIRT fires many different events during the course of executing a report. When BIRT fires an event, the appropriate event handler executes to handle the event. By default, event handlers are empty methods that do nothing. By supplying code for an event handler, a report developer customizes and extends the functionality of BIRT. Supplying code for an event handler is called scripting. An event handler can be scripted in either JavaScript or Java.
Report items can have four events: onPrepare, onCreate, onPageBreak, and onRender. Each event fires in a specific phase of report creation. onPrepare fires in the preparation phase. onCreate fires during the generation phase. onRender and onPageBreak fire during the presentation phase.
ROM properties
ROM element properties are typed. Property types are similar to variable types in programming or data types in database terminology. Like variables and data types, ROM property types can be simple or complex. Design.xsd defines these types. Simple types include color, dimension, number, and string. Complex types include lists and structures. A complex type contains more than one component. For example, a text type contains both the text and a resource key used to internationalize the text.
ROM slots
A ROM slot is a container for elements of defined types. For example, a report element has a Body slot that contains any number of any type of report item. The Styles slot in the report element contains only Style items, which are the styles available to the report.
ROM styles
The ROM style system is based on cascading style sheets (CSS), where a style set in a container cascades to its contents. The Report element contains all other elements, so the style property of the Report element defines the default style for the entire report. An element within the report can override the default style. A report developer can either choose a style from a defined set of styles or create a new style. Typical style attributes include alignment, background image, color, and text size.
About the ROM schema
The ROM schema, written in the XML Schema language, encapsulates the ROM specification. XML Schema provides a standard way of defining the structure, content, and semantics of an XML file. XML Schema is similar to Document Type Definition (DTD). The ROM schema, therefore, contains the formal expression of the content, structure, and semantics of the ROM report design. The ROM schema, design.xsd, is located at:
http://www.eclipse.org/birt/2005/design
Design.xsd is also in the plug-in, org.eclipse.birt.report.model.
A statement similar to the following one appears at the top of every report design, library, or template file:
<report xmlns="http://www.eclipse.org/birt/2005/design"
version="3.2.21" id="1">
BIRT uses this statement, which identifies the version of the schema, to interpret the file structure. A file is not valid if it contains elements that are not defined in the schema or that violate the rules in the schema.
Opening a file using a schema-aware tool such as XMLSpy supports verifying the file against the schema. Using a schema-aware tool also enables a developer of a custom report designer to verify the output of the custom report designer.
The ROM schema defines syntax that supports extensions to BIRT without making changes to the actual schema. For example, an extended item uses the following tag:
<extended-item name="extension">
The ROM schema defines properties using the following syntax:
<property name="propertyName">value</property>
The ROM schema does not define any actual properties. ROM element properties are defined in another file, rom.def.
About the rom.def file
The rom.def file contains metadata defining the specific ROM elements, their properties, their slots, and their methods. You can find rom.def in:
$INSTALL_DIReclipseplugins org.eclipse.birt.report.model_<version>.jar
The rom.def file is an internal file that the design engine uses to present a property sheet for a ROM element. The property sheet for an element contains the element’s properties and their types, the element’s methods, and valid choice selections for each of the element’s properties. When the BIRT development team changes the structure of a ROM element, the changed item includes an attribute that shows the BIRT version in which that change occurred, for example:
<Structure displayNameID="Structure.FormatValue"
name="FormatValue" since="2.6">
The rom.def file specifies the following kinds of metadata:
• Choice
A choice definition specifies all the allowable values that an attribute can have. Most choice definitions relate to style attributes. The following example from rom.def defines all the allowable font families available to a fontFamily style specification:
<ChoiceType name="fontFamily">
<Choice displayNameID="Choices.fontFamily.serif"
name="serif" />
<Choice displayNameID="Choices.fontFamily.sans-serif"
name="sans-serif" />
<Choice displayNameID="Choices.fontFamily.cursive"
name="cursive" />
<Choice displayNameID="Choices.fontFamily.fantasy"
name="fantasy" />
<Choice displayNameID="Choices.fontFamily.monospace"
name="monospace" />
</ChoiceType>
• Class
A class definition defines a Java class that a report designer application can access using the BIRT model API. Class definitions describe the following component types:
• Data types, such as Array, Number, and String
• Functional classes, such as Global, Math, and RegExp
A class definition defines attributes, constructors, localization, members, and methods identifiers. The following example from rom.def shows part of the definition of the Number class:
<Class displayNameID="Class.Number" name="Number"
native="true" toolTipID="Class.Number.toolTip">
<Constructor displayNameID="Class.Number.Number"
name="Number" returnType="Number"
toolTipID="Class.Number.Number.toolTip">
<Argument name="value" tagID="Class.Number.Number.value"
type="Object"/>
</Constructor>
<Member dataType="number"
displayNameID="Class.Number.MAX_VALUE" isStatic="true"
name="MAX_VALUE"
toolTipID="Class.Number.MAX_VALUE.toolTip"/>
<Member dataType="number"
displayNameID="Class.Number.MIN_VALUE" isStatic="true"
name="MIN_VALUE"
toolTipID="Class.Number.MIN_VALUE.toolTip"/>
...
<Method displayNameID="Class.Number.toExponential"
name="toExponential" returnType="String"
toolTipID="Class.Number.toExponential.toolTip" >
<Argument name="digits"
tagID="Class.Number.toExpoential.digits" type="number"
/>
</Method>
<Method displayNameID="Class.Number.toFixed" name="toFixed"
returnType="String"
toolTipID="Class.Number.toFixed.toolTip">
<Argument name="digits"
tagID="Class.Number.toFixed.digits" type="number"/>
</Method>
...
</Class>
• Element
The rom.def file contains an element definition for every ROM element. Every element definition includes attributes, such as the element’s name, display name, and the element type that it extends. ROM supports methods, properties, property visibility, slot, and style properties in an element definition. The following example from the rom.def file illustrates an element definition:
<Element allowsUserProperties="true" canExtend="true"
displayNameID="Element.Parameter" extends="ReportElement"
hasStyle="false" isAbstract="true" isNameRequired="true"
name="Parameter" nameSpace="parameter" since="1.0">
<Property displayNameID="Element.Parameter.helpText"
name="helpText" runtimeSettable="false" since="1.0"
type="string"/>
<Property displayNameID="Element.Parameter.helpTextID"
name="helpTextID" type="resourceKey"/>
<Property displayNameID="Element.Parameter.promptText"
name="promptText" runtimeSettable="false" since="2.0"
type="string"/>
<Property displayNameID="Element.Parameter.promptTextID"
name="promptTextID" since="2.1" type="resourceKey"/>
<Property displayNameID="Element.Parameter.hidden"
name="hidden" runtimeSettable="false" since="1.0"
type="boolean">
<Default>false</Default>
</Property>
<Method context="factory"
displayNameID="Element.Parameter.validate"
name="validate" returnType="boolean" since="2.5"
toolTipID="Element.Parameter.validate.toolTip">
<Argument name="reportContext"
tagID="Element.Parameter.validate.reportContext"
type="org.eclipse.birt.report.engine.api.script
.IReportContext"/>
</Method>
</Element>
The property visibility property specifies whether BIRT exposes an inherited property to the user interface. For example, the label element extends ReportItem, which has dataSet and dataBindingRef properties. Because a label does not bind data, a property inherited by a label element must not appear visible to a user. The following example shows the use of property visibility to hide these properties:
<Element canExtend="true" displayNameID="Element.Label"
extends="ReportItem" isAbstract="false"
javaClass="org.eclipse.birt.report.model.elements.Label"
name="Label" selector="label" since="1.0" xmlName="label">
...
<PropertyVisibility name="dataSet" visibility="hide"/>
<PropertyVisibility name="dataBindingRef" visibility="hide"
/>
...
</Element>
A Slot property defines the element as a container and specifies the types of items that the slot contains. Slots appear in the user interface in BIRT views such as Outline. The following example illustrates a slot definition:
<Element allowsUserProperties="true" canExtend="true"
displayNameID="Element.CascadingParameterGroup"
extends="ParameterGroup" hasStyle="false" isAbstract="false"
isNameRequired="true" javaClass="org.eclipse.birt.report
.model.elements.CascadingParameterGroup"
name="CascadingParameterGroup" since="2.0"
xmlName="cascading-parameter-group">
...
<Slot displayNameID="Element.CascadingParameterGroup.slot
.parameters" multipleCardinality="true" name="parameters"
since="2.0" xmlName="parameters">
<Type name="ScalarParameter"/>
<Trigger validator="CascadingParameterTypeValidator"/>
</Slot>
</Element>
A style property defines the style components supported by the ROM element. The following example illustrates style property definitions for the data element. The label element definition does not have these style properties because it contains only string values, not numbers.
<Element allowsUserProperties="true" canExtend="true"
displayNameID="Element.Data" extends="ReportItem"
hasStyle="true" isAbstract="false" isNameRequired="false"
javaClass="org.eclipse.birt.report.model.elements.DataItem"
name="Data" selector="data" since="1.0" xmlName="data">
...
<StyleProperty name="numberFormat"/>
<StyleProperty name="numberAlign"/>
...
</Element>
• Structure
A structure is a complex data type that typically consists of two or more members. A few structures that are candidates for future expansion have only a single member. The following example from the rom.def file illustrates the definition of a structure.
<Structure displayNameID="Structure.TimeInterval"
name="TimeInterval" since="2.5.2">
<Member displayNameID="Structure.TimeInterval.measure"
isIntrinsic="true" name="measure" since="2.5.2"
type="integer"/>
<Member detailType="interval"
displayNameID="Structure.TimeInterval.unit"
isIntrinsic="true" name="unit" since="2.5.2"
type="choice">
<Allowed>hour,minute,second</Allowed>
</Member>
</Structure>
• Style
A style definition contains the least information of any type of metadata described in rom.def. A style definition defines the name of the style, its display name, and a reference value, as shown in the following example.
<Style displayNameID="Style.Report" name="report"
reference="Overall default" />
• Validator
A validator definition specifies a Java class with which to do validation. Two of the validator classes are for validating values. The rest are semantic validators. The following example from rom.def illustrates a semantic validator definition.
<SemanticValidator
class="org.eclipse.birt.report.model.api.validators
.CascadingParameterTypeValidator" modules="design, library"
name="CascadingParameterTypeValidator" />
Understanding ROM elements
ROM elements are defined in a set of hierarchies. Abstract elements, which cannot be used directly in a BIRT file, are at the top of each hierarchy. These elements define key characteristics of concrete elements in the same way that abstract classes in Java define methods and variables that a concrete class implements. Report designs are made of concrete elements that derive from the abstract elements.
About the primary ROM elements
The primary ROM elements consist of abstract elements from which other elements derive and concrete elements that provide the overall file definition.
The following elements are the abstract components that form the basis for understanding ROM:
• DataSet
DataSet defines the fundamental properties of a data set relating to columns and parameters.
• DataSource
DataSource defines the methods that a concrete data source element must support.
• DesignElement
DesignElement defines basic features of ROM elements. DesignElement represents any component of a report design that has properties.
• Listing
Listing is the abstract base element for list and table items. Both items support a data set, filtering, sorting, and methods.
• MasterPage
MasterPage defines the basic properties of a page.
• ReportElement
ReportElement represents any item that can be named and customized. Most components in ROM derive from ReportElement, including the elements that are visible in the user interface, such as data sets, styles, master pages, and report items.
• ReportItem
ReportItem is the base element for the visual elements. A report item includes a style. The style provides visual characteristics for any element that appears in a report, such as a section or report item.
The following concrete elements describe the root element of a BIRT file:
ReportDesign contains information about a report design, defining properties that describe the design as a whole. Report design properties do not support inheritance because a design cannot extend another design. ReportDesign is the root element of a report design or a template.
• Library
Library is similar to ReportDesign, extending LayoutModule, but has a different set of slots and does not have methods.
About report item elements
BIRT provides many types of visual report components. Every type of visual report component has a corresponding ROM element that derives from the ReportItem element. Visual report components are called report items. Every report item has an entry in the palette, the view in BIRT Report Designer that the report developer uses to build a report layout.
About report items
BIRT provides container and simple report items. Container items are structural components that provide slot elements to hold one or more other report items. The slots in container items support both container and simple report items, so a grid can contain tables that contain other tables and grids, and so on. Simple report items are not structural and do not contain other items. These report items have properties that describe their behavior and appearance and do not provide slots. For example, the Image element is a simple report item.
Examples of container report items include:
• Grid
A grid contains a set of report items arranged into a matrix having a fixed set of columns and rows. Each cell in the grid can contain one or more simple or container report items.
• List
A list contains a set of arbitrary content based on data retrieved from a data set. A list is appropriate when some report items require a sophisticated layout and repeat that layout for each row in a query.
• Table
A table contains a set of report items arranged into a matrix. A table has a fixed set of columns and an arbitrary number of rows. A table produces a detail row for every row of data retrieved from a data set.
Understanding report item element properties
Each type of report item has its own set of properties in addition to the properties it inherits from ReportItem. Types of inherited properties include:
• Method, which defines executable code.
• Property, which includes such values as names and dimensions.
• Slot, which contains Type elements that define its contents, as shown in the following element definition.
<Slot name="reportItems"
displayNameID="Element.FreeForm.slot.reportItems"
multipleCardinality="true">
<Type name="Label" />
<Type name="Data" />
<Type name="Text" />
</Slot>
• StyleProperty, which defines style-related characteristics, such as color and font size.
About data report elements
Several elements in the ROM specification apply to data rather than visual report items. These data report elements describe data sources and data sets. The following elements are data report elements:
• OdaDataSource
The OdaDataSource element represents a connection to an external data system, such as an RDBMS, text file, or XML file.
• ScriptedDataSource
The ScriptedDataSource element represents a connection to an external data system that is not an ODA data source. The developer must provide scripts for opening and closing a scripted data source. ScriptedDataSource inherits from DataSource.
• OdaDataSet
The OdaDataSet element represents a tabular result set retrieved from a data source. An OdaDataSet element defines a data source, query, filters, parameters, and result set columns.
• JointDataSet
The JointDataSet element represents a data set that results from a join of several data sets.
• ScriptedDataSet
The ScriptedDataSet element represents a data set that is associated with a scripted data source. The developer must provide scripts for opening, closing, and fetching a row from a scripted data source.