BAM Dashboards for Open ESB and Java CAPS

SUN MICROSYSTEMS BAM Dashboards for Open ESB and Java CAPS Version 1.0 September 29, 2008 Please send feedback to: [email protected]

- 1 of 42 -

Table of Contents Introduction .................................................................................................................................. 3 Scenario ........................................................................................................................................ 3 Environment ................................................................................................................................. 4 Tutorial Format ............................................................................................................................. 4 Project 1: Installing the iReport NetBeans Plug-in Downloading iReports Plug-in for NetBeans .................................................................. 5 Installing the iReport Plug-In .............................................................................................. 6 Verifying Plug-in Installation .............................................................................................. 6 Project 2: Establishing a Test Database Creating a Java DB Database ......................................................................................... 7 Creating a Database Table ............................................................................................... 8 Populating a Database Table ........................................................................................... 9 Viewing Table Data ........................................................................................................... 9 Project 3: Developing a Report with iReport Registering a JDBC Connection to iReport .....................................................................10 Creating an iReport Report ................................................................................................11 Adding a Pie Chart ............................................................................................................. 15 Previewing a Report Design ..............................................................................................19 Displaying an Accumulator on a Chart ..............................................................................21 Hiding Report Sections ...................................................................................................... 22 Project 4: Developing the BAM Dashboard Exploring the iReports Life Cycle ...................................................................................... 28 Filling an iReport with Data ............................................................................................... 30 Importing the JasperSoft Library ....................................................................................... 31 Exporting an iReport to HTML ........................................................................................... 33 Deploying the Web Application ........................................................................................ 34 Testing the Web Application .............................................................................................34 Auto-Refreshing the Web Page ........................................................................................36 Inserting Additional Test Data ...........................................................................................38 Summary ....................................................................................................................................... 39

- 2 of 42 -

Introduction The purpose of this tutorial is to introduce you to building a BAM (business activity monitoring) dashboard display using the NetBeans IDE. JasperSoft has created a NetBeans plug-in module for its iReport open source offering that allows you to create sophisticated reports for display in either rich clients or in browsers. Having a BAM capability is essential in informing application users of decision-impelling events. For example, Open ESB's Intelligent Event Processor (IEP SE) may process streams of incoming financial transactions and discover fraudulent activity. Users would likely want a dashboard where IEP output could be monitored via business graphics. This tutorial will get you started with the iReport NetBeans plug-in by developing a web application that reads data generated by the Java One 2008 PennyLotto IEP demo and constantly refreshes a pie chart summary. Here are the topics we'll cover: -

Installing the iReport NetBeans Plugin Establishing a Test Database Building a Report with iReport Developing the Auto-Refreshing Dashboard

Scenario Let's assume that you are either familiar with the PennyLotto IEP demo from Java One 2008 or have read another tutorial in this series titled “Event Processing in Java CAPS 6: Open ESB Technology.” You understand that as the PennyLotto IEPmodule determines potential fraudulent transactions, it dumps incident records to a file. This file could populate a database table containing the person's name and transaction amount. Since BAM is such an important part of many web applications written today, you wonder how to reflect the incident data in BAM business graphics. You want to work through the steps of building a web application that summarizes the database data in a pie chart on a dashboard. When you are done, you want to show your colleagues your NetBeans and iReport prowess at: Building a Test Database: This is a simple one-table Java DB database. The INCIDENT table contains the following columns: recordid, name, amount and timestamp. These table rows record fraudulent incidents that occur at PennyLotto. You'll populate the INCIDENT table with six records initially.

Building a Report with iReport: JasperSoft's iReport tooling provides a sophisticated design environment to define reports. An open source version is available for download. The tooling shields you from editing the XML specification file. It also makes the compilation and data filling steps easy as you iterate towards a report design you like. iReport is 100& and is developed atop the NetBeans framework. It is available as a stand-alone tool. However, in this tutorial, we will use the NetBeans plug-in version. First, we'll create a complete report with tabular data and our pie chart. Next, we'll hide the tabular data so that only our pie chart displays for our dashboard.

Developing the Auto-Refresh Dashboard: In MVC (model-view-controller) fashion, our iReport report specification is the view layer. We'll develop a servlet that acts as the controller to periodically refill the report view with fresh database data (the model) and redisplays the pie chart.

- 3 of 42 -

Environment You'll need a modern computer with at least 1GB of RAM (2GB is better) and about 600MB of free disk space. Although the JDK and NetBeans work on a broad range of operating systems, I'll assume that you are using Windows XP. You may still be successful with another operating system, but the instructions were written and tested on a Windows XP (SP3) laptop. You'll need to have with NetBeans 6 or an Open ESB build installed. NetBeans 6 can be downloaded from http://www.netbeans.org/. Several download options are available. Choose the option for “All” so that you'll have additional capabilities that may be useful in other tutorials. You can find the latest Open ESB build at https://open-esb.dev.java.net/Downloads_OpenESB_Addons_NB6.html. I favor using recent Open ESB builds as it gives me the latest bug fixes that may not have made it into the NetBeans download yet.

