Home > Store

Integrating and Extending BIRT

Register your product to gain access to bonus material or receive a coupon.

Integrating and Extending BIRT


  • Sorry, this book is no longer in print.
Not for Sale


  • Copyright 2007
  • Edition: 1st
  • Book
  • ISBN-10: 0-321-44385-3
  • ISBN-13: 978-0-321-44385-4

A new edition of this title is available, ISBN-10: 0321580303 ISBN-13: 9780321580306

The second of a two-book series about business intelligence and reporting technology, Integrating and Extending BIRT introduces programmers to BIRT architecture and the reporting framework. Built on the Eclipse platform, this exciting technology makes it possible for programmers to build and deploy customized reports using scripting and BIRT APIs. In addition, programmers can extend the BIRT framework by building new plug-ins using the Eclipse Plug-in Development Environment.

This book describes the key components of BIRT architecture, applications, and engines, including installing, deploying, and troubleshooting the Reporting and Charting engines in an Enterprise Java application-server environment.For developers who wish to incorporate custom business logic in their reports or access data from Java objects, the book describes BIRT's extensive scripting capabilities in JavaScript and Java. For developers who want to extend the BIRT framework, the book describes the key extension points to use in creating customized report items, rendering extensions for generating output other than HTML or PDF, and Open Data Access (ODA) drivers for new data sources. The book provides extensive examples of how to build plug-ins to extend the features of the BIRT framework.

Topics discussed include

  • Installing and deploying BIRT
  • Deploying a BIRT report to an application server
  • Understanding BIRT architecture
  • Scripting in a BIRT report design
  • Integrating BIRT functionality in applications
  • Working with the BIRT extension framework

Sample Content

Online Sample Chapter

Using Scripting in a Report Design in BIRT

Downloadable Sample Chapter

Download the Sample Chapter from this book.

Table of Contents

Foreword xvii

Preface xix

Acknowledgments xxvii

Part I Installing and Deploying BIRT 1

Chapter 1 Prerequisites for BIRT 3

Requirements for the BIRT report designers 3

About installing required software 5

BIRT RCP Report Designer software requirements 5

BIRT Report Designer Full Eclipse Install software requirements 5

BIRT Report Designer software requirements 6

Prerequisites for other BIRT packages 7

BIRT Chart Engine software requirements 7

BIRT Demo Database software requirements 8

BIRT Report Engine software requirements 9

BIRT Samples software requirements 9

BIRT Test Suite software requirements 9

About types of BIRT builds 10

Chapter 2 Installing a BIRT Report Designer 13

Installing BIRT Report Designer 14

Downloading and installing BIRT Report Designer 14

Installing the auxiliary file for BIRT Report Designer 14

Testing the BIRT Report Designer installation 15

Installing BIRT Report Designer Full Eclipse Install 15

Downloading and installing BIRT Report Designer Full Eclipse Install 15

Installing the auxiliary file for BIRT Report Designer 16

Installing BIRT RCP Report Designer 16

Downloading and installing BIRT RCP Report Designer 17

Installing the auxiliary file for BIRT Report Designer 17

Testing the BIRT RCP Report Designer installation 18

Troubleshooting installation problems 18

Avoiding cache conflicts after you install a BIRT report designer 18

Specifying which Java Virtual Machine to use when you start a BIRT report designer 19

Installing a language pack 19

Chapter 3 Installing Other BIRT Packages 23

Installing BIRT Chart Engine 23

Installing BIRT Chart Engine from the Eclipse BIRT web site 24

Avoiding cache conflicts after installing 24

Installing BIRT Demo Database 25

Installing BIRT Demo Database from the Eclipse BIRT web site 25

Testing the BIRT Demo Database installation 25

Installing BIRT Report Engine 26

Installing BIRT Report Engine from the Eclipse BIRT web site 27

Testing the BIRT Report Engine installation 27

Installing BIRT Samples 28

Installing BIRT Test Suite 29

Chapter 4 Updating a BIRT Installation 31

Using the Eclipse Update Manager to update BIRT Report Designer installation 31

