Chapter 12. Debugging Event Handlers
The report debugger tool in BIRT provides functionality similar to other debugger frameworks, such as those in Java and C++ IDEs. The BIRT report debugger enables users to run reports step by step, set breakpoints, inspect instance properties, and watch and evaluate variable values in certain contexts. Using the debugger supports advanced report developers in spotting the errors in report designs quickly and making it easy to understand and identify exceptions during run time.
Unlike the standard Java debugger, the report debugger is based on the report object model tree. The report debugger provides the following functionality:
• Syntax checking of JavaScript expressions
• Debugging JavaScript event handlers
• Debugging Java event handlers
• Debugging report execution exceptions
• Inspecting report iteminstance and variable values
Based on the standard Eclipse debugging framework, the report debugger framework enhances the Eclipse built-in debugging features.
BIRT report debugger consists of the following parts:
• Report JavaScript debugger
• Report Java EventHandler debugger
In earlier versions of BIRT, the Java EventHandler debugger required setting an Eclipse workbench start-up parameter. In the current release, the new mechanism allows direct debugging of the report engine in the JVM.
The JavaScript debugger is implemented as a BIRT Report Script Virtual Machine (VM). The VM extends the standard Eclipse debug extension point and communicates directly with the Eclipse Debugging Framework. This VM handles all script debugging tasks, such as managing breakpoints, communicating with the engine task thread, and reporting to eclipse listeners. Figure 12-1 presents the BIRT Debugger architecture.
Figure 12-1 BIRT Debugger architecture
Checking the syntax of JavaScript expressions
BIRT Report Designer’s expression builder and script editor support writing JavaScript. Both editors validate the code by checking for syntax errors. The checking validates only JavaScript grammar not the semantics of the scripts.
The expression builder supports checking the code for syntax errors, as shown in Figure 12-2, in the following two ways:
• Selecting the Validate button. Information about the syntax error appears below the expression builder title bar.
• Choosing OK. A warning message appears if the script editor detects a syntax error. Choosing OK on the message saves the code. Choosing Cancel closes the message and returns focus to the expression builder.
Figure 12-2 Checking for JavaScript syntax errors in the expression builder
The script editor validates code dynamically. As the developer types JavaScript code, the editor validates the syntax and uses a red cross mark on the left border to indicate any line containing an error.
The line containing the error is marked and the exact location of the syntax error is highlighted, as shown in Figure 12-3.
Figure 12-3 Checking for JavaScript syntax errors in the script editor
A description of the error appears in a text box when the developer moves the mouse pointer over the error indicator on the left border, as shown in Figure 12-4.
Figure 12-4 Displaying a syntax error message in the script editor
Debugging JavaScript event handlers code
Users can set breakpoints on JavaScript code at specific execution points. During debugging, execution stops at a breakpoint and the user can inspect variables in the current context.
To debug JavaScript code, switch to the script editor and set a breakpoint by double clicking the left border at a specific line.
The BIRT report debugger uses the standard Eclipse debugging feature. This chapter provides only basic details about the debugger main components. Refer to the Eclipse documentation for more information about the debugger.
You manage the debugging or running of reports in the Debug perspective. To open the Debug perspective, choose Window→Open Perspective→Other→Debug, as shown in Figure 12-5.
Figure 12-5 Selecting the Debug perspective
The Debug perspective and its views are shown in Figure 12-6.
Figure 12-6 The upper portion of the Debug perspective
The Debug perspective contains the following views:
• Debug view
The Debug view shows reports you are currently debugging as well as any others you were debugging before you terminated them. This view includes processes and threads associated with the reports. An example of a debug view is shown in Figure 12-7.
The launch configuration entry appears at the top of the tree structure for each report you are debugging.
Each configuration has a debug target. A debug target is a running instance of a JVM executing code. Debug targets have properties that are useful for understanding the context in which the code is executing, the Java command line and JVM parameters, and the class path information.
The debug view displays suspended threads for each report you are debugging. Each thread in your program appears as a node in the tree under the debug target.
You can think of a stack frame as a method invocation. When one method invokes another, a stack frame is added to the top of the stack. When the method returns, that stack frame is removed from the top of the stack. An example of a stack frame appears as selected in Figure 12-7.
The Debug view provides the main buttons in Table 12-1 to control the debugging process, as shown in Figure 12-7.
Table 12-1 Debugger user interface buttons
• Variables view
Displays information about the variables associated with the stack frame selected in the Debug view, as shown in Figure 12-8.
• Breakpoints view
Lists all the breakpoints you currently have set in your workspace. Figure 12-9 shows a single breakpoint in the Breakpoints view.
Figure 12-9 List of breakpoints containing one breakpoint
Double-click a breakpoint to display its location in the script editor. You can delete, add, enable, or disable breakpoints. You can group breakpoints by working set or set hit counts.
Displays selected variables defined and manipulated in the script code, as shown in Figure 12-10.
The script editor and other views used by the Debug perspective appear in the lower portion of the Eclipse workbench, as shown in Figure 12-11.
Figure 12-11 Script, Console, and Outline views
• Script editor
Shows the script you are debugging in the debug and report design perspectives.
In Script, to set a breakpoint, double-click the vertical border on the left side at a specific line, as shown in Figure 12-12. The breakpoint appears in the border as a blue circle. The breakpoint is also added in the breakpoints view, as shown in Figure 12-9.
Figure 12-12 Setting a breakpoint
Shows the report structure in the Debug and Report Design perspectives. In the Debug perspective, this view shows only the scripts defined in the report design, as shown in Figure 12-11.
• Console view
Displays a variety of consoles depending on the type development and the current user settings.
The Process Console in the Debug perspective, as shown in Figure 12-11, displays the output of a process and accepts keyboard input to a process. The Process Console displays the following three kinds of text:
• Standard error
• Standard input
• Standard output
To specify different colors for these kinds of text, choose Window→Preferences. Then, in Preferences, expand Run/Debug and select Console.
Debugging Java event handler code
To set breakpoints on Java event handler code, use the standard Eclipse Java Development Tools (JDT) user interface. The JDT UI (org.eclipse.jdt.ui) plug-in implements the Java-specific user interface classes that manipulate Java elements. Packages in the JDT UI implement the Java-specific extensions to the workbench. During report execution, the report engine stops at each specific breakpoint. Developers can then inspect report item instances and variable values in the current context.
Debugging report execution exceptions
Exceptions are one of the most evident symptoms of execution errors. You can set breakpoints on certain exception classes when an exception occurs. Exception breakpoints stop execution whenever an exception of a selected type is thrown. This functionality is directly inherited from the JDT debugger and has the same capabilities. When a selected exception occurs, the report engine stops execution, and the report item instance and variable values can be examined in the current context.
Exception breakpoints can be viewed, enabled, or disabled using the standard Breakpoints view. Choosing Add Java Exception Breakpoint from the Breakpoints view activates these breakpoints, as shown in Figure 12-13. Alternatively, add a Java exception breakpoint by choosing Run→Add Java Exception Breakpoint.
Figure 12-13 Selecting an exception breakpoint
Execution can be stopped when the exception is either caught or uncaught, or both. The breakpoint appears in the Breakpoints view as shown in Figure 12-14. Enable or disable these breakpoints using the context menus in the Breakpoints view, the Java Editor ruler, and the script editor ruler.
Figure 12-14 Viewing a breakpoint in Breakpoint view
Using exception breakpoint debugging can be very helpful when you work on complex reports. For example, if a column in a report has an invalid data type, every time the report is run, the report engine throws a DataException. If the report uses multiple data sets or libraries, the exact column definition is not easy to find. In that situation, add a breakpoint exception for DataException and debug the report. When the DataException occurs again, the debugger stops the execution at the specific breakpoint. Inspect the current report context in the Variables view to identify the data set and the library names. The reportContext and rowInstance variables are shown in Figure 12-15. Knowing the data set makes locating and correcting the column definition to fix the error into a straightforward task.
Figure 12-15 Inspecting variables
Creating a debug configuration
Use the standard Eclipse debug launch configuration interface to start the report debugger. Set specific report debugger options on the configuration page. Ideally, use only one launch configuration type for both report and code debugging. To run a report in the Debug perspective, create a Report debug configuration by choosing Run→Debug Configurations. Figure 12-16 shows the Main page, which contains the key configuration settings for the Report debug configuration type.
Figure 12-16 Settings for a Report debug configuration
In Main, configure the following settings:
• Name
The name of the debug configuration. Good practice is to use the report name as the configuration name to aid in distinguishing among multiple configurations.
• Report file name
The path to the report file to debug. Debugging either a report design or a report document is available, depending on the task type.
• Engine home
The BIRT report engine home path. By default, BIRT uses the same engine that starts the debugger. Specify an external engine home to test the report using a different version of BIRT runtime libraries. The external report engine home typically points to a BIRT run-time folder, for example, C:irt-runtime-2_6_0ReportEngine.
• Temp folder
The temporary working folder for the report debugging process. By default, this folder is the system temp folder.
• Task type
The engine task type to use for the debug process. Table 12-2 lists and describes the available types:
Table 12-2 Engine task types for debugging a report
• Debug Type
The available types of debugging: All, Java, or JavaScript.
• Output
The available output format types for the debug process: DOC, HTML, PDF, PostScript, PPT, or XLS.
To open the generated output file when the debug process completes, select Open generated file when finished.
Launching the debug configuration establishes a connection between the debugger and the running report. You can then use breakpoints, stepping, or expression evaluation to debug your program.
How to create a debug configuration
The following section shows how to create a launch configuration to debug a BIRT report. The report name is ProductsByProductLineDBG.rptdesign.
1 Open a BIRT report in BIRT Report Designer.
2 Choose Run→Debug Configurations. Debug Configuration appears.
3 From the list of launch types, select Report. Then, choose New launch configuration, as shown in Figure 12-17.
Figure 12-17 Selecting New launch configuration
Debug Configuration creates a default report launch configuration named New_configuration, as shown in Figure 12-16.
4 In Name, type the name of the report to debug. By default, a new configuration uses the currently opened report as the file to debug. Change the name and other debug settings as required. For example, in Output, select the output format for the report.
5 If you are debugging a Java event handler, set the Java Classpath to ensure the report engine can find the event handler class. Choose Classpath, as shown in Figure 12-18. In Classpath, choose Add Project, Add JARs, or Add External JARs, according to the location of the eventhandlers.jar file.
Figure 12-18 Setting the classpath to Java event handlers in a project
6 Choose Apply to create the report debug configuration.
Tutorial 3: Debugging a report that contains Java and JavaScript code
This tutorial provides step by step instructions about how to debug a report that contains Java and JavaScript event handlers. The report example in this tutorial uses the Classic Models sample database and displays the car sales, grouping the data by country and customer. Additional analysis in the report highlights the orders having prices above the median price in fuschia and the orders having prices below the median price in yellow. The orders for the product line selected by the user appear in bold font. The report uses a JavaScript event handler to implement the highlighting and a Java event handler to set the bold font for certain rows.
Compiling the Java event handler class requires the coreapi.jar and scriptapi.jar files to be in the build classpath. These libraries are provided in the BIRT runtime package. Download the BIRT report engine runtime archive (.zip) file, birt-runtime-2_6_0.zip, from the Eclipse BIRT web site. Unzip the file in your environment.
To prepare to perform this tutorial, download the example project, DebugReportExample.zip containing SalesByCountry.rptdesign, from http://www.actuate.com/birt/contributions. This tutorial provides instructions about how to import the project into your workspace and how to debug the report.
Task 1: Preparing the report for debugging
This task assumes you have already uncompressed the example project into your workspace and opened BIRT Report Designer.
1 Import the project to the workspace.
1 Choose File→Import.
2 In Import, choose General→Existing Projects into Workspace as shown in Figure 12-19.
Figure 12-19 Importing an existing project
2 On Import Projects, in Select root directory, type the path to the workspace folder in the file system or choose Browse to find the folder.
3 Select the DebugReportExample project, as shown in Figure 12-20.
Figure 12-20 Selecting the project to import
Choose Finish. Navigator displays the imported project.
4 Expand the project to review its contents, as shown in Figure 12-21. The project contains the report design and supporting files, such as the Java event handler class DataItemProductNameEH.java and the logo image ClassicMogels.jpg.
Figure 12-21 Reviewing the project in Navigator
5 Choose the Problems view to confirm that the project compiled properly. If you see errors similar to those in Figure 12-22, update your Java build path to correct the paths to the scriptapi.jar and coreapi.jar libraries. If you do not see errors, proceed to step 7.
Figure 12-22 Reviewing errors in Problems view
6 Update the Java Build Path.
1 In Navigator, right-click the DebugReportExample project and choose Properties from the context menu.
2 In Properties, select Java Build Path. Errors indicate the missing libraries. In JARs and class folders on the buildpath, select coreapi.jar and scriptapi.jar, as shown in Figure 12-23, and choose Remove.
Figure 12-23 Removing JARs from the build path
3 Choose Add External Jars. JAR Selection appears.
4 Navigate to the folder containing the libraries. Press the Ctrl key and select coreapi.jar and scriptapi.jar. Choose Open.
The JARs are added to the build path as shown in Figure 12-24.
Figure 12-24 Adding external JARs to the build path
5 In Properties, choose OK. The errors in Problems disappear. If errors remain, right-click the DebugReportExample project. Choose Validate.
7 In Navigator, double-click SalesByCountry.rptdesign to open the report design. The report layout looks like the one shown in Figure 12-25.
Figure 12-25 Viewing the layout of the report design
8 Choose Preview to run the report. Enter Parameters appears.
9 In pProductLine, choose Planes from the drop-down list, as shown in Figure 12-26. Choose OK.
Figure 12-26 Selecting a parameter
The report preview looks like the one in Figure 12-27. The orders displaying in dark gray on the image and in fuchsia on your screen have a price greater than the median price of $1814.40. The orders having a price less than the median price are displayed in a light gray color, which displays silver on your screen. Orders for planes appear in a Bold font.
Figure 12-27 Previewing the SalesByCustomer report
Task 2: Setting a JavaScript breakpoint
In this task, you set breakpoints in JavaScript code. During debugging, you stop at a specific execution point and inspect variables.
1 Choose Layout to return to the layout editor.
2 In Outline, expand Scripts and Table. Select the onCreate method, as shown in Figure 12-28. In the editor, choose Script. The code appears in the script editor.
Figure 12-28 Selecting the onCreate script
3 In Script, to set a breakpoint, double-click the gray border at the left side of the following line:
if ( vOrderPrice > vMedianPrice );
The breakpoint appears in the gray border as a blue circle, as shown in Figure 12-29.
Figure 12-29 Setting a JavaScript breakpoint
Another way to add a breakpoint, as Figure 12-30 shows, is to right-click the gray border to the left of the line on which to add the breakpoint and from the context menu, choose Toggle Breakpoint.
Figure 12-30 Using Toggle Breakpoint
Task 3: Setting a Java breakpoint
To debug a Java event handler, open the Java source file in the Java editor and set breakpoints. Use the same technique to create a breakpoint as for a JavaScript event handler.
1 In Navigator, right-click DataItemProductNameEH.java. From the context menu, choose Open. The file opens in the Java editor.
2 Choose Window→Open Perspective→Other→Debug to open the Debug perspective.
3 To set a breakpoint, double-click the gray border to the left of the following line, as shown in Figure 12-31. Alternatively, place the cursor in the line of code and choose Run→Toggle Breakpoint.
Figure 12-31 Setting a Java breakpoint
String ProductLine = ( String )data.getRowData( )
.getColumnValue( "dsProductLine" );
4 Choose the Breakpoint view to review the list of the breakpoints, as shown in Figure 12-32.
Figure 12-32 Reviewing breakpoints
Task 4: Create the debug configuration
In this task, you set up the debug configuration. The default configuration uses the current opened report design as the default report file to debug. Change this file name and other debug settings as required. Then, debug the report on your workstation by running the debug configuration.
1 Choose Run→Debug Configurations. Debug Configuration appears.
2 From the list of launch types, select Report. From the toolbar, choose New launch configuration. A new configuration appears, as shown in Figure 12-33.
Figure 12-33 Setting up a debug configuration
3 In Name, type:
SalesByCustomer
5 In Output, select:
Open generated file when finished
Leave the suggested default values for the rest of the settings.
6 Set the Java Classpath. Add the path to the event handler class to ensure the report engine can find the class.
1 In Debug Configurations, choose Classpath.
2 In Classpath, select User Entries and then choose Add Project. Project Selection appears.
3 Select the DebugReportExample project as shown in Figure 12-34. The list of available projects includes projects in your workspace, which is likely to be different from the list shown in Figure 12-34.
Figure 12-34 Adding a project to the Java classpath
Choose OK. DebugReportExample is added to the classpath.
7 In Debug configurations, choose Apply to complete the creation of the debug configuration.
Task 5: Debugging the report
Debugging supports performing the following tasks:
• Stepping through the source in the script and Java editors as it executes.
• Managing breakpoints from the script editor and the breakpoints view.
• Examining variable values in the variables view.
• Evaluating expressions and viewing the results.
• Following the output of the program in the console view.
To make programs easier to debug, do not put multiple statements on a single line. Most of the debugger features operate on a line basis. For example, you cannot step over or set line breakpoints on more than one statement in a line.
1 Choose Debug. The debugging environment may take a few moments to start. Debug displays the status of the launch process in the bottom right corner of the screen, as shown in Figure 12-35.
Depending on your setup, the debug process appears in the debug stack view, as shown in Figure 12-36.
Figure 12-36 Inspecting the Debug view
2 In Input Parameters, select Planes as shown in Figure 12-37.
Figure 12-37 Entering the report parameter
Note that in debug mode, Input Parameters displays the parameter names, pProductLine and pStyle, instead of the display text. Displaying the parameter name supports finding the parameter in the Report Design perspective and provides information about values each parameter takes.
Choose OK. The report runs, and in a few seconds, execution stops at the breakpoint in the JavaScript onCreate method, as shown in Figure 12-38.
Figure 12-38 Stopping at the JavaScript breakpoint
3 Inspect the Console messages.
1 In Console, scroll down to look at the debug messages. The messages present information about the compiled and executed code in the report. These informational messages are written by different modules in the debug plug-in, org.eclipse.birt.report.debug.internal.core. The first several messages, printed in gray, as shown in Figure 12-39, appear in red on the screen.
Figure 12-39 Inspecting debug messages in Console
2 Scroll down and analyze the next set of messages, which appear darker in Figure 12-39. These are compilation messages for the JavaScript expressions and the script in the report’s onCreate( ) event.
3 The last few lines in the console, shown in Figure 12-39, trace the execution of each line of script. Note that the last message points to line 3 in this code snippet. You set the breakpoint at this line, as shown in Figure 12-38.
4 Observe the Debug view, as shown in Figure 12-40. This view shows the current debug target, the thread, and the current stack frame.
Figure 12-40 Inspecting the Debug view
The status of the current execution is Suspended. The highlighted line in Figure 12-40 shows the location of the suspended thread.
The last line shows the location of javaw.exe. The javaw.exe process is the Java Virtual Machine that runs programs written in the Java programming language.
5 Press <F6> to Step Over to the next line. The current row is highlighted in the script editor. A new message indicating the execution moved to line 7 appears in the Console view.
6 Inspect variable values.
1 In Variables, note the values of vMedianPrice and vOrderdPrice, as shown in Figure 12-41. Expand the this. variable in the Variables view. The two variables vMedianPrice and vOrderPrice also appear as properties of this.
Figure 12-41 Inspecting structures and values in the Variables view
Because the two variables contain the same value, 1814.4, the background color of the table row showing this order in the report remains unchanged.
2 To use an alternative way to check variable values, move the mouse pointer over the variable in the script editor as shown in Figure 12-42.
Figure 12-42 Using the mouse pointer to show the value of a variable
3 In the script editor, double-click vMedianPrice to select the text. Then, right-click vMedianPrice and choose Watch from the context menu, as shown in Figure 12-43.
Figure 12-43 Adding a variable to watch
The variable is added to the Expressions view. Expand vMedianPrice, as shown in Figure 12-44.
Figure 12-44 Inspecting the Expressions view
If the Expressions view is not visible, choose the Show View as a fast view icon in the bottom left corner of the screen. From the list that appears, select Expressions to add the view.
7 Press Resume <F8> to restart the report generation. Execution stops again at the breakpoint in the DataItemProductEH.java.
The debugger stops at this breakpoint as many times as there are records returned by the report query.
Figure 12-45 Stopping at a breakpoint in DataItemProductNameEH.java
8 Press <F6> to Step Over to the next line.
9 Press <F6> again. The current line of code executes and the product line, Planes, appears in Console.
10 In the Java editor, place the cursor at the following line:
data.getStyle().setFontWeight("bold");
11 Press <CTRL-R> to run the code to the current line. Report execution resumes and stops at the current line.
12 In the Variables view, inspect the available variables in the current context, as shown in Figure 12-46.
The current order is for the product line, Planes, and appears in the report in Bold font.
Figure 12-46 Inspecting the variables during report execution
13 In the Java editor, move the mouse pointer over the ProductLine text, as shown in Figure 12-47. The debugger parses the text and shows the value if it is available.
Figure 12-47 Moving the mouse pointer over Java text
14 In the Breakpoint view, deselect the two breakpoints as shown in Figure 12-48. In the next run, the debugger will not suspend execution at these breakpoints.
Figure 12-48 Disabling breakpoints
15 Press <F8> to resume the execution. As you selected Open the generated file in the debug options, the file opens after the debug process terminates. A new browser window containing the generated report appears, as shown in Figure 12-49.
Figure 12-49 Viewing the report in the browser
16 Examine the Debug view for the terminated debug process, as shown in Figure 12-50.
Figure 12-50 Inspecting the final status of the debug process