Tutorial Format In the pages that follow, you'll see a 3-column format. In the first column, we'll include headings to act as mileposts that to remind you of the purpose of the steps in the section. Hopefully, these headings will also be helpful later as you use this document as a reference. Each heading is listed in the table of contents to help you find a section quickly. In the second column, we've included detailed, step-by-step guidance on the keystrokes and mouse clicks required to accomplish the tasks. Along the way, you will find illustrations so you can compare what you see on your screen to what we intend. In the third column, you'll find narrative (in green) that provides background to the steps listed in the second column. We have included some conceptual topics, informal advice and some deeper technical tips here. Having them in a separate column hopefully keeps the second column more concise while providing some deeper insight into the projects.

- 4 of 42 -

Project 1: Installing the iReport NetBeans Plug-in In this project, we'll download JasperSoft's iReport plug-in module for NetBeans and install it. With the plug-in installed, you'll be able to use drag and drop and property windows to build your iReport definition rather than coding the details in an XML file. Downloading iReports Plug-in for NetBeans

Let's start out by creating a new directory for our tutorial efforts. We will also store software here that we download from JasperSoft's web site. Use Windows Explorer to create the C:\MyBAMTutorial directory.

We'll put everything we download and create in this tutorial into this directory.

Point your browser to JasperSoft's download page http://sourceforge.net/project/showfiles.php?group_i d=64348. This takes us to the sourceforge.net page where the open source version of iReport is available. Click on the Download link for iReport Plugin for NetBeans:

JasperSoft hosts it's community edition of its products as SourceForge.net.

Right-click on the iReport-nb-3.1.1-plugin.zip link and save the zip file in your C:\MyBAMTutorial directory. After the software is downloaded, find the zip file and expand it into the C:\MyBAMTutorial directory:

- 5 of 42 -

Download took about one minute for me on a broadband connection.

Installing the iReport Plug-In

Start your NetBeans. Use the Tools / Plugins sequence to display the Plugins Window. Click Downloaded tab and click Add Plugins button, Navigate to C:\MyBAMTutorial. Use Shift-click to select all three nbm files: ● heartbeat-plugin-nb-3.1.1.nbm ● iReport-nb-3.1.1.nbm ● jasperserver-plugin-nb-3.1.1.nbm

“nbm” stands for NetBeans module.

Click on Install and finish the wizard sequence by considering the license. Click Finish when you see the note that installation has been successful. Verifying Plug-in Installation

Check to see that the three plug-ins were installed by selecting the Installed tab shown below. Sort by category and find: ● ireport-designer from Tools category ● heartbeat from Uncategorized ● jasperserver-plugin from Uncategorized

Notice that when you click on a plug-in, you see a description of it displayed in the right panel. Here you learn a bit about the power of iReports.

Close the Plugins window. Your NetBeans installation has now been augmented with JasperSoft's powerful iReport report design, compile and test facility. - 6 of 42 -

Project 2: Establishing a Test Database The pie chart we'll include on our BAM dashboard will be driven by database content. We'll keep things real simple here. We will have just one table in our database. We'll use the bundled Java DB database that ships with NetBeans. We'll create our table and populate it with sample data. Creating a Java DB Database

In the Services panel right-click on Java DB node and select the Create Database option. For Database Name, enter FraudDatabase For User Name, enter admin For Password, enter admin

The admin/admin combination is pretty easy to remember.

Click OK. Watch as the jdbc:derby://localhost:1527/FraudDatabase [admin on ADMIN] line is added to list of connections. Right-click on this new database connection and select Connect. Expand the Tables node to see that no tables exist. Let's create one. Right-click on Tables and select the Execute Command option. This displays an SQL execution area where we can enter and execute SQL statements.

- 7 of 42 -

You'll appreciate the tight integration of database access and the NetBeans coding environment. It makes it easy to quickly change table contents and see changes reflected in your code that performs JDBC operations.

Creating a Database Table

In the SQL execution area, copy and paste the following statements that will create our INCIDENT table:

This syntax for the recordid column is a way to tell Java DB to automatically insert a sequential value whenever a new row is created.

CREATE TABLE INCIDENT ( RECORDID INTEGER PRIMARY KEY GENERATED ALWAYS AS IDENTITY, NAME VARCHAR(40), AMOUNT NUMERIC(15), TIMESTAMP VARCHAR(30) )

Click Run SQL tool to execute the CREATE TABLE statement:

Watch for a message like this to know that the SQL statement was processed: Executed successfully in 0.281 s, 0 rows affected. Line 1, column 1 Execution finished after 0.281 s, 0 error(s) occurred. Right-click on the Tables node and select Refresh. Your incident table appears:

Right-click on INCIDENT and select View Data to see that the table is empty as expected.

- 8 of 42 -

Populating a Database Table

Copy and paste the following statements into the SQL execution area and run them. This will add a few test incidents to the INCIDENT table: insert into incident (recordid,name,amount,timestamp) values(default,'Joe Doe',112.00,'2008-09-17T14:06:55.53-06:00'); insert into incident (recordid,name,amount,timestamp) values(default,'Joe Doe',122.00,'2008-09-17T14:07:55.53-06:00'); insert into incident (recordid,name,amount,timestamp) values(default,'Joe Doe',132.00,'2008-09-17T14:08:55.53-06:00'); insert into incident (recordid,name,amount,timestamp) values(default,'Sally Smith',122.00,'2008-09-17T14:06:55.53-06:00'); insert into incident (recordid,name,amount,timestamp) values(default,'Sally Smith',222.00,'2008-09-17T14:07:55.53-06:00'); insert into incident (recordid,name,amount,timestamp) values(default,'Bill Watkins',722.00,'2008-09-17T14:04:55.53-06:00');

