Integrating and Extending BIRT

597 Pages·2006·5.384 MB·English

by  Jason Weathersby, Don French, Tom Bondur, Jane Tatchell, Iana Chatalbasheva

Integrating and Extending BIRT
This page intentionally left blank
Integrating and Extending BIRT
Jason Weathersby • Don French • Tom Bondur
Jane Tatchell • Iana Chatalbasheva
UpperSaddleRiver,NJ•Boston•Indianapolis•SanFrancisco
NewYork•Toronto•Montreal•London•Munich•Paris•Madrid
Capetown•Sydney•Tokyo•Singapore•MexicoCity
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
[phone]
[email protected]
For sales outside the United States please contact:
International Sales
[email protected]
Visit us on the Web: www.awprofessional.com
This Book Is Safari Enabled
The Safari® Enabled icon on the cover of your favorite technology book means the book is
available through Safari Bookshelf. When you buy this book, you get free access to the
online edition for 45 days.
Safari Bookshelf is an electronic reference library that lets you easily search thousands of technical books,
find code samples, download chapters, and access technical information whenever and wherever you
needit.
To gain 45-day Safari Enabled access to this book:
■ Go to http://www.awprofessional.com/safarienabled
■ Complete the brief registration form
If you have difficulty registering on Safari Bookshelf or accessing the online edition, please e-mail
[email protected].
Library of Congress Cataloging-in-Publication Data
Integrating and extending BIRT/ Jason Weathersby... [et al.].
p. cm.
Includes index.
ISBN 0-321-44385-3 (pbk. : alk. paper)
1. Computer software--Development. 2. Application software--Development. 3. Client/server
computing. I. Weathersby, Jason.
QA76.76.D47I552 2006
005.1—dc22
2006014602
Copyright © 2006 Actuate Corporation
All rights reserved. Printed in the United States of America. 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
75 Arlington Street, Suite 300
Boston, MA 02116
Fax: [phone]
ISBN 0-321-44385-3
Text printed in the United States on recycled paper at R.R. Donnelley in Crawfordsville, Indiana.
First printing, October 2006
C o n t e n t s
Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xix
About this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Who should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xx
Contents of this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxiv
Syntax conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Part I Installing and Deploying BIRT. . . . . . . . . . . . . . . . . . . . 1
Chapter 1 Prerequisites for BIRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Requirements 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 . . . . . . . . . . . . . . . . . . . . 13
Installing 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
v
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 . . . . . . . . . . . . . . . . . . . . . . 23
Installing 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 . . . . . . . . . . . . . . . . . . . . . . . . . 31
Using 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 . . . . . . 33
About 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
__report parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
__document parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
vi Contents
__format parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
__locale parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
__isnull parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
__svg parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Report parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Part II Understanding the BIRT Framework . . . . . . . . . . . . . 45
Chapter 6 Understanding the BIRT Architecture . . . . . . . . . . . . . . . . . 47
Understanding 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 data engine components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
About the ODA framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .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 . . . . . . . . . . . . . . . 59
About 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
Contents vii
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 . . . . . . . . . . . . . . . . . . .71
Chapter 8 Using Scripting in a Report Design . . . . . . . . . . . . . . . . . . . 73
Overview 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 onCreate and onRender firing sequence dependencies . . . . . . . . . . . . . . . . . .75
About the ReportDesign firing sequence dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . .75
About the pageBreak event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Analysis of the execution sequence phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Overview of the report execution process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Preparation phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Report body processing phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Clean-up processing phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Row execution sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Table and list method execution sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
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
Chart instance getter methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Chart instance setter methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
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 . . . . . . . . . . . . 91
Using 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
viii Contents
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 . . . . . . . . . . . . . . . 111
Writing 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 methods for each report element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
About the IReportElement interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
About the element instance interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Using the IReportContext interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Using the IColumnMetaData interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
Contents ix