Preface
About this book
The second of a two-book series on business intelligence and reporting technology, Integrating and Extending BIRT, introduces programmers to BIRT architecture and the reporting framework. Its companion book, BIRT: A Field Guide, shows report developers how to create reports using the graphical tools of BIRT Report Designer. 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.
BIRT technology makes it possible for a programmer to build a customized report using scripting and BIRT APIs. This book informs report developers about how to write scripts that:
• Customize the report-generation process
• Incorporate complex business logic in reports
This book also informs application developers about how to:
• Debug and deploy reports
• Integrate reporting capabilities into other applications
• Extend BIRT functionality
A programmer can extend the BIRT framework by creating a new plug-in using the Eclipse Plug-in Development Environment (PDE). This book provides extensive examples that show how to build plug-ins to extend the features of the BIRT framework. The source code for these examples is available for download at http://www.actuate.com/birt/contributions.
The topics discussed in this book 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 BIRT 2.6 edition adds 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
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 and chapters.
Part 1, Installing and Deploying BIRT
Part 1 introduces the currently available BIRT reporting packages, the prerequisites for installation, and the steps to install and update the packages. Part 1 includes the following chapters:
• Chapter 1. Introducing BIRT Report Designers. 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 and update each of the available packages.
• Chapter 4. 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 about deploying a BIRT report to Apache Tomcat version 6.0. From those instructions, a developer can infer how to deploy to other versions.
Part 2, Understanding the BIRT Framework
Part 2 introduces the BIRT architecture and the Report Object Model (ROM) and provides background information that helps programmers design or modify reports programmatically, instead of using the graphical tools in BIRT Report Designer. Part 2 includes the following chapters:
• Chapter 5. 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 BIRT components.
• Chapter 6. Understanding the Report Object Model. This chapter provides an overview of the BIRT ROM. ROM is a specification for a set of XML elements that define both the visual and non-visual elements that comprise a report design. The ROM specification includes the properties and methods of those elements, and the relationships among the elements.
Part 3, Scripting in a Report Design
Part 3 describes how a report developer can customize and enhance a BIRT report by writing event handler scripts in either Java or JavaScript. Part 3 includes the following chapters:
• Chapter 7. 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 8. 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 9. 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 10. Working with Chart Event Handlers. This chapter describes the BIRT event handler model for the Chart Engine. The model is similar to the model for standard BIRT report elements and supports both the Java and JavaScript environments. This chapter provides details on both environments. The Chart Engine also supports this event model when used outside of BIRT.
• Chapter 11. Using Scripting to Access Data. This chapter describes how to access a data source using JavaScript code. A data source that you access using JavaScript is called a scripted data source. With a scripted data source, you can access objects other than an SQL, XML, or text file data source. A scripted data source can be an EJB, an XML stream, a Hibernate object, or any other Java object that retrieves data.
• Chapter 12. Debugging Event Handlers. This chapter describes how to use the BIRT report debugger to debug BIRT reports and event handlers written in JavaScript and Java. The BIRT report debugger enables users to run reports step by step, set breakpoints, inspect instance properties, and watch and evaluate variable values in certain contexts. The debugger supports advanced report developers in spotting the errors in report designs quickly, and makes it easy to understand and identify exceptions during run time. The chapter provides a tutorial with step-by-step instructions about debugging Java and JavaScript report event handlers.
Part 4, Integrating BIRT into Applications
Part 4 describes the public APIs that are available to Java developers, except the extension APIs. Part 4 includes the following chapters:
• Chapter 13. 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 14. Programming Using 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 package supports the process of generating a report from a report design. The org.eclipse.birt.report.model.api package supports creating new report designs and modifying existing report designs.
• Chapter 15. Programming Using the BIRT Charting API. 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. This chapter also describes the chart programming examples in the chart examples plug-in.
Part 5, Working with the Extension Framework
Part 5 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 5 includes the following chapters:
• Chapter 16. Building the BIRT Project. This chapter explains how to download BIRT 2.6 source code and build the BIRT project for development. This chapter describes how to configure an Eclipse workspace, download BIRT source code, and build the BIRT report and web viewers.
• Chapter 17. 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 18. 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 19. Developing a Report Rendering Extension. This chapter describes how to develop a report rendering extension using the Eclipse PDE with sample CSV and XML report rendering extensions as the examples. The 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 20. 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 SQL-transparent 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.6.0 user interface that allows a report designer to select an extended ODA driver.
• Chapter 21. Developing a Data Extraction Extension. This chapter describes how to develop a report data extraction extension using the Eclipse PDE. The data extraction example exports report data to XML format. The Eclipse PDE provides the basis for the extension.
• Chapter 22. Developing a Fragment. This chapter describes how to build a fragment. The BIRT Report Engine environment supports plug-in fragments. A plug-in fragment is a separately loaded package that adds functionality to an existing plug-in, such as a specific language feature in a National Language Support (NLS) localization application. The example in this chapter creates a Java resource bundle that adds translations to the messages defined in the messages.properties files for the org.eclipse.birt.report.viewer plug-in.
• Chapter 23. Developing a Charting Extension. This chapter discusses the process of adding a new chart type to the BIRT chart engine. BIRT provides a radar chart type with the chart engine as an example of how to build new chart types. This chapter describes how to create this radar chart example.
The Glossary contains a glossary of terms that are useful to understanding all parts of the book.
Typographical conventions
Table P-1 describes the typographical conventions that are used in this book.
Table P-1 Typographical conventions
Syntax conventions
Table 3-1 describes the symbols that are used to present syntax.
