Integrating and Extending BIRT

by Jason Weathersby, Tom Bondur, Iana Chatalbasheva

Overview

<>The world-wide developer community has downloaded over ten million copies of BIRT (Business Intelligence and Reporting Tools). Built on the open-source Eclipse platform, BIRT is a powerful reporting system that provides an end-to-end solution from creating and deploying reports to integrating report capabilities in enterprise applications.

Integrating and Extending BIRT, Third Edition, introduces programmers to BIRT architecture and the reporting framework. BIRT technology makes it possible for programmers to build customized reports using scripting and BIRT APIs. This book also includes extensive examples of how to use the Eclipse Plug-in Development Environment to build plug-ins to extend the features of the BIRT framework. The source code for these examples is available for download at www.eclipse.org/birt.

Key topics covered 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 into applications
• Working with the BIRT extension framework

This revised and expanded third edition features the following new content

• Updated architectural diagrams
• Expanded scripting examples
• Debugging event handlers
• Developing an advanced report item with data binding
• Developing a data extraction extension
• Developing a charting extension
  

Readers may also be interested in this book’s companion volume. BIRT: A Field Guide, Third Edition, is the authoritative guide to using BIRT Report Designer, the graphical tool that enables users of all levels to build reports, from simple to complex, without programming.

Product Details

ISBN-13:	9780132732529
Publisher:	Pearson Education
Publication date:	08/11/2011
Series:	Eclipse Series
Sold by:	Barnes & Noble
Format:	eBook
Pages:	880
File size:	26 MB
Note:	This product may take a few minutes to download.
Age Range:	18 Years

About the Author

The authors are members of the extended BIRT development team and have backgrounds in both computer science and technical writing. Collectively, they have 165 years of technical consulting, training, writing and publishing experience related to reporting, business intelligence tools, and database technologies. They have published forty-two titles on these topics through numerous editions.

The authors are members of the extended BIRT development team and have backgrounds in both computer science and technical writing. Collectively, they have 165 years of technical consulting, training, writing and publishing experience related to reporting, business intelligence tools, and database technologies. They have published forty-two titles on these topics through numerous editions.

The authors are members of the extended BIRT development team and have backgrounds in both computer science and technical writing. Collectively, they have 165 years of technical consulting, training, writing and publishing experience related to reporting, business intelligence tools, and database technologies. They have published forty-two titles on these topics through numerous editions.

The authors are members of the extended BIRT development team and have backgrounds in both computer science and technical writing. Collectively, they have 165 years of technical consulting, training, writing and publishing experience related to reporting, business intelligence tools, and database technologies. They have published forty-two titles on these topics through numerous editions.

The authors are members of the extended BIRT development team and have backgrounds in both computer science and technical writing. Collectively, they have 165 years of technical consulting, training, writing and publishing experience related to reporting, business intelligence tools, and database technologies. They have published forty-two titles on these topics through numerous editions.

Read an Excerpt

About this book

BIRT is a powerful reporting platform that provides end-to-end reporting solutions, from creating and deploying reports to integrating report capabilities into other enterprise applications. Two companion books, BIRT: A Field Guide to Reporting and Integrating and Extending BIRT, cover the breadth and depth of BIRT's functionality.

This book informs report developers about how to write scripts that:

• Customize the report-generation process

• Incorporate complex business logic in their reports

This book also informs application developers about how to:

• Deploy reports

• Integrate reporting capabilities into other applications

• Extend BIRT functionality

By its very nature, reporting is not a stand-alone technology. It draws on data generated by applications and is frequently integrated tightly within those applications. In some applications, such as performance monitoring, reporting provides the most tangible expression of value. Therefore, a successful reporting platform must emphasize interoperability and extensibility, and, a successful implementation of that platform must always involve some measure of integration and extension.

As you read this book, you will see the significant investment that has been made in BIRT to provide support for interoperability and extensibility. In the area of interoperability, for instance, BIRT supports flexible deployment of its report engine and viewer to a wide variety of J2EE application server environments. Other provisions for interoperability in the BIRT platform include the ability to dynamically build or modify reports from within an application using the design engine application programming interface (API) and the ability to access native data objects using the scripted data source mechanism.

In the area of extensibility, BIRT provides hooks to build upon platform capabilities in the following areas:

• Report Items. New controls may be added to the BIRT designer palette using the report item extension API.

• Complex Logic. Event handlers written in JavaScript or Java may be included in the generation or presentation phase of report or chart execution to incorporate custom logic required by the application.

• Data Access. The Open Data Access (ODA) extension provides the means to develop drivers for new, non-JDBC data sources as well as create graphical user interfaces for query specification.

• Rendering. New report output formats or output for specialized devices can be developed using the report rendering extension API.