Viewing Table Data

Right-click on INCIDENT and select View Data to verify that the six records have been added to the table:

Notice the “default” value inserted in the recordid column. As noted when we created the table, we defined this column to include a system-generated sequential value. So, default is a placeholder for that value to be inserted by Java DB.

If you ever need to clear all the rows from the table, enter the following command into the SQL execution area: delete from ADMIN.INCIDENT

- 9 of 42 -

Project 3: Developing a Report with iReport In this project, we'll use the iReport NetBeans plug-in to create an iReport definition containing rows of data from the INCIDENT table and a summary pie chart graphic. Then, we'll tailor the report so that only the pie chart appears since we just want business graphics to appear on our BAM dashboard. Registering a JDBC Connection to iReport

We need to let the iReport plug-in know that our new FraudDatabase should be the default target for all reporting. To register your JDBC connection to iReport, find the Report Datasource control at the top of the window:

Click on Report Datasource to display the Connections / Datasources window. Click the New button to identify a new datasource. In the Datasource window, select NetBeansDatabase JDBC connection and then click Next. In the Connection drop-down list, for Name, enter: FraudDatabaseConnection and then select the following connection: jdbc:derby://localhost:1527/FraudDatabase [admin on ADMIN] Click Test to see if iReport can “find” your database. Look for the Connection test successful! pop-up window as verification and click OK to dismiss the window. Click Save to record your selection and close the NetBeans Database JDBC connection window.

- 10 of 42 -

Test is sorta like the Ping feature that you can use in GlassFish when you create a new database connection pool and want to know if the pool can “see” the database before you create a JDBC datasource to use the pooled connections.

In the Connections / Datasources window, make sure that your FraudDatabaseConnection is the default by seeing that the Default check box is toggled one. Close the window:

Creating an iReport Report

To close the window, click on red X in the upper-right corner of the window since there is no Close or OK buttons. Sorta odd ...

With a database connection in place, we can now create our report page. Create a BAMDisplay project using the File / New Project / Web / Web Application sequence. For Project Name, enter BAMDisplay For Project Location, enter C:\MyBAMTutorial directory. Click Next Accept the defaults for server, Java EE version and Context Path by clicking Finish. An index.jsp page appears. Close it. On the BAMDisplay node in the Projects panel, use the File / New / Other / Report / Report sequence to begin creating a new iReport based upon a preconfigured datasource. For File Name, enter: PieChartByCulprit.jrxml Note: It is critical to include the .jrxml extension on the file name. Otherwise, you won't have access to the graphical Design mode. For Folder, enter: web/reports and click Next to move to the Query wizard window. For Connections / Data Sources, select FraudDatabaseConnection from the drop-down list.

- 11 of 42 -

The wizard step we skipped here by just clicking Finish provided the opportunity to select a framework like Visual Web JavaServer Faces. We don't need to create a user interface with one of these frameworks. The iReport capabilities will handle our view capabilities in our MVC (model-viewcontroller) pattern. The servlet we will create later will be our control. The database, of course, is our model.

Click the Design Query button:

The query design window appears as shown below. Next to Tables drop-down list (see below), select ADMIN from the drop-down list. The INCIDENT table appears in the list. Click and drag INCIDENT to the purple canvas area. Click on the check boxes for the NAME and AMOUNT columns:

Click the SQL tab (see the mouse pointer above) to see the generated SQL statements: SELECT INCIDENT."NAME" AS INCIDENT_NAME, INCIDENT."AMOUNT" AS INCIDENT_AMOUNT FROM "ADMIN"."INCIDENT" INCIDENT

- 12 of 42 -

This is pretty straightforward, but I think you can see by the WHERE, GROUP BY and HAVING options in the window that the queries can get much more sophisticated.

Click OK to return to the Query step in the wizard, then, click Next. When prompted for Fields, use the >> control (see below) to select all. Click Next:

Seems that the highlighted steps in the left panel (Group by here) don't match up with the currently displayed panels on the right (Fields here). Looks like a bug?

In the Group by wizard step, select INCIDENT_NAME from the Group 1 drop-down list, then click Next.

In the Layout wizard window, just click Next.

- 13 of 42 -

iReports provides a templating capability. Two template styles ship with the product: columnar and tabular. You can add your own standard templates to the design environment. We'll just take the default here (columnar).

Click Finish and you report design appears in the report editor window:

Note the Designer control that appears in the upper-left of the panel.

In the Report Inspector, find summary click on it:

If the Designer mode doesn't display, see the earlier note about needing to include the .jrxml extension for File Name. If the Report Inspector doesn't appear, use the Window menu bar option and find the Report designer menu option to hide and display panels that the iReports plug-in has added to your NetBeans environment.

The summary section is the most important one for us as this is where we will create our pie chart that summaries data delivered by the query and presented in tabular form in the details section of the report. Even though you can click around on the design canvas to find the report sections, the Report Inspector provides the most convenient and precise way of navigating the report structure. - 14 of 42 -