Updating BIRT RCP Report Designer installation 32

Chapter 5 Deploying a BIRT Report to an Application Server 33

About application servers 33

About deploying to Tomcat 33

About deploying to other application servers 34

Placing the BIRT report viewer on an application server 34

Installing the BIRT report viewer files 34

Installing the auxiliary file 35

Installing your JDBC drivers 35

Testing the BIRT report viewer installation 35

Using a different context root for the BIRT report viewer 36

Placing the viewer in a different location 36

Mapping the folders that the BIRT report viewer uses 36

Verifying that Apache Tomcat is running BIRT report viewer 39

Placing fonts on the application server 40

Viewing a report using a browser 40

Understanding the run and frameset servlets 41

Using the URL parameters for the run and frameset servlets 41

About the report item elements 67

About the report items 67

Understanding the report item element properties 67

About the data elements 68

Part II Understanding the BIRT Framework 45

Chapter 6 Understanding the BIRT Architecture 47

Understanding the BIRT integration 47

About the BIRT applications 51

About BIRT Report Designer and BIRT RCP Report Designer 51

About the BIRT report viewer 51

About the BIRT engines 52

About the report design engine 52

About the report engine 52

About the generation engine 52

About the presentation engine 52

About the chart engine 53

About the data engine 53

About the types of BIRT report items 53

About standard report items 54

About custom report items 54

About chart report items 54

About the ROM 54

About the types of BIRT files 54

About report design files 55

About report document files 55

About report library files 55

About report template files 55

About custom Java applications 56

About custom report designers 56

About custom Java report generators 56

About extensions to BIRT 57

Chapter 7 Understanding the Report Object Model 59

About the ROM specification 59

ROM properties 60

ROM slots 61

ROM methods 61

ROM styles 62

About the ROM schema 62

About the rom.def file 63

About the primary ROM elements 66

About the report item elements 67

About the report items 67

Understanding the report item element properties 67

About the data elements 68

Part III Scripting in a Report Design 71

Chapter 8 Using Scripting in a Report Design 73

Overview of BIRT scripting 73

Choosing between Java and JavaScript 73

Using both Java and JavaScript to write event handlers 74

Understanding the event handler execution sequence 74

About event firing sequence dependency 74

About the pageBreak event 75

Analysis of the execution sequence phases 75

About a report item event handler 81

About data source and data set event handlers 82

ODA data source events 82

Scripted data source events 82

ODA data set events 82

Scripted data set events 82

About ReportDesign event handlers 82

Writing event handlers for charts 83

Chart events 83

Chart script context 85

Chart instance object 86

Writing a Java chart event handler 87

Writing a JavaScript chart event handler 87

Getting a dynamic image from a Microsoft Access database 89

Chapter 9 Using JavaScript to Write an Event Handler 91

Using BIRT Report Designer to enter a JavaScript event handler 91

Creating and using a global variable 92

Understanding execution phases and processes 93

Using the reportContext object 94

Passing a variable between processes 95

Getting information from an HTTP request object 95

Using the this object 95

Using the this object's methods 95

Using the this object to set the property of a report item 96

Using the row object 99

Getting column information 99

Getting and altering the query string 100

Getting a parameter value 101

Changing the connection properties of a data source 101

Determining method execution sequence 102

Providing the ReportDesign.initialize code 102

Providing the code for the methods you want to track 103

Providing the ReportDesign.afterFactory code 103

Tutorial 1: Writing an event handler in JavaScript 104

Task 1: Open the report design 104

Task 2: Create and initialize a counter in the Table.onCreate( ) method 104

Task 3: Conditionally increment the counter in the Row.onCreate( ) method 106

Task 4: Display the result, using the ReportDesign.afterFactory( ) method 107

Calling Java from JavaScript 108

Understanding the Packages object 108

Understanding the importPackage method 109

Using a Java class 109

Placing your Java classes where BIRT can find them 110

Issues with using Java in JavaScript code 110

Chapter 10 Using Java to Write an Event Handler 111

Writing a Java event handler class 111

Locating the JAR files that an event handler requires 112