Who should read this book

This book is intended for people who have a programming background. These readers can be categorized as:

• Embedders and integrators. These individuals work with the software to integrate it into their current application infrastructure.

• Extenders. These individuals leverage APIs and other extension points to add capability or to establish new interoperability between currently disparate components or services.

To write scripts in report design, you need knowledge of JavaScript or Java. More advanced tasks, such as extending BIRT's functionality, require Java development experience and familiarity with the Eclipse platform.

Contents of this book

This book is divided into several parts. The following sections describe the contents of each of the parts.

Installing and Deploying BIRT

Part I, "Installing and Deploying BIRT," introduces the currently available BIRT reporting packages, the prerequisites for installation, and the steps to install and update the packages. Part I includes the following chapters:

Chapter 1, "Prerequisites for BIRT." BIRT provides a number of separate packages as downloadable archive (.zip) files on the Eclipse web site. Some of the packages are stand-alone modules, others require an existing Eclipse environment, and still others provide additional functionality to report developers and application developers. This chapter describes the prerequisites for each of the available packages.

Chapter 2, "Installing a BIRT Report Designer." BIRT provides two report designers as separate packages, which are downloadable archive (.zip) files on the Eclipse web site. This chapter describes the steps required to install each of the available report designers.

Chapter 3, "Installing Other BIRT Packages." This chapter describes the steps required to install each of the available packages.

Chapter 4, "Updating BIRT." BIRT packages are Eclipse-based, so it is easy to update any of them from earlier releases to release 2.0 or later. This chapter describes how you can install the latest packages without interrupting your work.

Chapter 5, "Deploying a BIRT Report to an Application Server." This chapter introduces the distribution of reports through an application server such as Apache Tomcat, IBM WebSphere, or BEA WebLogic. The instructions in the chapter provide detailed guidance into deploying a BIRT report to Apache Tomcat version 5.5.7. From those instructions, a developer can infer how to deploy to other versions.

Understanding the BIRT Framework

Part II, "Understanding the BIRT Framework," introduces the BIRT architecture and the Report Object Model (ROM) and provides background information that will help programmers design or modify reports programmatically, instead of using the graphical tools in BIRT Report Designer. Part II includes the following chapters:

Chapter 6, "Understanding the BIRT Architecture." This chapter provides an architectural overview of BIRT and its components, including the relationships among the BIRT components and BIRT's relationship to Eclipse and Eclipse frameworks. Architectural diagrams illustrate and clarify the relationships and workflow of the components. The chapter also provides brief overviews of all the major BIRTcomponents.

Chapter 7, "Understanding the Report Object Model." This chapter provides an overview of the BIRT ROM. ROM is a specification for a set of

Scripting in a Report Design

Part III, "Scripting in a Report Design," describes how a report developer can customize and enhance a BIRT report by writing event handler scripts in either Java or JavaScript. Part III includes the following chapters:

Chapter 8, "Using Scripting in a Report Design." This chapter introduces the writing of a BIRT event handler script in either Java or JavaScript, including the advantages and disadvantages of using one language over the other. BIRT event handlers are associated with data sets, data sources, and report items. BIRT fires specific events at specific times in the processing of a report. This chapter identifies the events that BIRT fires and describes the event firing sequence.

Chapter 9, "Using JavaScript to Write an Event Handler." This chapter discusses the coding environment and coding considerations for writing a BIRT event handler in JavaScript. This chapter describes several BIRT JavaScript objects that a developer can use to get and set properties that affect the final report. The BIRT JavaScript coding environment offers a pop-up list of properties and functions available in an event handler. A JavaScript event handler can also use Java classes. This chapter includes a tutorial that describes the process of creating a JavaScript event handler.

Chapter 10, "Using Java to Write an Event Handler." This chapter discusses how to write a BIRT event handler in Java. BIRT provides Java adapter classes that assist the developer in the creation of Java event handlers. The report developer uses the property editor of the BIRT Report Designer to associate a Java event handler class with the appropriate report element. This chapter contains a tutorial that steps through the Java event handler development and deployment process. This chapter also describes the event handler methods and their parameters.

Chapter 11, "Using a Scripted Data Source." BIRT supports getting data from any data source that can be processed with Java or JavaScript. To use a scripted data source in a BIRT report, the report developer implements an open and a close method for the data source and an open, a fetch, and a close method for the data set. A scripted data source can be an EJB, an

Integrating BIRT Functionality into Applications

Part IV, "Integrating BIRT Functionality into Applications," describes the public APIs that are available to Java developers, except the extension APIs.Chapter 12. Understanding the BIRT APIs. This chapter introduces BIRT's public API, which are the classes and interfaces in three package hierarchies:

• The report engine API, in the org.eclipse.birt.report.engine.api hierarchy, supports developers of custom report generators.

• The design engine API, in the org.eclipse.birt.report.engine.api hierarchy, supports the development of custom report designs.

• The chart engine API, in the org.eclipse.birt.chart hierarchy, is used to develop a custom chart generator.

Chapter 13, "Programming with the BIRT Reporting APIs." This chapter describes the fundamental requirements of a reporting application and lists the BIRT API classes and interfaces that are used to create a reporting application. This chapter describes the tasks that are required of a reporting application and provides an overview of how to build a reporting application. The org.eclipse.birt.report.engine.api and org.eclipse.birt.report.model.api packages support the process of generating a report from a report design.

Chapter 14, "Programming with the BIRT Charting APIs." This chapter describes the requirements of a charting application, either in a stand-alone environment or as part of a reporting application. The org.eclipse.birt.chart hierarchy of packages provides the charting functionality in BIRT. By describing the fundamental tasks required of charting applications, this chapter introduces the API classes and interfaces that are used to create a chart.

Working with the Extension Framework

Part V, "Working with the Extension Framework," shows Java programmers how to add new functionality to the BIRT framework. By building on the Eclipse platform, BIRT provides an extension mechanism that is familiar to developers of Eclipse plug-ins. This part also provides information about how to build the BIRT project for developers who need access to the complete BIRT open source code base. Part V includes the following chapters:

Chapter 15, "Building the BIRT Project." This chapter explains how to download BIRT 2.0.1 source code and build the BIRT project for development. This chapter describes how to configure an Eclipse workspace, download BIRT and Data Tools Platform (DTP) source code from the Eclipse Concurrent Versions System (CVS) repository, and build the BIRT report and web viewers.

Chapter 16, "Extending BIRT." This chapter provides an overview of the BIRT extension framework and describes how to use the Eclipse Plug-in Development Environment (PDE) and the BIRT extension points to create, build, and deploy a BIRT extension.

Chapter 17, "Developing a Report Item Extension." This chapter describes how to develop a report item extension. The rotated text extension example is a plug-in that renders the text of a report item as an image. The extension rotates the image in the report design to display the text at a specified angle. This chapter describes how to build the rotated text report item plug-in and add the report item to the BIRT Report Designer using the defined extension points.

Chapter 18, "Developing a Report Rendering Extension." This chapter describes how to develop a report rendering extension. The Comma-Separated Values (CSV) extension example is a plug-in that writes the table data in a report to a file in CSV format. This chapter describes how to extend the emitter interfaces using the defined extension points to build and deploy a customized report rendering plug-in that runs in the BIRT Report Engine environment.

Chapter 19, "Developing an ODA Extension." This chapter describes how to develop several types of DTP ODA extensions. The CSV ODA driver example is a plug-in that reads data from a CSV file. The Hibernate ODA driver example uses Hibernate Query Language (HQL) to provide a SQLtransparent extension that makes the ODA extension portable to all relational databases. This chapter shows how to develop an ODA extension to the BIRT Report Designer 2.0.1 user interface that allows a report designer to select an extended ODA driver. This chapter also describes how to implement an extension to an ODA JDBC driver to use a supplied connection.

The glossary contains terms that are useful to understanding all parts of the book.

Table of Contents

Foreword        xix

Preface          xxi

Acknowledgments          xxix

 

Part 1: Installing and Deploying BIRT         1

Chapter 1: Introducing BIRT Report Designers         3

Understanding BIRT components     3

Understanding Eclipse BIRT packages     4

About types of BIRT builds     5

 

Chapter 2: Installing a BIRT Report Designer         7

Installing BIRT Report Designer Full Eclipse Install     7

Installing BIRT RCP Report Designer     8

Troubleshooting installation problems     9

Installing a language pack     10

Updating a BIRT Report Designer installation     11

Updating BIRT RCP Report Designer installation    12

 

Chapter 3: Installing Other BIRT Packages          15

Installing Chart Engine     15

Installing BIRT Data Tools Platform Integration     17

Installing BIRT Demo Database     17

Installing Report Engine   19

Installing BIRT Samples   21

Installing BIRT Source Code    21

Installing BIRT Web Tools Integration     22

 

Chapter 4: Deploying a BIRT Report to an Application Server          25

About application servers      25

Placing the BIRT report viewer on an application server     26

Placing fonts on the application server     31

Viewing a report using a browser     31

Using connection pooling on Tomcat     32

 

Part 2: Understanding the BIRT Framework          37

Chapter 5: Understanding the BIRT Architecture         39

Understanding the BIRT integration      39

About the BIRT applications     43

About the types of BIRT report items     46

About the Report Object Model (ROM)      47

About the types of BIRT files      47

About custom Java applications     49