The default height for the summary section is to short. Click on summary in the Report Inspector and view the Properties window. Set its band height to 400

Adding a Pie Chart

The band height describes the height of the summary section in number of pixels. A height of 400 pixels should be plenty to display a big 3D pie chart for our dashboard.

From the Palette, drag and drop a Chart to the summary area of the canvas. The chart type window appears. Select the second pie chart called Pie 3D and click OK: There are so many charting styles to choose from. In the spirit of “keeping it simple,” we'll select a pie chart here. You can experiment with some of the others later.

A pie chart appears in the summary area.

- 15 of 42 -

Things can be complicated and overwhelming at first since there are so many options. To ease the learning curve, download JasperReports and explore the demos. You'll find the free community download at: http://www.jaspersoft.com/re gistration.html?d=jr_downloa d.html&m=&h=&f= Sign up, download (jasperreports3.1.0-project.zip or higher), unzip and explore your jasperreports3.1.0\demo\samples\charts directory. Start with the readme.txt file.

Click on the pie chart and enlarge so it fills most of the summary area.

Right-click on the pie chart and select Chart Data (as shown above). The Chart details window appears. Notice that there are two tabs: Dataset and Details. On the Dataset tab, set the Increment type to Group. On the Increment group field, set it to INCIDENT_NAME:

This signals to the designer to create an accumulator that counts all rows in a group. We specify INCIDENT_NAME as the group name, so the accumulator will hold the total number of records for each of the “culprits” in our INCIDENT database. Was with chart types, there is so much power in iReports that we can't cover in a tutorial like this. You see that you can condition incrementing of group counters. You also see that sub data sets can be specified. I found in-tool documentation to be scarce and the documentation on the web to be inadequate. Clearly, JasperSoft wants the new user to buy their “Definitive Guides” advertised here: http://jasperforge.org/website/ire portwebsite/IR%20Website/iRep ort_documentation.html?group_i d=243&header=project&leftnav= yes&target=ireport

- 16 of 42 -

Select the Details tab. In the Key expression field click the pencil edit icon shown below at the right:

The Expression editor window appears. Click Fields and then double-click on INCIDENT_NAME field to add $F{INCIDENT_NAME} to the expression canvas. Click Apply:

- 17 of 42 -

The Key expression tells the chart builder what the basis is for each pie-shaped piece of the chart. Here we specify that each pie is to represent a unique culprit in our database table.

You can click around on the panels in the Expression Editor to build the expression or you can just copy and paste the expression here into the top panel.

In the Value expression field, click the pencil edit icon at the right. The Expression editor window appears. Click Variables and then double-click on the INCIDENT_NAME_COUNT variable to add $V{INCIDENT_NAME_COUNT} to the expression canvas as shown below.. Click Apply. In the Label expression field, click the pencil edit icon at the right. The Expression editor window appears. Click Label and then double-click on the INCIDENT_NAME field to add $F{INCIDENT_NAME} to the expression canvas. Type + " - "' and then click Variables. Double-click on the INCIDENT_NAME_COUNT variable to add $V{INCIDENT_NAME_COUNT} to the expression canvas as shown in the diagram below. The final expression should read: $F{INCIDENT_NAME} + " - " + $V{INCIDENT_NAME_COUNT} Click Apply. Here is how the completed Details tab looks:

- 18 of 42 -

The Value expression communicates what will drive the size of the individual pieshaped pieces. In our case, we'll utilize the group counter that is available for individual names. This group counter was created as a result of our selection of INCIDENT_NAME as the increment group in the Dataset tab earlier.

The Label expression lets us specify how we want to assemble the label for each pie-shaped piece. Here we are indicating that we want the label for each piece to be the concatenation of: - Culprit name - A space, a hyphen, a space - Count of the number of incidents reported for the culprit

Select Close to dismiss the Chart details window. Save your work. Previewing a Report Design

Click on the Preview View control:

Your report appears:

- 19 of 42 -

The Preview facility is pretty powerful. It works our report specification through a threestep life cycle. First, it compiles the .jrxml file into a .jasper file object representation. Second, it fills the object representation with data from the data source. Third, it exports the results into HTML to display in a panel.

Click back on the Designer control to return to Designer mode. In Report Inspector, right-click on top level node (labeled null now) and select Properties:

Set the Report name field to CulpritPieChart and select Close:

- 20 of 42 -

It is important for every report to have a report name. Having null as a report name would cause some interesting debugging later as we drive the filling and exporting of our report in our servlet.

Displaying an Accumulator on a Chart

Let's add a total field to at the bottom of the chart to show the total number of incidents that are included. Click the Designer control if you need to in order to be in Designer mode. Click and drag a Static Text palette item below the pie chart:

Double click on the new field and change Static text to Total Incidents: Change the static text field's Horizontal Alignment property field to Right. Click and drag a Text Field palette item to the right of the Total Incidents: static text field. Click on the new text field and in its properties window, find the Text Field Expression property. Click ... to edit this property value. The Text Field Expression editor appears. Clear the expression area by deleting $F{field} Now, to add our variable, select Variables and then double-click on REPORT_COUNT to add $V{REPORT_COUNT} to the expression canvas. Next, in the third column select toString() String. This makes the final expression read: $V{REPORT_COUNT}.toString() Select OK to complete the expression editing. Stretch out the text field on the canvas so the value appears like this under your pie chart.

