Integrating and Extending BIRT

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.

Foreword xviiPreface xixAcknowledgments xxviiPart I Installing and Deploying BIRT 1Chapter 1 Prerequisites for BIRT 3Requirements for the BIRT report designers 3

About installing required software 5

BIRT RCP Report Designer software requirements 5

BIRT Report Designer Full Eclipse Install software requirements 5

BIRT Report Designer software requirements 6

Prerequisites for other BIRT packages 7

BIRT Chart Engine software requirements 7

BIRT Demo Database software requirements 8

BIRT Report Engine software requirements 9

BIRT Samples software requirements 9

BIRT Test Suite software requirements 9

About types of BIRT builds 10

Chapter 2 Installing a BIRT Report Designer 13Installing BIRT Report Designer 14

Downloading and installing BIRT Report Designer 14

Installing the auxiliary file for BIRT Report Designer 14

Testing the BIRT Report Designer installation 15

Installing BIRT Report Designer Full Eclipse Install 15

Downloading and installing BIRT Report Designer Full Eclipse Install 15

Installing the auxiliary file for BIRT Report Designer 16

Installing BIRT RCP Report Designer 16

Downloading and installing BIRT RCP Report Designer 17

Installing the auxiliary file for BIRT Report Designer 17

Testing the BIRT RCP Report Designer installation 18

Troubleshooting installation problems 18

Avoiding cache conflicts after you install a BIRT report designer 18

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

Installing a language pack 19

Chapter 3 Installing Other BIRT Packages 23Installing BIRT Chart Engine 23

Installing BIRT Chart Engine from the Eclipse BIRT web site 24

Avoiding cache conflicts after installing 24

Installing BIRT Demo Database 25

Installing BIRT Demo Database from the Eclipse BIRT web site 25

Testing the BIRT Demo Database installation 25

Installing BIRT Report Engine 26

Installing BIRT Report Engine from the Eclipse BIRT web site 27

Testing the BIRT Report Engine installation 27

Installing BIRT Samples 28

Installing BIRT Test Suite 29

Chapter 4 Updating a BIRT Installation 31Using the Eclipse Update Manager to update BIRT Report Designer installation 31

Updating BIRT RCP Report Designer installation 32

Chapter 5 Deploying a BIRT Report to an Application Server 33About application servers 33

About deploying to Tomcat 33

About deploying to other application servers 34

Placing the BIRT report viewer on an application server 34

Installing the BIRT report viewer files 34

Installing the auxiliary file 35

Installing your JDBC drivers 35

Testing the BIRT report viewer installation 35

Using a different context root for the BIRT report viewer 36

Placing the viewer in a different location 36

Mapping the folders that the BIRT report viewer uses 36

Verifying that Apache Tomcat is running BIRT report viewer 39

Placing fonts on the application server 40

Viewing a report using a browser 40

Understanding the run and frameset servlets 41

Using the URL parameters for the run and frameset servlets 41

About the report item elements 67

About the report items 67

Understanding the report item element properties 67

About the data elements 68

Part II Understanding the BIRT Framework 45Chapter 6 Understanding the BIRT Architecture 47Understanding the BIRT integration 47

About the BIRT applications 51

About BIRT Report Designer and BIRT RCP Report Designer 51

About the BIRT report viewer 51

About the BIRT engines 52

About the report design engine 52

About the report engine 52

About the generation engine 52

About the presentation engine 52

About the chart engine 53

About the data engine 53

About the types of BIRT report items 53

About standard report items 54

About custom report items 54

About chart report items 54

About the ROM 54

About the types of BIRT files 54

About report design files 55

About report document files 55

About report library files 55

About report template files 55

About custom Java applications 56

About custom report designers 56

About custom Java report generators 56

About extensions to BIRT 57

Chapter 7 Understanding the Report Object Model 59About the ROM specification 59

ROM properties 60

ROM slots 61

ROM methods 61

ROM styles 62

About the ROM schema 62

About the rom.def file 63

About the primary ROM elements 66

About the report item elements 67

About the report items 67

Understanding the report item element properties 67

About the data elements 68

Part III Scripting in a Report Design 71Chapter 8 Using Scripting in a Report Design 73Overview of BIRT scripting 73

Choosing between Java and JavaScript 73

Using both Java and JavaScript to write event handlers 74

Understanding the event handler execution sequence 74

About event firing sequence dependency 74

About the pageBreak event 75

