Integrating and Extending BIRT

Table of contents

1. Copyright
2. Foreward
3. 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
4. Acknowledgments
5. I. Installing and Deploying BIRT
   1. 1. Prerequisites for BIRT
      1. Requirements for the BIRT report designers
         1. About installing required software
         2. BIRT RCP Report Designer software requirements
         3. BIRT Report Designer Full Eclipse Install software requirements
         4. BIRT Report Designer software requirements
      2. Prerequisites for other BIRT packages
         1. BIRT Chart Engine software requirements
         2. BIRT Demo Database software requirements
         3. BIRT Report Engine software requirements
         4. BIRT Samples software requirements
         5. BIRT Test Suite software requirements
      3. About types of BIRT builds
   2. 2. Installing a BIRT Report Designer
      1. Installing BIRT Report Designer
         1. Downloading and installing BIRT Report Designer
         2. Installing the auxiliary file for BIRT Report Designer
         3. Testing the BIRT Report Designer installation
      2. Installing BIRT Report Designer Full Eclipse Install
         1. Downloading and installing BIRT Report Designer Full Eclipse Install
         2. Installing the auxiliary file for BIRT Report Designer
      3. Installing BIRT RCP Report Designer
         1. Downloading and installing BIRT RCP Report Designer
         2. Installing the auxiliary file for BIRT Report Designer
         3. Testing the BIRT RCP Report Designer installation
      4. Troubleshooting installation problems
         1. Avoiding cache conflicts after you install a BIRT report designer
         2. Specifying which Java Virtual Machine to use when you start a BIRT report designer
      5. Installing a language pack
   3. 3. Installing Other BIRT Packages
      1. Installing BIRT Chart Engine
         1. Installing BIRT Chart Engine from the Eclipse BIRT web site
         2. Avoiding cache conflicts after installing
      2. Installing BIRT Demo Database
         1. Installing BIRT Demo Database from the Eclipse BIRT web site
         2. Testing the BIRT Demo Database installation
      3. Installing BIRT Report Engine
         1. Installing BIRT Report Engine from the Eclipse BIRT web site
         2. Testing the BIRT Report Engine installation
      4. Installing BIRT Samples
      5. Installing BIRT Test Suite
   4. 4. Updating a BIRT Installation
      1. Using the Eclipse Update Manager to update BIRT Report Designer installation
      2. Updating BIRT RCP Report Designer installation
   5. 5. 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 files
            1. Installing the auxiliary file
            2. Installing your JDBC drivers
         2. Testing the BIRT report viewer installation
         3. Using a different context root for the BIRT report viewer
         4. Placing the viewer in a different location
         5. Mapping the folders that the BIRT report viewer uses
         6. Verifying that Apache Tomcat is running BIRT report viewer
      3. Placing fonts on the application server
      4. Viewing a report using a browser
         1. Understanding the run and frameset servlets
         2. Using the URL parameters for the run and frameset servlets
            1. __report parameter
            2. __document parameter
            3. __format parameter
            4. __locale parameter
            5. __isnull parameter
            6. __svg parameter
            7. Report parameters
6. 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 report viewer
      3. About the BIRT engines
         1. About the report design engine
         2. About the report engine
         3. About the generation engine
         4. About the presentation engine
         5. About the chart engine
         6. About the data engine
            1. About data engine 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 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