- 21 of 42 -

Sometimes, point and click features can make something easy hard. Here, all we want to do is enter: $V{REPORT_COUNT}.toString()

It is probably easier to just type (copy and paste) the expression into the editing area. It's nice to know that the point and click facility is there though. It can be helpful when considering more complicated expressions.

Preview again and notice that the count for total incidents displays:

Hiding Report Sections

It's great that iReport can generate tabular reports with rows and columns full of database data in addition to business graphics like pie charts. However, for our business dashboard, we may want only business graphics. So, how can we eliminate the tabular data and retain the pie chart? An iReport design is made up of sections. A quick look at the Report Inspector panel shows how data is grouped into sections for display: ● ● ● ● ● ● ● ● ●

title pageHeader columnHeader INCIDENT_NAMEGroupHeader detail INCIDENT_NAMEGroupFooter columnFooter pageFooter summary

We would like to hide all the sections except for the last one, the summary section. That is where our pie chart is located.

- 22 of 42 -

All these sections have a Print When Expression property that we can use to turn off printing. Click on title in the Report Inspector and then look in the Properties panel to find the Print When Expression property:

As the documentation at the bottom of the properties panel indicates, we can enter an expression here. When the expression returns blank or true, this section will be printed. OK, what expression would work? Let's establish a boolean variable and stuff it with true when we wanted all of our hidden sections to print and false when we wanted just the pie chart to appear. Then, let's include a Print When Expression for each section we want to hide. That expression will evaluate the boolean parameter and control display of the individual sections.

- 23 of 42 -

If the Print When Expression evaluates to blank or a true (boolean) value, the section will print. Sure, we could just delete the unwanted selections, but using Print When Expression is more elegant. What if we wanted to restore the tabular display based upon input from the user at our dashboard display?

First we need to create the boolean parameter and give it a default value by clicking on the XML tool to view the underlying XML statements for our report design. Add the tag shown below:

Here is the statement for easy copy and paste:

Use Alt-Shift-F to reformat the XML once you have added the statement. Save your work. Return to Designer mode by clicking on the Designer tool.

- 24 of 42 -

This is easy enough to understand. We name the parameter and declare it to be of Java type Boolean. Then, we instantiate a Boolean with the value set to false.

We now want to reference the isReportBodyToPrint parameter in the Print When Expression for the sections we want to hide: ● title ● pageHeader ● columnHeader ● INCIDENT_NAMEGroupHeader ● detail ● INCIDENT_NAMEGroupFooter ● columnFooter ● pageFooter For each of the sections listed above, click on it in the Report Inspector window and then find it's Print When Expression property in the property window. Click the Print When Expression property to display the expression editor. Either use the menus (select Parameters and then double-click on isReportBodyToPrint) or just copy and paste the expression below: Again, the point and click features of the editor are overkill for what we are doing here. Just copy and paste the desired expression into the expression creation area.

For cut and paste convenience, here is the expression: $P{isReportDataToPrint} Make sure you perform the same edit of the Print When Expression for each of the sections listed above before moving on.

- 25 of 42 -

Click on the Preview View control to see your report appear. Now, you are prompted for the value of the isReportDataToPrint parameter. Just click OK to accept the default we set (false).

We are prompted for the parameter value to allow use to test both true and false paths. By clicking OK, we accept the default which we set in this part of our parameter definition:

Notice that only the summary section appears so all you see is your pie chart. Section hiding mission was accomplished! It would be nice to have a heading displayed over our pie chart. We turned off the title section, but click on the pie chart and look in the Properties panel for an alternate way to label it. Find the Title Expression property and set is as shown below. Also adjust the Title Font as shown:

There are lots and lots of customization options. You can look forward to exploring them later on your own. Let's move on.

- 26 of 42 -

Click on the Preview control. Again, accept the default value of the isReportDataToPrint parameter and you'll see our finished pie chart:

Before we leave report design, set the isReportDataToPrint parameter to true when we preview and see if our tabular data appears along with the pie chart. Note: If you don't make any changes between previews, the report is not regenerated and you aren't prompted for parameter values. So, click on the XML control to view the XML. An easy way to make a change is to use Alt-Shift-F to reformat. After you do that, click the Preview control and answer true when prompted for isReportDataToPrint. The hidden sections are unhidden: Use the Zoom drop-down list in the upper-right corner (as illustrated here with the mouse cursor) to zoom out so you can see your entire report without scrolling.

- 27 of 42 -

Project 4: Developing the BAM Dashboard We have our pie chart ready for display, now we need a way to display it so it can be automatically refreshed periodically to display the latest data. In this project, we'll explore the life cycle for iReport generation and we'll create a servlet that periodically regenerates the iReport and displays it in a browser page. Exploring The report design (PieChartByCulprit.jrxml) provides the iReports the specification for a web page to be generated that Life Cycle displays our report. iReports has a four-step life cycle as illustrated below:

During Design, you use the standalone iReport tool or the iReport NetBeans Plug-in to create a remote specification as a .jrxml file. The Compile step takes the .jrxml file and produces an object representation stored in a .jasper file. Design and Compile typically form an iterative cycle during design time with frequent previews taken to assess progress. The preview generation actually performs the Fill and Export steps so the completed report can be previewed in the design environment. Once the specification is complete, the Fill and Export steps are invoked programmatically to read the latest database data, file the reports object structures and export the finished report to it its destination (rich client, web browser, PDF, ...) We can drive the entire four-step process programmatically. However, we don't have to do the compilation phase at runtime as this is done at design time when we use the Preview control to populate and display our report. The .jasper file created during compilation will be deployed as part of our web application. - 28 of 42 -

We'll create a servlet to do the filling and exporting steps at run time. Let's get started. Right-click on the BAMDisplay node in the Projects panel and use the New / Servlet sequence to start a new servlet. For Class Name, enter DisplayPieChart For Package, enter piechart and click Next. Accept the defaults for Servlet Name and URL Pattern(s) by clicking Finish. Your new servlet appears in the Java editor.

Let's address the filling step first by adding code to the processRequest method. Clear out the skeleton code that was initially created for the method:

- 29 of 42 -

Note that we are skipping the step in the wizard where we can pick a visual component framework like Visual Web JavaServer Faces or Struts. That's because we will let iReport generate our user interface based upon our .jrxml file. In MVC (modelview-controller) speak, our servlet will be just the controller while our iReport specification drives the generation of the view layer at runtime.

Filling an Add (copy and paste) the following Java statements iReport with to perform report filling. This takes care of Data populating the compiled report from your INCIDENTS table based upon the query you built during report design: // Fill Report ServletContext context = this.getServletConfig().getServletContext(); String reportName = "PieChartByCulprit"; String reportDirectory = "/reports/"; String compiledFileName = context.getRealPath(reportDirectory + reportName + ".jasper"); File reportFile = new File(compiledFileName); System.out.println("*** Filling report"); Map parameters = new HashMap(); parameters.put("ReportTitle", "Culprits Report"); parameters.put("BaseDir", reportFile.getParentFile()); JasperPrint jasperPrint = null; String dbURL = "jdbc:derby://localhost:1527/FraudDatabase;user=admin;password=admin"; Connection conn = null; try { Class.forName("org.apache.derby.jdbc.ClientDriver").newInstance(); conn = DriverManager.getConnection(dbURL); jasperPrint = JasperFillManager.fillReport(compiledFileName, parameters, conn); System.out.println("*** Report succesfully filled from file " + compiledFileName + " from database " + conn); } catch (Exception ex) { System.out.println("*** Could not create compiled jasper file: " + ex.getMessage()); } finally { try { conn.close(); } catch (SQLException ex) { System.out.println("*** Could not close connection after filling report"); }

You see lots of errors as designated by all the yellow and red icons along the left margin. The errors are caused by missing imports. Insert the following import statements at the top of your code right below the package piechart statement: import import import import import

javax.servlet.ServletContext; java.io.File; java.sql.Connection; java.sql.DriverManager; java.sql.SQLException;

- 30 of 42 -

That takes care of some of the problems, but the editor can't still find JasperPrint and the JasperFileManager classes. Let's focus on this now. When you installed the iReport NetBeans plug-in, a JasperSoft library was added to your NetBeans environment. Let's import that library into our project to address our two “class not found” problems. Importing the JasperSoft Library

Right-click on the BAMDisplay node in the Projects panel and select Properties. In the Properties window, select the Libraries node and use the Add Library button to display a list of libraries installed in your NetBeans environment. Scroll down the list of Available Libraries and select JasperReports 2.0.5-snapshot. Click Add Library and then OK.

- 31 of 42 -

The NetBeans Library feature is a convenient one. A library is a collection of one or more jar files containing class definitions needed by a programming API. iReport (the design time tool) and JasperReports (the runtime environment) require a bunch of jar files to be able to do compilation, filling and export. If you use the Tools / Libraries menu option and look inside the JasperReports library, you will see that it includes about 30 jar files. It sure is convenient to have them in a single library that you can add to your project rather than having to add each one individually. Thanks to NetBeans for providing the Libraries facility and thanks to JasperSoft for automatically installing their library complete with all the jar files we need.

Return to the Java editor window and click on each of the yellow light bulb icons and elect to have NetBeans import the class definition from the library we just added:

This adds the following import statements to the top of your servlet code: import net.sf.jasperreports.engine.JasperFillManager; import net.sf.jasperreports.engine.JasperPrint;

Use F9 (Build / Compile) to compile the servlet and check for errors. You should see ”BUILD SUCCESSFUL” in the Output panel indicating that our code is syntactically correct. Let's move on to the last step in the iReport report lifecycle – exporting the filled report objects. We'll export to HTML so we can display our report in the browser.

- 32 of 42 -

Exporting an iReport to HTML

Below the code you just added for filling the iReport objects with database data, copy and paste the following statements. These export an HTML representation of the filled, compiled report: // Export Filled Report to HTML response.setContentType("text/html;charset=UTF-8"); PrintWriter out = response.getWriter(); System.out.println("*** Exporting report to HTML"); String HTMLOutFileName = "../docroot/FraudIncidentReport.html"; try { JasperExportManager.exportReportToHtmlFile(jasperPrint, HTMLOutFileName); System.out.println("*** Successfully exported to HTML file: " + HTMLOutFileName); } catch (JRException ex) { System.out.println("*** Could not export report " + compiledFileName + " to HTML"); }

