Integrating and Extending BIRT Second Edition the eclipse series SERIES EDITORS Erich Gamma ■ Lee Nackman ■ John Wiegand Eclipse is a universal tool platform, an open extensible integrated development environment (IDE) for anything and nothing in particular Eclipse represents one of the most exciting initiatives hatched from the world of application development in a long time, and it has the considerable support of the leading companies and organizations in the technology sector Eclipse is gaining widespread acceptance in both the commercial and academic arenas The Eclipse Series from Addison-Wesley is the definitive series of books dedicated to the Eclipse platform Books in the series promise to bring you the key technical information you need to analyze Eclipse, high-quality insight into this powerful technology, and the practical advice you need to build tools to support this evolutionary Open Source platform Leading experts Erich Gamma, Lee Nackman, and John Wiegand are the series editors Titles in the Eclipse Series John Arthorne and Chris Laffra Official Eclipse 3.0 FAQs 0-321-26838-5 David Carlson Eclipse Distilled 0-321-28815-7 Eric Clayberg and Dan Rubel Eclipse: Building Commercial-Quality Plug-Ins, Second Edition 0-321-42672-X Adrian Colyer, Andy Clement, George Harley, and Matthew Webster Eclipse AspectJ: Aspect-Oriented Programming with AspectJ and the Eclipse AspectJ Development Tools 0-321-24587-3 Naci Dai, Lawrence Mandel, and Arthur Ryman Eclipse Web Tools Platform: Developing Java™ Web Applications 0-321-39685-5 Erich Gamma and Kent Beck Contributing to Eclipse: Principles, Patterns, and Plug-Ins 0-321-20575-8 Jeff McAffer and Jean-Michel Lemieux Eclipse Rich Client Platform: Designing, Coding, and Packaging Java™ Applications 0-321-33461-2 Diana Peh, Alethea Hannemann, Paul Reeves, and Nola Hague BIRT: A Field Guide to Reporting 0-321-44259-8 Dave Steinberg, Frank Budinsky, Marcelo Paternostro, Ed Merks EMF: Eclipse Modeling Framework 0-321-33188-5 Jason Weathersby, Don French,Tom Bondur, Jane Tatchell, and Iana Chatalbasheva Integrating and Extending BIRT 0-321-44385-3 For more information on books in this series visit www.awprofessional.com/series/eclipse Integrating and Extending BIRT Second Edition Jason Weathersby • Tom Bondur • Iana Chatalbasheva Don French Upper Saddle River, NJ • Boston • Indianapolis • San Francisco New York • Toronto • Montreal • London • Munich • Paris • Madrid Capetown • Sydney • Tokyo • Singapore • Mexico City Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks Where those designations appear in this book, and the publisher was aware of a trademark claim, the designations have been printed with initial capital letters or in all capitals The authors and publisher have taken care in the preparation of this book, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information or programs contained herein The publisher offers excellent discounts on this book when ordered in quantity for bulk purchases or special sales, which may include electronic versions and/or custom covers and content particular to your business, training goals, marketing focus, and branding interests For more information, please contact: U.S Corporate and Government Sales (800) 382-3419 corpsales@pearsontechgroup.com For sales outside the United States please contact: International Sales international@pearsoned.com Visit us on the Web: informit.com/aw Copyright© 2008 by Actuate Corporation All rights reserved This publication is protected by copyright, and permission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise For information regarding permissions, write to: Pearson Education, Inc Rights and Contracts Department 501 Boylston Street, Suite 900 Boston, MA 02116 Fax: (617) 671-3447 ISBN-13: 978-0-321-58030-6 ISBN-10: 0-321-58030-3 Text printed in the United States at OPM in Laflin, Pennsylvania First printing, June 2008 Co nten ts Foreword xix Preface xxi About this book xxi Who should read this book xxii Contents of this book xxii Typographical conventions xxvi Syntax conventions xxvii Acknowledgments xxix Part I Installing and Deploying BIRT Chapter Prerequisites for BIRT Downloading Eclipse BIRT components BIRT Report Designer software requirements About types of BIRT builds Chapter Installing a BIRT Report Designer Installing BIRT Report Designer Full Eclipse Install Installing BIRT RCP Report Designer 10 Troubleshooting installation problems 11 Avoiding cache conflicts after you install a BIRT report designer 12 Specifying a Java Virtual Machine when starting BIRT report designer 12 Installing a language pack 13 Updating a BIRT Report Designer installation 14 Updating BIRT RCP Report Designer installation 15 Chapter Installing Other BIRT Packages 17 Installing Chart Engine 17 Installing BIRT Data Tools Platform Integration 19 Installing BIRT Demo Database 19 Installing Report Engine 21 Installing BIRT Samples 23 Installing BIRT Source Code 23 v Installing BIRT Web Tools Integration 25 Chapter Deploying a BIRT Report to an Application Server 27 About application servers About deploying to Tomcat About deploying to other application servers Placing the BIRT report viewer on an application server Installing the BIRT report viewer as a web application Testing the BIRT report viewer installation Using a different context root for the BIRT report viewer Placing the BIRT report viewer in a different location Understanding the BIRT report viewer context parameters Verifying that Apache Tomcat is running BIRT report viewer Placing fonts on the application server Viewing a report using a browser Using connection pooling on Tomcat Setting up a report to use connection pooling Using a jndi.properties file Configuring a JNDI connection object on Tomcat Chapter Using Eclipse BIRT Web Viewer 39 Understanding Eclipse BIRT Web Viewer Understanding Web Viewer architecture Web Viewer servlets Web Viewer URL parameters Web Viewer fragments Web Viewer web.xml settings Web Viewer directory structure Web Viewer AJAX operation Using the Web Viewer Deployment wizard Web Viewer tag library Web Viewer RCP deployment Passing a web context object to the Web Viewer Building the Web Viewer Part II 39 44 45 46 50 52 54 55 61 63 76 78 78 Understanding the BIRT Framework 81 Chapter Understanding the BIRT Architecture 83 Understanding the BIRT integration About the BIRT applications About BIRT Report Designer and BIRT RCP Report Designer About the BIRT Viewer About the BIRT engines and services About the report design engine About the report engine About the generation services About the presentation services vi 27 27 28 28 28 30 30 30 31 32 33 33 34 34 34 35 Contents 83 87 87 88 88 89 89 89 89 About the chart engine 90 About the data services 90 About data services components 90 About the ODA framework 90 About the types of BIRT report items 90 About standard report items 90 About custom report items 91 About chart report items 91 About the Report Object Model (ROM) 91 About the types of BIRT files 91 About report design files 92 About report document files 92 About report library files 92 About report template files 92 About custom Java applications 93 About custom report designers 93 About custom Java report generators 93 About extensions to BIRT 93 Chapter Understanding the Report Object Model 95 About the ROM specification 95 ROM properties 96 ROM slots 97 ROM methods 97 ROM styles 97 About the ROM schema 98 About the rom.def file 98 About the primary ROM elements 101 About the report item elements 102 About the report items 102 Understanding the report item element properties 103 About the data elements 103 Part III Chapter Scripting in a Report Design 105 Using Scripting in a Report Design 107 Overview of BIRT scripting 107 Choosing between JavaScript and Java 107 Using both JavaScript and Java to write event handlers 108 Events overview 108 Engine task processes 108 BIRT Web Viewer 109 BIRT Report Designer 109 BIRT processing phases 110 BIRT event types 110 Parameter events 110 Report design events 111 Contents vii Data source and data set events ReportItem Events Event order sequence Preparation phase operation Generation phase operation About data source and data set events About data binding About the page break event About chart event order About table and list event order Completion of the generation phase Presentation phase operation Event order summary Chapter Using JavaScript to Write an Event Handler 127 Using BIRT Report Designer to enter a JavaScript event handler Creating and using a global variable Understanding execution phases and processes Using the reportContext object Using getOutputFormat Using reportContext to retrieve the report design handle Passing a variable between processes Using getAppContext Getting information from an HTTP request object Using the this object Using this object methods Using the this object to set the property of a report item Using the row object Getting column information Getting and altering the query string Changing the connection properties of a data source Getting a parameter value Determining method execution sequence Providing the ReportDesign.initialize code Providing code for the methods you want to track Providing the ReportDesign.afterFactory code Tutorial 1: Writing an event handler in JavaScript Task 1: Open the report design Task 2: Create and initialize a counter in the Table.onCreate( ) method Task 3: Conditionally increment the counter in the Row.onCreate( ) method Task 4: Display the result using the ReportDesign.afterFactory( ) method JavaScript event handler examples JavaScript onPrepare examples JavaScript onCreate examples JavaScript onRender examples Calling Java from JavaScript Understanding the Packages object Understanding the importPackage method viii Contents 112 113 115 115 116 118 119 120 121 121 124 124 125 127 128 129 130 131 132 133 134 135 135 136 136 138 139 140 140 141 142 143 144 144 144 145 145 146 148 149 149 149 151 151 151 151 Using a Java class 152 Placing Java classes 152 Issues with using Java in JavaScript code 153 Calling the method of a class that resides in a plug-in 153 Chapter 10 Using Java to Write an Event Handler 155 Writing a Java event handler class 155 Locating the JAR files that an event handler requires 156 Extending an adapter class 156 Making the Java class visible to BIRT 159 Associating the Java event handler class with a report element 160 BIRT Java interface and class naming conventions 161 Writing a Java event handler 161 Using event handler adapter classes 161 Using event handler interfaces 162 About the Java event handlers for report items 162 Using Java event handlers for the DataSource element 163 Using Java event handlers for the DataSet element 164 Using Java event handlers for the ScriptedDataSource element 164 Using Java event handlers for the ScriptedDataSet element 165 Using Java event handlers for the ReportDesign 166 Understanding the BIRT interfaces 166 About the element design interfaces 167 About the methods for each report element 167 About the IReportElement interface 168 About the element instance interfaces 168 Using the IReportContext interface 169 Using the IColumnMetaData interface 171 Using the IDataSetInstance interface 172 Using the IDataSetRow interface 172 Using the IRowData interface 173 Java event handler example 173 Report level events 173 Report item events 175 Debugging a Java event handler 180 Chapter 11 Working with Chart Event Handlers 183 Chart events overview 183 Understanding when chart events trigger 185 Prepare phase 185 Data binding phase 186 Static data 186 Dynamic data 186 Binding phase script events 187 Building phase 189 Rendering phase 191 Rendering phase script events 193 Rendering blocks 194 Contents ix ... Tatchell, and Iana Chatalbasheva Integrating and Extending BIRT 0-321-44385-3 For more information on books in this series visit www.awprofessional.com/series/eclipse Integrating and Extending BIRT. .. 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 to... Understanding BIRT architecture xxi ■ Scripting in a BIRT report design ■ Integrating BIRT functionality into applications ■ Working with the BIRT extension framework This revised BIRT 2.2.1 edition