About extensions to BIRT     50

 

Chapter 6: Understanding the Report Object Model       51

About the ROM specification    51

About the ROM schema    53

About the rom.def file     53

Understanding ROM elements     58

 

Part 3: Scripting in a Report Design          61

Chapter 7: Using Scripting in a Report Design         63

Overview of BIRT scripting     63

Events overview     64

Event order sequence     71

 

Chapter 8: Using JavaScript to Write an Event Handler         83

Using BIRT Report Designer to enter a JavaScript event handler     83

Using the reportContext object     86

Using the this object     93

Using the row object     96

Getting column information     97

Getting and altering the query string     98

Changing data source connection properties     99

Getting a parameter value     100

Determining script execution sequence     101

Tutorial 1: Writing an event handler in JavaScript     103

JavaScript event handler examples     107

Calling external JavaScript functions    111

Calling Java from JavaScript     112

Calling the method of a class in a plug-in     114

 

Chapter 9: Using Java to Write an Event Handler        117

Writing a Java event handler class     117

Writing a Java event handler    123

Understanding the BIRT interfaces    128

Java event handler example    135

Debugging a Java event handler    142

 

Chapter 10: Working with Chart Event Handlers    143

Chart events overview    143

Understanding the Chart script context    145

Understanding when chart events fire    150

Writing a Java chart event handler     164

Writing a JavaScript chart event handler     167

Using the simplified charting API     169

 

Chapter 11: Using Scripting to Access Data         173

Using a Scripted Data Source     173

Tutorial 2: Creating a scripted data source     175

Creating a web services data source using a custom connection class     184

 

Chapter 12: Debugging Event Handlers          187

Checking the syntax of JavaScript expressions     188

Debugging JavaScript event handlers code     190

Debugging Java event handler code     194

Debugging report execution exceptions    194

Creating a debug configuration     196

Tutorial 3: Debugging a report that contains Java and JavaScript code     198

 

Part 4: Integrating BIRT into Applications           215

Chapter 13: Understanding the BIRT APIs          217

Package hierarchy diagrams      218

About the BIRT Report Engine API      219

About the Design Engine API   226

About the BIRT Chart Engine API         239

 

Chapter 14: Programming Using the BIRT Reporting APIs            257

Building a reporting application    258

Generating reports from an application    262

Programming the structure of a report design   289

 

Chapter 15: Programming Using the BIRT Charting API          307

About the chart engine contents    307

About the environment for a charting application    308

About the charting API and the chart structure    310

Using the charting API to create a new chart    312

Modifying chart properties    312

Using a chart item in a report design     321

Using the BIRT charting API in a Java Swing application    334

Understanding the chart programming examples     340

 

Part 5: Working with the Extension Framework          347

Chapter 16: Building the BIRT Project         349

About building the BIRT project     349

Installing a working version of BIRT     350

Configuring Eclipse to compile BIRT and build the viewer JAR files     350

Downloading and extracting the correct version of the BIRT source code     353

Importing, building, and testing the BIRT project     354

Building new JAR files to display BIRT output     356

 

Chapter 17: Extending BIRT         359

Overview of the extension framework     359

Understanding the structure of a BIRT plug-in     359

Working with the Eclipse PDE     366

Creating the structure of a plug-in extension    370

Creating the plug-in extension content    373

Building a plug-in extension    377

Deploying the extension plug-in   381

Downloading the code for the extension examples    384

 

Chapter 18: Developing a Report Item Extension           387

Understanding a report item extension    387

Developing the sample report item extension    389

Understanding the rotated label report item extension     404

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

Developing an advanced report item    416

 

Chapter 19: Developing a Report Rendering Extension          465

Understanding a report rendering extension     465

Developing a CSV report rendering extension     466

Developing an XML report rendering extension     494

 

Chapter 20: Developing an ODA Extension           509

Understanding an ODA extension     510

Developing the CSV ODA driver extensions    511

Implementing the CSV ODA driver plug-in    513

Understanding the sample CSV ODA driver extension    522

Developing the CSV ODA user interface extension    530

Understanding the sample CSV ODA user interface extension    537

Testing the CSV ODA user interface plug-in    548

Developing a Hibernate ODA extension    554

 

Chapter 21: Developing a Data Extraction Extension          601

Understanding a data extraction extension    601

Developing an XML data extraction extension    602

 

Chapter 22: Developing a Fragment          635

Understanding a fragment     635

Developing the sample fragment     636

Creating a fragment project     637

Understanding the sample fragment     640

Building, deploying, and testing a fragment     641

 

Chapter 23: Developing a Charting Extension             647

About BIRT charting extension points   648

Setting up the build environment    650

Extending the chart model      652

 

Glossary             707

Index            779