You will see one error. The editor can'tfind the JasperExportManager class. To solve this, add the following import statement below your package statement:

import net.sf.jasperreports.engine.JasperExportManager;

Once again, use F9 (Build / Compile) to compile the servlet and check for errors. You should see ”BUILD SUCCESSFUL” in the Output panel indicating that our code is syntactically correct. Let's test our servlet by first building and deploying our web application.

- 33 of 42 -

Deploying the Web Application

Deploy your BAMDisplay web application to GlassFish so we can test the servlet. Right-click on BAMDisplay in the Projects panel and select Build. Watch the Output panel to see the If your GlassFish instance isn't up and running when reassuring message: “BUILD SUCCESSFUL.” Right-click on BAMDisplay in the Projects panel and select Undeploy and Deploy. Again watch the Output panel for progress messages.

Testing the Web Application

you deploy, it will be automatically started. This can make the first deploy of a session a lot slower than subsequent ones. My first deployment took about 90 seconds.

Right-click on your DisplayPieChart.java node in the Projects panel and select Run. The following popup window appears: This will result in the following URL that we could use from the browser to invoke our servlet: http://localhost:8080/BAMDisplay/DisplayPieChart

Accept the default URI by clicking on OK. Drum roll please ... the browser displays ... and nothing ... just a blank page! Humm ... Let's check the GlassFish V2 Output panel for errors:

That's what we hoped for based upon the System.out.println statements we included in our servlet code.

- 34 of 42 -

If you see a ConnectException referencing port 1527, it means that you need to go to the Services panel and connection your FraudDataBase connection.

So, what's up? Well, maybe it really did work? Revisit the following lines of code in our servlet: String HTMLOutFileName = "../docroot/FraudIncidentReport.html"; JasperExportManager.exportReportToHtmlFile(jasperPrint, HTMLOutFileName);

Note that the JasperExportManager is instructed to put the generated HTML into FraudIncidentReport.html in the docroot directory. The docroot directory is the top-level document directory for GlassFish's built-in web server. Use Windows Explorer to find your file in docroot:

Display the HTML file and your pie chart should appear as shown above. OK, it did work as we specified, but that won't work for our end user. It is unreasonable to ask him/her to search for the generated file to display it in the browser.

- 35 of 42 -

You can see that my GlassFish is installed under the C:\openesb directory. Yours will likely be in another place.

AutoRefreshing the Web Page

If this pie chart page is going to become part of a dashboard, we really have two problems to solve. First, it needs to display when we hit the servlet's URL instead of just landing invisibly in the docroot directory. Second, it needs to refresh periodically to Dashboard users wouldn't like having to constantly hit reflect the latest database contents. Let's return to the servlet's Java code and add the following at the bottom to solve the two problems:

the Refresh control on their browser to refresh the pie chart.

// Insert to control refresh and to locate graphics System.out.println("*** Inserting statements inside tag"); BufferedReader inputStream = new BufferedReader(new FileReader(HTMLOutFileName)); String htmlLine = ""; while ((htmlLine = inputStream.readLine()) != null) { out.println(htmlLine); if (htmlLine.equals("")) { out.println(""); out.println(""); } } out.close(); System.out.println("*** Successfully inserted and in section"); }

You'll need to add the following import lines to the top of your servlet to resolve “class not found”: import java.io.BufferedReader; import java.io.FileReader;

Use Alt-Shift-F to reformat your code and F9 to recompile it to check for errors. Right-click on BAMDisplay in the Projects panel and select Build. Watch the Output panel to see the reassuring message: “BUILD SUCCESSFUL.” Right-click on BAMDisplay in the Projects panel and select Undeploy and Deploy. Again watch the Output panel for progress messages. Right-click on your DisplayPieChart.java node in the You can also use the following URL to invoke the Projects panel and select Run. servlet:

http://localhost:8080/BAMDisplay/DisplayPieChart

- 36 of 42 -

As the pie chart displays in the browser window, watch for the page to refresh every 15 seconds. Since the data in the pie chart isn't changing, you'll have to watch the browsers refresh indicator. Look in the Output panel for further verification of the refresh. Every 15 seconds, you should see the following block of output indicating that the servlet is refilling the iReport objects from the database with each refresh cycle:

Great. You saw the browser refresh and you saw the System.out.println statements generate play-byplay to stdout with each refresh cycle, but it would be nice to see the chart change, right? To do that, we'll have to change the content of the database. In the Services panel, find your INCIDENT table again:

Right-click on INCIDENT and select View Data. That brings up a SQL command area populated with select * from ADMIN.INCIDENT. At the bottom, you see the rows that are currently in the table.

- 37 of 42 -

For Mozilla Firefox, the refresh indicator is the circle of dots in the upper-right corner below the red X:

Inserting Additional Test Data

