Integrating BIRT Jason Weathersby BIRT PMC Jason Weathersby
Integrating BIRT Jason Weathersby, BIRT PMC
Jason Weathersby, Actuate Corp Integrating BIRT Agenda • • API Overview OSGi Startup and Engine Creation Report Engine API Design Engine API Using the DE API within the RE API Deployment Scenarios Common BIRT Extensions 1
Jason Weathersby, Actuate Corp Integrating BIRT High Level BIRT Architecture Report Designer Eclipse Report Designer 1 Eclipse DTP ODA 2 Report Engine Chart Designer 5 Eclipse WTP 3 Report Design Engine XML Report Design Data Transform. Services Charting Engine Generation Services Presentation Services 5 HTML PDF DOC XLS Print PS CSV 4 Data Report Document Data 2 2
Jason Weathersby, Actuate Corp Integrating BIRT Pipeline with respect to the APIs Report Designer Design Engine Chart Builder Chart Engine Report Engine Optional Java Events Java. Script Events Rpt. Design XML Design File Paginated HTML PDF Generation Phase Presentation Phase CSV WORD Report Engine XLS Post. Script optional Rpt. Document Report Document Example Web Viewer Contains 3
Jason Weathersby, Actuate Corp Integrating BIRT API OSGi Startup • Platform Class • Used to startup required BIRT Plugins. • Uses OSGi. • Needed by both the DE API and the RE API • Uses a Platform. Config class to configure the startup. • Design. Config and Engine. Config extend the Platform. Config. • Platform. Context Class Determines location of Plugins. • Factory used to create Design. Engine or Report. Engine 4
Jason Weathersby, Actuate Corp Integrating BIRT set. Platform. Context( IPlatform. Context ) Used to locate the OSGi Plugins. Platform. Config set. BIRTHome( location ) Set the location of the BIRT Plugins set. OSGi. Arguments( String[] ) Used to configure OSGi. Extends Engine. Configure BIRT Extends Implements IEngine. Config set. Log. Config( location, level ) Set logging variables (null for location will not create a file). Design. Configure BIRT Implements IDesign. Config set. Resource. Locator( IResource. Locator ) Used to build your own resource locator set. App. Context( Hash. Map ) Can be used to add Java Objects for scripting. set. Resource. Path( Resource. Location ) Used to retrieve resources – Libs, Images, etc. set. Resource. Locator( IResource. Locator ) Used to build your own resource locator set. Temp. Dir( location ) birt. data. engine. memcachesize (default 10 M) set. Max. Rows. Per. Query( rows ) Maximum Rows to Retrieve 5
Jason Weathersby, Actuate Corp Integrating BIRT Platform Used to startup OSGi and create Factory Objects. Static methods. Startup Start the Platform Shutdown Stop the Platform create. Factory. Object Launch a plugin that implements the Factory. Service Extension Design. Engine. Factory Design Engine API OSGILauncher Startup Optionally Data. Adapter. Factory Data. Engine. Factory implement your Data Apater API Data Engine API Model to Data own IPlatform. Context Location=get. Platform() Platform. File. Context • Default Platform. Context • Looks for Plugins in BIRT_HOME Report. Engine. Factory Report Engine API Plaform. Config: Engine. Config/Design. Config Platform. Servlet. Context • Looks for javax. servlet. context. tempdir • Creates platform directory in tempdir • Uses get. Resource. Paths for /WEB-INF/platform to locate plugins • Copies plugins and configuration to the tempdir/platform directory 6
Jason Weathersby, Actuate Corp Integrating BIRT Platform Startup Code for DE and RE API Design Engine Sample Report Engine Sample IDesign. Engine engine = null; Design. Config config = new Design. Config( ); config. set. BIRTHome("C: /birt-runtime 2. 2. 0 m 5 rc/birt-runtime-2_2_0/Report. Engine"); try{ IReport. Engine engine=null; Engine. Config config = new Engine. Config; config. set. BIRTHome("C: /birt-runtime 2. 2. 0 m 5 rc/birt-runtime-2_2_0/Report. Engine"); try{ Platform. startup( config ); IDesign. Engine. Factory factory = (IDesign. Engine. Factory) Platform. create. Factory. Object( IDesign. Engine. Factory. EXTENSION_DESIGN_ENGINE_ FACTORY ); engine = factory. create. Design. Engine( config ); Platform. startup( config ); IReport. Engine. Factory factory = (IReport. Engine. Factory) Platform. create. Factory. Object( IReport. Engine. Factory. EXTENSION_REPORT_ENGINE _FACTORY ); engine = factory. create. Report. Engine( config ); }catch( Exception ex){ ex. print. Stack. Trace(); } 7
Jason Weathersby, Actuate Corp Integrating BIRT Report Engine API • • • 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 Run. And. Render. Task) Data. Extraction Task for retrieving Data from a report document. Parameter. Details Task for retrieving Parameter information, including dynamic and cascading information. 8
Jason Weathersby, Actuate Corp Integrating BIRT Report Engine Task Engine. Config Set configuration variables such as Engine Home and Log configuration Open Report Design and Documents. Create Engine Task. Report. Engine Generate one or more tasks Retrieve Parameters and their properties Get. Parameter. Definition. Task Does not support Pagination, TOC, Bookmarks. Run. And. Render. Task Data. Extraction. Task Run. Task Rpt. Design XML Design File Render. Task Rpt. Document Report Document Extract Data from Report Document Generate Paginated HTML, XLS, PDF Document, Postscript, XLS Retrieve TOC and Bookmarks 9
Jason Weathersby, Actuate Corp Integrating BIRT Simple RE API Process Report. Engine Create the report engine. open. Report. Design(report) Open Design create. Run. And. Render. Task(design) Create an Engine Task. HTMLRender. Options() Set rendering options. set. Render. Options(options) Set the task render options. run() Run and Render the report. Engine. Config config = new Engine. Config( ); config. set. BIRTHome("C: /birt-runtime/Report. Engine"); IReport. Engine engine = null; try{ Platform. startup( config ); IReport. Engine. Factory factory = (IReport. Engine. Factory) Platform. create. Factory. Object( IReport. Engine. Factory. EXTENSION_REPORT_ENGIN E_FACTORY ); engine = factory. create. Report. Engine( config ); }catch( Exception ex){ } IReport. Runnable design = null; design = engine. open. Report. Design(“Top. NPercent. rptdesign"); IRun. And. Render. Task task = engine. create. Run. And. Render. Task(design); HTMLRender. Option options = new HTMLRender. Option(); options. set. Output. File. Name("output/resample/Top. NPer cent. html"); options. set. Output. Format("html"); task. set. Render. Option(options); task. run(); 10
Jason Weathersby, Actuate Corp Integrating BIRT Report Engine Important Methods Report. Engine Reporting Task – One Engine Supports Multiple Task open. Report. Design() Seven Open methods that include support for Filename, Input. Stream, and Resource. Locator. open. Report. Document() Six Open methods that include support for Filename, IDoc. Archive. Reader, and Resource. Locator. change. Log. Level(newlevel ) New Logging Level. . create. Get. Parameter. Definition. Task Used to retrieve Parameter information. create. Run. Task Used to create a rptdocument from a rptdesign. Engine. Task create. Render. Task Used to render a rptdocument to an output format. create. Data. Extraction. Task Used to extract report data from a rptdocument. create. Run. And. Render. Task Used to execute a rptdesign and produce an output in the selected format. 11
Jason Weathersby, Actuate Corp Integrating BIRT Engine. Task Important Methods Engine. Task Base Class for all Task. set. Locale(). Set Locale for the Report. set. App. Context(). Modify Application Context for the task. set. Parameter. Value(Parameter Name, Parameter Value). Set individual Parameter. set. Parameter. Values(Hash. Map map). Set all parameters for the report. validate. Parameters(). Verifies proper parameter types. close(). Close the task and release resources. cancel(). Cancel a running task. Requires new Thread. Does not cancel actively running Queries. get. Status(). Get the status of the currently running task. Not Started, Running, Succeded, Failed, Cancelled. 12
Jason Weathersby, Actuate Corp Integrating BIRT Run. And. Render. Task Important Methods Run. And. Render. Task Execute a rptdesign and emit an output. run(). Executes the report design and produces the selected output. set. Render. Options(IRender. Options). Setup Render Options for the Task. 13
Jason Weathersby, Actuate Corp Integrating BIRT Run. Task Important Methods Run. Task Execute a rptdesign and create a rptdocument. run(String path). Run the task and output the rptdocument to the path location. Can be folder. run(IDoc. Archive. Writer). IDoc. Archive. Writer Allows the user to implement a writer to output the report document. set. Page. Handler(IPage. Handler) Allows setting a callback on each HTML page generation. Progressive Viewing. 14
Jason Weathersby, Actuate Corp Integrating BIRT Render. Task Important Methods Render. Task Render a rptdocument to an output. render(). Render the output. Set Render. Options first. set. Render. Options(IRender. Options). Setup Render Options for the Task. set. Bookmark(Bookmark). Renders the page that contains the Bookmark. set. Instance. Id(Instance. ID). Renders the page that contains the Instance Id. set. Page. Number(Page. Number). Renders the page specified by Page. Number. set. Page. Range(Page. Range). Renders the page range. 15
Jason Weathersby, Actuate Corp Integrating BIRT Get. Parmeter. Definition. Task Important Methods Get. Parameter. Definition. Task Retrieve report parameter details. get. Parameter. Defns(boolean Indclude groups). Returns a collection of the report parameter definitions. get. Parameter. Defn(Parameter. Name). Returns a IParameter. Defn. Base for the given parameter. See Report parameter details. get. Selection. List(Parameter. Name). Used to retrieve values for a parameter that are either dynamic or static. get. Selection. List. For. Cascading. Group(Group. Name, Object array). -Iterative call Used to retrieve values for a cascaded parameter. Object array contains nothing for first level, 1 value for second level. etc evaluate. Query( parameter. Group. Name) Used prior to getting the selection list for cascaded parameter. Caches result set in memory. get. Default. Values( ) Returns Hash. Map of all parameters with there default values (Param. Name –Value Pair). get. Parameters() get. Parameter(Parameter. Name) Used to retrieve report parameter handles 16
Jason Weathersby, Actuate Corp Integrating BIRT Report Parameter Details IParameter. Defn. Base interface for all Parameters. get. Parameter. Type() Returns the type of parameter eg (Filter, List, Table, Group or Scalar) get. Type. Name() Returns Type Name listed above. get. Help. Text() Help Text for the Parameter get. Prompt. Text() Prompt Text for the Parameter get. Handle() Handle to parameter design IScalar. Parameter. Defn Scalar Parameter Definition. IParameter. Group. Defn Parameter Group Definition. get. Data. Type Parameter Data Type (Float, String etc). IScalar. Parameter. Defn Scalar. IScalar. Parameter. Defn Parameter Definition. Scalar Parameter Definition. get. Display. Format Parameter formatting. allow. Blank() Can a blank parameter value be used. See Parameters example for more details. 17
Jason Weathersby, Actuate Corp Integrating BIRT Data. Extraction. Task Important Methods Data. Extraction. Task Retrieve data from a report document. These are result sets from a bound element not a dataset. get. Result. Set. List() Array. List of all data bound elements. Hint Name elements such as tables to make it easier. select. Result. Set(result. Set. Name) Set the data element you wish to extract. set. Instance. ID(Instance. ID) Set Instance ID of the data element to extract. Easier to use select. Result. Set select. Columns(String[]) Select the columns you wish to extract. set. Filters(IFilter. Definition[]) Set simplistic filters on the resultset to cull returned data. extract() Extract the results returns IExtraction. Results, which has methods for getting the metadata and results. 18
Jason Weathersby, Actuate Corp Integrating BIRT Render. Options • • • Used to Configure Report Output location and format. Plugin must exist that emits the chosen format. Used by Run. And. Render and Render Tasks. IRender. Option options = new Render. Option(); options. set. Output. Format("html"); options. set. Output. File. Name("output/customers. html"); if( options. get. Output. Format(). equals. Ignore. Case("html")){ HTMLRender. Option html. Options = new HTMLRender. Option( options); html. Options. set. Image. Directory("output/image"); html. Options. set. Html. Pagination(false); } task. set. Render. Option(options); 19
Jason Weathersby, Actuate Corp Integrating BIRT IRender. Option Base interface for Rendering Reports set. Base. URL(Url. String). Used to prepend URL to action handler. set. Output. File. Name(Filename). Output to specific filename. set. Output. Format(Format. String). Output to format. Eg pdf, html set. Output. Stream( Output. Stream). Renders to the Output. Stream. set. Supported. Image. Formats(Format. String). Set the image formats that the render supports. eg “PNG; GIF; JPG; BMP; SVG”. set. Action. Handler(IHTMLAction. Handler). Implement an Action Handler to handle hyperlinks or use the default. set. Image. Handler(IHTMLImage. Handler). Implement an Image Handler to handle reading and writing images. IPDFRender. Option Specific PDF rendering options IHTMLRender. Option Specific HTML rendering options set. Embeded. Font(boolean). Specify whether fonts should be embedded in the output. set. Image. Directory(Directory). Set the directory that the engine will store images. set. Font. Directory(Directory). Specify location of fonts. set. Base. Image. URL(String). Prepend uri to images. Must be Server. Image. Handler or Your own. set. Embeddable(boolean). Remove HTML and Body tags. 20
Jason Weathersby, Actuate Corp Integrating BIRT HTML Image and Hyperlink Management HTMLImage. Handler Class used to handle writing image files for a report output. HTMLComplete. Image. Handler File Based Image Management. HTMLServer. Image. Handler Allows Creating images in a directory and prepending the img src attribute with a URL. Write your Own HTMLAction. Handler Class used to handle building URLs generated from the hyperlink editor. Write your Own 21
Jason Weathersby, Actuate Corp Integrating BIRT Design Engine API • • • 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. 22
Jason Weathersby, Actuate Corp Integrating BIRT Elements • • • Elements – Report Objects such as Table, Label, Style etc. Properties – Modify the Element state and often support inheritance. Discussed in ROM specification. Simple and Complex properties. Slots – Describes element - container relationships. For example a Report element contains slots for Data Sources, Data Sets, Report Body, etc. Represented by Slot. Handle. 23
Jason Weathersby, Actuate Corp Integrating BIRT Simple DE API Process Design. Engine Create the Design Engine. new. Session. Handle(Locale) Design. Session used to create reports, libs, etc create. Design() Returns a Report. Design. Handle. get. Element. Factory() Returns Element. Factory to Create Report Elements. get. Body() Returns Slot. Handle use add to add new report element. Dessign. Session. save. As() Save Report Design. Config config = new Design. Config( ); config. set. BIRTHome("C: /birt-runtime-2. 2. 0 m 5 rc/birtruntime-2_2_0/Report. Engine"); IDesign. Engine engine = null; try{ Platform. startup( config ); IDesign. Engine. Factory factory = (IDesign. Engine. Factory) Platform. create. Factory. Object( IDesign. Engine. Factory. EXTENSION_DESIGN_ENGINE _FACTORY ); engine = factory. create. Design. Engine( config ); }catch( Exception ex){ ex. print. Stack. Trace(); } Session. Handle session = engine. new. Session. Handle( ULocale. ENGLISH ) ; Report. Design. Handle design = session. create. Design( ); Element. Factory factory = design. get. Element. Factory( ); Grid. Handle grid = factory. new. Grid. Item( null, 2 , 1 ); design. get. Body( ). add( grid ); 24 ); design. save. As( "output/desample/sample. rptdesign"
Jason Weathersby, Actuate Corp Integrating BIRT Session. Handle keys Session. Handle Class used to create and modify report content. Can be used to open many designs. open. Module(). Four methods open a module. Support for Input. Stream or Filename. Does not matter if Lib or Rpt. Design. open. Library(). Six methods for opening a Lib. Support for Base URL, Filename and Input. Stream. URL is used for relative resources. open. Design(). Six methods for opening a rptdesign. Support for Base URL, Filename and Input. Stream. URL is used for relative resources. create. Design(). create. Design(Report. Name) Create a new report design. Returns a Report. Handle. Used in creating a template as well. create. Library(). Create a new library. Returns a Library. Handle create. Library. From. Template(). Create a new library based on a rpttemplate (Must be a lib). Returns a Library. Handle create. Design. From. Template(). Create a new report design based on a rpttemplate (Must be a Report). Returns a Report. Handle set. Resource. Folder(String). Location of resources. set. Resource. Locator(IResource. Locator). Set your own resource locator. 25
Jason Weathersby, Actuate Corp Add Elements Integrating BIRT to Slots. Drop Element from report. Getter/Setter for names, and Savingproperties the module. styles. find. Element, find. Data. Set, etc. ROM Report Object Model Handles Design. Element. Handle Base class for all report elements. get. Defn to get Element Definition for slots etc. get. Data. Sets, get. Parameters, Embedded Images, etc. Configuration Variables. get. Themes and import. Css. Styles Module. Handle Provides most of the common design functions. Scripts get. Before. Factory, initialize, set. Before. Render. Slot. Handles Library. Handle suchas get. Body. Handle to a Library. Report. Design. Handle Scripts set. On. Create, get. On. Page. Break, etc. Report Design Handle. Set simple specific properties like set. Width, set. Bookmark. Abstract class. Comments and Custom. XML. Data. Binding calls set. Data. Set and get. Column. Bindings. Report. Element. Handle Parameter Binding using param. Bindings. Iterator. Non. Visual Elements. get and set. Result. Set. Column. Report. Item. Handle get and set. Help. Text. Visual Elements. Includes Data, Position and Style Label. Handle to a Label Element Scripts. get. Content. Slot. Handle for contents. Data. Item. Handle to a Data Element Cell. Handle to a Cell. 26
Jason Weathersby, Actuate Corp Integrating BIRT Properties, Slots and Structures Sample Element. Detail. Handle Base Class Property Handles, Slot Handles, Structure Handles. Value. Handle get. Property. Defn - IElement. Property. Defn. Simple. Value. Handle Abstract Class - get. Value commands. Add. Item used to add to list. Member. Handle Member of structure. Property. Handle Top level property can reference a struct List. Structure. Handle Complex Properties (struct). Filter. Condition. Handle Element Filter Condition Computed. Column. Handle Computed Column Handle Slot. Handle Use Add Method to add content. get. Contents (DE List) get. Count Style. Rule. Handle to Element Style Highlight. Rule. Handle Highlight Rule Handle 27
Jason Weathersby, Actuate Corp Integrating BIRT Report. Item. Details Example <table name="My. Customer. Table" id="6"> <list-property name="highlight. Rules"> <structure> <property name="operator">ge</property> <property name="background. Color">#FF 0000</property> <expression name="test. Expr">row["CREDITLIMIT"]</expression> <expression name="value 1">0</expression> </structure> </list-property> <property name="width">100%</property> <property name="data. Set">Data Set</property> <list-property name="bound. Data. Columns"> <structure> <property name="name">CUSTOMERNUMBER</property> <expression name="expression">data. Set. Row["CUSTOMERNUMBER"]</expre ssion> <property name="data. Type">integer</property> </structure> 28
Jason Weathersby, Actuate Corp Integrating BIRT Element. Factory Used to create new Report Elements. Use container Slot. Handle. add. Produces Slot. Handle. Design. Element. Handle. Cast to specific handle Label. Handle label 1 = element. Factory. new. Label("Label 1" ); <cell id="6"> Slot. Handle label 1. set. Text("Customer"); Cell. Handle cell = (Cell. Handle) tableheader. get. Cells( ). get( 0 ); cell. get. Content( ). add( label 1 ); <label name="Label 1" id="7"> <text-property name="text">Customer</text-property> </label> </cell> 29
Jason Weathersby, Actuate Corp Integrating BIRT Structure. Factory Used to create new structures (complex xml). Use Property. Handle on container to add to list. Produces Highlight. Rule hr = struct. Factory. create. Highlight. Rule(); hr. set. Operator(Design. Choice. Constants. MAP_OPERATOR_GT); hr. set. Test. Expression("row["Customer. Credit. Limit"]"); hr. set. Value 1("100000"); hr. set. Property(Highlight. Rule. BACKGROUND_COLOR_MEMBER, "blue"); Property. Handle ph = th. get. Property. Handle(Style. Handle. HIGHLIGHT_RULES_PROP); ph. add. Item(hr); <list-property name="highlight. Rules"> <structure> <property name="operator">gt</property> <property name="background. Color">blue</property> <expression name="test. Expr">row["Customer. Credit. Limit"]</expression> <expression name="value 1">100000</expression> </structure> </list-property> 30
Jason Weathersby, Actuate Corp Integrating BIRT Calling the DE API from the RE API/Report Script RE API Code before. Factory Script IReport. Runnable design = null; //Open the report design = engine. open. Report. Design("Reports/Top. NPercent. r ptdesign"); report. Context. get. Report. Runnable(). design. Handle. get. Design. Handle(). find. Element("table 1"). drop(); Report. Design. Handle report = (Report. Design. Handle) design. get. Design. Handle( ); report. find. Element(“table 1”). drop(); 31
Jason Weathersby, Actuate Corp Integrating BIRT Deployment Scenarios APIs (DE API, CE API, RE API) BIRT Tag Libs Chart Tag Libs Custom Servlet J 2 EE AS Web Viewer Plugin RCP Application Standalone Application Paginated HTML, PDF, XLS, WORD, Post. Script, TOC, Bookmarks, CSV 32
Report. Engine. Service. java For Jason Weathersby, Actuate Corp Viewer Engine Details. Integrating BIRT Web. Viewer. Example The default location for BIRT logs scriptlib Location for class files used in a Scripted Data Source. report Default location of Report Designs webcontent birt ajax pages Java. Script files used with the Viewer JSP Fragments used to build the Viewer The Viewer example uses a Images used by the Viewer images. Platform. Servlet. Context. So by default. CSS thefiles plugins used byare the Viewer styles searched for in WEBINF/platform. WEB-INF lib Location for BIRT required Jars. platform plugins configuration BIRT required runtime plug-ins. Location for OSGi configuration files. 33
Jason Weathersby, Actuate Corp Integrating BIRT Use Singleton to launch Design or Engine. Report Start Platform Servlet Example –Report See Dynamic Exampleon Servlet Startup and shutdown Platform on Servlet destroy. Your. Servlet. Example logs The default location for BIRT logs. report Default location of Report Designs Use. Default location for report images Platform. Servlet. Context images WEB-INF lib Location for BIRT required Jars. Copy from Runtime. platform plugins configuration BIRT required runtime plug-ins. Copy from runtime. Location for OSGi configuration files. Copy from runtime. 34
Jason Weathersby, Actuate Corp Integrating BIRT Web. Viewer Utility Class see RCPViewer Example • • • Web. Viewer. display() See Example for Options. Used with external browser or SWT Browser Widget. 35
Jason Weathersby, Actuate Corp Integrating BIRT Using the RE/DE API Plugins in an RCP application • • • Do not set BIRT Home and use engines as normal. See RCPEngine Example. Uses SWT Browser Widget. 36
Jason Weathersby, Actuate Corp Integrating BIRT Common BIRT Extensions • • Data Tool Extension Tasks • Open Data Access ODA – new sources of data – New Project Wizard • Driver. Bridge - enhance existing ODA drivers • ODA UI - create new user interface – New Project Wizard BIRT Extension Points • Aggregates – Create new Birt. Script Total functions • Report Items – Add items to the report palette • Emitters – Allow output in new formats • Charts – Create new types of charts 37
Jason Weathersby, Actuate Corp Integrating BIRT Questions? • Webinar on Actuate Usage of BIRT www. actuate. de/BIRT-Online. Seminar-2 • BIRT Book set giveaway drawing at Actuate Booth. • Birtworld. blogspot. com • www. eclipse. org/birt 38
- Slides: 39