Extending an adapter class 112

Making the Java class visible to BIRT 116

Associating the Java event handler class with a report element 116

BIRT Java interface and class naming conventions 117

Writing a Java event handler 118

Using event handler adapter classes 118

Using event handler interfaces 118

About the Java event handlers for report items 119

Using Java event handlers for the DataSource element 120

Using Java event handlers for the DataSet element 120

Using Java event handlers for the ScriptedDataSource element 121

Using Java event handlers for the ScriptedDataSet element 122

Using Java event handlers for the ReportDesign 122

Understanding the BIRT interfaces 123

About the element design interfaces 124

About the element instance interfaces 125

Using the IReportContext interface 126

Using the IColumnMetaData interface 128

Using the IDataSetInstance interface 128

Using the IDataSetRow interface 129

Using the IRowData interface 129

Chapter 11 Using a Scripted Data Source 131

Creating a scripted data source and scripted data set 131

Tutorial 2: Creating and scripting a scripted data source 133

Task 1: Create a new report 133

Task 2: Create a scripted data source 133

Task 3: Create a scripted data set 134

Task 4: Supply code for the open() and close( ) methods of the data source 135

Task 5: Supply code for the open() method of the data set 135

Task 6: Define output columns 135

Task 7: Place the columns on the report layout 137

Task 8: Supply code for the data set fetch() method 138

Using a Java object to access a data source 139

Performing initialization in the data set open( ) method 139

Getting a new row of data in the data set fetch( ) method 140

Cleaning up in the data set close( ) method 140

Deciding where to locate your Java class 140

Deploying your Java class 141

Using input and output parameters with a scripted data set 141

Part IV Integrating BIRT Functionality into Applications 143

Chapter 12 Understanding the BIRT APIs 145

Package hierarchy diagrams 146

About the BIRT Report Engine API 147

Creating the BIRT Report Engine 148

Using the BIRT Report Engine API 148

Report engine class hierarchy 151

Report engine interface hierarchy 152

About the design engine API 153

Using the BIRT design engine API 154

Design engine class hierarchy 157

About the BIRT Chart Engine API 163

Using the BIRT Chart Engine API 164

Chart engine class hierarchy 164

Chapter 13 Programming with the BIRT Reporting APIs 181

Building a reporting application 182

About the environment for a reporting application 183

Modifying a report design with the API 185

Generating reports from an application 185

Setting up the report engine 186

Opening a source for report generation 190

Accessing a report parameter programmatically 192

Preparing to generate the report 199

Generating the formatted output programmatically 203

Accessing the formatted report 203

About programming with a report design 204

About BIRT model API capabilities 205

Opening a report design programmatically for editing 206

Accessing a data source and data set with the API 214

Saving a report design programmatically 217

Creating a report design programmatically 217

Chapter 14 Programming with the BIRT Charting APIs 219

About the environment for building a charting application 220

Verifying the development environment for charting applications 221

Using the charting API to modify an existing chart 222

Getting a Chart object from the report design 222

Adding a series to a chart 224

Adding a chart event handler to a charting application 224

Using the charting APIs to create a new chart 225

Creating the chart instance object 226

Setting the properties of the chart instance object 227

Creating sample data 231

Getting an element factory object 231

Getting an extended item handle object 231

Setting the chart.instance property on the report item 231

Getting a data set from the report design 232

Binding the chart to the data set 232

Adding the new chart to the report design 232

Saving the report design after adding the chart 232

Putting it all together 233

Using the BIRT charting API in a Java Swing application 239

Understanding the chart programming examples 246

Part V Working with the Extension Framework 251

Chapter 15 Building the BIRT Project 253

About building the BIRT project 253

Assuring that you have the correct software on your system 254

Configuring the Eclipse workspace to compile BIRT 254

Creating Eclipse projects 256

Specifying the repository locations 257

Checking out the BIRT source 259

Adding the extra JAR file 261

Building the web viewer 262

Chapter 16 Extending BIRT 267

Overview of the extension framework 267

Understanding the structure of a BIRT plug-in 268

