You are previewing Integrating and Extending BIRT.
O'Reilly logo
Integrating and Extending BIRT

Book Description

The world-wide developer community has downloaded over three million copies of BIRT (Business Intelligence and Reporting Tools) from the Eclipse web site. 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.

The second of a two-book series on business intelligence and reporting technology, Integrating and Extending BIRT, Second Edition introduces programmers to BIRT architecture and the reporting framework. BIRT technology makes it possible for a programmer to build a customized report using scripting and BIRT APIs. A programmer can also extend the BIRT framework by creating a new plug-in using the Eclipse Plug-in Development Environment. This book provides extensive examples on how to build plug-ins to extend the features of the BIRT framework. The source code for these examples is available for download.

The 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 into applications

  • Working with the BIRT extension framework


  • This second edition, revised and expanded, adds the following new content

  • Updated architectural diagrams

  • Expanded scripting examples

  • Tag library descriptions

  • In-depth description of BIRT Web Viewer

  • Configuring BIRT to use a JNDI connection

  • XML report rendering plug-in example

  • Fragment plug-in localization example

  • Open Data Access (ODA) plug-in example implementing the new Data Tools Platform (DTP) design and run-time wizards

  • Table of Contents

    1. Copyright
    2. The Eclipse Series
      1. Series Editors
        1. Titles in the Eclipse Series
    3. Foreword
    4. Preface
      1. About this book
      2. Who should read this book
      3. Contents of this book
        1. Part I, Installing and Deploying BIRT
        2. Part II, Understanding the BIRT Framework
        3. Part III, Scripting in a Report Design
        4. Part IV, Integrating BIRT Functionality into Applications
        5. Part V, Working with the Extension Framework
      4. Typographical conventions
      5. Syntax conventions
    5. Acknowledgments
    6. I. Installing and Deploying BIRT
      1. 1. Prerequisites for BIRT
        1. Downloading Eclipse BIRT components
        2. BIRT Report Designer software requirements
        3. About types of BIRT builds
      2. 2. Installing a BIRT Report Designer
        1. Installing BIRT Report Designer Full Eclipse Install
        2. Installing BIRT RCP Report Designer
        3. Troubleshooting installation problems
          1. Avoiding cache conflicts after you install a BIRT report designer
          2. Specifying a Java Virtual Machine when starting BIRT report designer
        4. Installing a language pack
        5. Updating a BIRT Report Designer installation
        6. Updating BIRT RCP Report Designer installation
      3. 3. Installing Other BIRT Packages
        1. Installing Chart Engine
        2. Installing BIRT Data Tools Platform Integration
        3. Installing BIRT Demo Database
        4. Installing Report Engine
        5. Installing BIRT Samples
        6. Installing BIRT Source Code
        7. Installing BIRT Web Tools Integration
      4. 4. Deploying a BIRT Report to an Application Server
        1. About application servers
          1. About deploying to Tomcat
          2. About deploying to other application servers
        2. Placing the BIRT report viewer on an application server
          1. Installing the BIRT report viewer as a web application
          2. Testing the BIRT report viewer installation
          3. Using a different context root for the BIRT report viewer
          4. Placing the BIRT report viewer in a different location
          5. Understanding the BIRT report viewer context parameters
          6. Verifying that Apache Tomcat is running BIRT report viewer
        3. Placing fonts on the application server
        4. Viewing a report using a browser
        5. Using connection pooling on Tomcat
          1. Setting up a report to use connection pooling
          2. Using a jndi.properties file
          3. Configuring a JNDI connection object on Tomcat
      5. 5. Using Eclipse BIRT Web Viewer
        1. Understanding Eclipse BIRT Web Viewer
        2. Understanding Web Viewer architecture
          1. Web Viewer servlets
          2. Web Viewer URL parameters
          3. Web Viewer fragments
          4. Web Viewer web.xml settings
          5. Web Viewer directory structure
          6. Web Viewer AJAX operation
        3. Using the Web Viewer Deployment wizard
          1. Web Viewer tag library
          2. Web Viewer RCP deployment
          3. Passing a web context object to the Web Viewer
          4. Building the Web Viewer
    7. II. Understanding the BIRT Framework
      1. 6. Understanding the BIRT Architecture
        1. Understanding the BIRT integration
        2. About the BIRT applications
          1. About BIRT Report Designer and BIRT RCP Report Designer
          2. About the BIRT Viewer
        3. About the BIRT engines and services
          1. About the report design engine
          2. About the report engine
          3. About the generation services
          4. About the presentation services
          5. About the chart engine
          6. About the data services
            1. About data services components
            2. About the ODA framework
        4. About the types of BIRT report items
          1. About standard report items
          2. About custom report items
          3. About chart report items
        5. About the Report Object Model (ROM)
        6. About the types of BIRT files
          1. About report design files
          2. About report document files
          3. About report library files
          4. About report template files
        7. About custom Java applications
          1. About custom report designers
          2. About custom Java report generators
        8. About extensions to BIRT
      2. 7. Understanding the Report Object Model
        1. About the ROM specification
          1. ROM properties
          2. ROM slots
          3. ROM methods
          4. ROM styles
        2. About the ROM schema
        3. About the rom.def file
        4. About the primary ROM elements
        5. About the report item elements
          1. About the report items
          2. Understanding the report item element properties
        6. About the data elements
    8. III. Scripting in a Report Design
      1. 8. Using Scripting in a Report Design
        1. Overview of BIRT scripting
          1. Choosing between JavaScript and Java
          2. Using both JavaScript and Java to write event handlers
        2. Events overview
          1. Engine task processes
            1. BIRT Web Viewer
            2. BIRT Report Designer
          2. BIRT processing phases
          3. BIRT event types
            1. Parameter events
            2. Report design events
            3. Data source and data set events
              1. Non-scripted data source events
              2. Scripted data source events
              3. Non-scripted data set events
              4. Scripted data set events
            4. ReportItem Events
        3. Event order sequence
          1. Preparation phase operation
          2. Generation phase operation
            1. About data source and data set events
            2. About data binding
            3. About the page break event
            4. About chart event order
            5. About table and list event order
              1. Row execution sequence
              2. Table and list method execution sequence
              3. Table and list setup step
              4. Table and list processing step
              5. Table and list wrap-up step
            6. Completion of the generation phase
          3. Presentation phase operation
          4. Event order summary
      2. 9. Using JavaScript to Write an Event Handler
        1. Using BIRT Report Designer to enter a JavaScript event handler
          1. Creating and using a global variable
          2. Understanding execution phases and processes
        2. Using the reportContext object
          1. Using getOutputFormat
          2. Using reportContext to retrieve the report design handle
          3. Passing a variable between processes
          4. Using getAppContext
          5. Getting information from an HTTP request object
        3. Using the this object
          1. Using this object methods
          2. Using the this object to set the property of a report item
        4. Using the row object
        5. Getting column information
        6. Getting and altering the query string
        7. Changing the connection properties of a data source
        8. Getting a parameter value
        9. Determining method execution sequence
          1. Providing the ReportDesign.initialize code
          2. Providing code for the methods you want to track
          3. Providing the ReportDesign.afterFactory code
        10. Tutorial 1: Writing an event handler in JavaScript
          1. Task 1: Open the report design
          2. Task 2: Create and initialize a counter in the Table.onCreate( ) method
          3. Task 3: Conditionally increment the counter in the Row.onCreate( ) method
          4. Task 4: Display the result using the ReportDesign.afterFactory( ) method
        11. JavaScript event handler examples
          1. JavaScript onPrepare examples
          2. JavaScript onCreate examples
          3. JavaScript onRender examples
        12. Calling Java from JavaScript
          1. Understanding the Packages object
          2. Understanding the importPackage method
          3. Using a Java class
          4. Placing Java classes
          5. Issues with using Java in JavaScript code
        13. Calling the method of a class that resides in a plug-in
      3. 10. Using Java to Write an Event Handler
        1. Writing a Java event handler class
          1. Locating the JAR files that an event handler requires
          2. Extending an adapter class
          3. Making the Java class visible to BIRT
          4. Associating the Java event handler class with a report element
          5. BIRT Java interface and class naming conventions
        2. Writing a Java event handler
          1. Using event handler adapter classes
          2. Using event handler interfaces
          3. About the Java event handlers for report items
          4. Using Java event handlers for the DataSource element
          5. Using Java event handlers for the DataSet element
          6. Using Java event handlers for the ScriptedDataSource element
          7. Using Java event handlers for the ScriptedDataSet element
          8. Using Java event handlers for the ReportDesign
        3. Understanding the BIRT interfaces
          1. About the element design interfaces
            1. About the methods for each report element
            2. About the IReportElement interface
          2. About the element instance interfaces
          3. Using the IReportContext interface
          4. Using the IColumnMetaData interface
          5. Using the IDataSetInstance interface
          6. Using the IDataSetRow interface
          7. Using the IRowData interface
        4. Java event handler example
          1. Report level events
          2. Report item events
        5. Debugging a Java event handler
      4. 11. Working with Chart Event Handlers
        1. Chart events overview
        2. Understanding when chart events trigger
          1. Prepare phase
          2. Data binding phase
            1. Static data
            2. Dynamic data
            3. Binding phase script events
          3. Building phase
          4. Rendering phase
            1. Rendering phase script events
            2. Rendering blocks
            3. Rendering data points
            4. Rendering legend items
            5. Rendering axes
          5. Chart script context
          6. Chart instance object
            1. Chart instance getter methods
            2. Chart instance setter methods
            3. Miscellaneous chart instance methods
        3. Writing a Java chart event handler
          1. Setting up the chart event handler project
          2. Chart Java event handler examples
        4. Writing a JavaScript chart event handler
        5. Using the simplified charting API
          1. Getting an instance of a chart item
          2. Understanding the sub-interfaces of IChart
      5. 12. Accessing Data Programmatically
        1. Using a Scripted Data Source
        2. Tutorial 2: Creating and scripting a scripted data source
          1. Task 1: Create a new report design
          2. Task 2: Create a scripted data source
          3. Task 3: Create a scripted data set
          4. Task 4: Supply code for the open( ) and close( ) methods of the data source
          5. Task 5: Supply code for the open( ) method of the data set
          6. Task 6: Define output columns
          7. Task 7: Place the columns on the report layout
          8. Task 8: Supply code for the fetch( ) method of the data set
          9. Writing the scripted data set in Java
          10. Using a Java object to access a data source
            1. Performing initialization in the data set open( ) method
            2. Getting a new row of data in the data set fetch( ) method
            3. Cleaning up in the data set close( ) method
            4. Deciding where to locate your Java class
            5. Deploying your Java class
          11. Using input and output parameters with a scripted data set
        3. Creating a web services data source using a custom connection class
          1. The Connection Class
          2. The connection Instance
          3. The executeQuery( ) Method
          4. The disconnect( ) method
          5. Method calling and error handling
          6. Custom connection class example
    9. IV. Integrating BIRT Functionality into Applications
      1. 13. Understanding the BIRT APIs
        1. Package hierarchy diagrams
        2. About the BIRT Report Engine API
          1. Creating the BIRT ReportEngine instance
          2. Using the BIRT Report Engine API
            1. EngineConfig class
            2. ReportEngine class
            3. IReportRunnable interface
            4. IReportDocument interface
            5. IEngineTask interface
            6. IGetParameterDefinitionTask interface
            7. IDataExtractionTask interface
            8. IRunTask interface
            9. IRenderTask interface
            10. IRunAndRenderTask interface
          3. Report engine class hierarchy
          4. Report engine interface hierarchy
        3. About the Design Engine API
          1. Using the BIRT Design Engine API
            1. DesignConfig class
            2. DesignEngine class
            3. SessionHandle class
            4. ModuleHandle class
            5. ReportDesignHandle class
            6. LibraryHandle class
            7. DesignElementHandle class
            8. Individual element handle classes
          2. Design engine class hierarchy
            1. DesignElementHandle hierarchy
            2. ReportElementHandle hierarchy
            3. ReportItemHandle hierarchy
            4. ElementDetailHandle hierarchy
            5. StructureHandle hierarchy
          3. Design engine interface hierarchy
        4. About the BIRT Chart Engine API
          1. Using the BIRT Chart Engine API
          2. Chart engine class hierarchy
            1. chart.aggregate class and interface hierarchy
            2. chart.datafeed class and interface hierarchy
            3. chart.device class and interface hierarchy
            4. chart.event class and interface hierarchy
            5. chart.exception class hierarchy
            6. chart.factory class and interface hierarchy
            7. chart.log class and interface hierarchy
            8. chart.model interface hierarchy
            9. chart.model.attribute class and interface hierarchy
            10. chart.model.component interface hierarchy
            11. chart.model.data interface hierarchy
            12. chart.model.layout interface hierarchy
            13. chart.model.type interface hierarchy
            14. chart.render class and interface hierarchy
            15. chart.script class and interface hierarchy
            16. chart.util class hierarchy
      2. 14. Programming using the BIRT Reporting APIs
        1. Building a reporting application
          1. Creating and configuring a report engine
          2. Opening a report design or report document
          3. Ensuring access to the data source
          4. Preparing to create a report in the supported output formats
          5. Generating a report in one of the supported output formats
          6. Destroying the engine
          7. Optional tasks
          8. About the environment for a reporting application
            1. About plug-ins used by the report engine
            2. About libraries used by the report engine
            3. About required JDBC drivers
          9. Modifying a report design with the API
        2. Generating reports from an application
          1. Setting up the report engine
            1. Configuring the BIRT home
            2. Configuring the report engine
            3. Setting up a stand-alone or WAR file environment
              1. Setting up the platform context
              2. Setting up the HTML emitter
            4. Starting the platform
            5. Creating the report engine
            6. Using the logging environment to debug an application
          2. Opening a source for report generation
            1. Understanding an IReportRunnable object
            2. Understanding an IReportDocument object
          3. Accessing a report parameter programmatically
            1. Creating a parameter definition task object for the report design
            2. Testing whether a report design has report parameters
            3. Getting the report parameters in a report design
            4. Getting the default value of each report parameter
            5. Getting valid values for parameters using a restricted set of values
            6. Getting the attributes of each report parameter
            7. Collecting an updated value for each report parameter
            8. Getting the values for cascading parameters
          4. Preparing to generate the report
            1. Setting the parameter values for running a report design
            2. Adding to the report engine’s class path
            3. Providing an external object to a report design
            4. Setting up the rendering options
              1. Setting up HTML rendering options
              2. Setting up the PDF rendering options
          5. Generating the formatted output programmatically
          6. Accessing the formatted report
          7. Cancelling a running report task
        3. Programming with a report design
          1. About BIRT model API capabilities
          2. Opening a report design programmatically for editing
            1. Configuring the design engine to access a design handle
            2. Using an IReportRunnable object to access a design handle
          3. Using a report item in a report design
            1. Accessing a report item by name
            2. Accessing a report item by iterating through a slot
            3. Examining a report item programmatically
            4. Accessing the properties of a report item
            5. Modifying a report item in a report design programmatically
            6. Accessing and setting complex properties
              1. Using a property handle
              2. Using styles on a report item
            7. Understanding property structure objects
              1. Using an existing property structure object
              2. Creating a property structure object
            8. Adding a report item to a report design programmatically
          4. Accessing a data source and data set with the API
            1. About data source classes
            2. About data set classes
            3. Using a data set programmatically
              1. Changing the properties of a data set
              2. Changing the data set binding of a report item
          5. Saving a report design programmatically
          6. Creating a report design programmatically
      3. 15. Programming using the BIRT Charting API
        1. About the chart engine contents
        2. About the environment for charting application
          1. Configuring the chart engine run-time environment
          2. Verifying the environment for charting applications
        3. Using the charting API to modify an existing chart
          1. Getting a Chart object from the report design
          2. Modifying chart properties
            1. Modifying plot properties
            2. Modifying the legend properties
            3. Modifying the series properties
            4. Modifying axes properties
          3. Adding a series to a chart
          4. Adding a chart event handler to a charting application
            1. Adding a Java chart event handler to a charting application
            2. Adding a JavaScript chart event handler to a charting application
        4. Using the charting APIs to create a new chart
          1. Creating the chart instance object
          2. Setting the properties of the chart instance object
            1. Setting the chart color and bounds
            2. Setting plot properties
            3. Setting legend properties
            4. Setting legend line properties
            5. Setting axes properties
            6. Creating a category series
            7. Creating an orthogonal series
            8. Defining the orthogonal series data values
            9. Setting the orthogonal series properties
            10. Setting the series definition properties
            11. Adding a series definition to a chart
            12. Adding series and queries to the series definitions
        5. Using a chart item in a report design
          1. Setting the chart type and subtype
          2. Creating sample data
          3. Getting a design engine element factory object
          4. Getting an extended item handle object
          5. Setting up the report item as a chart
          6. Getting a data set from the report design
          7. Binding the chart to the data set
          8. Adding the new chart to the report design
          9. Saving the report design after adding the chart
          10. Putting it all together
        6. Using the BIRT charting API in a Java Swing application
        7. Understanding the chart programming examples
          1. api.data examples
            1. DataCharts example
            2. GroupOnXSeries example
            3. GroupOnYAxis example
          2. api.data.autobinding example
          3. api.format example
          4. api.interactivity examples
          5. api.pdf example
          6. api.preference example
          7. api.processor example
          8. api.script examples
          9. api.viewer examples
            1. Chart3DViewer example
              1. CurveFittingViewer example
              2. DialChartViewer example
              3. SwingChartViewerSelector example
              4. SwingLiveChartViewer example
            2. SWTChartViewerSelector example
          10. builder example
          11. report examples
            1. MeterChartExample example
            2. SalesReport example
            3. StockReport example
          12. report.design examples
          13. report.design.script examples
          14. view example
    10. V. Working with the Extension Framework
      1. 16. Building the BIRT Project
        1. About building the BIRT project
        2. Installing a working version of BIRT
        3. Configuring the Eclipse workspace to compile BIRT
        4. Downloading and extracting the correct version of the BIRT source code
        5. Importing, building and testing the BIRT project
        6. Building new JAR files to display BIRT output
          1. Building the viewservlets.jar file
          2. Building the chart-viewer.jar file
      2. 17. Extending BIRT
        1. Overview of the extension framework
        2. Understanding the structure of a BIRT plug-in
          1. Understanding an extension point schema definition file
          2. Understanding a plug-in manifest file
          3. Understanding a plug-in run-time class
        3. Working with the Eclipse PDE
          1. Understanding plug-in project properties
          2. Understanding the Eclipse PDE Workbench
        4. Creating the structure of a plug-in extension
        5. Creating the plug-in extension content
        6. Building a plug-in extension
          1. Generating an Ant build script
          2. Testing a plug-in extension
        7. Deploying the extension plug-in
          1. Installing feature updates and managing the Eclipse configuration
          2. Creating an update site project
        8. Downloading the code for the extension examples
      3. 18. Developing a Report Item Extension
        1. Understanding a report item extension
        2. Developing the sample report item extension
          1. Downloading BIRT source code from the CVS repository
          2. Creating a rotated label report item plug-in project
          3. Defining the dependencies for the rotated label report item extension
          4. Specifying the run-time package for the rotated label report item extension
          5. Declaring the report item extension points
          6. Creating the plug-in extension content
        3. Understanding the rotated label report item extension
          1. Understanding RotatedLabelItemFactoryImpl
          2. Understanding RotatedLabelUI
          3. Understanding RotatedLabelPresentationImpl
          4. Understanding GraphicsUtil
          5. Understanding RotatedLabelCategoryProviderFactory
          6. Understanding RotatedLabelGeneralPage
        4. Deploying and testing the rotated label report item plug-in
          1. Deploying a report item extension
          2. Launching the rotated label report item plug-in
      4. 19. Developing a Report Rendering Extension
        1. Understanding a report rendering extension
        2. Developing a CSV report rendering extension
          1. Creating a CSV report rendering plug-in project
          2. Defining the dependencies for the CSV report rendering extension
          3. Declaring the emitters extension point
          4. Understanding the sample CSV report rendering extension
            1. Implementing the emitter interfaces
            2. Implementing the content interfaces
          5. Understanding the CSV report rendering extension package
            1. Understanding CSVReportEmitter
              1. Understanding the other CSVReportEmitter methods
            2. Understanding CSVTags
            3. Understanding CSVWriter
            4. Understanding CSVRenderOption
          6. Testing the CSV report rendering plug-in
          7. Launching the CSV report rendering plug-in
            1. About ExecuteReport class
            2. About the report design XML code
        3. Developing an XML report rendering extension
          1. Creating an XML report rendering plug-in project
          2. Defining the dependencies for the XML report rendering extension
          3. Declaring the emitters extension point
          4. Understanding the sample XML report rendering extension
          5. Understanding the XML report rendering extension package
            1. Understanding XMLReportEmitter
              1. Understanding the other XMLReportEmitter methods
            2. Understanding XMLTags
            3. Understanding XMLFileWriter
            4. Understanding XMLRenderOption
            5. Understanding LoadExportSchema
          6. Testing the XML report rendering plug-in
      5. 20. Developing an ODA Extension
        1. Understanding an ODA extension
        2. Developing the CSV ODA driver extensions
          1. About the CSV ODA plug-ins
          2. Downloading BIRT source code from the CVS repository
        3. Implementing the CSV ODA driver plug-in
          1. Understanding the ODA data source extension points
            1. Understanding dataSource extension point properties
            2. Understanding ConnectionProfile properties
          2. Understanding the dependencies for the CSV ODA driver extension
        4. Understanding the sample CSV ODA driver extension
          1. Implementing the DTP ODA interfaces
          2. Understanding the CSV ODA extension package
            1. Understanding Driver
            2. Understanding Connection
            3. Understanding Query
            4. Understanding ResultSet
            5. Understanding ResultSetMetaData
            6. Understanding DataSetMetaData
            7. Understanding Messages
            8. Understanding CommonConstants
        5. Developing the CSV ODA UI extension
          1. Creating the CSV ODA UI plug-in project
          2. Understanding the ODA data source UI extension points
            1. Understanding the ConnectionProfile extension point
            2. Understanding the propertyPages extension point
            3. Understanding the dataSource extension point
        6. Understanding the sample CSV ODA UI extension
          1. Implementing the ODA data source and data set wizards
          2. Understanding the org.eclipse.birt.report.data.oda.csv.ui.impl package
          3. Understanding the org.eclipse.birt.report.data.oda.csv.ui.wizards package
            1. Understanding Constants
            2. Understanding CSVFilePropertyPage
            3. Understanding CSVFileSelectionPageHelper
            4. Understanding CSVFileSelectionWizardPage
            5. Understanding FileSelectionWizardPage
        7. Testing the CSV ODA UI plug-in
        8. Developing a Hibernate ODA extension
          1. Creating the Hibernate ODA driver plug-in project
          2. Understanding the sample Hibernate ODA driver extension
            1. Understanding HibernateDriver
            2. Understanding Connection
            3. Understanding DataSetMetaData
            4. Understanding Statement
            5. Understanding ResultSet
            6. Understanding HibernateUtil
          3. Building the Hibernate ODA driver plug-in
          4. Developing the Hibernate ODA UI extension
          5. Understanding the sample Hibernate ODA UI extension
            1. Understanding HibernatePageHelper
            2. Understanding HibernateDataSourceWizard
            3. Understanding HibernatePropertyPage
            4. Understanding HibernateHqlSelectionPage
          6. Building the Hibernate ODA UI plug-in
          7. Testing the Hibernate ODA UI plug-in
      6. 21. Developing a Fragment
        1. Understanding a fragment
        2. Developing the sample fragment
        3. Creating a fragment project
        4. Understanding the sample fragment
        5. Building, deploying and testing a fragment
    11. Glossary