Robert Thornton ([email protected])Java ConsultantDaugherty Business Solutions
25 Apr 2006
The Eclipse Business Intelligence and Reporting Tools (BIRT) project comprises aset of open source plug-ins for Eclipse that you can use to create compelling reportsfor Web applications. Learn how to install BIRT V2.0, configure it for use with adatabase, employ its functionality to design dynamic reports and charts, and createtemplates for future reports.
Section 1. Before you start
About this tutorial
Business intelligence refers to collecting and analyzing business information.Reports are one main avenue for doing that and a key part of most organizations.Your company collects a lot of data about its business and performance. However, ifthat data isn't compiled and presented in an orderly way, key decision-makers basetheir choices on guesswork. By pulling raw data out of those disparate systems andpresenting it in an intelligent fashion, those decision-makers can make informedchoices that help steer your company in the right direction.
The Eclipse Business Intelligence and Reporting Tools (BIRT) project is a set ofopen source plug-ins for Eclipse you can use to create compelling reports for Webapplications. Using BIRT, you can create dynamic database-driven reports with a full
range of formatting capabilities. BIRT V2.0 supports Hypertext Markup Language(HTML) and Portable Data Format (PDF) report generation, and can embed thesereports seamlessly into existing Java™ Platform Enterprise Edition applications.BIRT reports can present data in lists, tables, and myriad chart types.
You can do most of what you need to do with BIRT through the BIRT ReportDesigner, in which you can drag and drop components to create rich reports. Forthose cases where you need to go beyond that, BIRT can call Java objects. BIRT isnot limited to working with a set number of databases. If you have a data source thatisn't Java Database Connectivity (JDBC)-accessible, you can use the Open DataAccess framework built into BIRT to write connectors to talk to any data source andpresent it as a tabular data source.
BIRT reports can combine data from multiple data sources and multiplerepresentations of the same data source all on the same reports. With compoundreports, you can combine charts, lists, and other data into one report.
Objectives
Our goal here is to help you get familiar with BIRT and with the BIRT ReportDesigner so you're prepared to connect to data sources and create dynamic reports.The tutorial also provides an overview of BIRT's formatting and layout abilities, aswell as template-creation capabilities.
Prerequisites
This is written for Java developers who will be generating reports or reportdevelopers who will be using BIRT, and whose skills and experience are at abeginning to intermediate level. You should have a general familiarity with Eclipseand installing plug-ins.
System requirements
To run the examples in this tutorial, you must have a system capable of runningEclipse (Microsoft® Windows®, Linux®, Solaris, AIX®, HP-UX, Mac OS X) with atleast 200 MB of free disk space.
Download and install the following tools and technologies:
• Java technology from Sun Microsystems or from IBM
• Eclipse SDK V3.1 or later
• The Eclipse Graphical Editor Framework (GEF) V3.1 run time
• The Eclipse Modeling Framework (EMF) V2.1 run time
Installing BIRT is a straightforward process consisting mainly of extracting variousfiles. Complete the steps at Eclipse.org's Installing BIRT to install and configureBIRT.
For this tutorial, you will connect to an Apache Derby database. To install it,download the Derby plug-ins for Eclipse and install them in your Eclipse installationdirectory.
Now you're ready to begin. Open Eclipse with the -clean option and look at BIRT.
The BIRT Report Designer
The first step in creating a report is to create a report project. Click File > New >Project to launch the New Project Wizard. Open the Business Intelligence andReporting Tools folder, select Report Project and click Next. Name the projectBirtTutorial and click Finish. Click Yes in the window prompting you to switch to theReport Design perspective.
Now, create a report by right-clicking the BirtTutorial project in the Navigator,pointing to New, then clicking Report. Name the report Employees.rptdesign. YourNavigator should appear similar to Figure 1 when you expand it.
Figure 1. The Navigator after creating the Employees Report project
The BIRT Report Designer perspective consists of three views:
• Palette -- The Palette contains the set of elements you can add to areport (such as labels, tables, and charts).
• Property Editor -- The Property Editor is just what it sounds like: a quickway to view and modify properties of a report or report element.
• Data Explorer -- In the Data Explorer, you configure the data sources thereport will talk to. (You'll learn more about the Data Explorer later in thistutorial.)
Generate your first report
Now you're ready to create your first report. Click and drag a Label element fromthe Palette onto the top of the report. Double-click inside the box created for thelabel on the report, then type the title Employee Salary Report and press Enter. Withthe label highlighted, switch to the Property Editor and make the title centered, bold,and with a size of X Large.
With something on the report, you want to look at it to make sure it worked. You canview the report in one of two ways: by previewing it or by running the report. TheBIRT Report Designer can quickly generate a preview of what the report will looklike. At the bottom of the report window, notice three tabs: Layout, Preview, andScript. Layout is currently selected. On this tab, you place the report elements on thereport. Click the Preview tab to see a preview of the report with your title, as shownin Figure 2. Also notice that the current date appears on the left side of the report.
Figure 2. The Preview view of the report
The second way to view the report is actually to run it. Right-click the report in theNavigator, point to Report, then click Run Report to launch the BIRT ReportViewer. As you see in Figure 3, the only difference between the two views is that theReport Viewer has a header section in which you can toggle the table of contents,rerun the report, export the data, and scroll through the pages of the report.
Figure 3. The Report Viewer when the report is run
Now you must add some header information to the report. Click and drag the Textelement from the Palette onto the report beneath the title. The Edit Text Item windowappears automatically. Add the following warning text:
Confidential! Property of My Company.This report is only to be viewed by:Jane CEOFred CFOSam Controller
My Company's privacy policy is located at http://mycompany.com/privacy.html.
Click OK and click Preview. This text gets the point across, but it should really bemore eye-catching. Switch the content type from Plain Text to HTML. Double-clickthe text box to bring up the Edit Text Item window again, then selectHTML/Dynamic Text from the drop-down list. Mark up the text to make it match thetext in Listing 1.
Listing 1. Rich-text warning message
<CENTER><H2>Confidential! Property of My Company.</H2></CENTER>
This report is only to be viewed by:<UL><LI>Jane CEO</LI><LI>Fred CFO</LI><LI>Sam Controller</LI></UL>My Company's privacy policy is located at <ahref="http://mycompany.com/privacy.html">http://mycompany.com/privacy.html</a>
When you're finished, click OK and click the Preview tab. Your report should nowlook like the preview shown in Figure 4.
Most of the interesting reports you'll create require some form of dynamic content.BIRT excels at dynamic reports, offering options that vary from lists and tables to awide array of charts.
Configure your database
To generate a report with a list of data from a database, you must have a databaseto talk to. You use the Apache Derby plug-in for this. To configure, complete thesesteps:
1. Right-click the BirtTutorial project in the Navigator. Point to ApacheDerby, then click Add Apache Derby Nature.
2. Right-click the project again, point to Apache Derby, and click StartDerby Network Server. A window appears informing you that the plug-inis trying to start the server.
3. Click OK and switch to the Console. If the database server startedsuccessfully, you should see the message Server is ready toaccept connections on port 1527. Also, a small green arrowshould appear on the project name in the Navigator.
With the database server running, create a schema and populate some data for the
report to use by right-clicking the project again, pointing to Apache Derby, andclicking ij (for Interactive SQL). This command embeds the ij client in the Console.In ij, type:
to create and connect to a database named BirtTutorial. This database requires theuser name birtTutorial and the password birtTutorial before connecting you to it forthe ij session.
Next, create the Employee table by typing the text shown in Listing 2 in the ijsession.
Listing 2. Text for the Employee table
CREATE TABLE employees(employeeid integer not nullgenerated always as identity (start with 1, increment by 1),lastname varchar(50),firstname varchar(50),title varchar(50),salary integer,raise integer,department varchar(50));
The last step in preparing the database is to add data to the table. Execute thestatement shown in Listing 3 to create default data in the ij session.
1. In the Data Explorer, right-click Data Sources and click New DataSource.The New Data Source window appears with five different data sourcetypes to select from.
2. Click JDBC Data Source and name it EmployeeDataSource. ClickNext.
3. On the resulting page, specify the connection string for the data source:
1. Add the Derby JDBC driver by clicking Manage Drivers.
2. On the Jar Files tab, click Add.
3. Navigate to Eclipse installationdirectory/plugins/org.apache.derby.core_10.1.2, then double-clickderbyclient.jar.
4. Click OK to return to the New Data Source window.
5. Select the driver org.apache.derby.jdbc.ClientDriver (v10.1), whichnow appears in the Driver Class list.
6. Type jdbc:derby://localhost:1527/BirtTutorial for thedatabase URL.
7. Type birtTutorial for the user name and the password, thenclick Test Connection.
8. When the test is successful, click Finish.
Create a data set
To display data from the data source on the report, you must create data sets for it.A data set represents the data available from the database to be put on the report.You can have many data sets for one data source. If your report were talking toseveral databases (or even to a database and a couple of external systems or files),each one would be a data source, and each query you wanted to display on thereport would be a data set for that data source.
Creating a data set is straightforward:
1. In the Data Explorer, right-click Data Sets and click New Data Set. TheNew Data Set window appears.
2. Name the new data set Employee Salaries, selectEmployeeDataSource as the data source and specify SQL SelectQuery as the data set type.
3. Click Finish. The Edit Data Set window appears. Type the followingStructured Query Language (SQL) query:
SELECT lastname, firstname, salary FROM employees
4. In the left pane of the window, click Preview Results. You should see theoutput of the query as shown in Figure 5. Click OK. Now, you're ready toput the dynamic content into the report.
Figure 5. Preview of the data set query
Use the data set on the report
You use a Table element to iterate over the rows of a data set and display thecolumns of it. Go to the Palette, and drag a Table element onto the report beneaththe Text element. When the Insert Table window appears, specify three columnsand one detail. Click OK.
Next, tell the Table element which columns of the data set should go into eachcolumn of the table. Do so by switching to the Data Explorer, expanding the datasets, and expanding the Employee Salaries data set. Drag the LASTNAME columnonto the first column in the table in the detail row. Notice that the table automaticallypopulates the header row for that column with the name of the column in the dataset. Next, drag the FIRSTNAME column into the middle column of the table and theSALARY column into the last column. Click the Preview tab to see the complete listof the employees of My Company, as shown in Figure 6.
Figure 6. Preview the report with the Employees table defined
Sort the table by last name by hovering your mouse over the table. The Table tabappears beneath the table in the left corner. Click that tab to make Table the activeelement. To sort the data:
1. In the Property Editor, click the Sorting tab, then click Add in theupper-right corner of the tab. A row appears in the Sort table.
2. Click in the first column of that row (the Sort Key column), then click thedown arrow that appears until you select LASTNAME.
3. Save the report and click the Preview tab.
The report is now sorted correctly.
Calculate the totals
One last piece of data is missing from the report: a total of all the salaries. Tocalculate the totals:
1. From the Palette, drag a Data element into the SALARY column in thefooter row. The Expression Builder window appears.
2. In the Category window at the bottom, select BIRT Functions, thenselect Total as the subcategory.
3. Double-click sum; Total.sum() appears in the Expression pane.
4. With the cursor positioned between the parentheses of sum, select theAvailable Data Sets category, select the Employee Salariessubcategory, and double-click SALARY.
5. Click OK and click the Preview tab to see the total salary for MyCompany at the bottom of the table, as shown in Figure 7.
Figure 7. Preview the new report total
Section 4. Customization
Now that you've created a basic dynamic report, you need to clean it up and providepolish so it looks professional. Some simple changes can help you get to that point.
Format numbering
To format the numbering in the table, select the salary cell and the salary footer inthe table. (Select multiple objects by pressing Ctrl and clicking the objects.). Now,
3. Select Currency from the Format Number as drop-down list, thenchange the symbol to be the dollar sign ($).
4. Select the Use 1000s separator check box.
5. Click General in the Properties pane, and make the column right-justifiedinstead of left. Right-justify the header and footer for that column, as well.
Filter information
Another customization you might consider is to hide the chief executive officer's(CEO's) salary. To do so, complete these steps:
1. Highlight the SALARY cell and switch to the Property Editor.
2. Click Visibility in the Properties pane and select the Hide Element checkbox.
3. Select the For specific outputs option.
4. Select the HTML check box.
5. Click the ... button to build the expression.
6. Type the expression row["LASTNAME"] == 'Conrad' to filter out theCEO's salary, then click OK.
7. Select the PDF check box, and type the same expression there. If youdon't select this check box, the CEO's salary would be hidden when thereport was viewed as a Web page, but not when a PDF was generated.Your report should now appear similar to Figure 8.
A better solution is to add the Title column from the database to the EmployeeSalaries data set:
1. Right-click Employee Salaries in the Data Explorer and click Edit.
2. Add the Title column to the select clause.Note that the order of the fields in the select clause doesn't matter.
3. Click OK, then go back to the Property Explorer visibility section andchange the expression to row["TITLE"] == 'CEO'. Now anyemployee with the title of CEO will have her salary hidden on this report.
Distinguish certain employees
The next step in customizing this report is to distinguish people from the salesdepartment. You can do this in any of several ways. A couple of options are to addthe department field to the Employee Salaries data set and change the sort criteriafor the table to sort first by department. Alternatively, you could provide some type ofcolor-coding to the report.
For this report, leave the sorting by last name intact. Instead, change the report toitalicize all the salespeople's names. Go back into the Employee Salaries data setand add the Department column to the select clause, just as you just did for thetitle. Now, change the row of the table to look different depending on whichdepartment the employee is in.
To edit the properties for a row, you must select the detail row. Hover your mouseover the table and click the Table tab that appears. Doing so brings up the outlinefor the table so you can click the entire row, as shown in Figure 9.
1. Open the Property Editor and click the Highlights tab.
2. Click Add and click the ... button at the top.
3. Use the Expression Builder to create the expressionrow["DEPARTMENT"] and click OK.
4. Select Equal from the second list and type "Sales" in the third box.Make sure that you include the quotation marks in the field. In this way,you can change the format of the row for all rows where the employee isin the Sales department.
5. Change the font, size, and color of the text for that row. Set the font toArial, blue, and italics.
6. Click OK, and preview the report. It should look similar to Figure 10.
What if my company has a large number of employees? You need to be able toallow management or human resources to pull up just one individual's information.You can use Report Parameters to limit the results shown to the user. With ReportParameters, you can prompt the user for information before the report is run. In thiscase, you'll prompt users to select a name:
1. Right-click Report Parameters in the Data Explorer and click NewCascading Parameter.
2. Change the name to EmployeeName and click Create New.
3. Name the data set EmployeeName, and type the query SELECTlastname, firstname FROM employees.
5. Select the new data set from the Data Set list.
6. Double-click the first row of the Value column in the grid below and selectlast name.
7. Double-click the Display Text column and select the same.
8. In the Properties area, name the parameter Last name and set theprompt text to Enter last name of employee.
9. In the second row, do the same with the name First name, then clickOK.
Now you need to tell the table to filter the results based on those parameters:
1. Select the table, switch to the Property Editor, then click the Filters tab.
2. Click Add in the upper-right corner of the tab.
3. Double-click the Expression column of the new filter criteria and switch tothe Expression Editor.
4. Use the Category and Sub-Category to highlight your new ReportParameter group, then double-click Last name. When you click OK, theExpression column should read params["Last name"].
5. Click in the Value 1 column and select build expression andLASTNAME from the data set. Click OK. That cell should readrow["LASTNAME"].
6. Add another filter criterion and set it for first name.
7. Right-click your report in the Navigator and click Run Report.
You'll be prompted to type a last name and first name for the employee you want tosee. When you type a last name, BIRT restricts the list of first names from which youcan select to only those where the last name matches your selection. You can alsouse the Preview window to see the results of this, but BIRT won't always prompt youto type the parameter values. In the upper-left corner of the Preview window, clickShow Report Parameters to specify new values to preview with.
To make your report particularly useful, it should present a visual indicator of howmuch of your salary costs are going to each department. You could list subtotalsbelow your table, but instead, let's put BIRT's charting capabilities to the test.
Switch to the Palette and drag a Chart element onto your report beneath the table.The New Chart Wizard opens. Select Pie Chart from the list of chart types and clickNext.
Specify where the data from the report is coming from. You need a new data set thatgroups the salaries together by department. Select the Use Data Set option, thenclick Create New. Name the data set Department Salaries, click Finish, andset the SQL query to SELECT department, SUM(salary) FROM employeesGROUP BY department.
Click OK, then select the new data set from the list. Next, specify the categorydefinition, which identifies each piece of the pie. Think of this definition as the sourcefrom which BIRT gets the labels for each slice in the pie. For this report, thecategories are the departments. Click and drag the Department column header inthe Data Preview table into the Category Definition box. When you release themouse button, BIRT populates the report with row["DEPARTMENT"].
The last step on this page of the wizard is to specify the slice size definition, whichspecifies what the chart uses to determine the size of each piece of the pie. You getthis data from the 2 column. Click and drag the 2 column header into the Slice SizeDefinition box. Your report preview area should now look like Figure 11. Click Next.
Figure 11. Chart preview area after setting the slice size definition
Format the pie chart
BIRT gives you a lot of control over the chart for formatting and setting JavaScriptevents. For now, you can add some simple formatting to the chart so people looking
1. Click Series in the left pane, then change the Value Series Title toDepartment Contribution.
2. Click Chart Area in the left pane and set the Chart Title to Salariesby Department.
3. Click Legend beneath Chart Area in the left pane and click Layout.
4. Set Orientation to Horizontal and Position to Below.
5. Click Finish, then click Preview.
Your chart should appear similar to Figure 12.
Figure 12. Previewing the finished pie chart
Create a bar chart
This report needs one more chart -- one showing the changes in salary for theemployees in the sales department between last year and this year. To create thischart:
1. Drag a new Chart element onto the report.
2. Select Bar Chart and the first subtype and click Next.
3. Define the data set to be used for this chart by selecting the Use Data Setoption, then click Create New.
4. Name the data set SalesSalaryAndRaise and click Finish.
5. Set the SQL query to:
SELECT lastname || ', ' || firstname, salary, raiseFROM employees WHERE department = 'Sales'
6. Click OK and select the new data set from the list.
7. Drag the 1 column, which represents the employee name, into theCategory (X) Series box, populating it with row["1"]. For the first Yseries, you must have a calculated value: salary minus the raise theemployee most recently received. So, select Series 1 from the list, thenclick fx to launch the Expression Editor for the data in this series. Use theboxes at the bottom to type this expression:
row["SALARY"]-row["RAISE"]
8. Select New Series from the top drop-down list in the Slice Size Definitionsection, then drag the Salary column header from the Data Preview intothe data box for that series.
9. Click Next to move on to formatting the chart.
Format the bar chart
To format the bar chart, click Series in the left pane and make the followingchanges:
• Change the Category (X) Series Title to Employee.
• Change the Value (Y) Series - 1 Title to 2005.
• Change the Value (Y) Series - 2 Title to 2006.
Click Chart Area in the left pane and change the Chart Title to Sales EmployeesSalary Changes. Click Finish, then click Preview. Your chart should look similarto Figure 13.
The report you've created so far is basic in appearance. Luckily, with BIRT V2.0, youcan create report templates that are designed once and reused to provide aconsistent, professional appearance for the reports created.
Create a template
To create a template:
1. Click File > New and click Template.
2. Name the template tutorial.rpttemplate and click Finish. A neweditor appears that looks similar to the Report Editor.
3. Drag the grid control from the palette on the left onto the template area.
4. Specify the grid to have one column and two rows.
5. Drag one label into each row. Change the top label to Acme, Inc. andthe bottom label to Annual Report.
With labels on the template, you can specify formatting and color options. Select thefirst label and switch to the Property Editor. After selecting General from the list onthe left, center the text, change the font to Arial, and change the font size to X Large.Then change the label's color to white and the background color to red. Repeat thesame steps for the second label, except set its size to Medium and its backgroundcolor to blue. Click the Preview tab: You should see a template similar to Figure 14.
Figure 14. Template with red and blue headings
You can also enhance templates to make them easier for report designers to use.Right-click the top label and select Create Report Template Item from the menu.For the instructions, specify Double-click to change the report heading.Repeat the process for the bottom label. For the instructions, specifyDouble-click to change the report subheading. Your template editor
Figure 15. Template with instructions for designers
The next step is to publish the template for use. Click File > Publish to TemplateFolder. Type Tutorial Template for the display name and TutorialDescription for the description. Then click Finish to publish the template.
Use the tutorial template
Now that you have created a template, it's time to put it to use. Click File > New >Report. For the report name, specify templateBasedReport.rptdesign andclick Next. In the window that appears, select the tutorial template and click Finish.A new editor opens for the report.
You can now customize the report headings:
1. Double-click the heading area, and type Tutorial Heading.
2. Click the subheading and type Tutorial Sub-heading.
3. Change your active editor to Employees Report in the Layout view.
4. Hold down the Ctrl key and select all the elements in the report.
5. Right-click the selected elements and click Copy.
6. Change back to templateBasedReport. Right-click the report and clickPaste to insert the table and the two charts from your earlier report.
The report elements you copied into the report layout area of the new report alsoneed the supporting data specified in the Data Explorer. Copy the data sources, datasets, and report parameters from the Employees report to the Template Basedreport. After copying the various elements, previewing the new report displays areport similar to Figure 16.
In this tutorial, you built a dynamic report using multiple data sets and showing datain multiple ways. You created two charts -- one with two series -- and learned somebasic formatting and layout techniques using BIRT V2.0. You also created a reporttemplate for use in future reports. From here, you can continue learning to formatreports in different ways or move on to more advanced topics, such as linking reportsections, building shared report components, and scripting reports.
BIRT V2.0 has two methods for sharing components across reports. Libraries allowyou to share report components such as data sources and visual report itemsamong multiple reports. When you update the library, all reports using it aredynamically updated. With templates, you can share the structure of reports acrossmany reports. The BIRT Designer comes with several templates, such as SimpleListing and Dual Column Listing. The list of available templates appears when you'recreating a new report.
You can also script BIRT V2.0 using Java and JavaScript code. Prior to BIRT V2.0,you could write event handlers only with JavaScript code. By writing event handlersin the Java language, you can debug the handlers using Eclipse. The BIRT ScriptEditor, used to code JavaScript event handlers, has also been improved in 2.0 toinclude code completion and syntax highlighting, making development of eventhandlers easier.
• See the developerWorks tutorial "Extract information from databases usingBIRT and Eclipse" to learn more about using and installing BIRT V1.0
• Visit the developerWorks Apache Derby project resources for articles andtutorials about the Derby database. Also visit the Apache Derby Web site formore information.
• Visit the developerWorks Java technology zone for extensive how-toinformation, tools, and project updates to help you develop with Javatechnologies and use them with IBM products.
• Expand your Eclipse skills by visiting the developerWorks Eclipse projectresources.
• Browse all of the Eclipse content on developerWorks.
• Stay current with developerWorks technical events and webcasts.
• Visit the developerWorks Open source zone for extensive how-to information,tools, and project updates to help you develop with open source technologiesand use them with IBM's products.
Get products and technologies
• Be sure to download the BIRT Report Framework V2.0.
• Get Java technology from Sun Microsystems or from IBM.
• Download the Eclipse SDK.
• Get the Eclipse Graphical Editor Framework (GEF) run time.
• Download the Eclipse Modeling Framework (EMF) run time.
• Get Apache Axis.
• See the latest Eclipse technology downloads at IBM alphaWorks.
• Build your next development project with IBM trial software, available fordownload directly from developerWorks.
Discuss
• The Eclipse newsgroups has lots of resources for people interested in usingand extending Eclipse.
• Get involved in the developerWorks community by participating indeveloperWorks blogs.
Scott DelapScott Delap is an independent consultant specializing in Java EE and rich Javaclients. He has presented papers at JavaOne and is actively involved in the desktopJava community. He is also the administrator of ClientJava.com, a portal focused ondesktop Java development. ClientJava.com is frequently featured all over the Web,from JavaBlogs to Sun Microsystems' Web site.
Robert ThorntonRobert Thornton has been developing in the Java language for six years and iscurrently a consultant for Daugherty Business Solutions. He works as a developerand architect on Java EE applications at various clients in the St. Louis, Mo., area.He has a strong focus on object-oriented development and works primarily in theJava and C++ languages.