Analysis of the execution sequence phases 75

About a report item event handler 81

About data source and data set event handlers 82

ODA data source events 82

Scripted data source events 82

ODA data set events 82

Scripted data set events 82

About ReportDesign event handlers 82

Writing event handlers for charts 83

Chart events 83

Chart script context 85

Chart instance object 86

Writing a Java chart event handler 87

Writing a JavaScript chart event handler 87

Getting a dynamic image from a Microsoft Access database 89

Chapter 9 Using JavaScript to Write an Event Handler 91Using BIRT Report Designer to enter a JavaScript event handler 91

Creating and using a global variable 92

Understanding execution phases and processes 93

Using the reportContext object 94

Passing a variable between processes 95

Getting information from an HTTP request object 95

Using the this object 95

Using the this object's methods 95

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

Using the row object 99

Getting column information 99

Getting and altering the query string 100

Getting a parameter value 101

Changing the connection properties of a data source 101

Determining method execution sequence 102

Providing the ReportDesign.initialize code 102

Providing the code for the methods you want to track 103

Providing the ReportDesign.afterFactory code 103

Tutorial 1: Writing an event handler in JavaScript 104

Task 1: Open the report design 104

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

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

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

Calling Java from JavaScript 108

Understanding the Packages object 108

Understanding the importPackage method 109

Using a Java class 109

Placing your Java classes where BIRT can find them 110

Issues with using Java in JavaScript code 110

Chapter 10 Using Java to Write an Event Handler 111Writing a Java event handler class 111

Locating the JAR files that an event handler requires 112

Extending an adapter class 112

Making the Java class visible to BIRT 116

Associating the Java event handler class with a report element 116

BIRT Java interface and class naming conventions 117

Writing a Java event handler 118

Using event handler adapter classes 118

Using event handler interfaces 118

About the Java event handlers for report items 119

Using Java event handlers for the DataSource element 120

Using Java event handlers for the DataSet element 120

Using Java event handlers for the ScriptedDataSource element 121

Using Java event handlers for the ScriptedDataSet element 122

Using Java event handlers for the ReportDesign 122

Understanding the BIRT interfaces 123

About the element design interfaces 124

About the element instance interfaces 125

Using the IReportContext interface 126

Using the IColumnMetaData interface 128

Using the IDataSetInstance interface 128

Using the IDataSetRow interface 129

Using the IRowData interface 129

Chapter 11 Using a Scripted Data Source 131Creating a scripted data source and scripted data set 131

Tutorial 2: Creating and scripting a scripted data source 133

Task 1: Create a new report 133

Task 2: Create a scripted data source 133

Task 3: Create a scripted data set 134

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

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

Task 6: Define output columns 135

Task 7: Place the columns on the report layout 137

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

Using a Java object to access a data source 139

Performing initialization in the data set open( ) method 139

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

Cleaning up in the data set close( ) method 140

Deciding where to locate your Java class 140

Deploying your Java class 141

Using input and output parameters with a scripted data set 141

Part IV Integrating BIRT Functionality into Applications 143Chapter 12 Understanding the BIRT APIs 145Package hierarchy diagrams 146

About the BIRT Report Engine API 147

Creating the BIRT Report Engine 148

Using the BIRT Report Engine API 148

Report engine class hierarchy 151

Report engine interface hierarchy 152

About the design engine API 153

Using the BIRT design engine API 154

Design engine class hierarchy 157

About the BIRT Chart Engine API 163

Using the BIRT Chart Engine API 164

Chart engine class hierarchy 164

Chapter 13 Programming with the BIRT Reporting APIs 181Building a reporting application 182

About the environment for a reporting application 183

Modifying a report design with the API 185

Generating reports from an application 185

Setting up the report engine 186

Opening a source for report generation 190

Accessing a report parameter programmatically 192

Preparing to generate the report 199

Generating the formatted output programmatically 203

Accessing the formatted report 203

About programming with a report design 204

About BIRT model API capabilities 205

Opening a report design programmatically for editing 206

Accessing a data source and data set with the API 214

Saving a report design programmatically 217

Creating a report design programmatically 217

Chapter 14 Programming with the BIRT Charting APIs 219About the environment for building a charting application 220

Verifying the development environment for charting applications 221

Using the charting API to modify an existing chart 222

Getting a Chart object from the report design 222

Adding a series to a chart 224

Adding a chart event handler to a charting application 224

Using the charting APIs to create a new chart 225