7. III. Scripting in a Report Design
   1. 8. Using Scripting in a Report Design
      1. Overview of BIRT scripting
         1. Choosing between Java and JavaScript
         2. Using both Java and JavaScript to write event handlers
      2. Understanding the event handler execution sequence
         1. About event firing sequence dependency
            1. About the onCreate and onRender firing sequence dependencies
            2. About the ReportDesign firing sequence dependencies
         2. About the pageBreak event
         3. Analysis of the execution sequence phases
            1. Overview of the report execution process
            2. Preparation phase
            3. Report body processing phase
            4. Clean-up processing phase
            5. Row execution sequence
            6. Table and list method execution sequence
               1. Table and list setup phase
               2. Table and list processing phase
               3. Table and list wrap-up phase
               4. Ungrouped table or list detail execution sequence
               5. Grouped table or list execution sequence
      3. About a report item event handler
      4. About data source and data set event handlers
         1. ODA data source events
         2. Scripted data source events
         3. ODA data set events
         4. Scripted data set events
      5. About ReportDesign event handlers
      6. Writing event handlers for charts
         1. Chart events
         2. Chart script context
         3. Chart instance object
            1. Chart instance getter methods
            2. Chart instance setter methods
         4. Writing a Java chart event handler
         5. Writing a JavaScript chart event handler
      7. Getting a dynamic image from a Microsoft Access database
   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. Passing a variable between processes
         2. Getting information from an HTTP request object
      3. Using the this object
         1. Using the this object’s 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. Getting a parameter value
      8. Changing the connection properties of a data source
      9. Determining method execution sequence
         1. Providing the ReportDesign.initialize code
         2. Providing the 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. Calling Java from JavaScript
          1. Understanding the Packages object
          2. Understanding the importPackage method
          3. Using a Java class
          4. Placing your Java classes where BIRT can find them
          5. Issues with using Java in JavaScript code
   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
      2. Making the Java class visible to BIRT
      3. Associating the Java event handler class with a report element
      4. BIRT Java interface and class naming conventions
         1. Naming convention for event handler interfaces
         2. Naming convention for event handler adapter classes
         3. Naming convention for ROM element instance interfaces
         4. Naming convention for ROM element design interfaces
      5. 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
      6. 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. 11. Using a Scripted Data Source
      1. Creating a scripted data source and scripted data set
      2. Tutorial 2: Creating and scripting a scripted data source
         1. Task 1: Create a new report
         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 data set fetch( ) method
      3. 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
      4. Using input and output parameters with a scripted data set
8. IV. Integrating BIRT Functionality into Applications
   1. 12. Understanding the BIRT APIs
      1. Package hierarchy diagrams
      2. About the BIRT Report Engine API
         1. Creating the BIRT Report Engine
         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. DesignEngine class
            2. SessionHandle class
            3. ModuleHandle class
            4. ReportDesignHandle class
            5. LibraryHandle class
            6. DesignElementHandle class
            7. Individual element handle classes
         2. Design engine class hierarchy
            1. ReportElementHandle hierarchy
            2. ReportItemHandle hierarchy
            3. ElementDetailHandle hierarchy
            4. StructureHandle hierarchy
      4. About the BIRT Chart Engine API
         1. Using the BIRT Chart Engine API
         2. Chart engine class hierarchy
            1. chart.aggregate hierarchy
            2. chart.datafeed hierarchy
            3. chart.device class hierarchy
            4. chart.device interface hierarchy
            5. chart.event class hierarchy
            6. chart.exception class hierarchy
            7. chart.factory class hierarchy
            8. chart.log class hierarchy
            9. chart.model class hierarchy
            10. chart.model.attribute interface hierarchy
            11. chart.model.attribute class hierarchy
            12. chart.model.component interface hierarchy
            13. chart.model.data interface hierarchy
            14. chart.model.layout interface hierarchy
            15. chart.model.type interface hierarchy
            16. chart.render hierarchy
            17. chart.script hierarchy
            18. chart.util class hierarchy
   2. 13. Programming with 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. Shutting down 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 engine 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. Using the logging environment to debug an application
               1. How to use BIRT logging
         2. Opening a source for report generation
            1. Understanding an IReportRunnable object
               1. How to access a report design
            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
               1. How to set the value of a known report parameter
               2. How to use the Collection of report parameters
            8. Getting the values for cascading parameters
               1. How to use cascading parameters
         4. Preparing to generate the report
            1. Setting the parameter values for running a report design
            2. Setting up the rendering options
            3. Setting up the rendering context
            4. Setting up the HTML rendering context
            5. Setting up the PDF rendering context
               1. How to configure properties for a report in HTML format
            6. Providing an external connection to run a report design
         5. Generating the formatted output programmatically
         6. Accessing the formatted report
      3. About 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. 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. 14. Programming with the BIRT Charting APIs
      1. About the environment for building a charting application
      2. Verifying the development 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 axes properties
            2. Modifying plot properties
            3. Modifying the legend properties
            4. Modifying the series 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 a y-series
            8. Defining the y-series queries
            9. Setting the y-series properties
            10. Setting the properties of the x- and y-series
            11. Adding a series definition to the Axis object
            12. Adding series, queries, and categories to the series definitions
         3. Creating sample data
         4. Getting an element factory object
         5. Getting an extended item handle object
         6. Setting the chart.instance property on the report item
         7. Getting a data set from the report design
         8. Binding the chart to the data set
         9. Adding the new chart to the report design
         10. Saving the report design after adding the chart
         11. Putting it all together
      5. Using the BIRT charting API in a Java Swing application
      6. Understanding the chart programming examples
         1. DataCharts
         2. GroupOnXSeries
         3. GroupOnYAxis
         4. AutoDataBinding
         5. FormatCharts
         6. InteractivityCharts
         7. PDFChartGenerator
         8. StyleProcessor
         9. ScriptViewer
         10. Viewer
         11. ChartWizardLauncher
         12. Report
         13. Preference