Understanding an extension point schema definition file 268

Understanding a plug-in manifest file 271

Understanding a plug-in run-time class 272

Working with the Eclipse PDE 275

Understanding plug-in project properties 277

Understanding the Eclipse PDE Workbench 277

Creating the structure of a plug-in extension 279

Creating the plug-in extension content 283

Building a plug-in extension 287

Generating an Ant build script 290

Testing a plug-in extension 291

Deploying the extension plug-in 291

Installing feature updates and managing the Eclipse configuration 293

Creating an update site project 294

Downloading the code for the extension examples 297

Chapter 17 Developing a Report Item Extension 299

Understanding a report item extension 299

Developing the sample report item extension 301

Downloading BIRT source code from the CVS repository 302

Creating a rotated label report item plug-in project 302

Defining the dependencies for the rotated label report item extension 305

Specifying the run-time package for the rotated label report item extension 307

Declaring the report item extension points 307

Creating the plug-in extension content 312

Understanding the rotated label report item extension 316

Understanding RotatedLabelItemFactoryImpl 318

Understanding RotatedLabelUI 319

Understanding RotatedLabelPresentationImpl 319

Understanding RotatedLabelReportItemImpl 320

Understanding RotatedLabelPropertyEditUIImpl 320

Understanding GraphicsUtil 321

Deploying and testing the rotated label report item plug-in 324

Deploying a report item extension 324

Launching the rotated label report item plug-in 324

Chapter 18 Developing a Report Rendering Extension 329

Understanding a report rendering extension 329

Developing the CSV report rendering extension 330

Downloading BIRT source code from the CVS repository 330

Creating a CSV report rendering plug-in project 331

Defining the dependencies for the CSV report rendering extension 334

Declaring the emitters extension point 335

Understanding the sample CSV report rendering extension 337

Implementing the emitter interfaces 337

Implementing the content interfaces 339

Understanding the CSV report rendering extension package 341

Understanding CSVReportEmitter 341

Understanding CSVTags 348

Understanding CSVWriter 348

Understanding the BIRT report engine API package 348

Understanding RenderOptionBase 349

Understanding CSVRenderOption 349

Understanding EngineConstants 349

Testing the CSV report rendering plug-in 350

Launching the CSV report rendering plug-in 353

About ExecuteReport class 357

About the report design XML code 359

Chapter 19 Developing an ODA Extension 365

Understanding an ODA extension 366

Developing the CSV ODA driver extensions 366

About the CSV ODA plug-ins 367

Downloading BIRT source code from the CVS repository 367

Implementing the CSV ODA driver plug-in 368

Defining the dependencies for the CSV ODA driver extension 370

Specifying the run-time settings for the CSV ODA driver extension 370

Declaring the ODA data source extension point 371

Understanding the sample CSV ODA driver extension 379

Implementing the DTP ODA interfaces 379

Developing the CSV ODA UI extension 390

Creating the CSV ODA UI plug-in project 390

Defining the dependencies for the CSV ODA UI extension 392

Specifying the run-time settings for the CSV ODA UI extension 393

Declaring the ODA data source UI extension point 393

Understanding the sample CSV ODA UI extension 403

Implementing the ODA data source and data set wizards 404

Understanding the org.eclipse.birt.report.data.oda.csv.ui.wizards package 405

Testing the CSV ODA UI plug-in 414

Developing a Hibernate ODA extension 419

Creating the Hibernate ODA driver plug-in project 420

Understanding the sample Hibernate ODA driver extension 426

Building the Hibernate ODA driver plug-in 439

Developing the Hibernate ODA UI extension 441

Understanding the sample Hibernate ODA UI extension 448

Building the Hibernate ODA UI plug-in 458

Testing the Hibernate ODA UI plug-in 460

Glossary 465

Index 525


Download the Foreword from this book.


Download the Index from this book.



Download the Errata from this book.

Submit Errata

More Information

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information

To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.


Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.


If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information

Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.


This site is not directed to children under the age of 13.


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information

If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information

Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents

California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure

Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact

Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice

We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020