Creating the chart instance object 226

Setting the properties of the chart instance object 227

Creating sample data 231

Getting an element factory object 231

Getting an extended item handle object 231

Setting the chart.instance property on the report item 231

Getting a data set from the report design 232

Binding the chart to the data set 232

Adding the new chart to the report design 232

Saving the report design after adding the chart 232

Putting it all together 233

Using the BIRT charting API in a Java Swing application 239

Understanding the chart programming examples 246

Part V Working with the Extension Framework 251Chapter 15 Building the BIRT Project 253About building the BIRT project 253

Assuring that you have the correct software on your system 254

Configuring the Eclipse workspace to compile BIRT 254

Creating Eclipse projects 256

Specifying the repository locations 257

Checking out the BIRT source 259

Adding the extra JAR file 261

Building the web viewer 262

Chapter 16 Extending BIRT 267Overview of the extension framework 267

Understanding the structure of a BIRT plug-in 268

Understanding an extension point schema definition file 268

Understanding a plug-in manifest file 271

Understanding a plug-in run-time class 272

Working with the Eclipse PDE 275

Understanding plug-in project properties 277

Understanding the Eclipse PDE Workbench 277

Creating the structure of a plug-in extension 279

Creating the plug-in extension content 283

Building a plug-in extension 287

Generating an Ant build script 290

Testing a plug-in extension 291

Deploying the extension plug-in 291

Installing feature updates and managing the Eclipse configuration 293

Creating an update site project 294

Downloading the code for the extension examples 297

Chapter 17 Developing a Report Item Extension 299Understanding a report item extension 299

Developing the sample report item extension 301

Downloading BIRT source code from the CVS repository 302

Creating a rotated label report item plug-in project 302

Defining the dependencies for the rotated label report item extension 305

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

Declaring the report item extension points 307

Creating the plug-in extension content 312

Understanding the rotated label report item extension 316

Understanding RotatedLabelItemFactoryImpl 318

Understanding RotatedLabelUI 319

Understanding RotatedLabelPresentationImpl 319

Understanding RotatedLabelReportItemImpl 320

Understanding RotatedLabelPropertyEditUIImpl 320

Understanding GraphicsUtil 321

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

Deploying a report item extension 324

Launching the rotated label report item plug-in 324

Chapter 18 Developing a Report Rendering Extension 329Understanding a report rendering extension 329

Developing the CSV report rendering extension 330

Downloading BIRT source code from the CVS repository 330

Creating a CSV report rendering plug-in project 331

Defining the dependencies for the CSV report rendering extension 334

Declaring the emitters extension point 335

Understanding the sample CSV report rendering extension 337

Implementing the emitter interfaces 337

Implementing the content interfaces 339

Understanding the CSV report rendering extension package 341

Understanding CSVReportEmitter 341

Understanding CSVTags 348

Understanding CSVWriter 348

Understanding the BIRT report engine API package 348

Understanding RenderOptionBase 349

Understanding CSVRenderOption 349

Understanding EngineConstants 349

Testing the CSV report rendering plug-in 350

Launching the CSV report rendering plug-in 353

About ExecuteReport class 357

About the report design XML code 359

Chapter 19 Developing an ODA Extension 365Understanding an ODA extension 366

Developing the CSV ODA driver extensions 366

About the CSV ODA plug-ins 367

Downloading BIRT source code from the CVS repository 367

Implementing the CSV ODA driver plug-in 368

Defining the dependencies for the CSV ODA driver extension 370

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

Declaring the ODA data source extension point 371

Understanding the sample CSV ODA driver extension 379

Implementing the DTP ODA interfaces 379

Developing the CSV ODA UI extension 390

Creating the CSV ODA UI plug-in project 390

Defining the dependencies for the CSV ODA UI extension 392

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

Declaring the ODA data source UI extension point 393

Understanding the sample CSV ODA UI extension 403

Implementing the ODA data source and data set wizards 404

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

Testing the CSV ODA UI plug-in 414

Developing a Hibernate ODA extension 419

Creating the Hibernate ODA driver plug-in project 420

Understanding the sample Hibernate ODA driver extension 426

Building the Hibernate ODA driver plug-in 439

Developing the Hibernate ODA UI extension 441

Understanding the sample Hibernate ODA UI extension 448

Building the Hibernate ODA UI plug-in 458

Testing the Hibernate ODA UI plug-in 460

Glossary 465Index 525