9. V. Working with the Extension Framework
   1. 15. Building the BIRT Project
      1. About building the BIRT project
         1. Assuring that you have the correct software on your system
         2. Configuring the Eclipse workspace to compile BIRT
      2. Creating Eclipse projects
         1. Specifying the repository locations
         2. Checking out the BIRT source
         3. Adding the extra JAR file
      3. Building the web viewer
   2. 16. 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. 17. 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 RotatedLabelReportItemImpl
         5. Understanding RotatedLabelPropertyEditUIImpl
         6. Understanding GraphicsUtil
      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. 18. Developing a Report Rendering Extension
      1. Understanding a report rendering extension
      2. Developing the CSV report rendering extension
         1. Downloading BIRT source code from the CVS repository
         2. Creating a CSV report rendering plug-in project
         3. Defining the dependencies for the CSV report rendering extension
         4. Declaring the emitters extension point
      3. Understanding the sample CSV report rendering extension
         1. Implementing the emitter interfaces
         2. Implementing the content interfaces
         3. Understanding the CSV report rendering extension package
            1. Understanding CSVReportEmitter
            2. Understanding the other CSVReportEmitter methods
            3. Understanding CSVTags
            4. Understanding CSVWriter
         4. Understanding the BIRT report engine API package
            1. Understanding RenderOptionBase
            2. Understanding CSVRenderOption
            3. Understanding EngineConstants
      4. Testing the CSV report rendering plug-in
         1. Launching the CSV report rendering plug-in
         2. About ExecuteReport class
         3. About the report design XML code
   5. 19. 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. Defining the dependencies for the CSV ODA driver extension
         2. Specifying the run-time settings for the CSV ODA driver extension
         3. Declaring the ODA data source extension point
      4. Understanding the sample CSV ODA driver extension
         1. Implementing the DTP ODA interfaces
         2. Understanding the CSV ODA extension package
            1. Understanding CSVFileDriver
            2. Understanding CSVFileQuery
            3. Understanding ResultSet
            4. Understanding ResultSetMetaData
            5. Understanding DataSetMetaData
            6. Understanding Messages
            7. Understanding DataTypes
            8. Understanding CommonConstant
      5. Developing the CSV ODA UI extension
         1. Creating the CSV ODA UI plug-in project
         2. Defining the dependencies for the CSV ODA UI extension
         3. Specifying the run-time settings for the CSV ODA UI extension
         4. Declaring the ODA data source UI 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.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
10. Glossary