BIRT Exchange
Integrating BIRT within your
Applications
Jason Weathersby
BIRT Evangelist
1
Actuate Corporation © 2007
Agenda
•
•
•
•
BIRT Overview
BIRT Scripting
BIRT Engine(s) Overview
Deploying BIRT
• Deploying the BIRT Viewer
• Deploying a custom Servlet, which calls the BIRT APIs
• RCP Deployment
2
Actuate Corporation © 2009
High Level BIRT Architecture
DE API
Design Engine
RE API
Report Engine
CE API
Chart Engine
Can be ran outside of OSGi
Core BIRT Open Source Products
Report Designer
Chart Builder
Example Viewer
Can be ran outside of BIRT
3
Actuate Corporation © 2009
Produces XML Report,
Templates, and Library
Designs
Runs Reports and
produces output – PDF,
HTML, Doc, XLS, PS,
PPT Etc
Consume Chart EMF
model and produces
Chart Output. Supports
13 Main types and many
sub types. Ouputs to
PNG, JPG, BMP, SVG,
PDF, SWT, and SWING
BIRT Designer
4
Actuate Corporation © 2009
High Level BIRT Architecture: APIs
BIRT Report Designer
Eclipse
Eclipse
Custom Report
Report
DTP,
Designer UI
Designer
WTP,…
Chart
Designer
Chart UI API
Report Design Engine
Design Engine API
XML
Report
Design
Report Engine API
Report
Document
BIRT Report Engine
Generation
Services
Scripting API
Data
Data
Services
Open Data Access
Data
5
Actuate Corporation © 2009
Charting
Engine
Chart Engine API
Presentation
Services
Emitter API
HTML
PDF
Excel
Word
PowerPoint
PostScript
…
BIRT Pipeline with respect to the APIs
BIRT Report Designer
Chart Builder
Report Design Engine
Charting Engine
HTML
BIRT Report Engine
PDF
RptDesign
XML
Design File
Optional Java Events
CSV
WORD
JavaScript Events
XLS
PS
Generation Phase
Presentation Phase
RptDocument
Report
Document
6
Actuate Corporation © 2009
PPT
Agenda
BIRT Scripting
7
Actuate Corporation © 2009
Scripting
• BIRT JavaScript
• Based on Mozilla Rhino
- This is Server Side Scripting not Browser Based Scripting
• Two types of Scripting
Expression Scripts - Scripts that return a data value. Available
in the Expression Builder.
Element Scripts – JavaScript methods that are called on
events. Customize the behavior of the Report. Available in the
Script view. Context of when the event occurs is important.
Can also be implemented in Java.
• Element Scripts are Provided for Charts as well, but these
scripts run at render time, not generation time.
• Java/JavaScripts Can be debugged within the designer
8
Actuate Corporation © 2009
Expression Scripting
9
Actuate Corporation © 2009
Expression Scripting – Example Locations
•
•
•
•
•
•
•
•
•
•
Creating the display value for a report item
Creating a computed field in Data Explorer
Specifying a filter condition
Specifying a data series for a chart
Specifying a map condition
Specifying a highlight condition
Specifying a group key
Specifying a hyperlink
Specifying the URI for an image
Specifying dynamic data in a text control
10
Actuate Corporation © 2009
Report Scripting
Optional Java Events
JavaScript Events
Generation Phase
Report Level
initialize
beforeFactory
afterFactory
onPageStart
onPageEnd
Master Page
onPageStart
onPageEnd
11
Actuate Corporation © 2009
Data Source/Set
beforeOpen
afterOpen
onFetch
beforeClose
afterClose
Report Element
onPrepare
onCreate
onPageBreak
Presentation Phase
Report Level
initialize
beforeRender
afterRender
Report Element
onRender
Chart Events
onRender
..
Element Scripting
12
Actuate Corporation © 2009
Element Event Handlers using Java
• A set of Adapters are
supplied that allow most
event handlers to be built in
Java.
• The class is a property of the
element.
• Can be debugged with JDT
using the BIRT Report
Configuration.
• BIRT 2.5 adds new instance
setting
13
Actuate Corporation © 2009
BIRT Scripting Demo
DEMO
See Hidden Slides for
Event Orders
19
Actuate Corporation © 2009
Agenda
BIRT Engine(s) Overview
20
Actuate Corporation © 2009
Report Engine
• Used to Generate Report Documents.
• Used to Generate Report Output (PDF, HTML, Paginated
•
•
•
•
HTML,WORD, XLS, Postscript)
Engine Creates task to implement operations.
One or Two Phase operation (Run Task then Render Task or
RunAndRenderTask)
DataExtraction Task for retrieving Data from a report document.
ParameterDetails Task for retrieving Parameter information,
including dynamic and cascading information.
21
Actuate Corporation © 2009
Report Engine Task
EngineConfig
Set configuration variables such as
Engine Home and Log configuration
Open Report Design and Documents. Create
Engine Task.
ReportEngine
Generate one or more tasks
Retrieve Parameters and
their properties
GetParameterDefinitionTask
Does not support Pagination, TOC,
Bookmarks.
RunAndRenderTask
DataExtractionTask
RunTask
RptDesign
RptDesign
XML
RptDesign
XML
Design
File
XML
Design
File
Design File
22
Actuate Corporation © 2009
RenderTask
RptDocument
RptDocument
Report
RptDocument
Report
Document
Report
Document
Document
Extract Data from Report Document
Generate Paginated
HTML, XLS, PDF
Document, Postscript,
XLS
Retrieve TOC and Bookmarks
Design Engine
• Used to Generate/Modify Report Designs, Templates and
Libraries.
• Can be used in conjunction with the RE API to modify designs
on the fly.
• Can be used within BIRT Script to modify designs on the fly.
• Create and delete report elements.
• Put report elements into slots.
• Get and set parameter values.
• Retrieve metadata from report elements, properties and slots.
• Undo/Redo
• Semantic Checks on report designs.
23
Actuate Corporation © 2009
Chart Engine - Two different Chart APIs
1. Model
2. Engine
• Create
• Edit
• Save/Load
• Bind Data
• Build
• Render
Optional Prepare Method.
Called before Bind Data. In
BIRT this sets up the Run Time
Context
24
24
Actuate Corporation © 2009
Chart Engine Flow – ChartEngine Generator class
Chart Engine
1. prepare
2. bind data
Chart Model
3. build
dv.SWT
dv.PNG
4. render
dv.JPG
dv.PDF
dv.SVG
dv.SWING
dv.BMP
25
25
Actuate Corporation © 2009
Device
Renderer
BIRT OSGi Startup
• Platform Class
• Used to startup required BIRT Plugins.
• Uses OSGi.
• Needed by DE API, CE API and the RE API
• Uses a PlatformConfig class to configure the startup.
• DesignConfig and EngineConfig extend the PlatformConfig.
• PlatformContext Class Determines location of Plugins.
• Factory used to create DesignEngine or ReportEngine
26
Actuate Corporation © 2009
Platform Startup
Platform
Used to startup OSGi and create Factory Objects. Static methods.
Startup
Start the Platform
Shutdown
Stop the Platform
createFactoryObject
Launch a plugin that implements the FactoryService Extension
DesignEngineFactory
Design Engine API
OSGILauncher
Startup
Optionally
implement your
own
IPlatformContext
IPlatformContext setPlatformContext
String Location=getPlatform()
PlatformFileContext
•Default PlatformContext
•Looks for Plugins in BIRT_HOME
27
Actuate Corporation © 2009
ReportEngineFactory
Report Engine API
PlaformConfig: EngineConfig/DesignConfig
PlatformServletContext
•Looks for javax.servlet.context.tempdir
•Creates platform directory in tempdir
•Uses getResourcePaths for /WEB-INF/platform to locate plugins
•Copies plugins and configuration to the tempdir/platform directory
Platform Startup Code for DE, CE and RE API
Design Engine Sample
Report Engine Sample
IDesignEngine engine = null;
DesignConfig config = new DesignConfig( );
config.setBIRTHome("C:/birt/birt-runtime2_5_1/ReportEngine");
try{
Platform.startup( config );
IDesignEngineFactory factory = (IDesignEngineFactory)
Platform
.createFactoryObject(
IDesignEngineFactory.EXTENSION_DESIGN_ENGINE
_FACTORY );
engine = factory.createDesignEngine( config );
IReportEngine engine=null;
EngineConfig config = new EngineConfig();
config.setBIRTHome("C:/birt/birt-runtime2_5_1/ReportEngine");
try{
Platform.startup( config );
IReportEngineFactory factory = (IReportEngineFactory)
Platform
.createFactoryObject(
IReportEngineFactory.EXTENSION_REPORT_ENGINE_
FACTORY );
engine = factory.createReportEngine( config );
Chart Engine Sample
PlatformConfig pf = new PlatformConfig();
pf.setBIRTHome("C:/birt/birt-runtime-2_5_1/birt-runtime2_5_1/ReportEngine");
ChartEngine ce = ChartEngine.instance(pf);
//non OSGi startup of CE
PlatformConfig pf = new PlatformConfig();
pf.setProperty("STANDALONE", true);
ChartEngine ce = ChartEngine.instance(pf);
28
Actuate Corporation © 2009
Notes:
If you are using the APIs in an application that
is already using OSGi and the BIRT
plugins are deployed, alter the code like:
Confing.setBIRTHome(“”); and do not do a
Platform.startup();
Only startup the platform once for the lifetime
of your application.
Engine Extras
• Using a supplied connection
• JNDI
• Connection Profiles
• Driver Bridge
• ODA App Context
config.getAppContext().put("OdaJDBCDriverClassPath",
"c:/birt/mysql/mysql-connector-java-5.0.4-bin.jar");
task.getAppContext().put("OdaJDBCDriverPassInConnection",
this.getConnection());
• ClassPath Management
• Set the Parent Class loader
config.getAppContext().put(EngineConstants.APPCONTEXT_CLASSLO
ADER_KEY, yourclass.class.getClassLoader());
• Add to the class path
config.getAppContext().put(EngineConstants.WEBAPP_CLASSPATH_K
EY, "c:/jars/mjo.jar");
29
Actuate Corporation © 2009
Calling the DE API from the RE API/Report Script
RE API Code
beforeFactory Script
IReportRunnable design = null;
//Open the report design
design =
engine.openReportDesign("Reports/Top
NPercent.rptdesign");
reportContext.getDesignHandle().
findElement("table1").drop();
ReportDesignHandle report =
(ReportDesignHandle)
design.getDesignHandle( );
report.findElement(“table1”).drop();
30
Actuate Corporation © 2009
Simple DE API exist for use in script as
well. See example.
BIRT Engine Demo
DEMO
31
Actuate Corporation © 2009
Agenda
BIRT Deployment
32
Actuate Corporation © 2009
BIRT Deployment Scenarios
APIs (DE API, CE API, RE API)
BIRT Tag
Libs
Chart Tag
Libs
Custom Servlet
J2EE AS
Web Viewer
Web Viewer
Plugin
RCP Application
Standalone Application
Paginated HTML, PDF, XLS, WORD, PostScript, TOC, Bookmarks, CSV
33
Actuate Corporation © 2009
Main Web Viewer Servlet Mappings
Web Viewer Servlet Mappings
frameset
run
preview
34
Actuate Corporation © 2009
Use this mapping to launch the complete AJAX based report viewer.
Contains toolbar, navbar and table of contents features. Run and
Render task are separated. This option will also create a
rptdocument file.
Use this mapping to launch the viewer without the navbar, toolbar or
table of contents. This mapping uses the RunAndRender task to
create the output and does not support pagination and does not
create a rptdocument. This mapping does use the AJAX framework
to allow cancelling a report.
This mapping is used to RunAndRender a report directly to an
output format, or to render an existing rptdocument directly to an
output format. It does not use the AJAX framework, but will launch
a parameter entry dialog.
BIRT WebViewer Structure
WebViewerExample
The default location for BIRT logs.
logs
Location for class files used in a Scripted Data Source.
scriptlib
Default location of Report Designs
report
webcontent
birt
ajax
JavaScript files used with the Viewer
pages
JSP Fragments used to build the Viewer
images
Images used by the Viewer
styles
CSS files used by the Viewer
WEB-INF
lib
Location for BIRT required Jars.
platform
plugins
35
Actuate Corporation © 2009
configuration
BIRT required runtime plug-ins.
Location for OSGi configuration files.
Custom Servlet Deployment
Use Singleton to launch Design or
Report Engine. Start Platform on
Servlet Startup and shutdown
Platform on Servlet destroy.
YourServletExample
logs
The default location for BIRT logs.
report
Default location of Report Designs
images
Default location for report images
WEB-INF
lib
Location for BIRT required Jars. Copy from
Runtime.
platform
plugins
configuration
36
Actuate Corporation © 2009
BIRT required runtime plug-ins. Copy from
runtime.
Location for OSGi configuration files. Copy
from runtime.
RCP Deployment
• Using the BIRT Plugins in Eclipse based applications
37
Actuate Corporation © 2009
WebViewer Utility Class see RCPViewer Example
• WebViewer.display()
• See Example for
Options.
• Used with external
browser or SWT
Browser Widget.
• Use the BIRT Runtime
download and add the
plugins to your project
– See example target
38
Actuate Corporation © 2009
Using the RE/DE API Plugins in an RCP application
• Do not set BIRT Home,
Do not startup the
Platform, and use
engines as normal.
• See RCPEngine
Example.
• Uses SWT Browser
Widget.
• Use the BIRT Runtime
download and add the
plugins to your project
– See example target
39
Actuate Corporation © 2009
BIRT Extensions Points
• BIRT is not just a tool but a framework.
• Predominant Extension Points.
• Emitter – Used to create additional output formats.
• ODA – DTP – Used to add customized Data Source Drivers
• Report Item – Used to extend the Palette with additional items.
• Chart Types – Used to add or extend chart types
40
Actuate Corporation © 2009
Resources
BIRT Exchange Community Site
Centralized hub for BIRT developers
• Access demos, tutorials, tips and techniques, documentation…
• Enables developers to be more productive and build applications faster
• Marketplace for applications
Explore
• Search/sort
• Rate, comment
• Forums
Download
• Documentation
• Software
• Examples
www.birt-exchange.com
41
Actuate Corporation © 2009
Contribute
• BIRT designs, code
• Technical tips
• Applications