Chapter 5. Understanding the BIRT Architecture
BIRT consists of many related components. This chapter provides an overview of the BIRT architecture, the BIRT components, the Eclipse components upon which BIRT relies, and the relationships that tie them all together.
Understanding the BIRT integration
As an Eclipse project, BIRT is tightly integrated with Eclipse frameworks and platforms. Like all Eclipse projects, BIRT is implemented as a set of Eclipse plug-ins. The BIRT plug-ins provide the functionality for all BIRT components, including BIRT applications, the engines that drive the applications, and supporting application programming interfaces (APIs). The BIRT plug-ins also provide the interface mechanism for communicating with several Eclipse frameworks and platforms.
The relationships between BIRT and the Eclipse components are most easily viewed as a stack. Each tier in the stack depends upon, uses, and integrates with the tier below it, as shown in Figure 5-1.
Figure 5-1 BIRT components as plug-ins to the Eclipse platform
Figure 5-2 presents the various BIRT components and how they relate to one another. In this diagram, a component in a solid box is a standard BIRT component. A component in a dashed box is a custom component that a Java developer can provide. Some custom components are extensions of BIRT and others are applications that use the BIRT APIs. A component in a dotted box is a standard BIRT component that the containing component uses. For example, because BIRT Report Designer uses the design engine, the design engine appears in a dotted box within the box for BIRT Report Designer.
Figure 5-2 Task flow among standard BIRT components and custom components
Figure 5-3 shows the relationships among BIRT components as they generate a formatted report from a design.
Figure 5-3 Task flow among BIRT and custom components to generate a report
BIRT Report Designer provides drag-and-drop capabilities to design reports quickly. The report designer uses the design engine to produce XML report design files. The BIRT Report Engine consumes these report design files, then, at run-time, fetches the appropriate data using queries defined at design-time. A BIRT report for immediate viewing is generated in memory and emitted in the desired output format, which can be a Microsoft Excel, non-paginated HTML, paginated HTML, PDF, PostScript, Microsoft PowerPoint, or Word file. To create a persistent report, the report engine transforms and summarizes the data and caches the generated report in an intermediate binary file, the report document file. This caching mechanism enables BIRT to scale to handle large quantities of data. BIRT also provides a tightly integrated charting component, which supports including a variety of chart types in reports. The charts are rendered at runtime using the charting engine. This charting engine also supports creating chart output separate from a report. Figure 5-4 illustrates this architecture and process flow.
Figure 5-4 BIRT architecture and process flow
About the BIRT applications
There are three BIRT applications: BIRT Report Designer, BIRT RCP Report Designer, and BIRT Report Viewer. The two report designers are very similar. BIRT Report Designer runs as a set of Eclipse plug-ins and lets you build reports within the Eclipse workbench. BIRT RCP Report Designer has a simplified report design interface based on Eclipse Rich Client Platform.
About BIRT Report Designer and BIRT RCP Report Designer
BIRT Report Designer is a graphical report design tool. BIRT Report Designer uses the design engine to generate a report design file based on the report object model (ROM). ROM supports the standard set of BIRT report items and custom report items. BIRT Report Designer also supports the reuse of a report design by saving it as a template. You can also save individual report components in a component library, making those components accessible to other report designs.
The primary functional differences between the BIRT RCP Report Designer and BIRT Report Designer are:
• BIRT RCP Report Designer has no integrated debugger.
• BIRT RCP Report Designer does not support Java event handlers.
Other than these differences, the functionality of the two report designers is identical and all further mentions of BIRT Report Designer in this chapter apply equally to BIRT RCP Report Designer.
About the BIRT Viewer
BIRT provides the BIRT Viewer web application that includes all the necessary files to deploy to most J2EE application servers. This web application supports running reports and viewing paginated HTML, with a table of contents and bookmarks, and extracting data to a values file. URLs provide this level of integration. The host application forwards the reporting request to the BIRT Viewer and allows the user to interact directly with the report.
The BIRT Viewer is also available as an Eclipse plug-in. This plug-in is used within the report designer to preview and display a report while it is being developed. Within BIRT Report Designer, it is deployed to and works with the Eclipse Tomcat application server plug-in. As report requests are made, the Eclipse workbench starts the Tomcat application and launches the BIRT Viewer.
About the BIRT engines and services
An engine is a set of Java APIs that provide basic functionality in a specific domain. BIRT contains several engines, for example, the report engine, design engine, and chart engine. These engines provide several different types of services. A service is a set of Java classes that provide functionality using the API provided from different engines. For example, the generation services use the design engine API and report engine API to generate reports and produce report documents respectively.
About the design engine
The design engine contains the APIs used to validate and generate a report design file. BIRT Report Designer and any custom Java application that generates a BIRT report design use the design engine. The generation services also use the design engine when building the report document. The design engine contains APIs that validate the elements and structure of the design file against the ROM specification.
About the report engine
The BIRT report engine enables XML report designs created by the BIRT Report Designer to be used by a J2EE/Java application. To support this functionality, the report engine provides two core services, generation and presentation.
The report engine provides extensions to support custom report items and custom output formats. The report engine also supports Java application developers who want to integrate powerful report generation and viewing capabilities into their applications without having to build the infrastructure from lower-level Java components.
The BIRT report engine API supports integrating the run-time part of BIRT into Java applications. The report engine provides the ability to specify parameters for a report, run a report to produce HTML, PDF, DOC, PS, or PPT output and fetch an image or chart.
About the generation services
The generation service within the report engine connects to the data sources specified in a report design, uses the data engine to retrieve and process the data, creates the report layout, and generates the report document. Report content can be either viewed immediately using the presentation services, or saved for later use. The saved report documents containing snapshot views of data can be retained for use and comparison over time.
About the presentation services
The presentation services process the report document created by the generation services and render the report to the requested format and the layout specified in the design. The presentation services use the data engine to retrieve and process data from the report document. The presentation services use whichever report emitter they require to generate a report in the requested format. BIRT has several standard emitters, HTML PDF, DOC, PPT, PS, and XLS. BIRT also supports custom emitters that modify these default formats or deliver new formats.
Extensions to the presentation engine and services provide display capability for chart report items and custom report items.
About the chart engine
The chart engine contains APIs to generate charts and associate them with data from a data source. The BIRT Report Viewer interprets any chart information in a report design and uses the chart engine to generate the chart specified by the design. Use of the chart engine is not restricted to a BIRT application. Any Java application can use chart engine APIs to create and display a chart.
About the data engine and services
The data engine contains the APIs and provides services to retrieve and transform data. The data services retrieve data from its source and process the data as specified by the report design. When used by the generation engine, the data services retrieve data from the data source specified in the design. When used by the presentation engine, the data services retrieve data from the report document. The data engine extension of ODA provides the connection method and the drivers for data sources.
About data services
The data engine provides two key service types: data access services and data transformation services. The data access services communicate with the ODA framework to retrieve data. The data transformation services perform such operations as sorting, grouping, aggregating, and filtering the data returned by the data access services.
About the ODA framework
BIRT uses the ODA framework provided by the Eclipse Data Tools Platform project to manage ODA and native drivers, load drivers, open connections, and manage data requests. The ODA framework contains extension points that support adding a custom ODA driver. Write a custom ODA driver if you have a data source that BIRT does not support and a scripted data source is not desired. Use of a custom ODA driver may require extending not only the data engine but also BIRT Report Designer. A BIRT Report Designer extension is necessary if the data source requires a user interface component to specify the data set and data source properties.
About the types of BIRT report items
A report item is a visual component of a report, such as a label, a list, or a chart. There are three categories of report items in BIRT: standard report items, custom report items, and the chart report item.
About standard report items
A report item is a visual component of a report. A report item can be as simple as a label or as complex as a cross tab. Every report item has an icon on the Palette view in BIRT Report Designer.
About custom report items
Custom report items are either new report items or extensions of existing report items. An example of an extension to a report item is adding a property, such as color. An example of a new report item is the rotated text report item, which is a reference implementation of a report item extension.
Creating a new report item and extending an existing report item both involve extending BIRT through the Eclipse plug-in mechanism. Custom items require an extension to one or more of the following components to support the new item:
• BIRT Report Designer
Extending BIRT Report Designer provides user interface components for a report developer to specify properties and other settings for the report item.
• The design engine
Extending the design engine validates the report item settings provided by a report developer.
• The report engine
Extending the report engine supports generating and presenting report output for the report item.
About the chart report item
A chart report item is a standard BIRT component implemented as a BIRT extension. The user interface for creating a chart report item is a chart builder that steps the report developer through the process of designing the chart and associating it with the appropriate data columns.
About the Report Object Model (ROM)
ROM is the model upon which BIRT is based. ROM is a specification for the structure, syntax, and semantics of the report design. The formal expression of ROM is through an XML schema and a semantic definition file. The ROM specification appears in the following plug-in JAR file:
$INSTALL_DIReclipseplugins
org.eclipse.birt.report.model_<version>.jar
About the types of BIRT files
BIRT Report Designer uses four types of files:
• Report design files
• Report library files
• Report template files
The following sections provide a brief overview of each of these file types.
About report design files
A report design file is an XML file that contains the report design, the complete description of a BIRT report. The report design describes every aspect of a report, including its structure, format, data sources, data sets, JavaScript event handler code, and the names of Java event handlers. BIRT Report Designer creates the report design file and BIRT report engine processes it.
The file extension of a report design file is rptdesign.
About report document files
A report document file is a binary file that encapsulates the report design, incorporates the data, and contains additional information, such as data rows, pagination information, and table of contents information.
The file extension of a report document file is rptdocument.
About report library files
A report library file is an XML file that contains reusable and shareable BIRT report components. A report developer uses Resource Explorer in BIRT Report Designer to provide shared access to a library, update a library, and use report elements from a library.
A BIRT report library can contain any report element, such as:
• Data sets and data sources
• Embedded images
• Event handler code
• Styles
• Visual report items
The file extension of a report library file is rptlibrary.
About report template files
A report template is an XML file that contains a reusable design. A report developer can use a template as a basis for developing a new report. A report developer uses a report template to maintain a consistent style across a set of report designs and for streamlining the report design process. A report template can specify many different elements of a report, including:
• One or more data sources
• One or more data sets
• Part or all of the layout of a report design, including grids, tables, lists, and other report items
• Grouping, filtering, and data binding definitions
• Styles
• Library components
• Master pages
• Cheat sheets
Report templates act as a starting point for report development. They speed up report development by capturing the layout of common types of reports. They also make it easy to create reports with a consistent look. Building BIRT templates is similar to building BIRT reports. The difference lies in converting report items into template report items which act as placeholders.
The file extension of a report template file is rpttemplate.
About custom Java applications
Java developers can use the BIRT APIs to create a custom report designer or a custom report generator.
About a custom report designer
A custom report designer is a Java application that a Java developer creates to generate a well-formed report design file based on specific requirements. A custom report designer does not necessarily include a user interface. A typical example of a custom report designer is a Java application that dynamically determines the content, structure, or data source for a report, based on business logic. A custom report designer uses the same design engine API as BIRT Report Designer.
About a custom Java report generator
A custom Java report generator performs the same function as the BIRT report generator and is typically integrated into either a web application or a stand-alone Java application. A custom Java report generator uses the report engine API to read a report design file and generate a report. A custom Java report generator can use business logic to implement security requirements, control content, and determine the output format.
About extensions to BIRT
Through its public APIs and the BIRT extension framework, BIRT enables a Java developer to expand the capabilities of BIRT. BIRT uses Eclipse extensions to enable extending the functionally of the framework. The extension points provided by BIRT support the creation of new graph types, additional data sources, report controls, and emitters for rendering to additional outputs. These extension points appeal to users who have specialized data access and formatting needs. The following list shows some of the possible custom extensions:
• A custom report item
A custom report item is a report item extension. This report item can be an extension, an existing BIRT report item, or a new report item.
• A custom ODA data source driver
A custom ODA data source driver is a custom ODA extension that connects to a data source type other than those that BIRT directly supports.
• A custom report emitter
A custom report emitter generates a report in a format other than HTML or PDF.
Later chapters in this book provide fully worked examples of all these types of extensions.