With your pie chart page still displaying in the browser, copy and paste the following insert statements into the SQL command area and then click the Run SQL tool to execute them. This will give our pie chart more data to display: insert into incident (recordid,name,amount,timestamp) values(default,'Joe Doe',412.00,'2008-09-17T14:10:55.53-06:00'); insert into incident (recordid,name,amount,timestamp) values(default,'Tom Tilman',100.00,'2008-09-17T14:07:55.53-06:00'); insert into incident (recordid,name,amount,timestamp) values(default,'Tom Tilman',732.00,'2008-09-17T17:08:55.53-06:00'); insert into incident (recordid,name,amount,timestamp) values(default,'Bill Watkins',122.00,'2008-09-17T14:06:55.53-06:00'); insert into incident (recordid,name,amount,timestamp) values(default,'Bill Watkins',222.00,'2008-09-17T14:07:55.53-06:00'); insert into incident (recordid,name,amount,timestamp) values(default,'Bill Watkins',722.00,'2008-09-17T14:04:55.53-06:00');

Watch the pie chart page refresh and see the pie chart change. Click the Run SQL tool again to execute this batch of insert statements a second time to see additional changes on the next refresh cycle. With 18 records in the database, here is how the chart displays:

Success! Our dashboard displays automatically to show the current contents of the underlying database.

- 38 of 42 -

●

Summary

We accomplished quite a bit in the four projects. Let's review by revisiting the highlights of each: Project 1: Installing the iReport NetBeans Plug-in ●

We started out by installing the iReport plugin for NetBeans. iReport is a Java application built atop the NetBeans framework. We could use iReport as a stand-alone tool. However, we chose to download the version that plugs into an existing NetBeans installation and runs alongside other plug-ins that you have in your NetBeans environment.

●

iReport, created by JasperSoft, provides design, compilation and preview capabilities for report generation. Under the covers it uses JasperSoft's JasperReports to fill reports with database data and export the finished product to formats like HTML and PDF.

●

JasperSoft makes both iReport and JasperReports available in community edition form free for download and use from the Web.

Project 2: Establishing a Test Database ●

We built a test database to contain fraud incidents that might be generated by the Java One 2008 PennyLotto IEP demo. PennyLotto features the Intelligent Event Processor (as provided by the IEP Service Engine) and watches streams of financial data. It generates alerts when it detects fraudulent behavior.

- 39 of 42 -

●

For convenience, we used the built-in Java DB (Derby) database in NetBeans and we built a new FraudDatabase. When the new Java DB database was built, a JDBC connection was automatically created for us in the Services panel that we could use to access its contents.

●

We used the SQL execution area and the JDBC connection to create a simple INCIDENT table containing columns for recordid, name, amount and timestamp. We populated the table with some sample data.

Project 3: Developing a Report with iReport ●

Our first step in building our report was to register our JDBC connection to the iReport plug-in. We tested that connection to make sure that iReport could "see" FraudDatabase in Java DB.

●

We created our BAMDisplay web application project and started building the PieChartByCulprit.jrxml iReport specification.

●

Initially, we had to specify the query we would base our report upon. We kept it simple by selecting only the name and amount columns since this is all the data we anticipated needing in our BAM dashboard business graphics. Actually, we ended up using only the name data.

●

We specified that the query data was to be grouped by name since we were thinking ahead that our business graphic would be a pie chart and each pie piece would represent a unique culprit.

- 40 of 42 -

●

We used a default report template but learned that iReport allows us to create our own standard templates and include them in the tool. The default template showed our data in tabular form.

●

We did a lot of detail work getting the pie chart configured. The key decisions we were to: ● Accumulate totals based upon group change and defined group to mean the name of our culprit ● Have each pie piece be based upon a unique culprit name ● Base the size of the pie pieces on the value of the group (name) accumulator ● Label each piece by concatenating the culprit's name with the accumulator count (number of times his/her name appeared in the query result set)

●

We added a label at the bottom of the pie chart to show how many total incidents were represented in our report.

●

We began pondering how to hide the tabular report data that we didn't want to show on our BAM dashboard. We used a boolean parameter and print expressions for each unwanted section to condition printing based upon the parameter's default value we set in the XML view of the .jrxml report specification.

●

We tested our report with iReport's preview feature and were happy with the report specification. Next step was to "drive" the filling and exporting of the report via a servlet.

- 41 of 42 -

Project 4: Developing the Dashboard ●

We reviewed the four-step life cycle of a report in iReport and JasperReports. We saw that the Design and Compile steps had been the primary focus of our design time work so far. However, some Fill and Export work had been done also during report preview.

●

We turned our attention to driving Fill and Export programmatically from a servlet so the user could see the report as a HTML page displayed in a browser.

●

Servlet programming become the focus as we created the servlet and utilized JasperSoft's API to fill the report from our INCIDENT table in Java DB. Then, we used the API to export the filled report objects into HTML form. An HTML file was generated successfully in GlassFish's docroot directory.

●

Having the end user have to manually find the generated report and display it in the browser wasn't meeting our expectations. The servlet should automatically display the report in the browser and automatically refresh the contents of the report periodically to show fresh database data.

●

So, we added a bit of code in our servlet to augment the HTML that was generated by the export API. Specifically, we added a tag to set a refresh interval. We also added a tag so that the servlet could find generated graphics files produced during export.

●

We tested our servlet and watched it work on updated data from the INCIDENT table.

I hope that you enjoyed this tutorial and would enjoy hearing from you. Please provide feedback to: [email protected].

- 42 of 42 -