Pentaho Reporting 3.5 for Java Developers
Create advanced reports, including cross tabs, sub-reports, and charts that connect to practically any data source using open source Pentaho Reporting
Will Gorman
¿A r \ LfI i\ nI r
PUBLISHING BIRMINGHAM - MUMBAI
Pentaho Reporting 3.5 for Java Developers Copyright © 2009 Packt Publishing
All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews. Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, Packt Publishing, nor its dealers or distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book. Packt Publishing has endeavored to provide trademark information about all the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.
First published: September 2009
Production Reference: 1310809
Published by Packt Publishing Ltd. 32 Lincoln Road Olton Birmingham, B27 6PA, UK. ISBN 978-1-847193-19-3 www.packtpub.com
Cover Image by Vinayak Chittar (vinayak. chittar@gmail. com)
Table of Contents Preface Chapter 1: A n Introduction to Pentaho Reporting Typical uses of Pentaho Reporting Operational reporting Business intelligence reporting Financial reporting Production reporting Pentaho Reporting history Pentaho Reporting timeline Feature overview An advanced reporting algorithm A multitude of available data sources A wide variety of output formats Pixel accurate rich formatting Embedded charts Report parameterization Formulas and style expressions Sub-reports Cross Tab Reports Interactive reporting Rich authoring tools Reporting server Java API for building reports Extensibility A business friendly open source license Pentaho reporting roadmap Pentaho Reporting architecture
1 7 8 8 9 9 11 12 13 14 14 14 15 17 18 18 19 19 20 20 22 23 23 23 23 24 24
Table of Contents
LibBase LibDocBundle LibFonts LibFormat LibFormula LibLoader LibRepository LibSerializer LibXml Report Engine Core Report Engine Extensions Summary
24 25 25 25 25 25 25 26 26 26 26 27
Chapter 2: Pentaho Reporting Client and Enterprise Examples Pentaho Reporting and example prerequisites Setting up Pentaho Reporting Building your first report Report Designer introduction Creating and configuring your first data source Report layout
29 29 30 32 32 34 35
Creating the report title
36
Creating column headings
36
Populating the details band
37
Creating a report summary
38
Previewing and saving your report
38
Embedding your report in a Swing application Setting up the Swing example application Incorporating Pentaho Reporting into the application Embedding your report in an enterprise web application Setting up the example Tomcat application Incorporating Pentaho Reporting into the web application Adding additional output formats Summary Chapter 3: Pentaho Reporting Examples in the Real World Setting up the example data source ElectroBarn inventory report Configuring the data source Creating a query Creating the Report Header and Page Footer Defining the Group Header Defining the Details band Defining the Group Footer and the Report Footer band [N]
40 40 43 47 47 49 53 54 55 55 58 58 59 60 62 63 64
Table of Contents
Adding a pie chart Incorporating the inventory report into your J2EE environment Adding report selection as an input to the servlet Compiling and deploying the report servlet
65 66 66 66
End of the day cashier balances Configuring an input parameter Configuring the data source query Creating the Report Header and Page Footer Defining the Details band Defining the Group bands Defining the main Group Header Incorporating the End of Day report into your J2EE environment ElectroBarn invoice example Configuring the data source query Defining the Group Header Defining the sub-report Defining the Details band Defining the Group Footer and Page Footer Incorporating the invoice report into your J2EE environment Summary
68 68 70 71 72 72 73 76 78 79 80 81 83 83 84 86
Chapter 4: Design and Layout in Pentaho's Report Designer Report Designer user interface components Menu and toolbar Report element palette Report canvas tab panel Report Explorer Element Properties Messages Report bands Common properties
87
Size and position properties Padding and border properties Page behavior properties Foreground and background color properties Excel properties Attribute properties Style inheritance
Page Header and Page Footer Report Header and Report Footer Group Header and Group Footer Details Body
87 88 89 89 89 89 90 90 90 90 92 94 94 94 95 95
95 95 96 96
Table of Contents
Watermark Report elements Common properties Common text properties
96 96 97 97
Font style properties
98
Text style properties
98
Text spacing properties
99
Link properties
100
Excel properties
100
label text-field message number-field date-field resource-label resource-message resource-field chart co nte nt (stati c i m ag e) content-field (dynamic image) rectangle ellipse horizontal-line and vertical-line band sub-report survey-scale line-sparkline bar-sparkline pie-sparkline simple-barcodes Visual layout in Report Designer The Grid Guidelines Additional visual indicators Moving and aligning single elements Aligning groups of elements Miscellaneous layout capabilities Pentaho Report Designer shortcut keys Working with fonts Considerations for different output formats Cell output Paging [iv]
100 100 100 101 101 102 102 102 103 103 103 104 104 104 105 105 105 106 106 106 107 107 108 108 109 110 110 111 112 113 114 114 116
Table of Contents
Limits to rich graphics and charts Summary
116 116
Chapter 5: Working with Data Sources Pentaho Reporting Engine Data API The DataFactory interface The ContextAwareDataFactory interface The TableModel interface DataFactory serialization Additional data source metadata Existing DataFactory implementations TableDataFactory NamedStaticDataFactory Query syntax NamedStaticDataFactory example
117 117 118 119 119 120 121 121 121 122 122 123
SQLReportDataFactory
125
StaticConnectionProvider DriverConnectionProvider JndiConnectionProvider SQLReportDataFactory example
126 126 126 128
XPathDataFactory
129
XPathDataFactory example
131
HQLDataFactory
132
StaticSessionProvider DefaultSessionProvider HQLDataFactory Example
133 133 134
PmdDataFactory
137
XMI file Domain Id IPmdConnectionProvider Registering MQL Queries PmdDataFactory example
137 137 137 138 138
KettleDataFactory
143
KettleDataFactory example
145
BandedM DXDataFactory
148
BandedMDXDataFactory example
149
DenormalizedM DXDataFactory CompoundDataFactory Experimental data factories Accessing data throughout a report Summary Chapter 6: Including Charts and Graphics in Reports Supported charts Common chart rendering properties [v]
152 153 153 153 154 155 155 157
Table of Contents
Common category series rendering properties Common XY series rendering properties Common dataset properties Common category series dataset properties Common XY series dataset properties Area chart Area chart example
159 161 162 163 163 164 164
Bar chart
165
Bar chart example
166
Line chart
167
Line chart example
168
Pie chart
168
Pie chart example
170
Ring chart
171
Ring chart example
172
Multi pie chart
172
Multi pie chart example
173
Waterfall chart
173
Waterfall chart example
174
Bar line chart
174
Bar line chart example
175
Bubble chart
176
Bubble chart example
176
Scatter chart
177
Scatter chart example
178
XY Area, XY Bar and XY Line charts XY charts example
178 179
Extended XY Line chart
179
Extended XY Line chart example
180
Radar chart
181
Radar chart example
181
Including static images in your report Including dynamic images in your report Summary Chapter 7: Parameterization, Functions, Formulas, and Internationalization in Reports Report parameterization Providing report parameters Available report parameter types Working with functions and expressions Common functions Report functions Summary functions [vi]
182 182 183 185 185 186 186 187 188 189 190
Table of Contents
Running functions Advanced functions Image functions Script functions Working with formulas Formula syntax Formula data types Formula operators Formula functions
192 194 196 197 198 199 199 200 201
Date time functions Logical functions Mathematical functions Text functions Reporting Specific functions Miscellaneous functions
201 202 203 204 206 206
Internationalization and localization of reports Localizing fields Localization example Summary
207 208 209 210
Chapter 8: Adding Sub-Reports and Cross Tabs to Reports Adding sub-reports Multi-page sub-report example Chart sub-report example Side-by-side sub-report example Adding cross tabs Cross tab MDX example Cross tab SQL example Multiple row and column cross tab example Summary
211 211 212 217 219 221 222 228 229 230
Chapter 9: Building Interactive Reports Interactive reports in Swing Registering event callbacks
231 231 231
ReportHyperlinkListener ReportActionListener ReportMouseListener
231 232 233
Interactive Swing example Interactive reports in HTML Interactive HTML report properties Manipulating the reporting HTML DOM Including an external CSS or JavaScript resource Interactive HTML example
[vii]
234 241 241 243 243 243
Table of Contents Adding interactive elements to the dashboard
Summary
247
250
Chapter 10: API-based Report Generation Understanding the serialized report format settings.xml datadefinition.xml and the datasources folder Parameters Data source reference Functions and expressions
251 251 252 252 252 254 254
Data sources folder layout.xml
255 256
Group and detail band hierarchy Report elements Example layout.xml file
258 258 261
styles.xml
262
Example styles.xml file
263
Additional required files Building and running a .prpt bundle example file Building a report using Pentaho Reporting's Java API Adding a data source Defining parameters Including functions and expressions Defining the report's layout Common report bands Group band hierarchy
264 265 266 267 267 268 269 269 269
Adding elements to the report Java API example Wizard Java API Summary
270 272 274 275
Chapter 11: Extending Pentaho Reporting Implementing report functions and expressions Implementing expressions Defining an expression class
277 277 277 278
Defining expression metadata
278
An example expression
281
Implementing functions Implementing a formula function Regex formula function example Implementing BeanShell expressions Example BSHExpression Implementing a report element Defining an ElementType class [viii]
287 287 289 292 292 293 293
Table of Contents
Defining element metadata Defining read and write handlers An example report element Summary
294 296 296 305
Chapter 12: Additional Pentaho Reporting Topics Using Pentaho Reporting with Pentaho's Business Intelligence Server Downloading and Installing the Bl Server Publishing a report to the Bl Server Scheduling reports Configuring permissions Report emailing and bursting Managing database connections and users Creating ad hoc reports Mobile reporting Mobile report server Mobile report design Example: Pentaho's ¡Phone Bl extension Data source metadata in Pentaho Reporting MetaTableModel API Mapping external metadata Using metadata attributes in a report Current MetaTableModel implementations Metadata example: DefaultMetaTableModel Working with Pentaho Reporting's output layer The OutputProcessorMetaData interface The OutputProcessor interface RenderNode Document Object Model Updating Report Designer Example: PojoObject output The Pentaho community—getting help and contributing Asking questions, helping others Online documentation Submitting bugs and viewing backlogs Contributing code Enterprise support Summary
307
Index
347
[ix]
307 308 309 311 313 313 316 318 319 320 321 321 322 323 324 326 327 328 335 335 336 336 337 337 343 343 343 343 344 344 345
Preface Pentaho Reporting lets you create, generate, and distribute rich and sophisticated report content from different data sources. Knowing how to use it quickly and efficiently gives you the edge in producing reports from your database. If you have been looking for a book that has plenty of easy-to-understand instructions and also contains lots of examples and screenshots, this is where your search ends. This book shows you how to replace or build your enterprise reporting solution from scratch with Pentaho's Reporting Suite. Through detailed examples, it dives deeply into all aspects of Pentaho's reporting functionalities, providing you with the knowledge you need to master report creation.
What this book covers Chapter 1 —An Introduction to Pentaho Reporting provides a quick overview of Pentaho Reporting, including a feature summary and architectural summary, as well as a history of the product. Chapter 2-Pentaho Reporting Client and Enterprise Examples tells how to install and create reports, and how to embed reports in your J2EE and client Java applications. Chapter 3 - Pentaho Reporting Examples in the Real World tells how to connect to a JDBC data source and create realistic inventory, balance, and invoice reports, including charts and sub-reports. Chapter 4 - Design and Layout in Pentaho's Report Designer takes a deep dive into Pentaho's Report Designer, learning how to create great-looking reports. Chapter 5 - Working with Data Sources teaches the various ways to connect your report to live data, including JDBC, Hibernate, Java Beans, OLAP, and many other data sources.
Preface
Chapter 6 - Including Charts and Graphics in Reports is about incorporating Pie, Bar, Line, and many other chart types in your reports, as well as including dynamic images in your report. Chapter 7 - Parameterization, Functions, Formulas, and Internationalization in Reports defines parameters for dynamic report generation. It helps you write formulas and use available functions for rich summary and calculated values in your reports, along with dynamically adjusting colors and styles using expressions in your report. Chapter 8—Adding Sub-Reports and Cross Tabs to Reports gives an overview of how to build reports that include side-by-side sub-reports and cross tabs. Chapter 9 - Building Interactive Reports teaches how to add dynamic interaction to HTML and Swing reports, for immediate feedback and dashboard-like functionality. Chapter 10 - API-based Report Generation is about building reports from XML and by using Pentaho Reporting's Java Bean API. Chapter 11- Extending Pentaho Reporting teaches how to write custom functions and elements within Pentaho Reporting. Chapter 12 - Additional Pentaho Reporting Topics discovers how to use Pentaho Reporting with the Pentaho BI Server, including Pentaho Metadata. It aids in learning more about Pentaho Reporting's open source approach, and how you can contribute to the free software movement.
Who this book is for This book is primarily written for Java developers who want to assemble custom reporting solutions with Pentaho Reporting. Their main interest is in the technical details of creating reports. They want to see how to solve common report problems with a minimum of fuss and don't need an overview of BI or the importance of reporting. Secondary audiences of this book are information technologists who need to install a reporting solution in their environment, and want to learn advanced concepts within Pentaho Reporting such as sub-reports, cross tabs, data source configuration, and metadata-based reporting.
[2]
Preface
Conventions In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning. Code words in text are shown as follows: "Copy the servlet file chapter2\src\ Chapter2Servlet. java to chapter3\src\Chapter3Servlet. java, a n d r e n a m e
the class to Chapter3Servlet." A block of code will be set as follows: String reportName = request.getParameter("reportName"); if (reportName == null) { response.getWriter().println("No report parameter specified"); return;
Any command-line input or output is written as follows: a n t
r e s t a r t _ t o m c a t
New terms and important words are shown in bold. Words that you see on the screen, in menus or dialog boxes for example, appear in our text like this: "Right-click on the sub-report element in the canvas and select Edit SubReport".
Warnings or important notes appear in a box like this.
Tips and tricks appear like this.
[3]
] 1
Preface
Reader feedback Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of. To send us general feedback, simply drop an email to feedback@packtpub. com, and mention the book title in the subject of your message. If there is a book that you need and would like to see us publish, please send us a note in the SUGGEST A TITLE form on www. packtpub. com or email suggestopacktpub.com.
If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide on www. packtpub. com/authors.
Customer support Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.
Downloading the example code for the book Visit http: / /www. packtpub. com/f iles/code/3193_Code. zip to directly
download the example code. ^
The downloadable files contain instructions on how to use them.
J
Errata Although we have taken every care to ensure the accuracy of our contents, mistakes do happen. If you find a mistake in one of our books — maybe a mistake in text or code—we would be grateful if you would report this to us. By doing so, you can save other readers from frustration, and help us to improve subsequent versions of this book. If you find any errata, please report them by visiting http: //www. packtpub. com/support, selecting your book, clicking on the let us know link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata added to any list of existing errata. Any existing errata can be viewed by selecting your title from http: //www. packtpub. com/support.
[4]
Preface
Piracy Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works in any form on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy. Please contact us at copyright@packtpub. com with a link to the suspected pirated material. We appreciate your help in protecting our authors, and our ability to bring you valuable content.
Questions You can contact us at questions@packtpub. com if you are having a problem with any aspect of the book, and we will do our best to address it.
[5]
1
An Introduction to Pentaho Reporting Pentaho Reporting is an easy-to-use, open source, lightweight suite of Java projects built for one purpose —report generation. In this book, you'll discover how easy it is to embed Pentaho Reporting into your Java projects, or use it as a standalone reporting platform. Pentaho Reporting's open source license —the GNU Lesser General Public License (LGPL) — gives developers the freedom to embed Pentaho Reporting into their open source and proprietary applications at no cost. An active community participates in the development and use of Pentaho Reporting, answering forum questions, fixing bugs, and implementing new features. While many proprietary reporting options are available, none can offer the openness and flexibility that Pentaho Reporting provides its users with. As with most successful open source projects, Pentaho Reporting has a proven track record, along with a long list of features. Most of this history has been documented in open forums and in email threads, which are still available for folks to browse through and glean ideas from. Starting as a side hobby and turning into an enterprise reporting suite over the course of seven years, the Pentaho Reporting Engine and its suite of tools such as the Report Designer, Report Design Wizard, and Pentaho's web-based Ad Hoc Reporting user interface, are used as critical components in countless corporate, educational, governmental, and community-based information technology solutions. In most business software applications, a reporting component is necessary, be it for summarizing data, generating large numbers of customized documents, or simply for making it easier to print information that would be useful in various output formats. With a complete set of features, including PDF, Excel, HTML, and RTF report generation, along with advanced reporting capabilities such as sub-reports and cross tabs, Pentaho Reporting can crack the simplest of problems quickly, along with solving the more advanced challenges when designing, generating and deploying reports.
An Introduction to Pentaho Reporting
Read on in this chapter to learn more about the typical uses, history and origins of Pentaho Reporting, along with a more detailed overview of the reporting functionality that Pentaho Reporting provides.
Typical uses of Pentaho Reporting Business users need access to information in many different forms for many different reasons. Pentaho Reporting addresses the following typical uses of reporting, along with many other types that will be covered in this book.
Operational reporting One of the most commonly used forms of reporting is operational reporting. When a developer or an IT organization decides to generate reports directly from their operational data sources for the purpose of detailed transaction level reporting, this is referred to as operational reporting. In this scenario, the database is designed to solve an operational problem, and usually contains live data supporting critical business functions. Users of Pentaho Reporting can point directly to this data source and start generating reports. Some examples of operational reporting include building custom reports directly based on a third-party software vendor's database schema such as Bugzilla's bug tracking system or SugarCRM's Customer Relationship Management system. These reports might include summaries of daily activity, or detailed views into particular projects or users in the system. Reports might also be generated from data originating from an in-house custom application. These reports are typically based on a SQL backend, but could be generated from flat log files or directly from in-memory Java objects. Pentaho Reporting's parameterization capabilities provide a powerful mechanism to render up-to-the-minute customized operational reports. With features such as cross tabs and interactive reporting, business users can quickly view their operational data and drill back into operational systems that might require attention. There are limitations when developing reports based on live operational data. Developers need to be careful to make sure that queries in the operational system do not impact the performance of regular operations. An extremely CPU-intensive query could delay a transaction from taking place. Also, certain historical questions —for example, state transitions or changes to particular informational fields such as address—aren't traditionally captured in an operational schema design.
[8]
Chapter 1
Business intelligence reporting When you've reached the limits of operational reporting, the next logical step is to move your data into a data warehouse. This move is often referred to as business intelligence reporting. Reporting alone does not provide the necessary tools to make this transition. You will need an Extract, Transform, and Load (ETL) tool such as Pentaho Data Integration, along with a sensible warehouse design such as a snow flake schema, in order to enable business intelligence reporting. This type of use allows business users to monitor changes over time. It also helps gain performance benefits by pre-calculating aggregations and defining schemas that are built in mind for summarized reporting. Until recently, data warehousing and business intelligence have been limited to large enterprises due to the cost of software and limited expertise. With open source tools becoming more widely available, a large number of small and medium size businesses are deploying data warehouses, in order to get solutions for the critical questions in their business domain. Common examples of data warehouse reporting include combining sales and inventory data into a single location for reporting, or combining internal proprietary sales data with publicly available market trends and analysis. Pentaho Reporting's flexible data source support makes it easy to incorporate reports into your business intelligence solutions. Also, with Pentaho Reporting's speed and scalability, you can deploy Pentaho Reporting with confidence that reports will be executed efficiently. As with all approaches, there are limitations to this approach. In traditional warehousing, data is usually batched nightly, weekly, or monthly. Therefore, business users rarely get to see up-to-the-minute reports on business operations. Also, when designing a warehouse, it is important to ask the correct business questions. Unfortunately, it is possible to build a data warehouse and still not address business users' needs, if not investigated ahead of time.
Financial reporting Financial reporting is a very specific, but very common form of reporting, geared towards generating financial summaries for accountants, managers, and business investors. Standard reports that fall into this category include balance sheets, income statements, retained earning statements, and cash flow statements. Unlike business intelligence or operational reporting, many of these reports are required by law, with regulations around their content and presentation. Financial reports often include computations for assets, liabilities, revenues, and expenses.
[9]
An Introduction to Pentaho Reporting
Following is the Screenshot showing one such report:
Steel
Wheels
Steel Wheels, Inc. Income Statement From June 1 through June 30,2005
Revenue Direct Sales
400,000
Channel Sales
150,000
Total Revenue
$550.000
Beginning inventory
40,000
Net purchases
325,000
Encinq inventory
35,000
Cost of goods sold
S 330.000 ; 220,000
Gross Margin Expenses Selling expenses Sales salaries
48,000
Nonrecurring item
12,000
Other
13,000
Tota I SeBng expenses
73,000
General and administrative expenses Office salaries
27,100
Depreciation
5,500
Amortization
3,200
Bad debt
4,500
Other
24,200
Tota I General a nd admi nistratwe expenses
64.500
Total Expenses Other revenues
Ï 137.500
Interest
5,200
Dividends
7,200
Gai n on sale of equ ipment
8,600
Total Other revenu es
S 21,000
Other expenses Interest
9,400
Writeoff -goodwill
5,000
Unusual item • loss on sale of lon^-term investment Total Other expenses
5,100 • 19,500
IncomBtax expense
33,600
Extraordinary item - gain on disposal of business segment
24,000
Other Comprehensive Income
12,000
Net Income
Report Run: M M
S 86,400
11:59 PM
With features such as group summary aggregations, Pentaho Reporting makes it very easy for developers to implement custom financial reports that business managers and owners require. Typically, this type of data exists in a controlled form, be it in a proprietary system such as QuickBooks or SAP, or in a secure database system such as Oracle or MySQL. Due to the sensitivity of this data, developers will need to be conscious of who has access to reports and may want to implement features such as audit logging. [10]
Chapter 1
Production reporting Another typical use of Pentaho Reporting includes production reporting. This type of reporting includes reports such as a customized form letter, invoice, or postcard for a large audience, as well as automated mail merging. Normally, batch processing is involved in this form of reporting. However, custom reports generated for individuals based on a standard template can also fall under this category.
Steel
Wkeels
Wheds 500 Hiemajiarial Speedway, Dayton a Baacti, FL 32114 {1231 456-7890 hfltUWw.slAelwh-Mb.Qdrti FLn Date:a-3 C3 Operational Reports
m
e-
Production Reports
1 Formula
Resources Quick Start Guide Wik] - Report Designer Forums
S]
0
Show at startup
50.7 of 254.1
[22]
Chapter 1
Reporting server As a part of the Pentaho suite, reports created by Pentaho Reporting may be published, executed, and scheduled on Pentaho's Business Intelligence Server. The BI Server offers authentication and authorization, as well as a central repository, to manage your business reports. The BI Server also hosts the web-based Ad Hoc Reporting user interface for creating Pentaho Metadata-based reports. By combining the use of Pentaho Report Designer and Pentaho's BI Server, there is no need to write any code to get your business up and running with Pentaho Reporting.
Java API for building reports Pentaho Reporting comes with a well-documented Java API for building reports from the ground up, so developers can stick with the Java programming language when customizing existing report templates or building reports from scratch. This Java API allows developers to create and modify the various sections of a report, including the various header, footer, group and detail bands, along with creating and modifying objects within each section of a report.
Extensibility Pentaho Reporting is designed from the ground up in pure Java, exposing many interfaces for extension. From implementing basic formulas and functions that can be embedded in reports, to writing a custom data source or output format, Pentaho Reporting's source code and API interfaces are well documented and easy to work with.
A business friendly open source license One very attractive feature of Pentaho Reporting is its license. Pentaho Reporting is available for free under the GNU Lesser General Public License. This license allows other open source and proprietary projects to embed Pentaho Reporting without fear of large license fees or viral open source limitations. As an open source project, developers also have unprecedented access to the engine and to a large group of software developers within the Pentaho Reporting community. This community includes open discussion forums, Internet Relay Chat (IRC) along with commercial support and licensing, if required.
[23]
An Introduction to Pentaho Reporting
Pentaho reporting roadmap In addition to these features, Pentaho Reporting is in active development. Please visit http: //reporting. pentaho. org to learn more about what additional features and functionality are being considered for development, or to access early release versions of the product.
Pentaho Reporting architecture The Pentaho Reporting Engine is broken up into eleven main Java projects, which are then combined to author and render reports. The Pentaho Reporting Engine is backward compatible to Java 1.2.2, making certain that it stays as lightweight and as useful as possible. Most of the eleven libraries are independently useful for Java developers, outside of using them strictly for reporting purposes. The following diagram describes the various dependencies between each of the reporting projects:
LibBase LibBase is the root library for all other Pentaho Reporting libraries. This library contains common capabilities, such as debug and error logging utilities, library configuration, along with library initialization APIs, for consistent startup and shutdown management of the reporting engine.
[24]
Chapter 1
LibDocBundle LibDocBundle abstracts the management of Pentaho Reporting file bundles, which are by default stored as ZIP files, and implements the OpenDocument format (ODF). This makes it simpler for other parts of the reporting engine to work with and manipulate Pentaho Reporting's file formats.
LibFonts LibFonts allows Pentaho Reporting to work with TrueType system fonts, extracting the necessary metadata from font types, populating an abstract interface to allow appropriate rendering in various contexts, including PDF and Excel views.
LibFormat LibFormat is a string formatting library, which can render dates and numbers appropriately based on format strings. This library is focused on memory and CPU efficiency for high performance report rendering.
LibFormula LibFormula is a formula parsing and execution library based on the OpenFormula standard. You can learn more about OpenFormula by visiting http: //wiki . oasisopen, org/of f ice/About_OpenFormula. This library is similar in function to Excel-based formula definitions. LibFormula is a very general library, and is used outside Pentaho Reporting in other projects that require OpenFormula style parsing and execution.
LibLoader LibLoader manages the loading and caching of all necessary resources required for generating reports in a generic way, providing a simple API for other parts of the reporting engine that control static and dynamic content, including data sources and images.
LibRepository LibRepository abstracts the input and output of hierarchical storage systems, such as file systems, that Pentaho Reporting interacts with. This makes it possible for a custom storage system such as FTP, to be implemented and to be mapped to the API, giving Pentaho Reporting access to the system.
[25]
An Introduction to Pentaho Reporting
LibSerializer LibSerializer provides helper methods for serializing non-serializable objects. This is necessary so that the reporting engine can serialize standard Java classes that don't implement Java's Serializable interface.
LibXml LibXml provides utility classes for SAX (Simple API for XML) parsing and XML writing, based on Java's JAXP (Java API for XML Parsing) API. This library assures the speedy loading and validation of Pentaho Reporting XML template files.
Report Engine Core The Report Engine Core project contains the main reporting algorithm for rendering reports, along with the necessary functionality to support styling. This project also contains the algorithms for rendering specific outputs, including PDF, Excel, CSV, XML, and more. The engine relies on the already mentioned Lib libraries for managing the loading, parsing, formatting, rendering, and archiving of generated reports.
Report Engine Extensions The Report Engine Extensions project contains third-party extensions to the reporting engine, which are very useful, but increase dependencies. Extensions in this project include JavaScript Expression support using the Rhino project, a Hibernate data source factory, Barcode support using Barbecue, Sparkline support, along with additional JDK 1.4 support for configuration and printing. Additional extension projects exist that include charting and many of the data sources discussed in this book. When combined, these libraries form the Pentaho Reporting Engine. In addition to these libraries, there are also other related open source tools and projects in the Pentaho Reporting landscape, including the Report Engine Demo, Report Design Wizard, Report Designer, and the web-based Ad Hoc Reporting user interface.
[26]
Chapter 1
Summary In this chapter, we've highlighted some typical uses of Pentaho Reporting, providing you with baseline ideas for implementing your own solutions. Typical uses for embedded reporting include operational, business intelligence, financial, and production reporting. We've covered the unique history of Pentaho Reporting, from its JFreeReport roots to its current status as Pentaho Reporting. We've learned about the individuals who have built Pentaho Reporting from a spare time open source project into an enterprise level reporting engine, competing with proprietary reporting engines. We've also learned a great deal about the rich features of Pentaho Reporting. Core features include a wide variety of data source integration, along with PDF, HTML, and Excel rendering. On the other hand, more advanced features include sub-reports and cross tab reports. Additionally, developer-oriented features such as open Java APIs, along with the available source code and a business-friendly LGPL open source license gives Pentaho Reporting a leg up on all other Java Reporting toolkits. The architecture of Pentaho Reporting is also covered in this chapter, providing developers with a twenty thousand foot view of where they might be able to modify or contribute to the Pentaho Reporting Engine, along with giving them the ultimate flexibility of access to source code. You'll soon be able to apply the rich feature set of Pentaho Reporting to your use case. In the following chapters, we'll introduce you to Pentaho Reporting's easy to use Report Designer and Java API, making it fun and easy to embed reporting into your Java application.
[27]
2
Pentaho Reporting Client and Enterprise Examples This chapter is focused on getting up and running with Pentaho Reporting. You'll begin by setting up an environment for building and embedding reports. From there, you will walk through creating a report. After creating the report, you'll walk through embedding the report into a Java Swing Client application, and finally you'll walk through embedding the same report into a Java Enterprise J2EE application. Along the way you'll receive an introduction on building a report, getting data into the report, along with generating PDF, Excel, and RTF output documents. This chapter is written as a tutorial. The best way to learn is to follow the instructions on your PC while reading. At the end of this chapter, you'll feel comfortable with the basics of building and embedding a Pentaho Report. Later chapters will assume that your environment is configured appropriately and that you've retained the knowledge that you gained in this chapter, so pay attention!
Pentaho Reporting and example prerequisites Pentaho Reporting and Pentaho Report Designer are written in pure Java, allowing any operating system that supports the Java Runtime Environment to run the application. This tutorial requires the use of JDK 5.0 or later. Pentaho Reporting is a cross-platform application and will run in Linux, Windows, Mac, and other Java-supported environments. The reporting engine is backward compatible to JDK 1.4, and the core engine component is backward compatible to JDK 1.2.2. The Report Designer is compatible with JDK 5.0 and above.
Pentaho Reporting Client and Enterprise Examples
The only prerequisites needed before starting the examples in this chapter are Sun's Java Development Kit, Apache Ant for builds, and Apache Tomcat to host the example J2EE application. To get started, please visit http: / /j ava. sun. com/ and download the latest patch release of the J2SE 6.0 JDK. Verify your install by running j ava -vers ion on the command line. Download the binary distribution of Apache Ant 1.7 from http: //ant. apache. org. Verify that Ant 1.7 is accessible in your system path by typing ant -version on the command line. Finally, download the binary distribution of Apache Tomcat 5.5 from http: //tomcat. apache. org. To verify that you've installed Tomcat correctly, start up the server by running bin/startup. bat on command line, and verify that you can access http: //localhost: 8 08 0/. One common issue when running Apache Tomcat is a port conflict with 8080. You can adjust the default ports Tomcat uses by modifying the Connector element in conf /server . xml.
I I I
Setting up Pentaho Reporting To install Pentaho Reporting, your first task is to download Pentaho Report Designer. Visit http: //reporting. pentaho. org, and follow the link to download the Report Designer, under the Report Creation Tools section of the webpage. Follow the link to download the latest stable binary distribution. When downloading Pentaho Report Designer, three packages are available. The first two packages, prd-ce- * . zip and prd-ce- * . tar .gz, contain the binary distribution archived in their preferred archive formats. The third package, prd-ce - src- * . zip, contains the entire source code of the Pentaho Report Designer. If modifications are necessary, if you would like to build the project yourself, or if you would like to take a look at the source, download the source distribution. Otherwise, stick with the binary distributions. Once you've downloaded the binary distribution of the Report Designer, create a directory on your machine and unzip the contents of the package into that directory. Once the contents are unzipped, you will see report-designer. exe in the main directory. Double-click the executable to start Pentaho Report Designer. You should see the Report Designer welcome screen as shown next:
[30]
Chapter 1 Pentaho Report Designer File
Edit
1 0
View
Format
Data
Window
Help
o T
a
Dala ¡
Samples cAdvanced
© pentaho I
• C3 CM aits 113 Financial Reports Q
o p e n s o u r c e business intelligence ~ 0-
9
images
r i Legacy Operational Reports
fr- | _ j production Reports
Resources Quick Start Guide Wiki - Report Designer Forums
IS
0
Show at startup
When running Linux, start Pentaho Report Designer by running I report - des igner . sh. If you are running on a Macintosh, use I report-designer.app. I
At this point, you may want to create a shortcut to your desktop or to your start menu. Simply right-click on report-de signer. exe and select Create Shortcut. Rename the shortcut to the name of your choice and then drag the shortcut to your start menu or desktop. You've successfully installed Pentaho Report Designer! Pentaho Report Designer comes packaged with the core Pentaho Reporting Engine libraries, so you now have the necessary reporting components to complete the examples in this chapter. If you've experienced difficulties installing Pentaho Report Designer, there are some common troubleshooting issues that you will want to verify. The most common issue is related to the Java Virtual Machine and SDK that you've installed on Windows. The report-des igner. exe uses the first Java command found on the system path. Therefore, you will want to verify that your path is configured correctly. You can do this by executing j ava -version in a command window, in order to see which version of Java you are using. [31]
Pentaho Reporting Client and Enterprise Examples
Building your first report Now that you've successfully installed Pentaho Report Designer, this example will walk you through building a very simple report, along with embedding it into a simple Swing application. This simple report will display the eleven Java libraries involved in Pentaho Reporting, along with the size of each library. At the bottom of the report, you'll have a summary that shows the total size of the libraries. Before you begin, create a directory called chapter2 on your machine, to manage the files you create in this chapter.
Report Designer introduction When you first start Report Designer, you are taken to a welcome screen. From this start page, you can create a new report, or browse example reports to help you learn the various capabilities of Pentaho Reporting. Get started by clicking the New Report button on the welcome page. j n j x j File
Edit
View
Format
i l l
Data
Window
Help
H
Welcome |x|
100%
—
H
(x) |
ZCL
I Structure
3.0
3.5
4.0
ijts
5.0
Page Header
[32]
5.5
0.0
j Data
j
É Master Report n Page Header H Report Header { H Groups U Report Footer U Page Footer • Watermark
Chapter 1
The report canvas, shown in the center of the previous screenshot, is where you define the look of your report. Note that at this point you haven't decided if the report will be rendered as PDF, RTF, or Excel. In fact, any report definition can be rendered in all of those formats. Therefore, at this point, you do not have to worry about that. The report canvas contains a set of bands that together make up a report. Bands include the Report Header and Report Footer, individual Group Header and Group Footer bands, as well as a Details band that is rendered for each row of data. Reports may also contain a page header and footer. To the left of the canvas is a palette where you can choose the various report elements you would like to include in your report, such as labels, fields, and graphics. You can drag-and-drop these report elements into the various sections of the report canvas. To the right of the canvas is the Structure tab and Data tab. Below these tabs, the details of the currently selected structure or data item are displayed. The Master Report structure tree includes details about every report object displayed on the report canvas, while the report data tree includes details about the report's data source information, parameters, and functions. Below the canvas is an optional messages panel that displays help, warning, and error messages that help you understand what might be wrong with your report. An example message might be an undefined field warning. You can hide any of the panels around the canvas by changing their visibility within the Window menu. This can help manage your screen while designing reports. You'll now begin to create a very basic report with the Report Designer.
[33]
Pentaho Reporting Client and Enterprise Examples
Creating and configuring your first data source First, you need to define a dataset that you want to report on. To keep things simple, this example will have you enter some example data into a table dataset. Click on the Data tab on the righthand side of Report Designer. Now, right-click on the Data Sets tree item and select Table. The following dialog will appear: ^
Table Data source Editor
®
@ I)
Available Queries
•
Use First Row as Header
Cartcel
Click the add query image button, and then enter the Name as default for the table. This name will be referenced in your report as the main source of data. Click the add column image button to add a third column. Double-click and edit the column headers to be Library Name, Library Description, and Library Size. Double-click on the Library Size column header table cell and select j ava. lang. integer as the data type for this column. Enter the following data into the table cells, clicking the add row image button to add additional rows of data. An empty report titled chapter2_tabledata. prpt is available with this book, in order to avoid the need to type this data. Library Name
Library Description
Library Size
LibBase
Library containing common functions
121745
LibLoader
Loading and caching library
122900
LibSerializer
Java serialization utility library
25689
LibRepository
Hierarchical storage library
63655
LibXml
XML utility library
72896
LibFormula
Implementation of OpenFormula
368263 248320
LibFonts
Font utility library
LibDocBundle
ZIP bundle library
71186
LibFormat
String formatting library
69464
Report Engine Core
Base report engine
3375047
Report Engine Extensions
Group of common extensions
92335
[34]
Chapter 1 Hie library sizes shown here may vary between releases of Pentaho Reporting, so they might not actually match the
[
I I
'
current size of the JAR files.
I
\\ X
Once you've entered data in your table, the Table Datasource Editor dialog should look similar to this: ^
Table Datasource Edltor
®
Available Queries
@
Q
default
Name I default
••
Library Name (class java.la. LibBase LibLoader Lib Se rial ¡¿er LibRepository LibXml LibFormula LibFonts LibDocBundle LibFormat Report Engine Core Report Engine Extensions •
.Library Description (class java.lang.Stri.. J Library Size (cla... Library containing common functions 121745 Loading and caching library 122900 Java serialization utility library 25689 Hierarchial storage library 63655 XML utility library 72896 Implementation of OpenFormula 368263 Font utility library 248320 ZIP bundle library 71186 String formatting library 69464 Base report engine 3375047 Group of common extensions 92335
Use First Row as Header
on
Cartcel
Now click the OK button. You should see the expanded Data Sets tree with the three new columns, as shown in the following screenshot: Structure
O •
fx
\ Data
|_
•3
Data Sets
? •
Table Î
C 3 default Q
Library N a m e (String)
Q
Library Description (String)
Q
Library Size (Integer)
JbI Functions a s Parameters
Report layout With the dataset defined, it's now time to build a very simple report. In this report, you'll include a report title, column headings, and a details band for the reporting libraries. You will also include a summary section displaying the total number of libraries, as well as the sum of their sizes. [35]
Pentaho Reporting Client and Enterprise Examples
Creating the report title From the palette on the left, drag a Label report element over to the upper left of the report's Report Header. Edit the label by either double-clicking directly on it, or by selecting the value property on the right side in the Attributes tab panel. Enter Pentaho Report Engine Library Report as the title of the report. Also, adjust the font and size of this label. Making sure you have the label selected, change the font size in the top toolbar from lOpt to 16pt. Also, select the bold font option. At this point, you may need to resize the label to display the entire report title. Move the mouse to the bottom right of the label and drag the label to accommodate the size of the title. Pentaho Report-Design er Eile
Edit
View
Eormat
• B a «9 W e l c o m e |x]
Data
Window
Help
S« & %
!> G
Ab
» 100%
0
|
0.5
1.0
1.5
16
T 2.0
B 2.5
I 3.0
U 3.5
U 4.0
4.5
5.0
im Page Header
iPentalio Report Engine Library Report
E
AÜ
•
Report H e a d e r
•
Creating column headings Below the report title, add three more labels that will represent the column headings for the details data. The three labels should be Library Name, Library Description, and Library Size. You may want to enable Snap Guides, which renders a rectangle around the labels, making it easier to view their alignments. To do this, select the View | Guides | Snap option in the main menu. Also, add a horizontal-line report element below the labels to distinguish the header row from the data. You may adjust the line width and color by editing the stroke and text-color style attributes of the line in the Style tab panel appearing on the right side of the window.
[36]
Chapter 1 I £ Pentaho Report-DesRj ner File
•
Edit
View
e\B
Format
X
«7
W e l c o m e (x) Ab
Data
Window
Help
I
0 0
0
| < m a s t e r report> (x)
JB
* 100%
0.5
1.0
1.5
2.0
2.5
IRI 3.0
3.5
n 4.0
4.5
5.0
5.5
6.0
n
mi IS
Page H e a d e r
m
ID
D o
P e n t a h o R e p o r t E n g i n e L i b r a r y Rep ort
M
Report H e a d e r
ID 1LibraiyName I
Library Dcactiptian
D
Libmryíüi ze
Ab 0]
ID
D %
Details o
Populating the details band The details band of the report will repeat itself for each row of data, provided by the dataset in the report. The example dataset includes eleven libraries, so there will be eleven individual rows represented by the objects placed in the details band. To place the dataset fields in the details band, select the Data tab, and then drag-and-drop the Library Name, Library Description, and Library Size fields into the details band, resizing them appropriately to fit the report. « Pentaho Report-Desig File
•
Edit
View
3
H
a
Format
I Welcome @
Data
Window
§
Help
0
0
0
1
(x)
Structure
B •.5 . 1 . 0
El IS]
.1.5
i
• 2.0 . 2.5 . 3.0 • 3.5 • 4.0 • 4.5 • 5.0 • 5.5 • 6 1
Data |
G fx
U l i
Ü
•
Data Sets C3 Table (default) f-
Page Header
default O Library Name (Object)
g
Q Library Description (Ob Report Header
H
Pentalio Report Engine Library Report 1
library Name
Library Description
Q ¡Library Size (Object) Library S Í2
Jí*i Functions Parameters
Libruy D escrjjliori
SB
[37]
Pentaho Reporting Client and Enterprise Examples
Creating a report summary As the final step in completing the report, add a summary section that includes the total number of libraries in the report, along with a total of space needed for all the libraries. First, place a line element at the top of the Report Footer band. Also, place two labels—Library Count: and Total Library Size: —close to the right side of the report. It's now time to create the functions necessary to calculate the total number of libraries and their size. Click on the Data tab and right-click on the Functions item in the tree. Click the Add Function... menu item. Select the Count (Running) function within the Running functions group and click Add. Name the function Library Count. Also add a Sum (Running) function, which is located in the Running functions group. Name the function Total Library Size. Set the Field Name to Library Size. Finally, drag-and-drop the Library Count and Total Library Size functions into the Report Footer band. Feel free to adjust the style of these labels and fields. H
Util
m
J
Pentalio R e p o r t E n g i n e L i b r a r y R e p ort Report Header
Library Naine
Library Description
Library Size
Library Name
Library D esaiptimi
Library Siae
Q
m
Item Count Function: Library Count
Q Item Sum: Total Library Size
B0
%
Library Description (Object) Library Size (Object)
Ji»i Functions
A& Details
• 0
Q Convert To Number: Size Conversion library Report Footer
L
Coutii: Library Count
3
Parameters
Total librcay Size : Total Library Size 1
1
Previewing and saving your report The Report Designer allows you to preview your report by clicking on the Preview icon in the toolbar above the canvas. Alternatively, you may preview the report in various output formats by clicking on the menu File | Preview As. Take a look at the example report to make sure all fields appear and render appropriately.
[38]
Chapter 1 Pentaho Report-Desig File
Edit
View
[We a
a
Format
Data
f Welcome (x)
Window
Help
www s a i
' (x)
s> a
I Structure
| Data
ö H
a
B Data Sets ? C3 Table (default) ? [ 3 default 0
Library Name (Object)
Q Library Description (Object) P e i i t a l l o R e p o r t E n g i n e L i b r a r y R e p 011
0
Libraiy Description
LibiaiySize
lib Bis«
Library c outlining c oiimm functions
121Ï45
LibLotder
Loi tliig aid L « diing libra ry
133900
LibraiyNante
libôeiulmi
Itva semlratimi utility übnty
Lib Repository
Hierarchial storage ltraiy
LJbHnl
XML utility litmiy
7285(3
libFomiuii
fmplemanlatmi of QpenFomiul»
36S26i
LibRnns
Füianrüiry library
2+8320
LibDoc Bundle
ZIP bundle library
lib Format
Sting formatting übrn}'
69+64
Report Ehgine Cijre
Gase report engine
337304?
Report Eligius Extensions
Group of cornu
25SS9 63655
Library Size (Object)
J\*\ Functions 0
Item Count Function: Library Count
0
Item Sum: Total Library Size
Q Convert To Number: Size Conversion Parameters
7118(3
92335 Libraiy Count: 11 Total Libraiy Sze:
Once you are satisfied with the look of your report, save the report for later access by the Swing and J2EE examples. Go to File | Save As, and save this report as chapter2/data/chapter2_report. prpt, in order to access it later. The prpt file generated by the Report Designer is similar to OpenOffice.orgs's OpenDocument format. This file is a ZIP bundle that includes a main report XML file, along with other supporting files, including any necessary images, data source information, sub-reports, and more. If you are interested in viewing the contents of the file, use your favorite unzip utility and extract the included files. You've successfully built your first report with Pentaho Reporting! Now you'll need a place to execute your report. For non-developers, Pentaho provides an open source business intelligence reporting server, discussed in the last chapter of this book. The next two examples demonstrate embedding your report into a custom Swing and J2EE application.
[39]
Pentaho Reporting Client and Enterprise Examples
Embedding your report in a Swing application You're now going to leave the world of what-you-see-is-what-you-get report building and enter Java land. This example includes defining a simple Swing application that will include Pentaho Reporting's Swing preview dialog, affectionately named PreviewDialog. The example application will simply render a report. With the help of the PreviewDialog helper widget, you'll be able to save the report in a variety of formats, along with being able to preview and print right from the application.
Setting up the Swing example application The first step in building the application is to define a Swing application shell. This example shell is an extremely simple Swing application that is only a few lines of Java code. You'll start adding to it once you've got the initial application defined and once it is successfully compiled. In the chapter2 directory, create two new subdirectories called src and lib. The src subdirectory will contain the entire example source, and the lib subdirectory will contain all the necessary JAR dependencies. Create the file chapter2SwingApp. j ava in the src directory with the following Java code: import j ava.awt.*; import j ava.awt.event.*; import javax.swing.*; public class Chapter2SwingApp extends JFrame { // constructor which displays the simple // application shell public Chapter2SwingApp() { super("Chapter 2"); // exit the JVM when the window is closed this.addWindowStateListener(new WindowAdapter() { public void windowClosed(WindowEvent e) { System.exit(0);
}>;
}
// display a preview and exit button in the // main window of the example application. add(new JLabel("Chapter 2 Swing Application")); JPanel buttonPanel = new JPanel(); JButton previewButton = new JButton("Preview"); [40]
Chapter 2 JButton exitButton = new JButton("Exit"); buttonPanel.add(previewButton); buttonPanel.add(exitButton); add(buttonPanel, BorderLayout.SOUTH); previewButton.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent e) { onPreview();
exitButton.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent e) { System.exit(0);
// The onPreview method is called when the preview // button is pressed public void onPreview() { // TODO: Load Report and Launch the Preview Dialog
} // the main method is the entry point into our application public static void main(String args []) { // TODO: Initialize the Reporting Engine Chapter2SwingApp app = new Chapter2SwingApp(); app.pack(); app.setVisible(true);
For n o w , the c o d e contains t w o T O D O c o m m e n t s w h e r e Pentaho Reporting Engine integration c o d e will go. To c o m p i l e a n d run this application, you'll n e e d to define a simple A n t build. xml file, located in the chapter2 folder. This file includes all the necessary targets a n d classpath entries for building the complete S w i n g application. «project name="Chapter 2 Examples" default="run"> «include name="*.jar" /> [41 ]
Pentaho Reporting Client and Enterprise Examples «include name="*.jar" /> T h e first A n t build target, clean, clears out the c o m p i l e d class files f r o m the classes directory. T h e s e c o n d A n t build target, compile, generates the class files a n d places t h e m in the classes directory. T h e final A n t build target, run, executes the Chapter2SwingApp J a v a application. Y o u ' v e n o w set u p the J a v a application shell a n d build script. Verify that y o u can run the S w i n g application b y typing ant in the chapter2 project directory. Y o u should see a w i n d o w a p p e a r with a P r e v i e w a n d a n Exit Button.
E
Chapter 2
0 @ ®
[Chapter 2 Swing Application!
L
Preview
[42]
Exit
J
Chapter 1
Incorporating Pentaho Reporting into the application As the first step towards integrating Pentaho Reporting into your example application, you need to copy the necessary reporting engine JAR files. These JAR files are already a part of the Pentaho Report Designer located in the designer's l ib directory. You simply need to copy them into the chapter2/lib directory. Each JAR file appears with a version number in the Report Designer. Because the version numbers may vary, they are not included in this list. Following is the list of the JAR files that you must copy into chapter2/lib for the examples to compile and run successfully: •
commons-logging-api.jar
•
itext.j ar
•
poi.jar
•
libbase.jar
•
libdocbundle.jar
•
libfonts.jar
•
libformat.jar
•
libformula.jar
•
libloader.jar
•
librepository.jar
•
libserializer.jar
•
libxml.j ar
•
pentaho-reporting-engine-classic-core.jar
•
pentaho-reporting-engine-classic-extensions.jar
In addition to the eleven libraries discussed in the first chapter, you must also include three external libraries. Pentaho Reporting uses Apache Commons Logging for logging, iText for rendering PDF documents, and POI for rendering Excel documents. Additional libraries are required when working with charts and other extensions to the reporting engine.
[43]
Pentaho Reporting Client and Enterprise Examples
Now that the JAR files have been copied, you can begin writing the necessary integration code, embedding Pentaho Reporting into your sample chapter2SwingApp. j ava source file. First, start off by initializing the reporting engine within the application's main method: public static void main (String args[]) { // TODO: Initialize the Reporting Engine ClassicEngineBoot.getlnstance().start(); Chapter2SwingApp app = new Chapter2SwingApp();
This single line of code allows the Pentaho Reporting Engine to boot up. The boot up process includes loading system fonts and initializing the engine, based on configuration properties. In this first example, you do not need to adjust any of the default initialization behavior of the engine. In future chapters, you'll explore the startup process in more detail. To compile, you must also add the following import to the beginning of the file: import
org.pentaho.reporting.engine.classic.core.ClassicEngineBoot;
You are now ready to write the code to render the report using the reporting engine's Swing PreviewDialog helper widget. There are two steps to this process, loading the report and launching the preview dialog. First, add the following lines to the preview button's ActionListener. handleAction () method to load the report definition: public void handleAction() { // TODO: Load Report and Launch the Preview Dialog try { // load report definition ResourceManager manager = new ResourceManager(); manager.registerDefaults(); Resource res = manager.createDirectly( new URL("file:data/chapter2_report.prpt"), MasterReport.class); MasterReport report = (MasterReport) res.getResource();
To load the report, use LibLoader's ResourceManager to generate a MasterReport object. The ResourceManager. createDirectly () API call may throw a
ResourceException, if the resource is not available or fails to load. In addition to this code, you must also add the following Java imports: import j ava.net.URL; import org.pentaho.reporting.engine.classic.core.MasterReport; import org.pentaho.reporting.libraries.resourceloader.Resource; import org.pentaho.reporting.libraries.resourceloader.ResourceManager;
[44]
Chapter 1
Now that the report is loaded, you can launch the preview dialog: // launch the preview dialog final PreviewDialog preview = new PreviewDialog(report) ; preview.addWindowListener(new WindowAdapter() { public void windowClosing (final WindowEvent event) { preview.setVisible(false);
}>;
}
preview.pack () ; preview.setVisible (true) ;
The only parameter provided to the preview dialog is the MasterReport object. The setVisible (true) call renders the dialog on screen.
The following import must also be added: import org.pentaho.reporting.engine.classic.core.modules.gui.base. PreviewDialog;
To finish the onPreview () method, you need to handle the exceptions thrown by the three sections you just wrote. The two types of exceptions thrown, ResourceException, which is thrown when loading the report, and the lOException,
which may be thrown when parsing the URL string, both need to be caught: } catch (ResourceException e) { e.printStackTrace(); } catch (lOException e) { e.printStackTrace();
}
}
The following two imports must be added to complete the handleAction () method: import java.io.lOException; import org.pentaho.reporting.libraries.resourceloader. ResourceException;
In this example application, any thrown exceptions are printed to standard error. In production applications that you build, you may want to present the error in a dialog, or handle the exception differently.
[45]
Pentaho Reporting Client and Enterprise Examples
With this final set of code, you've now completed the first example of embedding Pentaho Reporting into a Swing application. In just 19 lines of code and 8 imports, you've added reporting capabilities to your application! Run the ant command again and see the results: f
Print Preview
Report
Export
a
View
Help
100%
Pentaho
R e p o r t E n g i i i e L ib r a r y R e p
ort
Library Name
Library Description
L i b r a r y S izs
LibBase
Library c oniaining c emmon functions
121745
LibLowler
Loa diig and cachinglibrary
122900
Lib fcrialirer
J « n seràliatioin utility library
256S9
62655
Lib Repository
Hier archial storage Ibraiy
Lib H i d
X M L utility library
72896
LibEbmrnh
Tnip lerne n t i t i m of QjpenFannuk
368263
Lib Etants
Font utility l i b r u y
248320
LibDoc&mdle
ZIP bundle libnuy
711S6
LibFbmiaî
Slriigfamattiiig Ebraiy
38.99 Variance: $0.00
Individual Purchases: Purchase ID: 1 Employee ID: 1 Payment Type: cash Purchase Tune: May 27, 2008 10:05 AM Purchased
Items
Green Electronics MP3 Audio Mini Player
Quantity
Sale Pnce
Total
1
$75.99
$75.99
Purchase Total: $75.99 Purchase ID: 2 Employee ID: 1 Payment Type: cash Purchase Tune: May 27, 2008 10:26 AM P-urrbnrarl Ttamr
rhmntitv
Prim
Tntnl
In this example, you learned how to incorporate reporting formulas and functions, along with using style expressions and multilevel groupings, in order to organize your data. You also learned how to define and use report parameters.
ElectroBarn invoice example It's often the case that a small-or medium-sized business will want to customize their invoices and use a reporting engine to generate standard templates for use. In this example, you'll learn how to build a bursting invoice report, along with learning about additional capabilities of Pentaho Reporting, including sub-reports and external URL linking. As in previous examples, you'll first build the report using the Pentaho Report Designer, and then update your J2EE environment with the necessary changes to render the invoice report. [78]
Chapter 1
Configuring the data source query To start, launch the JDBC Data Source dialog. You've already configured the ElectroBarn JDBC data source, so simply select that option in the Connection list. Now, define a query and launch the query designer, making sure to select the Public schema. This query will involve multiple tables. First, double-click the INVOICES table, in order to add it to your SQL Query. The INVOICES table contains general invoice information, such as the customer ID and shipping information. Next, double-click the INVOICE ITEMS and INVENTORY tables. These tables define the individual invoice items purchased, and will be used to calculate the total invoice price, along with displaying the individual purchased items. You now need to define the relationships between the tables. Within the visual table views, drag-and-drop the INVOICES . INVOICEID column over to the INVOICE ITEMS . INVOICEID column. This sets up an inner join one-to-many relationship between the INVOICES and INVOICEITEMS tables. Now, drag-and-drop the INVOICEITEMS . ITEM ID column over to the INVENTORY, ITEM ID column. You've now set up the relationships between these tables. Finally, you need to specify the correct ORDER BY columns. First, right-click on the INVOICE . INVOICEID column in the tree view and add it to the ORDER BY clause, followed by the INVOICEITEMS . ITEMID column being added to the ORDER BY clause. You should now have the following query defined for the report: SELECT "INVOICES"."INVOICEID", "INVOICES"."CUSTOMERID", "INVOICES"."SALESREP", "INVOICES"."INVOICEDATE", "INVOICES"."SHIPDATE", "INVOICES"."SHIPBY" , "INVOICES"."SHIPCOST" , "INVOICES"."NOTES" , "INVOICEITEMS"."ITEMID" , "INVOICEITEMS"."QUANTITY" , "INVENTORY"."ITEMNAME", "INVENTORY"."ITEMDESCRIPTION", "INVENTORY"."ITEMCATEGORY", "INVENTORY"."ITEMID", "INVENTORY"."ONHAND", "INVENTORY"."ONORDER", "INVENTORY"."SALEPRICE", [79]
Pentaho Reporting Examples in the Real World "INVENTORY"."COST", "INVENTORY"."MANUFACTURER" FROM "INVENTORY" INNER JOIN "INVOICEITEMS" ON "INVENTORY"."ITEMID" = "INVOICEITEMS"."ITEMID" INNER JOIN "INVOICES" ON "INVOICEITEMS"."INVOICEID" = "INVOICES"."INVOICEID" ORDER BY "INVOICES"."INVOICEID" ASC, "INVOICEITEMS"."ITEMID" ASC
Defining the Group Header In this report, you'll define a single group. The root group should include the grouping field INVOICEID. For the group header and footer, uncheck the hide-on-canvas attributes. Now, you're ready to begin populating the group header. Note that because you'll want the ability to burst multiple invoice reports, you'll place no header information in the report header. Instead, you'll place this information in the group header. Include the company's logo as in previous examples, along with displaying company details such as the address, by including labels. Below the company details, add a label that will render as a hyperlink in the PDF. First, define a basic label with the URL http : //www. ElectroBarn. com. Then edit the url style attribute of the label with the same URL. Defining the url style attribute lets the reporting engine's report layout renderer know to create a hyperlink over the defined report element. On the right side of the invoice, include labels and fields to display the INVOICEID, INVOICEDATE, and SALESREP of the invoice, along with a large label clearly marking this report as an invoice. Now, add a sub-report element to the group header, selecting the Inline option. An inline sub-report allows side-by-side sub-reporting, whereas a banded sub-report acts as an additional report band and can have a dynamic height. Size the sub-report to fill half the screen. At the bottom of the group header, you'll add the column headings including Invoice Items, Quantity, Sale Price, and Total. Also, add a colorful rectangular background to the header row, in order to distinguish it from the invoice data.
[80]
Chapter 4
When you've completed these steps, your group headers should look something like the following: INVOICE iif.Dti
mbryoicEn»
iKDils DtteilHYOICEDATE t l i s H i p K ALES REP
Defining the sub-report In the sub-report, display the customer details of the invoice. Right-click on the sub-report element in the canvas and select Edit SubReport. This opens a new canvas tab, where you can edit the sub-report. Bring up the Sub-report Parameters dialog by right-clicking and editing the Parameters tree item in the Data tab of the sub-report. Sub-report Parameters
X
Import Parameters
00
Outer N a m e CUSTOMERID
Inner N a m e CUSTOMERID
Export Parameters
00
Outer N a m e
Inner N a m e
Ok
[81 ]
Cancel
Pentaho Reporting Examples in the Real World Add CUSTOMERID as an import parameter, using the same value for the Outer Name and Inner Name. Once you've configured the CUSTOMERID as an input, configure the sub-report's SQL query. Right-click on the Data Sets tree item in the Data tab, and select the JDBC menu option. Add a data source query with the name customerdetails . This query should include all the columns of the CUSTOMERS table. In addition to adding the table, right-click on the WHERE clause and add a condition where "CUSTOMERS"."CUSTOMERID" = ${CUSTOMERID}. This limits the results of the sub-query to the current customer. Your query result should look like this: SELECT "CUSTOMERS" "CUSTOMERS" "CUSTOMERS" "CUSTOMERS" "CUSTOMERS" "CUSTOMERS" "CUSTOMERS" "CUSTOMERS" FROM "CUSTOMERS" WHERE "CUSTOMERS"
"CUSTOMERID", "NAME", "CONTACT", "ADDR1", "ADDR2", "CITY", "STATE", "ZIPCODE"
"CUSTOMERID"=
You're now ready to populate the sub-report. In this example, place a rectangle with a black border in the sub-report Details band, along with a Customer: label and the appropriate fields to display the customer details. To add the Attn : in front of the CONTACT field, morph the field into a message-field, and edit the value to equal Attn: $(CONTACT). For the CITY, STATE and ZIPCODE fields, morph the CITY field and edit the value to equal $(CITY), $(STATE) $(ZIPCODE).
CUSTOMERID NAME Aitn: Î C C O N T A C T ) ADD E l ADD H W C I T Y ) , E S T A T E ) $(ZIPCODE)
You've now created your first sub-report! This sub-report will be bundled as part of the . prpt file when saving the main report.
[82]
Chapter 1
Defining the Details band The Details band of the invoice report should contain the columns ITEMNAME, QUANTITY, and SALEPRICE. It should also contain a report function of the type Open Formula titled TotalltemPrice, with the formula: =[QUANTITY] * [SALEPRICE]
In addition to the data fields, you'll also include a rectangular background that fills the entire height of the Details band. You'll do some row banding with this rectangle, so make sure to give it a name such as detailsRect. Now, set the visible style formula of the rectangle to the following: = IF(ISEVEN(ROWCOUNT() ) ; TRUE() ; FALSE() )
For every other row, the rectangle will hide itself, allowing the rows of your invoice items to be clearly banded together. B
Details
ITEMNAME
QUANTITY
SALEPRICE
TotillilLiEril 6
Defining the Group Footer and Page Footer To complete the invoice report, you'll need to populate the Group Footer with the necessary summary values, along with a notes section for the invoice. Define a new report function of type Sum that sums the TotalltemPrice expression, in order to calculate the Pur chase Total. Also, define a formula-based number field called TaxTotal with the following formula: =[PurchaseTotal]*0.06
Use a 6% sales tax in the example. For a grand total number field, define the following formula that sums all of the costs: =[PurchaseTotal] * 1.06 + [SHIPCOST]
[83]
Pentaho Reporting Examples in the Real World
In addition to displaying the summarized invoice costs, also add the NOTES field to your report. Text fields have the ability to wrap multiple lines, if necessary. Resize the field to fill in the left portion of the Group Footer as shown in the following screenshot: Nous:
! a n TdtiLPurchiiETBUl Tax Total TaxTctal
0.5
NOTES
i w o i c s Total : luvoic e Tot * 1
1.0 .
Footer
2.0
.
1.5
.
Group
Supping Total: SHIP CO ST
Thank you for shopping at ElectroBarn! pageofpages
As a final touch to the Group Footer, add a friendly message such as Thank you for shopping at ElectroBarn!, which will encourage your customers to continue shopping at ElectroBarn. The very last step in completing the report is to add a page count in the Page Footer band, as well as to force page breaks after each Group Footer. To make this report burstable, you'll want to reset the page counter at the end of every invoice and begin each invoice at the top of a page. You can do this by selecting the pagebreak-after style property in the group footer, which forces a new page below the group footer. Also, you need to set the group property of the Page of Pages Function to the invoice group. You've now completed the design of the report. Save the report as chapter3\data\invoices . prpt.
Incorporating the invoice report into your J2EE environment You're now ready to update your J2EE environment, in order to render the invoices report. There are no changes required to the servlet, but you will need to update the home page of the web application. Add a link to the report, in the HTML of your chapter3 home page, index. html. Invoice Report
[84]
Burst
Chapter 1
You're now ready to run the Ant script and deploy the modified web application. Type the ant restart_tomcat command to build the new war. Visit http: //localhost: 8 08 0/chapter3 and click the Burst Report link. The final result should look something like this:
INVOICE
Electro Barn 7 5 8 7 S h o p p i n g C e n t e r Dr.
n v o l c e ID: 0 0 0 0 3 5 4 3
Sarasota. FL 3 2 1 2 3
Invoice Date: S e p 21, 2 0 0 8
httpV/www. E l e c t r o B a r n . c o m
S a l e s Rep: T o m S c o t t C u s t o m e r : 00000001 Y E P Enterprises Attn: A a r o n G e r b e r 9 2 8 9 E n t r e p r e n e u r i a l Lane Suite 1034 O r l a n d o . FL 3 2 8 2 8 Invoice
Items
Quantity
Sale
Price
Total
Electro RC Car Racer
3
$59.95
$179.85
Ethanol Hybrid RC E n v l r o C a r
3
$44.95
$134.85
Electro RC Solar S p e e d Boat
3
$79.99
$239.97
RememberRing
3
$29.95
S89.85
ScratchTab
1
$39.95
Notes
S39.95
Item Total:
S684.47
Tax Total
$41.07
S h i p p i n g Total:
$25.00
nvolce T o t a l
S750.54
Thank you for shopping at ElectroBarn!
This report could be sent directly to a printer to generate all the invoices for a day. Or you could parameterize the report down to an individual invoice, allowing customers to access their invoices online. Another option for bursting might include generating individual PDFs per invoice, and either mailing them out or sending them to another system to process. In this example, you learned how to add a sub-report to a main report, along with learning additional functions and styles, including row banding, URL display, and page breaking.
[85]
Pentaho Reporting Examples in the Real World
Summary In this chapter, you built three real world reports, learning the breadth of functionality provided by Pentaho Reporting. In the first example, you learned how to work with SQL data sources, define charts, and how to use formulas and functions in an inventory report. In the second example, you defined a parameterized cashier balance report with dynamically driven styles, including adding traffic lighting to the report. In the third example, you incorporated inline sub-reports into an invoice report, along with adding hyperlinks and row banding to the report. You embedded these reports in a J2EE environment, which involved adding JAR dependencies for charting and updating your servlet to support parameterization. Now that you've experienced Pentaho Reporting in the real world, it's time to dive deeper into each subject area, allowing you to gain the expertise to build advanced reports with Pentaho Reporting.
[86]
4
Design and Layout in Pentaho's Report Designer In this chapter, you'll dive deep into the concepts and functionality of Pentaho's Report Designer, related to the design and layout of a report. The Report Designer is designed for business users who want to design reports in a what-you-see-is-what -you-get (WYSIWYG) drag-and-drop client environment. You'll first learn about the Report Designer's user interface, highlighting the different components that work together to build a report. You'll then learn more about the core layout bands presented in the Report Designer, including detail and group bands. From there, you'll explore in detail the various elements available to designers, how they are used, and what they might be used for. You'll also learn the ins and outs of visual layout within the reporting canvas, including advanced concepts such as grids and guides. You'll close the chapter with more details when working with fonts, along with considerations for dealing with the various output formats supported by Pentaho Reporting.
Report Designer user interface components After launching the Report Designer, you'll notice the following six main user interface components that work together to create a report, from the top left to the bottom right of the main Report Designer window: •
The menu and toolbar
•
The report element palette, where you can select report elements for your report
•
The report canvas tab panel, which displays your reports
Design and Layout in Pentaho's Report Designer
•
The Report Explorer panel with Structure and Data tabs, which displays the entire report in object tree form
•
The Element Properties panel, which displays all the Styles and Attributes associated with the currently selected report element
•
The Messages panel, which displays warnings and errors related to the currently opened report
M f f l a a a File Edit View
iMm Format
•IIMIB
Data
Window
Help
W B
0
[o]
0
j (x)
I Structure | Data | 0.5
1.0
1.5
2.0
B 2.5
I 0.0
n 3.5
mm m
U 4.0
4.5
5.0
5.5
6.0
[ ï l
l ^ l ^ l
¡Master Reportl • Page Header H Report Header - { 3 Groups - U Report Footer o- _ Page Footer o - n Watermark
Report Header
Style
Attributes
Name family bold italics
text-wrap text-color
© This report does not define a query. No data will be available in the report.
.
Menu and toolbar The menu and toolbar contain useful functionality to make building a report easier, along with basic functionality such as saving, opening, and publishing of reports. Many of the options in the menu and toolbar are available as shortcut keys.
[88]
Chapter 1
Report element palette The report element palette panel is located on the left side of the Report Designer and contains an icon list of the types of elements that can be placed on the report, including labels, shapes, fields, charts, and more. To add an element to your report, drag-and-drop an element from the palette into the report canvas.
Report canvas tab panel The report canvas tab panel is located in the center of the Report Designer. Once you've created a new report or opened an existing one, this is where you drag-and-drop report elements to build your report. In design mode, the canvas displays the currently visible report bands. The canvas offers many visual features that allow you to manage the alignment and sizing of your report elements. In addition to the design canvas, you can also preview the current report. You can quickly toggle between live data and the report template in this fashion.
Report Explorer The Report Explorer, located on the right side of the Report Designer, includes a Structure tab panel. The Structure tab panel contains the tree structure of a report, including all the report bands. The Data tab panel contains all the data sources, functions, and parameters of a report. Right-clicking on various portions of the structure and data trees presents options such as adding new data sources and sub-groups. The Report Explorer may be hidden through the Window application menu.
Element Properties The Element Properties panel is located below the report explorer panel, on the right side of the Report Designer, and displays the details of the currently selected item in the report explorer or canvas. All styles and attributes, which are editable, appear in this panel. Many editable properties provide additional dialogs for advanced editing capabilities. The Element Properties panel may be hidden through the Window application menu.
[89]
Design and Layout in Pentaho's Report Designer
Messages The Messages panel is located at the bottom of the Report Designer and displays any active warnings or errors that are present in the report. Selecting a message will automatically select the element and property in question, making it easy to track down issues in your report. The Message panel is hidden by default, and can be made viewable through the Window application menu.
Report bands When first creating a report in your canvas and report explorer structure tree, you will see a Page Header, Report Header, Details band, Report Footer, and a Page Footer band appear as part of the report. These bands, along with other bands, including Group, Watermark, and No Data bands that you may define, make up the entire visual report. All bands may contain elements from the palette, and act as containers for rendering these elements. Each band has a different life cycle, and is rendered based on their context. In this section, you'll go over each band's properties, along with the context in which each band renders itself.
Common properties All bands share a common set of properties, which are explained using tables in the forthcoming sub-sections. Certain properties may offer a dialog for editing, which is displayed in the list as well.
Size and position properties These properties define the size and position for the band. These properties may be edited together by selecting the band in the structure tree and then clicking on the Format | Size & Border... menu item, or individually within the Report Element Styles tab.
[90]
Chapter 1
D
Font
üJ [^Advanced Font-Settings
Minimum Size Width
| Paragraph
| Hyperlinks
| Size and Borders
|* Color and Background
Borders
10.0
None
All
Horizontal
Vertical
Line-Style Style
Left
solid
Height |10.0
dashed dot-dash
Paddings
dot-dot-dash Left Right Top
JÜ
dotted
S m
hidden none double groove
Bottom
inset outset ridge wave
Ftounded Corners Width
m
Color
Height
j1
Width I
Cancel
I
The following table lists the size and position properties: Property name
Description
layout
Defines how elements within the band are rendered. •
The default layout is canvas, which allows you to specify exactly where each report element in the band should render.
•
The block layout stacks all the items in a band from top to bottom.
•
The inline layout stacks all the items left to right, with wrapping.
•
The row layout displays all the report elements in a single row.
height
The height of this element. A number between -100 and 0 represents a percentage of the parent container's height.
width
The width of this element. A number between -100 and 0 represents a percentage of the parent container's width. The x location of this element within its parent container.
y
The y location of this element within its parent container.
visible
If set to false, the element is not rendered.
invisible--cosumes-space
If set to true, children of this band that are invisible will still consume space in the report.
dynamic-height
If set to true, informs the reporting engine that this element has a dynamic height. [91]
Design and Layout in Pentaho's Report Designer Property name
Description
preferred-height
The preferred height of this element.
preferred -width
The preferred width of this element.
max-height
The maximum height of this element.
max-width
The maximum width of this element.
x-overflow
If set to true, text may overflow horizontally outside of the element.
y-overflow
If set to true, text may overflow vertically outside of this element.
fixed-position
If specified, sets the fixed vertical position of this band within a report.
box-sizing
This is either set to content-box or border-box. If set to content-box, the sizing styles do not include the border, and if set to border-box, the sizing styles do include the border box. The default value of this style is content-box.
Padding and border properties These properties define the padding and border definition for the band. Border information includes thickness, line type, and color. These properties may be edited together by selecting the band and then clicking on the Format | Size & Border... menu item, or individually within the Report Element Styles tab.
• Font
ü l
\ Advanced Font-Settings
Minimum Size Width
| Paragraph
[ Hyperlinks
| Size and Borders
Borders
10 0
None
All
Horizontal
Height |10.0
Vertical
Left
Color anil Background Line-Style Style solid dashed dot-dash
Paddings
dot-dot-dash Left
[
Right
|
S M
dotted hidden none
Top Bottom
double
s
groove inset outset ridge Rounded Corners
wave
Width
Color
Auto...
Height
Width
I OK
[92]
T
Cancel
Chapter 1
Padding Styles Property name
Description
top
The height of the padding on the top of an element.
bottom
The height of the padding on the bottom of an element.
left
The width of the padding on the left of an element.
right
The width of the padding on the right of an element.
Border Styles Property name
Description
top-style
The style of the top border.
top-size
The width of the top border.
top-color
The color of the top border
top-left-height
The height of the top left corner's radius.
top-left-width
The width of the top left corner's radius.
top-right-height
The height of the top right corner's radius.
top-right-width
The width of the top right corner's radius.
bottom-size
The width of the bottom border.
bottom-style
The style of the bottom border. Style values include none, hidden, dotted, dashed, solid, double dot-dash, dot-dot-dash, wave, groove, ridge, inset, and outset.
bottom-color
The color of the bottom border. Colors can be represented as strings using the same syntax as HTML colors, #RRGGBB hex values.
bottom-left-height
The height of the bottom left corner's radius.
bottom-left-width
The width of the bottom left corner's radius.
bottom-right-height
The height of the bottom right corner's radius.
bottom-right-width
The width of the bottom right corner's radius.
left-color
The color of the left border.
left-size
The width of the left border.
right-size
The width of the right border.
right-style
The style of the right border.
break-color
If the element is split, this is the color of the border where the break occurred.
break-size
If the element is split, this is the width of the border where the break occurred.
break-style
If the element is split, this is the style of the border where the break occurred.
[93]
Design and Layout in Pentaho's Report Designer
Page behavior properties Page behavior properties impact how bands are rendered relative to individual pages. Property name
Description
pagebreak-before
Places a page break before rendering the band.
pagebreak-after
Places a page break after rendering the band.
avoid-page-break
Forces the band to skip to the next page instead of a split rendering.
orphans
Hie number of contiguous bands to group before a page break occurs.
widows
The number of contiguous bands to group after a page break
Foreground and background color properties Bands have default foreground and background colors. These colors appear within the Styles tab as text-color and bg-color.
Excel properties Report bands define specific properties related to Excel. Property name
Description
sheet name
The name of the sheet to render the band.
format-override
The Excel cell data format string.
formula-override
The Excel cell data formula string.
wrap-text-override
If true, wraps a text-based report element text within an Excel Cell. This value is inherited by text-based report elements within the band. [94]
Chapter 1
Attribute properties The following common attribute property is shared by all bands: Property name
Description
hide-on-canvas
If checked, the band will not appear in the canvas, otherwise it will appear. This property does not impact whether a band is rendered or not during report generation. It is strictly a design time property.
Style inheritance Additional styles are available for each band, which are inherited by the report elements within the band. Report elements inherit the style properties of their parent band.
Page Header and Page Footer The Page Header and Page Footer bands appear at the beginning and end of each page, determined by the specific output format. These bands differ slightly from the common properties defined earlier. The pagebreak-before and pagebreak-after properties do not apply to these bands. Also, the following properties are available in addition to the defaults: Property name
Description
display-on-firstpage
The default value is true for this property. If set to false, the first page will not contain this band.
display-on-lastpage
The default value is true for this property. If set to false, the last page will not contain this band.
sticky
If the Page Header or Footer is defined as sticky, they will be printed on each page as if they were part of a sub-report definition being rendered.
Report Header and Report Footer The Report Header and Report Footer appear at the beginning and end of a report, and are often used to display the title and summary information. The Report Header and Footer do not define any additional properties beyond the common set of properties.
[95]
Design and Layout in Pentaho's Report Designer
Group Header and Group Footer The Group Header and Group Footer bands may appear for each defined group configured as part of the report. A grouping defined in a report is a set of identical values in one or more selected data columns. A new group is triggered when the values change in the defined group column(s). It's critical that columns defined as groupings are sorted appropriately before being passed into Pentaho Reporting, otherwise, duplicate groups may appear in the rendered report. The Group Header and Footer differ slightly from the common properties defined earlier. Property name
Description
sticky
If the group header or footer is defined as sticky, they will be printed on each page as if they were part of a sub-report definition being rendered.
repeat-header
The band will be displayed at the beginning of new pages, in addition to its default rendering.
Details Body The Details Body consists of four distinct bands. The Details Header and Details Footer band are rendered before and after a grouping of detail rows. A Details band is rendered for every row of data, and a No Data band is rendered when no data is available for the report. The Details Header, Details Footer, and No Data bands are hidden in the Report Designer by default. The Detail Header and Footer bands share the same additional properties, sticky and repeat-header, as the group bands. The rest of the detail bands define no additional properties beyond the common set of properties.
Watermark The Watermark band appears behind all the other bands, and is used for background images and styling of the report. The Watermark band defines no additional properties beyond the common set of properties.
Report elements All available report elements appear in the palette, and may be dragged and dropped into the report canvas. Report elements make up the content of your report. They range from the label and text elements to graphic, chart, and sub-report elements.
[96]
Chapter 1
Common properties Most report elements inherit from a common set of properties, which are listed in the following table: Property name
Description The unique name of the element within the report. This property is not commonly edited.
Size and Position Properties
The X and Y location of the element, in relation to its parent band. These properties appear in the style attributes list as x and y.
Padding and Border Properties
The padding and border definition of an element. Border information includes thickness, line type, and color. These properties may be edited together by selecting the band and then clicking on the Format | Size & Border... menu item, or individually within the Report Element Styles tab. Report Elements share the same individual padding and border properties as report bands defined above.
Additional properties shared by report elements, including HTML and Event properties, are defined in Chapter 9.
Common text properties These are the list of common text properties shared by text elements, including the label, text-field, message, number-field, date-field, resource-field, and resource-message. One special consideration is that it is possible to morph one type of text field into another by using the menu option Format | Morph. For example, you could convert a text-field into a number-field by simply morphing the field.
[97]
Design and Layout in Pentaho's Report Designer
Font style properties Font properties of a report element may be edited as a group by selecting Format | Font..., or edited individually within the Element Properties Style tab. They may also be edited using the canvas toolbar.
Font
\ Advanced Font-Settings
| Paragraph
[ "Hyperlinks
Font-Family
|* Size and Borders""^ Color and Background
Font-Style
Arial -
Arial
Piain
12
Bold
6
Arial Black
Italics
Arial Narrow
Bold-Italics
10
Arial Unicode MS
12
Bitstream V e r a Sans
14
Bitstream V e r a Sans Mono
16
Bitstream V e r a Serif
18
Book Antiqua
20
Bookman Old Style
24
•
-
=
Underline
Individual font styles are defined later in the Working with fonts section.
Text style properties The following properties impact the appearance of text within report elements: Property name
Description
h-align
Hie horizontal alignment of the text within the element. This property is also editable in the main toolbar.
v-align
The vertical alignment of the text within the element. This property is also editable in the main toolbar.
v-align-in-band
Specifies the vertical alignment of text. Appropriate values include use-script, baseline, sub, super, top, text-top, central, middle, bottom, and text-bottom.
text-wrap
Specifies if the text should wrap. Appropriate values include none and wrap.
text-color
The foreground font color. This property is also editable in the main toolbar.
bg-color
The background color of the text element.
line-height
The value of the font's line height within the text element. [98]
Chapter 1 Property name
Description
overflow-text
This is normally set to "..", and is the text that is appended to the string if it appears longer than the available space to render. This appears as overflow-text in the styles list.
trim
If trim is set to true, any leading or trailing whitespace is removed.
trim-white space
trim-whitespace defines the following different trim modes: • The preserve option makes no changes to whitespace. • The preserve-breaks option trims all whitespace between words, and at the beginning and ending of new lines, but does not remove any new lines. •
The collapse option trims all whitespaces down to single spaces, including new lines.
•
The discard option removes all whitespaces from the text element.
encoding
If set, this overrides the default PDF Font character encoding.
rich-text-type
The type of text to render in the report. This attribute defaults to text/plain, but also may be set to text/html and text/rtf. If text/html is specified, html formatting elements are rendered within the text report element, the same concept applies for the text/rtf format. This attribute is located in the common group within the Attributes tab.
Text spacing properties Text spacing properties define how characters are rendered in text elements. Property name
Description
character
Specifies the minimum character spacing when rendering justified text.
word
Specifies additional padding between words when rendering.
preferred-character
Specifies the preferred character spacing when rendering justified text.
character-spacing
Specifies the maximum character spacing when rendering justified text.
[99]
Design and Layout in Pentaho's Report Designer
Link properties Report elements may specify link properties, allowing links to appear in a report. Property name
Description
html-anchor
The name of the anchor tag in HTML.
url
The url of the link.
url-tooltip
The tooltip of the link.
url-window-title
The window title of the link.
Excel properties Report elements may customize specific style properties related to Excel. Report elements share the properties format-override, formula-override, and wrap-textoverride, defined earlier in the common properties section of report bands.
label The label element Ab allows you to specify static text within your report. Label utilizes the following property: Property name
Description
value
The text to render the report.
text-field The text-field element [H] allows you to render a field as text within your report. The text-field utilizes the following properties. Property name
Description
field
The source field to render within the text field.
if-null
The string to display if the source field value is null.
message The message element HÎ3 enables field values to be included in larger messages, along with combining multiple fields into a single text element. The message element references the data source within the format string, by specifying "$(Field Name)" for the fields to render. The message element utilizes the following properties:
[100]
Chapter 4 Property name
Description
value
The value attribute represents the format of the string. An example might be "Field: $(Field)".
if-null
The string to display if the message field value is null.
number-field The number-field element !H1 is similar to the text-field, with an additional ability to format a number based on a format string. The number-field utilizes the following properties: Property name
Description
format
This field represents the format of the number, using fava's Decimal Format definition. An example might
be "#,##0.###".
field
The source field to render within the number field.
if-null
The string to display if the source field value is null.
date-field The date-field element ilg] is similar to the text-field, with the additional ability to format a date based on a format string. The date-field utilizes the following properties: Property name
Description
format
This field represents the format of the date. An example might be mm-dd-yyyy.
field
The source field to render within the date field.
if-null
The string to display if the source field value is null.
[101 ]
Design and Layout in Pentaho's Report Designer
resource-label The resource-label element Ah is similar to the label element, except that it loads its text from an internationalized resource file. The resource-label utilizes the following properties: Property name
Description
resource-identifier
The primary name of the resource file. For example, if the default localized resource file is named myreport. properties, this value should be set to myreport. Also note, the report's resources path must be configured to point to the directory where the localized resource files exist.
value
The key name (located in the resource file) of the resource to render.
resource-message The resource-message element is similar to the message field, except that it loads its format key from a resource file. The resource-message element utilizes the following properties: Property name
Description
resource-•identifier
The primary name of the resource file.
resource-•value
The key name of the resource message to render.
if-null
The string to display if the resource format key message field's value is null.
resource-field The resource-field element ^ is similar to the resource-label, except that it determines the resource key using the field name provided by the data source. The resource-field utilizes the following properties: Property name
Description
resource-identifier
The primary name of the resource file.
field
The name of the field to render as text within the resource file.
if-null
The string to display if the resource field value is null.
The following elements do not include the common text properties, and are not considered text elements.
[102]
Chapter 1
chart The chart element [©] allows you to place a chart within your report. The chart element, in its various forms, contains a large number of properties that are covered in Chapter 6.
content (static image) The content element Sfc allows you to place a static image in your report. You may edit the location of the content element by right-clicking on the element and selecting Edit Content.... When selecting an image, you may choose to embed it into the report definition, or link to it externally. The content element utilizes the following properties: Property name
Description
value
The URL of the image to render. This displays a file dialog for selecting an image. HTTP and other virtual file system URLS may be used as well.
aspect-ratio
It should be set to true for the image to keep its aspect ratio when rendering. This is a style attribute within the object category.
scale
It should be set to true for the image to adjust its width and height, based on the report element's width and height. This is a style attribute within the object category.
content-field (dynamic image) The content-field element Ly] is similar to the content element. However, it allows you to dynamically determine the content of the image, based on a report field. The content-field utilizes the following properties: Property name
Description
field
The name of the data source field that populates the image. The content-field element is often used in conjunction with report functions that generate Drawable objects.
If-null
The content to display if the field is null.
aspect-ratio
It should be set to true for the image to keep its aspect ratio when rendering.
scale
It should be set to true for the image to adjust its width and height, based on the report element's width and height. This is a style attribute within the object category.
[103]
Design and Layout in Pentaho's Report Designer
rectangle The rectangle element \ ! allows you to render a rectangle within a report. The rectangle utilizes the following properties: Property name fill
Description If set to true, it fills the rectangle with the selected value of fill-color.
fill-color
The color of the rectangle.
aspect-ratio
If true, maintains an equal width and height of the rectangle.
draw-outline
Draws the border of the rectangle if set to true.
arc-width
It defines the width of curved edges. The default value is 0.0.
arc-height
It defines the height of curved edges. The default value is 0.0.
ellipse The ellipse element G allows you to render an ellipse within a report. The ellipse element utilizes the following properties: Property name fill
Description If set to true, it fills the rectangle with the selected value of fill-color.
fill-color
The color of the ellipse.
aspect-ratio
If true, maintains an equal width and height of the ellipse,
draw-outline
If set to true, it draws the border of the ellipse.
horizontal-line and vertical-line The horizontal-line and vertical-line elements EEI LiJ allow you to draw a line within a report. These elements utilize the following properties: Property name
Description
stroke
The width and pattern in which to draw the line. [H^^M
xj
Width: 5.0 Dashes: Sample
OK
text-color
Cancel
The color in which to render the line. [104]
Chapter 1
band The band element allows the grouping of other elements into a single group, making it easier to control the group's location and size as a single unit. Tbe band element utilizes the following properties: Property name
Description
layout
The layout method of rendering the grouped components. This is identical to the layout attribute, which is defined above as a common property of bands.
hide-on-canvas
If true, the element will not appear in the canvas, otherwise it will appear. This property does not impact whether the element is rendered or not during report generation.
sub-report The sub-report element 1 3 allows you to embed a sub-report within a band of your main report. The sub-report element utilizes the following properties: Property name
Description
query
The query name to use as the data source for the sub-report.
limit
If specified, limits the rows of data rendered in a sub-report.
timeout
If specified, limits the maximum time a sub-report query may execute.
survey-scale The survey-scale element renders a simple scale within a report. The survey-scale element utilizes the following properties: Property name
Description
field
If specified, the name of the data field which contains either a single value that renders a point in the scale, or a three value array that renders a point, along with a low and high marker within the survey scale.
value
If specified as a single number, this value is rendered as a point in the scale. If specified as a three number array, it will render as a point, along with a low and high marker. This value may also be a single string, with numbers separated by commas — for example, "3,1,5".
highest
The highest number to render in the scale.
[105]
Design and Layout in Pentaho's Report Designer Property name
Description
lowest
The lowest number to render in the scale.
upper-bound
The range-upper-bound value defines the upper bound of a background rectangle rendered as part of the survey-scale.
lower-bound
The range-lower-bound value defines the lower bound of a background rectangle rendered as part of the survey-scale.
line-sparkline T h e l i n e - s p a r k l i n e e l e m e n t ¿1 r e n d e r s a sparkline in a report. T h e l i n e - s p a r k l i n e e l e m e n t utilizes the f o l l o w i n g properties: Property name
Description
field
If specified, the field represents an array of numbers, which get rendered as a sparkline. This array may be represented as a comma separated string as well.
value
If specified, the array of numbers is rendered as a sparkline.
spacing
It helps specify the pixel spacing between each point in the sparkline. Unless specified, it defaults to 2 pixels.
bar-sparkline T h e b a r - s p a r k l i n e e l e m e n t 1=3 r e n d e r s a s i m p l e b a r chart in a report. T h e b a r sparkline e l e m e n t h a s t h e s a m e p r o p e r t i e s a s the l i n e - s p a r k l i n e e l e m e n t .
pie-sparkline T h e p i e - s p a r k l i n e e l e m e n t ¡i) r e n d e r s a s i m p l e p i e chart, b a s e d o n a single v a l u e b e t w e e n 0 a n d 1. T h e p i e - s p a r k l i n e e l e m e n t utilizes t h e f o l l o w i n g properties: Property name
Description
field
If specified, it is the field containing the pie slice value,
value
If specified, it is the value of the pie slice.
low-slice
The maximum percentage value to be considered as a low slice. This value defaults to 0.30.
medium-slice
The maximum percentage value to be considered as a medium slice. This value defaults to 0.70.
high-slice
The maximum percentage value to be considered as a high slice. This value defaults to 1.0
[106]
Chapter 5 Property name
Description
low-color
The color in which to render the pie slice if it's in the low-slice range. This value defaults to green.
medium-color
The color in which to render the pie slice if it's in the medium-slice range. This value defaults to yellow.
high-color
The color in which to render the pie slice if it's in the high-slice range. This value defaults to red.
simple-barcodes T h e simple-barcodes element EJf renders a b a r c o d e i m a g e in a report. T h e simple-barcodes element utilizes the f o l l o w i n g properties: Property name
Description
type
Found under the barcode-settings category in the Attributes tab. This is the name of the type of barcode to render. To get a full list of supported types and supported values for each type, see the report engine extensions favadoc for the following class: org . pentaho . reporting . engine . classic . extensions. modules.sbarcodes.SimpleBarcodesUtility
field
If specified, it is the field containing the barcode value.
value
If specified, the value of the barcode.
show-text
If set to true, the value of the barcode is displayed below the barcode.
checksum
If set to true, includes a checksum in certain types of barcodes.
bar-width
The width in pixels of the barcode lines. If not specified, defaults to one pixel.
bar-height
The height in pixels of the entire barcode. If not specified, defaults to 10 pixels.
Visual layout in Report Designer W i t h Pentaho Report Designer, y o u h a v e pixel level control of your individual elements w i t h i n a report. Grid a n d guide lines m a y appear w i t h i n each report canvas band, w h i c h m a k e it simple to align a n d configure locations of the elements.
[107]
Design and Layout in Pentaho's Report Designer
The Grid By default, the report grid is hidden from view. To enable the grid, enable the menu item View | Grids | Show. The grid presents itself in point units (also known as pixel units), with a light gray grid line displayed every five pixels, along with a darker shade guide line presented every 25 pixels. Grid lines are useful for visual feedback of alignment, as well as providing a method to snap elements to the grid. This makes aligning of elements a simple exercise. Tod
50
L
TSO
200
2=
Ruier — G r i d Line
=
*>
M a j o r Line
To adjust the ruler unit to centimeters, millimeters, inches, or picas, go to the View | Units sub-menu. The default grid size may be adjusted from five pixels to another number by launching the grid size dialog. Select the View | Grids | Settings menu item and adjust your grid sizing. Note that the darker shade major guide line appears between every five regular grid lines. You may show or hide the grid by selecting the menu item View | Grids | Show, or by pressing Ctrl+Quote.
Guide lines Guide lines allow you to specify a custom grid line. To add a new horizontal or vertical guide line, click within the ruler section of the report canvas. A new blue guide line should appear. Guide lines are useful for visual feedback of layout, as well as snap to grid features that simplify element placement. 50
100
150
200
1—1
i-e a cElectro Barn c a
a a
Guide lines may be moved by dragging their location within the ruler. They may also be moved by right-clicking on the line within the ruler and selecting Properties..., and then typing in the new value for the guide line. [108]
Chapter 5
It is possible to deactivate a single guide line by right-clicking and selecting Deactivate. This causes the guide line to be removed from the report canvas content, and appear as a greyed out mark within the ruler section of the canvas. Also, guide lines may be completely removed from the report by right-clicking and selecting Delete. All guide lines may be activated and deactivated together by selecting View | Guides | Show Rulers, or by clicking Ctrl+Semicolon. This is useful if you use many guidelines and want to quickly see the report without all the blue lines running through it.
Additional visual indicators In addition to grid lines and grid guides, a couple of other handy shortcuts exist to make it easier to lay out your report. By default, when selecting a report element, the style of the selection is considered an Outline Selection. An alternative selection style is Clamp Selection. You may toggle between these two types of selections by selecting View | Outline Selection or View | Clamp Selection. ; a a «ElectroBarn < ?pentaho-dataset j ava.lang.String,j ava.lang.String,j ava.lang.Integer? > LibBase Base library containing common functions 113210 LibLoader Loading and caching library 53 552 Due to the verbosity of XML, this example is limited to a couple of rows. Once you've created the XML file, you need to deploy the correct extension JAR files to the chapter5/lib directory. Copy the pentaho-reporting-engine-classic -extensions-xpath. jar file, located in the Report Designer's lib folder, into the chapter5/lib folder. Now, you're ready to write some code. As in the earlier examples, add the following load data section to the onPreview method within a freshly copied Chapter2SwingApp, renamed to XPathDataFactoryApp: // load report xpath data XPathDataFactory factory = new XPathDataFactory(); factory.setXqueryDataFile("file:data/xpathexample.xml"); factory.setQuery("default", "/ExampleResultSet/Row"); report.setDataFactory(factory) ; Also, make sure to add the following import at the beginning of the file: import org.pentaho.reporting.engine.classic.extensions.datasources. xpath.XPathDataFactory;
[131]
Working with Data Sources Due to the naming of column headers in XPathDataFactory being mapped to the element node names in the XML file, you must also modify the sample report. Copy chapter2_report. prpt to chapter5/data/xpath_report. prpt, and change the referenced field names in Pentaho Report Designer, as shown in the following bullet list: •
Library Name to NAME
•
Library Description to DESCRIPTION
•
Library Size to SIZE
Also change the Total Library Size function's Field Name to SIZE. Once you've saved your changes, update the xPathDataFactoryApp class with the new location of the report PRPT file. Finally, you'll need to add the following Ant target to your build. xml file: Type ant runxpath on the command line to verify the results.
HQLDataFactory The org.pentaho.reporting.engine.classic.extensions.datasources. hibernate. HQLDataFactory class allows you to populate your report based on a Hibernate query. Hibernate is an open source relational persistence engine. Hibernate allows you to easily persist your Java objects to a database. Much like many of the other DataFactory implementations, the HQLDataFactory is configured with information to connect to Hibernate, along with the ability to specify named queries. The HQLDataFactory API defines an interface called SessionProvider, which it uses to gain access to the current Hibernate Session object. The SessionProvider contains a single API method, getSession ( ) , which returns an instance of org. hibernate . Session. There are two implemented versions of this session provider. At this time, HQLDataFactory is not available as a data source within Pentaho Report Designer, so code is required to utilize Hibernate as a data source.
[132]
Chapter 5
StaticSessionProvider The StaticSessionProvider simply takes in an org. hibernate . Session object as a constructor parameter, making available the already existing Session object to the HQLDataFactory. This would be used if your system already has an initialized Hibernate session.
DefaultSessionProvider The DefaultSessionProvider requires no constructor parameters, and uses the following API call to generate a SessionFactory from Hibernate: sessionFactory = new Configuration().configure(). buildSessionFactory(); The created sessionFactory instance is used to create new sessions, which the HQLDataFactory uses to query Hibernate. The HQLDataFactory provides two constructors. The first constructor takes in a sessionProvider, as described above. The second constructor simply takes in a Hibernate Session instance, which it uses to query Hibernate. This constructor uses a StaticSessionProvider, under the covers, to pass in the Session to HQLDataFactory. Once you've instantiated your factory, you may add named queries to the factory by making the following API call: void setQuery(String name, String queryString); The setQuery method takes in the name of the query, and the Hibernate query, in order to execute. HQLDataFactory uses Hibernate's query language, which is well-documented at http://www.hibernate.org/hib_docs/reference/en/html/queryhql. html You may include report parameters in your query by using the HQL syntax ": ParameterName" The max results and query timeout parameters are supported by HQLDataFactory.
[133]
Working with Data Sources
HQLDataFactory Example To demonstrate using HQLDataFactory, you must first set up a simple Hibernate application. To begin, download the latest version of Hibernate from http: //www. hibernate. org. This example uses version 3.2.6.ga. Place the hibernate. j ar file and all the JAR files from the Hibernate distribution's lib folder into the chapter5/lib folder. You must also deploy the pentahoreporting- engine- classic- extensions -hibernate . j ar file, located in Pentaho Report Designer's lib folder, into the chapters/lib folder. In the SQLReportDataFactory example given earlier, you defined an HSQLDB data source. You'll reuse that data source in this example. Once you've moved the appropriate JAR files into Chapter 5, you'll need to define a simple Java class, chapter5/src/Librarylnfo. java, which maps to your HSQLDB data source: public class Librarylnfo { private String name; private String description; private long size; public Librarylnfo() {} public void setName(String name) { this.name = name;
} public String getName() { return name;
}
public void setDescription(String description) { this.description = description;
}
public String getDescription() { return description;
}
public void setSize(long size) { this.size = size;
}
public long getSize() { return size;
[134]
Chapter 5 Define the Hibernate mapping between the HSQLDB database and the Libraryinf o class, saved as chapter5/src/Librarylnf o . hbm. xml: «property name="description" type="string"/> «property name="size" type="long"/> Now, you're ready to configure the Hibernate settings file with the appropriate JDBC information and mapping input. Save the following as chapters/src/ hibernate.cfg.xml: «property name="connection.driver_class"> org.hsqldb.j dbcDriver «property name="connection.url"> j dbc:hsqldb: file : data/libraryinfo «property name="dialect">org.hibernate.dialect.HSQLDialect «property name="cache.provider_class"> org.hibernate.cache.NoCacheProvider «mapping resource="Libraryinfo.hbm.xml"/>
[135]
Working with Data Sources At this point, you're ready to add a load data section to the onPreview method within a freshly copied Chapter2SwingApp, renamed to HQLDataFactoryApp: // load hql data source DefaultSessionProvider sessionProvider = new DefaultSessionProvider(); HQLDataFactory factory = new HQLDataFactory(sessionProvider); factory.setQuery("default", "select name as NAME, description as DESCRIPTION, size as SIZE from LibraryInfo"); report.setDataFactory(factory) ; Be sure to add the following import statements at the beginning of the file: import org.pentaho.reporting.engine.classic.extensions.datasources. hibernate.DefaultSessionProvider; import org.pentaho.reporting.engine.classic.extensions.datasources. hibernate.HQLDataFactory; Due to the naming of column headers in HQLDataFactory being mapped to the attributes of queried objects, you must also modify the sample report. Copy chapter2_report. prpt to chapter5/data/hql_report. prpt, and change the column names, as shown in the following list: •
Library Name to NAME
•
Library Description to DESCRIPTION
•
Library Size to SIZE
Also change the Total Library Size function's Field Name to SIZE. Once you've saved your changes, update the HQLDataFactoryApp class with the new location of the report X M L file. As the last step, you'll need to add the following Ant target to your build. xml file: Type ant runhql on the command line to view the results!
[136]
Chapter 5
PmdDataFactory The org.pentaho.reporting.engine.classic.extensions.datasources.pmd. PmdDataFactory class allows you to populate your report, using a Pentaho Metadata Query. Pentaho Metadata allows a database administrator to define a business layer of their relational data for end users, simplifying the ability to query the data, as well as protecting users from the complexities that may exist in a database schema. Pentaho's Metadata Query Language (MQL) is an XML-based query model that simplifies querying databases, and is currently used within the Pentaho Report Designer and Pentaho Web Ad Hoc Report client tools. In order for PmdDataFactory to initialize properly, it must have access to certain Pentaho Metadata configuration properties that can be configured at runtime, or be passed in by a configuration file.
XMI file The XMI file contains a serialized version of the defined metadata model, and is required in order to execute MQL queries. The XMI file contains information including how to connect to the relational data source, as well as the business model mapping of the relational data. This file is loaded at runtime into the configured repository of Pentaho Metadata. The XMI file may be configured by calling the setXmiFile method. This file is loaded with Pentaho Reporting Engine's ResourceManager.
Domain Id The metadata domain id is used to map a name to the XMI file within the metadata repository. This name is also referenced in the MQL query file. Therefore, it is important to use the same name in the MQL query, as well as the PmdDataFactory. The domain may be set by the setDomainid method.
IPmdConnectionProvider PmdDataFactory uses the IPmdConnectionProvider interface to obtain the metadata domain objects as well as the database connection for the query. The IPmdConnectionProvider must be specified via the setConnectionProvider method. A default implementation, PmdConnectionProvider, manages loading the XMI file as well as determining the database connection to be used based on metadata information provided in the XMI file. The IPmdConnectionProvider defines the following methods:
[137]
Working with Data Sources // returns a connection object based on the relational data source Connection gu8etConnection(DatabaseMeta databaseMeta) throws ReportDataFactoryException; // returns a metadata repository based on the domain id and xmi file IMetadataDomainRepository getMetadataDomainRepository(String domain, ResourceManager resourceManager, ResourceKey contextKey, String xmiFile) throws ReportDataFactoryException;
Registering MQL Queries Once you've configured the PmdDataFactory correctly, you need to provide named MQL queries via the setQuery (String name, String query) method. Please see http://wiki.pentaho.com/display/ServerDoc2x/03.+Pentaho+Metadata+MQL+ Schema to learn more about the MQL query format.
PmdDataFactory example To begin, you'll need to build a very simple Pentaho Metadata model. First, download Pentaho Metadata Editor from SourceForge: http: //sourcef orge. net/ pro j ects/pentaho. Click on the Download link, and select the Pentaho Metadata package. Download the latest "pme-ce" zip or tar distribution, depending on your operating system environment. For Windows, unzip the download, and run metadata-editor. bat. For Linux and Mac, untar the download and run metadata-editor. sh. From the main window, select File | new Domain File... Now, it's time to define your physical model. Right-click on the Connections tree item and select New Connection... Name the Connection Library Info and select Hypersonic as the connection type. Set the Host Name to file: and the Database Name to the full path to your example libraryinf o. script file minus the . script file extension. Set the Port Number to blank, and finally set the username to sa and password to blank.
[138]
Chapter 5
Click Test to make sure you are connected properly, and then click OK. This will bring up an Import Tables dialog. Select LIBRARYINFO and click OK.
I m p o r t Tables Select the tables to import
LIBRARYINFO
OK
Cancel
[139]
Working with Data Sources
This will generate a default physical model. Now that you've defined the physical model, you'll need to build a business model. Right-click on Business Models and select the New Business Model menu item. Give this model the ID of LIBRARYINFO_MODEL, and select Library Info as the connection. Finally, under the Settings section, set the Name to Library Info. j Business Model Properties ID:
LIBRARYINFO MODEL
Connection:
Library Info
Properties
Q Q
Available -
- General ÜI Name
Settings
General
tLl Description Security Information
Locale
String
en US
Library Info
Description Locale
String
en US
Security Information Selected Users/Groups
Q
Q
Permissions
Cancel
In the main window, drag-and-drop the LIBRARYINFO table from the Library Info connection into the Business Tables tree. This will bring up a new Business Table Properties dialog. Click OK. Double-click on the Business View tree element to bring up the Manage Categories dialog. Select the LIBRARYINFO business table and click the Add Arrow in between the two list boxes. This will create a new category with the same name as the business table.
[140]
Chapter 5
B
£ Manage Categories Manage
Categories
Select an available table or column and use the arrow buttons to add a new category or column within a category, Create new, generic categories by clicking on the 'Add' button to the right.
J Available Business Tables -
•
LIBRARYINFO
-
;
[I
NAME
i
[I
DESCRIPTION
1
n
SIZE
Ö
Business View Categories
O
ï f t LIBRARYINFO
>
:
n
size
i
[I
DESCRIPTION
1
[I
NAME
C
Close
)
Once completed, the main Business Model Tree should look like this: ^
Pentaho M e t a d a t a Editor - Library I n f o
File
Edit
Tools '
a
Help
a
â
%
?
Parent Concept Connections ¡
"
0
Graphical View"^
Locale:
Library Info
- ?rary Info
>
Locales Log View ] _ U S
- Ç ] LIBRARYINFO : W] NAME
Base
:
DESCRIPTION
Base
SIZE
Base
% &-f|
Business Models
H V T n i - i b r a r v Info (Library Info] 1 3 - l f è Business Tables - [ ] LIBRARYINFO ;
1
NAME
Base
i
1
DESCRIPTION
Base
1
1
SIZE
Base
IÉËÉ L I B R A R Y I N F O
Bfl Relationships -
Business View -
ft
LIBRARYINFO
|
i
SIZE
Base
i
i
DESCRIPTION
Base
1
i
NAME
Base
1
>
Now that you've defined your metadata model, export the model as an XMI file by selecting the File | Export to XMI File... menu item. First, you will be prompted to save the Domain file. Name the Domain Library Info. Finally, save your XMI file as chapter5/data/libraryinfo.xmi.
[141]
Working with Data Sources Once you've exported your metadata model, you must set up your environment with the necessary JAR files. Copy all the JAR files located in the lib and lib-ext folders from the Pentaho Metadata Editor distribution into the chapters/lib folder. Also, copy the pentaho-reporting-engine-classic-extensions-pmd. jar file, located in the Pentaho Report Designer lib folder, into the chapters/lib folder. After copying the correct JAR files, go ahead and add a new load data section of the onPreview method within a freshly copied chapter2SwingApp, renamed to PmdDataFactoryApp: // load MQL data source PmdDataFactory factory = new PmdDataFactory(); factory.setConnectionProvider(new PmdConnectionProvider()); factory.setXmiFile("data/1ibraryinfo.xmi"); factory.setDomainld("Library Info"); factory.setQuery("default" , "" + "" + " relational" + " Library Info" + LIBRARYINFO_MODEL" + " Library Info" + " " + " " + BC_LIBRARYINFO" + BC_LIBRARYINFO_NAME" + " " + " " + BC_LIBRARYINFO" + BC_LIBRARYINFO_DESCRIPTION" + " " + " " + BC_LIBRARYINFO" + BC_LIBRARYINFO_SIZE" + " " + " «/selections>" + ""); Notice that MQL is in XML format. Much like your other queries, you've selected library name, description, and size from the data source.
[142]
Chapter 5 Finally, make sure to add the following imports to the class: import org.pentaho.reporting.engine.classic.extensions.datasources. pmd.PmdDataFactory; import org.pentaho.reporting.engine.classic.extensions.datasources. pmd.PmdConnectionProvider; Due to the built in naming of column headers in PmdDataFactory, you must also modify your sample report. Copy chapter2_report .prpt to chapter5/data/ pmd_report. prpt, and change the column names as shown in the following list: •
Library Name to BC_LIBRARYINFO_NAME
•
Library Description to BC_LIBRARYINFO_DESCRIPTION
•
Library Size to BC_LIBRARYINFO_SIZE
Also change the Total Library Size function's Field Name to BC_LIBRARYINFO_SIZE. Once you've saved your changes, update the PmdDataFactoryApp class with the new location of the report PRPT file. Finally, you'll need to add the following Ant target to the build. xml file: Type ant runpmd on the command line to view the results!
[ '
You may also consider doing this example without the necessity of the load data section, by adding a Metadata data source to
I I
your report within Pentaho Report Designer.
I
KettleDataFactory The org.pentaho.reporting.engine.classic.extensions.datasources. kettle. KettleDataFactory class allows you to populate your report from a Kettle transformation. Kettle is a data integration tool, also known as an ETL (Extract Transform and Load) tool. Kettle transformations support a multitude of data source inputs and transformation capabilities. Kettle, also known as Pentaho Data Integration, provides mechanisms to incorporate data from Excel, SQL, XML, Text, and many other data sources. It also provides the ability to combine the results into a single result set, which Pentaho Reporting can use to render a report.
[143]
Working with Data Sources To initialize KettleDataFactory, you must provide the location of the Kettle transformation to execute, along with the step within the transformation to use the data from. This is done via the KettleTransformationProducer interface. There are two provided implementations of KettleTransformationProducer. The first is KettleTransFromFileProducer, which loads a Kettle transformation from the file system. The KettleTransFromFileProducer class must be instantiated with the following parameters: final String repositoryName, // the repository name final String transformationFile, // the path of the tranformation file to execute final String stepName, // the step name to collect data from final String username, // the repository user name final String password, // the repository password final String[] definedArgumentNames, // the names of reporting properties to be passed into Kettle via Transformation Arguments final ParameterMapping[] definedVariableNames // the names of reporting properties to be passed into Kettle via Transformation Parameters The second implementation of KettleTransformationProducer is KettleTransFromRepositoryProducer. This loads the transformation from an existing Kettle Repository. The kettleTransFromRepositoryProducer class must be instantiated with the following parameters: final String repositoryName, // the repository name final String directoryName, // the repository directory final String transformationName, // the transformation name in the repository final String stepName, // the step name to collect data from final String username, // the repository user name final String password, // the repository password final String[] definedArgumentNames, // the names of reporting properties to be passed into Kettle via Transformation Arguments final ParameterMapping[] definedVariableNames // the names of reporting properties to be passed into Kettle via Transformation Parameters The KettleDataFactory has a default constructor. To add Kettle transformation queries to the KettleDataFactory, call the setQuery(String, KettleTransformationProducer) method.
[144]
Chapter 5
Kettle Data Factory example To start the example, you first need to build a Kettle transformation. Download Pentaho Data Integration 3.2 from SourceForge: http://sourceforge. net/ projects/pentaho. Click on the Download link, and select the Data Integration package. Download the latest "pdi-ce" ZIP (compressed file), TAR, or D M G distribution, depending on your operating system environment. Install the distribution. To bring up the user interface, run Kettle. exe if you are a Windows user. For Linux and Mac users, run spoon. sh. On Kettle's intro screen, select the button No Repository. Kettle allows you to store and manage your transformations in a central repository, but you won't be using that feature in this example. In the main window, double-click on the Transformations folder to begin creating your first transformation. Drag-and-drop a Table input step from the step's Input folder into your transformation. Double-click on the new step to configure the Table input. In the Table input dialog, first configure a new connection to your HSQLDB file-based database. Click the New... button next to the Connection. In the Database Connection dialog, enter the Connection Name as Library Info and select Hypersonic as the Connection Type. Set the Database Name to the full path to your example, that is, libraryinf o. script file minus the . script file extension. Set the Host Name to file: and the Port Number to blank. Finally, set the user name to sa and password to blank. X]
"5 D a t a b a s e Connection
Advanced Options Pooling Clustering
Connection Name: | Library Info Settings^
Connection Type: ExtenDB Firebird SQL Generic database Greenplum Gupta SQL Base H2
file: Database Name: c: ^Dath\to\diapter 5 Viata tybraryinfo Port Number:
IBM DB2 Informix Ingres Intersystems Cache KingbaseES MS Access MS SQL Server MaxDB (SAP DB) MonetDB MySQL
d
Access: ODBC JNDI
Explore
[145]
Working with Data Sources
Once you've configured your connection, click the Test button to make sure it can connect successfully, and then click the Explore button and verify that the LIBRARY INFO table exists: 3 Database explorer o r correction [Library Info] B
I g
Library I n f o
+
®
Schema's
0
Preview f i r s t 100 r o w s o f [LIBRARYINFO]
Tables
IS
P r e v i e w f i r s t . . . r o w s o f [LIBRARYINFO]
H |LIBRARYINFO
L
!
Views
Number o f r o w s o f [LIBRARYINFO]
Show l a y o u t o f [LIBRARYINFO] G e n e r a t e DDL G e n e r a t e DDL for o t h e r c o n n e c t i o n O p e n SQL for [LIBRARYINFO]
T r u n c a t e table [LIBRARYINFO]
OK
Refresh
|
Now click the OK button to return to the Table input dialog. Click the Get SQL select statement... button. This brings up the database explorer. Select the LIBRARYINFO table from the list of tables and click OK. An additional dialog should appear asking if you would like to include the field names in the SQL. Click the Yes button. Your Table input dialog should look like this: Table input Step name
Table input
Connection
Library Infb
[Edit,,, | [ N e w , , , |
SQL
Set SQL select statement,,,
SELECT NAME , ,
DESCRIPTION SIZE
FEOM
LIBRARYINFO
Line 1 Column 0 Enable lazy conversion
•
Replace variables in script?
•
Insert data from step Execute for each row?
•
Limit size I j j
OK
Cancel
[146]
Preview
Chapter 5 Click OK on the Table input dialog to update the transformation step. Finally, save your transformation as chapter5/data/libraryinfo. ktr. Now that you've created your transformation file, it's time to set up the DataFactory. First, you must place the necessary JAR files into the chapters/lib folder. You'll need to place all the JAR files located in Kettle's lib and libext folders into the chapter5/lib folder. Also, you'll need to place the pentaho-reporting-engineclassic-extensions-kettle. jar file, located in the Pentaho Report Designer lib folder, into the chapter5/lib folder as well. This example also uses the libraryinfo. script and libraries . txt files you defined earlier, so make sure they are available in the chapters/data folder. Now, you are ready to go ahead and add a new load data section to the onPreview method within a freshly copied Chapter2SwingApp, renamed to KettleDataFactoryApp: // load Kettle data source // Initialize Kettle EnvUtil.environmentInit(); StepLoader.init(); JobEntryLoader.init() ; // Build Data Factory KettleTransFromFileProducer producer = new KettleTransFromFileProducer ("Embedded Repository", "data/libraryinfo.ktr", "Table input", "", "", new String[0], new ParameterMapping[0] ) ; KettleDataFactory factory = new KettleDataFactory(); factory.setQuery("default" , producer); report.setDataFactory(factory) ; StepLoader and JobLoader both may throw a KettleException, so you must also add the following catch block to the end of the onPreview method: catch (KettleException e) { e.printStackTrace() ;
} You must also add the following imports to complete the example: import org.pentaho.di.core.exception.KettleException; import org.pentaho.di.core.util.EnvUtil; import org.pentaho.di.j ob.JobEntryLoader; import org.pentaho.di.trans.StepLoader; import org.pentaho.reporting.engine.classic.core.ParameterMapping; import org.pentaho.reporting.engine.classic.extensions.datasources. kettle.KettleTransFromFileProducer; import org.pentaho.reporting.engine.classic.extensions.datasources. kettle.KettleDataFactory; [147]
Working with Data Sources Due to the names of column headers in this example, you must also modify your sample report. Copy chapter2_report.prpt to chapter5/data/kettle_report. prpt, and change the column names, as shown in the following bullet list: •
Library Name to NAME
•
Library Description to DESCRIPTION
•
Library Size to SIZE
Also change the Total Library Size function's Field Name to SIZE. Once you've saved your changes, update the KettleDataFactoryApp class with the new location of the report PRPT file. Finally, you'll need to add the following Ant target to the build. xml file: Type ant runkettle on the command line to view the results!
BandedMDXDataFactory The org.pentaho.reporting.engine.classic.extensions.datasources. olap4 j . BandedMDXDataFactory class allows you to populate your report from A n olap4 j data source. olap4 j is a Java API for connecting to multi-dimensional OLAP (Online Analytical Processing) data sources. As of olap4j 0.9.7.145, there is a driver written for the Mondrian Relational OLAP Engine, as well as an Extensible Markup Language for Analysis (XMLA) driver implementation, which provides communication with Microsoft Analysis Services, along with other X M L A compatible OLAP services. Natively, OLAP data sources support result sets with more than two axes. In a traditional result set used by Pentaho Reporting, there are column headers, along with rows of data. W h e n using OLAP data, the data source needs to determine how to map the richer OLAP data into a standard TableModel data source. With BandedMDXDataFactory, the factory maps the row and column axes of the OLAP result set to a TableModel. The column headers display the dimensions selected in the column axis. The rows show the row axis information selected. For instance, if a year was selected from the time dimension on the column axis, in the column header you would see the member name [Time].[1997], To learn more about olap4j and Mondrian's Relational OLAP engine, please visit http://www.olap4j.org and http://mondrian.pentaho.org. [148]
Chapter 5 To configure the BandedMDXDataFactory, you must first create an object that implements the OlapConnectionProvider interface. The DriverConnectionProvider provides an implementation. The DriverConnectionProvider contains a default constructor, and may be configured with the following methods: void setDriver(String driver); The setDriver method specifies the driver class to use. void setURL(String url); The setURL method specifies the URL the driver should connect to. void setProperty(String name, String value); The setProperty method specifies additional connection properties. After creating a valid OlapConnectionProvider, pass that object into the BandedMDXDataFactory constructor. Once you've created the factory, you may add Multi-dimensional Expression (MDX) queries by calling the setQuery (String name, String mdxQuery) method.
BandedMDXDataFactory example To begin this example, you first need to create a simple OLAP model that you can query. First, download Mondrian's Schema Workbench from the following SourceForge URL: http://sourceforge.net/projects/mondrian. Once you've unzipped the Schema Workbench, copy the hsqldb. j ar into the workbench/ drivers folder. To bring up the main window, run workbench. bat in Windows, or run workbench. sh if you are a Mac or Linux user. Before you design an OLAP Model, first configure your relational data source. Select the menu item Tools | Preferences. Now, specify the necessary JDBC information. Set org.hsqldb. jdbcDriver for the Driver Class Name and jdbc:hsqldb:file:c:\path\to\chapter5\ data\libraryinfo for the Connection URL. Finally, set the username to sa, and the password to blank. Now, click the Accept button. m
I Workbench Preferences JDBC Driver Class Name |org.hsqldb.)dbcDriver Connection URL
|jdbc;hsqldb:file:c:Jbookf319 3_ch a pte r5lc h a pte r5ld atall i bra ryi nfo
User name
sa
Password Accept
[149]
Cancel
Working with Data Sources
Select the menu item File | New | Schema. Right-click on the schema and select the add Cube menu item. Name the Cube as Library Info. Select the cube's Table tree node and set the name attribute of the Table to Library Info. This will act as your fact table. Now, right-click on the cube and select the A d d Dimension menu item. Set the dimension name to Library. Because you're using the fact table for the dimension, also known as a degenerate dimension, there is no need for a foreign key. Right-click on the Table element within the Hierarchy and select the Delete menu item. This element is also not needed. Right-click on the Hierarchy and select the Add Level menu item. Set the level's name attribute to Library Name, and the column attribute to NAME. NOW, rightclick on the level and select the Add Property menu item. Rename the property to LibDescription and set the column attribute to DESCRIPTION. Set the type attribute to String. Finally, right-click on the Library Info cube again and select the A d d Measure menu item. Set the measure's name to size, and enter SIZE for the column attribute. Select sum for the aggregator. Schema Workbench ! File
I II p |
5
Edit
View
I
El
Tools
«3 ë E
Help
0
S c h e m a - N e w S c h e m a 1 (libraryinfo.mondrian.xml)
A
UDF
name SOI Table: LIBRARYINFO Library ¿ih
|
I |~||
Value Library Info
cache
0
enabled
0
Library N a m e ®
%
fZU
caption
Hierarchy
f
%x
Cube Attribute
( J ) Library info
9
c" p "
% ûp + m a
CM
-
Schema
A
]
Windows
Description
Size
Database - null (HSQL Database Engine)
You're now done creating a very simple OLAP model. Go ahead and save this model to data/library info. mondrian. xml. Once saved, verify the model by selecting the menu item File | New | M D X Query, and typing in the following query:
[150]
Chapter 5 WITH MEMBER [Measures].[Name] AS '[Library].CurrentMember.Caption' MEMBER [Measures].[Description] AS '[Library].CurrentMember. Properties("LibDescription")' select [Library] .Children on rows, { [Measures] . [Name] , [Measures] . [Des cription] , [Measures] . [Size] } on columns from [Library Info] Make sure results are returned. Now that you have your OLAP schema file defined, you're ready to begin interfacing the OLAP data source with Pentaho Reporting. First, you must copy over the necessary JAR files. Place all the JAR files that exist in the workbench/lib folder in chapter5/lib folder. Also, place the pentaho-reporting-engine-classicext ens ions-olap4j . jar and olap4 j . jar files, found in Pentaho Reporting's lib folder, into the chapter5/lib folder. Add the following load data section to the onPreview method within a freshly copied Chapter2SwingApp, renamed to BandedMDXDataFactoryApp: // load olap data DriverConnectionProvider provider = new DriverConnectionProvider() ; provider.setDriver("mondrian.olap4j.Mondrian01ap4j Driver") ; provider.setUrl("jdbc:mondrian: "); provider.setProperty("Catalog", "data/libraryinfo.mondrian.xml"); provider.setProperty("JdbcUser", "sa"); provider.setProperty("JdbcPassword", "") ; provider.setProperty("Jdbc", "jdbc:hsqldb:file:data/libraryinfo"); provider.setProperty("JdbcDrivers", "org.hsqldb.j dbcDriver") ; // create the factory BandedMDXDataFactory factory = new BandedMDXDataFactory(provider); // add the MDX query factory.setQuery("default", "WITH MEMBER [Measures] . [Name] AS '[Library].CurrentMember.Caption' MEMBER [Measures].[Description] AS '[Library].CurrentMember.Properties(\"LibDescription\")' select [Library] .Children on rows, { [Measures] . [Name] , [Measures] . [Description], [Measures].[Size]} on columns from [Library Info]"); report.setDataFactory(factory) ; You must also add the following imports to complete the example: import org.pentaho.reporting.engine.classic.extensions.datasources. olap4 j.Dri verConne ct i onProvi der; import org.pentaho.reporting.engine.classic.extensions.datasources. olap4j.BandedMDXDataFactory;
[151]
Working with Data Sources Due to the built in naming of column headers in BandedMDXDataFactory, you must also modify your sample report. Copy the chapter2_report. prpt to chapters/data/banded_mdx_report. prpt, and change the column names as shown in the following bullet list: •
Library Name to [Measures] . [Name]
•
Library Description to [Measures] . [Description]
•
Size to [Measures] . [Size]
Also change the Total Library Size function's Field Name to [Measures] . [size]. Once you've saved your changes, update BandedMDXDataFactoryApp with the correct PRPT file to load. Finally, you'll need to add the following Ant target to the build. xml file: Type ant runmdx on the command line to view the results.
[ \\ '
You may also consider doing this example without the necessity of the load data section, by adding an olap4j data source to your report within Pentaho Report Designer.
I I I
DenormalizedMDXDataFactory The org.pentaho.reporting.engine.classic.extensions.datasources. olap4 j . DenormalizedMDXDataFactory class queries an olap4 j data source in a similar fashion as the BandedMDXDataFactory. The only difference is the mapping from OLAP to a two-dimensional result set. The DenormalizedMDXDataFactory maps all the axes of the OLAP result set to a TableModel, in a denormalized or flattened fashion. The column headers display the dimensional metadata selected in the axes, as well as the measure metadata selected. For instance, if a year was selected from the time dimension, in the column header you would see the level name [Time].[Year], DenormalizedMDXDataFactory is often used with crosstabs, and will be used again in Chapter 8.
[152]
Chapter 5
CompoundDataFactory The org.pentaho.reporting.engine.classic.core.CompoundDataFactory class is a useful factory when working with sub-reports that contain different data sources than the primary report. For instance, with CompoundDataFactory, you may use a SQLReportDataFactory for your master report query, as well as an XPathDataFactory for a sub-report query. The CompoundDataFactory has a default constructor, and you may add child data factories by calling the add (DataFactory) or add (index, DataFactory) methods. DataFactory instances are queried in the order of their index. All reports generated by the Report Designer use the CompoundDataFactory, making it possible for users to add different types of data sources to their report in the user interface.
Experimental data factories Additionally, there are community contributed DataFactory implementations that are available. Two examples include the XQjReportDataFactory, which uses the j avax. xml. xquery API to query XML database data sources, as well as the ScriptableDataFactory, which uses the Bean Scripting Framework to execute query scripts in different scripting languages that return a TableModel implementation.
Accessing data throughout a report Once you've configured your DataFactory implementation, it is important to know how to access this data within a report. As mentioned in the previous chapter, elements that contain the field name property access row data via the column headers provided by the data source. In addition to accessing the fields directly, you may also access this data in functions and formulas. Functions in Pentaho Reporting will contain a property named "Field" or "Fields" that allow you to select a list of fields from the defined data source. To reference a field in a formula, you will need to place brackets around the field name. An example reference to a field name in a formula might be "[Library Description]". When using a DataFactory that isn't supported directly in the Report Designer such as the Hibernate HQLDataFactory, you will need to manually type in the name of the fields into the Report Designer. Another issue with using non-supported DataFactory classes in the Report Designer is that the report preview won't be available for use. One strategy to avoid these issues is to build a sample dataset, which contains the identical column headers in a Report Designer supported DataFactory implementation, in order to verify that reports look as expected. [153]
Working with Data Sources
Summary In this chapter, you were introduced to the Pentaho Reporting Engine Data API. The Data API provides a rich, easy-to-implement mechanism for providing data to a report. The DataFactory interface, along with the TableModel interface, make up the backbone of this API. Additional capabilities of this API include the ability to serialize connection information, as well as provide a richer set of metadata for result sets by using MetaTableModel. Out of the box, the Pentaho Reporting Engine comes with a rich set of DataFactory implementations that make it possible to connect to practically any type of backend data, including Java Objects, JDBC, X M L XPath, HQL, Pentaho Metadata, Pentaho Integration, and OLAP data sources. Once you've configured access to your underlying data, it's simple to reference that data within your report, via report elements, functions, and formulas.
[154]
6
Including Charts and Graphics in Reports In this chapter, you'll learn how to incorporate charts and graphics into Pentaho Reports. You'll learn about the different types of charts supported, and how to configure them in Pentaho Report Designer. You'll also learn how to populate a chart with various types of data. In addition to learning all about charts, this chapter also covers the various methods for including visual information in your report, including embedding images and Java graphics in your report.
Supported charts Pentaho Reporting relies on JFreeChart, an open source Java chart library, for charting visualization within reports. From within Report Designer, many chart types are supported. In the chart editor, two areas of properties appear when editing a chart. The first area of properties is related to chart rendering, and the second tabbed area of properties is related to the data that populates a chart.
Including Charts and Graphics in Reports Following is the Screenshot of the chart editor within Pentaho Report Designer:
m
lifel f Primary DataSource
f Secondary DataSource
|
| Bar Chart Name B Required
Value *
CategorySet Data Collector I
name data-source
Data Collector 0
no-data-message
CHART. U SE R_N 0_DATA_...
title-field SansSerif-BOLD-14
B Options stacked
False
stacked-percent
False
horizontal
False
bar-borders
False
max-bar-width series-color
Value Data Collector 0
category-column value-columns
sub-title title-font
name
use-value-columns use-series-columns
dependencyLevel
D
B General default-font
SansSerif-8
3-D
False
grldllnes
True
All chart types receive their data from three general types of datasets. The first type is known as a Category Dataset, where the dataset series and values are grouped by categories. A series is like a sub-group. If the exact category and series appear, the chart will sum the values into a single result. The following table is a simple example of a category dataset: Category
Series
Sale Price
Store 1 Sales
Cash
$14
Store 1 Sales
Credit
$12
Store 2 Sales
Cash
$100
Store 2 Sales
Credit
$120
Pentaho Reporting builds a Category Dataset using the categorySetDataCollector. Also available is the PivotcategorySetcollector, which pivots the category and series data. Collector classes implement Pentaho Reporting's Function API. The second type of dataset is known as an XY Series Dataset, which is a two dimensional group of values that may be plotted in various forms. In this dataset, the series may be used to draw different lines, and so on. Here is a simple example of an XY series dataset: [156]
Chapter 5 Series
Cost of Goods (X)
Sale Price (Y)
Cash
10
14
Credit
11
12
Cash
92
100
Credit
105
120
Note that X is often referred to as the domain, and Y is referred to as the range. Pentaho Reporting builds an XY Series Dataset using the XYSeriesCollector. The XYZSeriesCollector also exists for three dimensional data. The third type of dataset is known as a Time Series Dataset, which is a two dimensional group of values that are plotted based on a time and date. The Time Series Dataset is more like an XY Series than a Category Dataset, as the time scale is displayed in a linear fashion with appropriate distances between the different time references.
Time
Series
Sale Price
May 05, 2009 11:05pm
Cash
$14
June 07, 2009 12:42pm
Credit
$12
June 14, 2009 4:20pm
Cash
$100
June 01, 2009 1:22pm
Credit
$120
Pentaho Reporting builds a Time Series Dataset using the TimeSeriesCollector.
Common chart rendering properties Most charts share a common set of properties. The following properties are common across most charts. Any exceptions are mentioned as part of the specific chart type. Required Property Group Property name
Description
name
The name of the chart object within the report. This is not displayed during rendering, but must be unique in the report. A default name is generated for each chart added to the report.
data-source
The dataset name for the chart, which is automatically populated with the name of the dataset in the Primary DataSource panel of the chart editor.
no-data-message
The message to display if no data is available to render the chart.
[157]
Including Charts and Graphics in Reports Title Property Group Property name
Description
chart-title
The title of the chart, which is rendered in the report.
chart-title-field
A field representing the chart title.
title-font
The chart title's font family, size, and style.
Options Property Group Property name
Description
horizontal
If set to True, the chart's X and Y axis are rotated horizontally. The default value is set to False.
series-colors
The color in which to render each series. The default for the first three series colors are red, blue, and green.
General Property Group Property name
Description
3-D
If set to True, renders the chart in a 3D perspective. The default value is set to False.
anti-alias
If set to True, renders chart fonts as anti-aliased. The default value is set to True.
bg-color
Sets the background around the chart to the specified color. If not set, defaults to gray.
bg-image
Sets the background of the chart area to the specified image. If not set, the background of the chart area defaults to white. The chart area is the area within the axes of the chart. Supported image types include PNG, JPG, and GIF file formats.
show-border
If set to True, displays a border around the chart. The default value is set to True.
border-color
Sets the border to the specified color. If not set, defaults to black.
plot-border
If set to False, clears the default rendering value of the chart border.
plot-bg-color
Sets the plot background color to the specified color. If not set, defaults to white.
plot-fg-alpha
Sets the alpha value of the plot foreground colors relative to the plot background. The default value is set to 1.0.
plot-bg-alpha
Sets the alpha value of the plot background color relative to the chart background color. The default value is set to 1.0.
[158]
Chapter 5 Legend Property Group Property name
Description
show-legend
If set to True, displays the legend for the chart. The default value is set to False.
location
The location of the legend in relation to the chart, which may be
legend-border
If set to True, renders a border around the legend. The default
set to top, bottom, left, or right. The default location is bottom. value is set to True. legend-font
The type of Java f o n t to render the legend labels in.
legend-bg-color
Sets the legend background color. If not set, defaults to white.
legend-font-color
Sets the legend font color. If not set, defaults to black.
Advanced Property Group Property name dependencyLevel
Description The dependency level field informs the reporting engine what order the chart should be executed in relation to other items in the report. This is useful if you are using special functions that may need to execute prior to generating the chart. The default value is set to 0. Negative values execute before 0, and positive values execute after 0.
Common category series rendering properties T h e following properties appear in charts that render category information: Options Property Group Property name
Description
stacked
If set to True, the series values will appear layered on top of one another instead of being displayed relative to one another.
stacked-percent
If set to True, determines the percentages of each series, and renders the bar height based on those percentages. The property stacked must be set to True for this property to have an effect.
General Property Group Property name
Description
gridlines
If set to True, displays category grid lines. This value is set to True by default.
[159]
Including Charts and Graphics in Reports X-Axis Property Group Property name
Description
label-rotation
If set, adjusts the inline item label rotation value. The value should be specified in degrees. If not specified, labels are rendered horizontally. You must have show-labels set to true for this value to be relevant.
date-format
If the item value is a date, a Java date format string may be provided to format the date appropriately. Please see Java's SimpleDateFormat JavaDoc for formatting details.
numeric-format
If the item value is a decimal number, a Java decimal format string may be provided to format the number appropriately. Please see Java's DecimalFormat JavaDoc for formatting details.
text-format
The label format used for displaying category items within the chart. This property is required if you would like to display the category item values. The following parameters may be defined in the format string to access details of the item: • • •
{0}: To access the Series Name detail of an item {1}: To access the Category detail of an item {2}: To access the Item value details of an item
To display just the item value, set the format string to "{2}". x-axis-title
If set, displays a label describing the category axis.
show-labels
If set to true, displays x-axis labels in the chart.
x-axis-label-width
Sets the maximum category label width ratio, which determines the maximum length each category label should render in. This might be useful if you have really long category names.
x-axis-label-rotation
If set, adjusts the category item label rotation value. The value should be specified in degrees. If not specified, labels are rendered horizontally.
x-font
The font to render the category axis title and labels in.
Y-Axis Property Group Property name
Description
y-axis-title
If set, displays a label along the value axis of the chart.
label-rotation
If set, determines the upward angle position of the label, where the value passed into JFreeChart is the mathematical pie over the value. Unfortunately, this property is not very flexible and you may find it difficult to use.
y-tick-interval
The numeric interval value to separate range ticks in the chart.
y-font
The font to render the range axis title in.
[160]
Chapter 5 Y-Axis Property Group Property name
Description
y-sticky-0
If the range includes zero in the axis, making it sticky will force truncation of the axis to zero if set to True. The default value of this property is True.
y-incl-0
If set to True, the range axis will force zero to be included in the axis.
y-min
The minimum value to render in the range axis.
y-max
The maximum value to render in the range axis.
y-tick-font
The font to render the range tick value in.
y-tick-fmt-str
The Decimal Format string to render the numeric range tick value.
enable-log-axis
If set to true, displays the y-axis as a logarithmic scale.
log-format
If set to true, will present the logarithmic scale in a human readable view.
Common XY series rendering properties The following properties appear in charts that render XY series information. X-Axis Property Group Property name
Description
x-incl-0
If set to True, the domain axis will force zero to be included in the axis. The default value of this property is True.
x-min
The maximum value to render in the domain axis.
x-max
The minimum value to render in the domain axis.
x-sticky-0
If the domain includes zero in the axis, making it sticky will force truncation of the axis to zero if set to True. The default value of this property is True.
x-tick-font
The font in which to render the domain tick value.
x-tick-fmt-str
The DecimalFormat string to render the numeric domain tick value.
x-title
The title to display on the domain axis.
x-font
The font in which to render the domain axis title.
x-vtick-label
If True, renders the domain tick labels vertically. This value defaults to False.
x-tick-interval
The numeric interval value to separate x-axis ticks in the chart.
x-tick-time-p erio d
If rendering a time series dataset, this property is the time period to display in the x-axis. [161]
Including Charts and Graphics in Reports Y-Axis Property Group Property name
Description
y-incl-0
If set to True, the range axis will force zero to be included in the axis.
y-max
The maximum value to render in the range axis.
y-min
The minimum value to render in the range axis.
y-sticky-0
If the range includes zero in the axis, making it sticky will force truncation of the axis to zero if set to True. The default value of this property is True.
y-tick-font
The font to render the range tick value in.
y-tick-fmt-str
The DecimalFormat string to render the numeric range tick value.
y-title
The title to display on the range axis.
y-font
The font to render the range axis title in.
y-tick-interval
The numeric interval value to separate y-axis ticks in the chart.
enable-log-axis
If set to true, displays the y-axis as a logarithmic scale
log-format
If set to true, will present the logarithmic scale in a human readable view.
Common dataset properties The following properties are common across all chart datasets: Common Property Group Property name
Description
name
The name of the chart's dataset, also referenced in the chart rendering properties.
Series Property Group Property name
Description
series-by-value
If set, values entered act as the series name for the value columns provided.
series-by-field
If set, fields entered act as the series name for the value column provided. Setting this property will slice the value column into series groups.
[162]
Chapter 5 Group Property Group Property name
Description
reset-group
This property defines the group level at which the data should be reset.
group-by
This property defines the group level at which the data should be collected.
Advanced Property Group Property name
Description
dependencyLevel
The dependency level field informs the reporting engine about the order in which the chart data source should be executed in relation to other items in the report. This is useful if you are using special functions that may need to be executed" prior to generating the data for the chart. The default value is set to 0.
Common category series dataset properties T h e following properties are c o m m o n across all charts that utilize category series dataset for populating the chart: Common Property Group Property name
Description
category-column
The data source column used to determine the category.
value-columns
The data source columns used to determine the chart values.
Common XY series dataset properties T h e following properties are c o m m o n across all charts that utilize the X Y series dataset for populating a chart: Common Property Group Property name
Description
x-value-columns
The data source column that populates the X axis.
y-value-columns
The data source column that populates the Y axis.
N o w that you've r e v i e w e d the c o m m o n set of properties for all charts, you'll b e g i n to explore the individual charts, including going through their configurable properties, as w e l l as p r o v i d i n g a quick example.
[163]
Including Charts and Graphics in Reports
Area chart The area chart displays a category dataset as a line, with the area underneath the line filled in. Multiple areas may appear depending on the number of series provided. The area chart is useful for visualizing the differences between two or more sets of data. It utilizes the common properties defined in the previous tables, including the category series common properties. The area chart defines no additional properties.
Area chart example This example will demonstrate the area chart's capabilities. First, you'll need a rich enough dataset to demonstrate this and all the other charts in this chapter. You'll reuse the ElectroBarn HSQLDB data source configured in Chapter 3. To begin, launch Pentaho Report Designer and create a new report. Now, select the Data tab. Right-click on the Data Sets tree element, and select the JDBC data source. If ElectroBarn is not already configured as a connection type, click the Connections add image button and fill in the following values, customizing the database location for your particular environment: Connection Name
ElectroBarn
Connection Type
Hypersonic
Host Name
file:
Database Name
c:\ path\ to\ chapter3\ data\ electrobarn
Port Number
User name
sa
Password
Click the Test button to verify your connection, and then click O K when you are done. You need to define a SQL statement to populate your chart. You'll define a simple query that takes a look at the inventory data. Add a new query with the following SQL code: SELECT "INVENTORY" "INVENTORY" "INVENTORY" FROM "INVENTORY" ORDER BY "INVENTORY"
. "ITEMCATEGORY", ."SALEPRICE" , . "COST"
."ITEMCATEGORY" ASC
[164]
Chapter 5
Click OK. You're now ready to add a chart to your empty report. For this example, select the Chart report element from the palette and drag it into the Report Header. Double-click on the chart, or right-click on the chart and select Chart.... Once the Edit Chart dialog appears, select the Area Chart Q . In the Primary DataSource tab, select the ITEMCATEGORY data field as your category-column. For your value-columns, select SALEPRICE and COST. Enter the strings Sale Price and Cost as the series-by-value values. When rendering an area chart, the order of value columns is important. If a larger value is rendered after a smaller value, the smaller value will not appear on the chart. Once you configured the data for the chart, you can also make some customizations to the rendering. Set horizontal to True, as well as specifying the bg-color as yellow. Finally, set the show-legend property to True. Click the OK button and then preview your report to see the results! 0
250
500
750
1,000
1,250
1,500
1,750
2,000
2,250
2,500
Batteries
C o m p u t e r Accessories
Electric C o m p o n e n t s
Electronics
RC Vehicles
Sale Price
•
Cost
Bar chart The bar chart displays individual bars broken out into individual categories and series. Bar charts are useful for comparing relative sizes of data across categories. The bar chart utilizes the common properties defined earlier, including the category series common properties.
[165]
Including Charts and Graphics in Reports The bar chart defines the following additional rendering properties: Options Property Group Property name
Description
bar-borders
If set to False, clears the default rendering value of the chart border. Identical to the plot-border property.
max-bar-width
Hie maximum width of a bar in pixels. Unless set, bars will generally expand to the available space within the chart.
Bar chart example You'll now build an example bar chart. Create a new report with the ElectroBarn data source, and use the following SQL query, which investigates purchase quantity and payment type: SELECT "INVENTORY"."ITEMCATEGORY", "PURCHASES"."PAYMENTTYPE", "PURCHASEITEMS"."QUANTITY" FROM "PURCHASES" INNER JOIN "PURCHASEITEMS" ON "PURCHASES"."PURCHASEID" = "PURCHASEITEMS"."PURCHASEID" INNER JOIN "INVENTORY" ON "PURCHASEITEMS"."ITEMID" = "INVENTORY"."ITEMID" ORDER BY "INVENTORY"."ITEMCATEGORY" ASC, "PURCHASES"."PAYMENTTYPE" ASC Place a Chart element in the Report Header of the report, selecting bar jjj_ as its type. To begin, configure the dataset properties for your bar chart. Set category-column to ITEMCATEGORY, value-columns to QUANTITY, and series-by-field to PAYMENTTYPE. By setting the series-by-field property, the chart will create a series for each PAYMENTTYPE in the dataset. Now, you'll customize the look of your chart. First, set the X-Axis show-labels property to True and text-format to { 2 } . This will display the value of each bar at the top of the bar. Then set max-label-width to 2 . 0, so that you can easily see all the category names in the chart. Finally, set the show-legend to True, in order to see what types of payments map to which bar color. You're now ready to preview your chart!
[166]
Chapter 5
Line chart The line chart displays connected lines between categories for each series provided. This chart is useful for visualizing trends. The line chart utilizes the common properties defined in the previous tables, including the category series common properties. The line chart defines the following additional rendering properties: Options Property Group Property name
Description
line-style
Hie style of line to draw. Appropriate values for this property are solid, dash, dot, dashdot, and dashdotdot.
line-size
The thickness of the line to draw in pixels.The default value is set to 1.
show-markers
If set to True, displays markers at each category location within the line.
Note that the stacked and stacked-percent properties do not apply to the line chart type.
[167]
Including Charts and Graphics in Reports
Line chart example In this example, reuse the SQL query and dataset sections from your area chart example. Select the Line chart type [j^], and customize the chart with show-markers set to True as well as line-size set to 4.0. The result should look like this:
Pie chart The pie chart displays a sliced, multi-colored pie with individual slices consisting of individual series information. The pie chart uses its own dataset type, versus using a category or XY series dataset. The pie chart utilizes the common properties defined above, but does not utilize the category or XY dataset properties. Instead, it defines its own properties for providing chart data using the PieDataSetCollector. The pie chart defines the following rendering properties: Required Property Group Property name
Description
ignore-nulls
If set to False, the pie chart will render series data containing null values as a point in the pie chart, otherwise it will ignore the series item and will not render it.
ignore-zeros
If set to False, the pie chart will render series data containing zero values as a point in the pie chart, otherwise it will ignore the series item and will not render it.
[168]
Chapter 7 Options Property Group Property name
Description
slice-colors
The color in which to render each slice of the pie. The default for the first three series colors are red, blue, and green.
explode-pct
The percentage value to extract the sliced segment out of the main pie chart. This is used only if explode-slice is set.
explode-slice
The slice to extract from the pie chart, starting with zero. The values minValue or maxValue may be used instead, which select the minimum or maximum slice from the pie.
label-format
The pie label format string has a default value of {0}, and can reference the following fields:
rotate-clockwise
• •
{0}: Series name {1}: Series raw value
• •
{2}: Percentage value {3}: Total raw value
If set to True, the pie's series are laid out in a clockwise fashion, otherwise the series are laid out counter clockwise. This property defaults to True.
Legend Properties Property name
Description
legend-label-format
The pie legend label format string has a default value of {0}, and can reference the same fields as Pie Label Format.
Note that the pie chart does not share the common properties horizontal, series-color, stacked, or series-names. The pie chart defines the following dataset properties: Required Property Group Property name
Description
series-by-field
The data source column used to determine the pie slice series.
value-column
The data source column used to determine the pie slice percentages.
[169]
Including Charts and Graphics in Reports
Pie chart example For the pie chart example, you'll compare the various costs of inventory items to one another by category. First, you'll need to define an SQL query as shown next: SELECT "INVENTORY" ."ITEMCATEGORY" , "INVENTORY"."ITEMNAME", "INVENTORY"."COST" FROM "INVENTORY" ORDER BY "INVENTORY"."ITEMCATEGORY" ASC, "INVENTORY"."ITEMNAME" ASC
You'll then need to define a Group Header for your report. Right-click on the Groups section within the report structure and edit the root group, naming the group item category. Select the ITEMCATEGORY field as the only field in the Selected Items list. Expand the Group node in the structure tree, and select the Group Header. Now, uncheck the hide-on-canvas property, so you can view the Group Header in the canvas. Drag-and-drop the ITEMCATEGORY field at the top of the Group Header. Place a chart below the text field, and click Edit Chart... Select the Pie chart type 3 . You'll start configuring the chart by selecting the correct dataset. For the value-column, select the COST field. For the series-by-field property, select the ITEMNAME field. You'll also need to tell the chart collector to reset the data after each group. Set the reset-group property to the already defined item category group. Finally, you'll want to customize some of the rendering properties. Set the explode-slice to maxvalue, and set the explode-pct to o. 5. This will highlight the most expensive item in each category. Also set show-legend to False to hide the legend and show-labels to True to display the individual pie slice labels.
[170]
Chapter 7
Click the OK button and preview the report. You should see a group of charts as shown in the following figure: Computer Accessories
2GB USB Memory Stick
Wireless 802.11g Router
External 120GB Harddrive
Wireless 802.11g Bridge Tried and True PC Speakers
Green Electronics AC PSU
Tried and True External DVD Player ScratchTab Infrared Wireless Mouse and Keyboard
Green Electronics Ink Jet Printer
Ring chart The ring chart is identical to the pie chart, except that it renders as a ring versus a complete pie. In addition to sharing all the properties similar to the pie chart, it also defines the following rendering property ^ : Options Property Group Property name
Description
section-depth
Th is property defines the percentage of the radius to render the section as. The default value is set to 0.5.
[171]
Including Charts and Graphics in Reports
Ring chart example For this example, simply open the defined pie chart example and select the Ring chart type. Also, set the section-depth to o. 1, in order to generate the following effect: Computer Accessories
Multi pie chart The multi pie chart renders a group of pie charts, based on a category dataset. This meta-chart renders individual series data as a pie chart, each broken into individual categories within the individual pie charts. The multi pie chart utilizes the common properties defined above, including the category dataset properties. In addition to the standard set of properties, it also defines the following two properties: Options Property Group Property name
Description
label-format
This label defines how each item within a chart is rendered. The default value is set to "{0}". The format string may also contain any of the following: • • •
by-row
{0}: To render the item name {1}: To render the item value {2}: To render the item percentage in relation to the entire pie chart
This value defaults to True. If set to False, the series and category fields are reversed, and individual charts render series information.
[172]
Chapter 7
Note that the horizontal, series-color, stacked and stacked-percent properties do not apply to this chart type.
Multi pie chart example This example demonstrates the distribution of purchased item types, based on payment type. To begin, create a new report. You'll reuse the bar chart's SQL query. Now, place a new Chart element into the Report Header. Edit the chart, selecting Multi Pie [ff] as the chart type. To configure the dataset for this chart, select ITEMCATEGORY as the category-column. Set the value-columns property to QUANTITY and the series-by-field to PAYMENTTYPE.
Electric Compon ents
Compon
cash
credit
Batteries Compute rAccess ories Electric Compon ents
Electroni
debit
check
Waterfall chart The waterfall chart displays a unique stacked bar chart that spans categories. This chart is useful when comparing categories to one another. The last category in a waterfall chart normally equals the total of all the other categories to render appropriately, but this is based on the dataset, not the chart rendering. The waterfall chart utilizes the common properties defined above, including the category dataset properties. The stacked property is not available for this chart. There are no additional properties defined for the waterfall chart. [173]
Including Charts and Graphics in Reports
Waterfall chart example In this example, you'll compare by type, the quantity of items in your inventory. Normally, the last category would be used to display the total values. The chart will render the data provided with or without a summary series, so you'll just use the example SQL query from the bar chart example. Add a Chart element to the Report Header and select Waterfall [t^] as the chart type. Set the category-column to ITEMCATEGORY, the value-columns to QUANTITY, and the series-by-value property to Quantity. Now, apply your changes and preview the results.
Bar line chart The bar line chart combines the bar and line charts, allowing visualization of trends with categories, along with comparisons. The bar line chart is unique in that it requires two category datasets to populate the chart. The first dataset populates the bar chart, and the second dataset populates the line chart. The bar line chart utilizes the common properties defined above, including the category dataset properties. This chart also inherits the properties from both the bar cbart, as well as the line chart. This chart also has certain additional properties, which are listed in the following table: Required Property Group Property name
Description
bar-data-source
The name of the first dataset required by the bar line chart, which populates the bars in the chart. This value is automatically populated with the correct name.
line-data-source
The name of the second dataset required by the bar line chart, which populates the lines in the chart. This value is automatically populated with the correct name. [174]
Chapter 7 Bar Options Property Group Property name
Description
ctgry-tick-font
Defines the Java font that renders the Categories.
Line Options Property Group Property name
Description
line-series-color
Defines the color in which to render each line series.
line-tick-fmt
Specifies the Java DecimalFormat string for rendering the Line Axis Labels
lines-label-font
Defines the Java font to use when rendering line labels.
line-tick-font
Defines the Java font to use when rendering the Line Axis Labels.
As part of the bar line chart, a second y-axis is defined for the lines. The property group Y2-Axis is available with similar properties as the standard y-axis.
Bar line chart example To demonstrate the bar line chart, you'll reuse the SQL query from the area chart example. Create a new report, and add a Chart element to the Report Header. Edit the chart, and select Bar Line §j|] as the chart type. You'll begin by configuring the first dataset. Set the category-column to ITEMCATEGORY, the value-columns to COST, and the series-by-value property to cost. To configure the second dataset, set the category-column to ITEMCATEGORY, the value-columns to SALEPRICE, and the series-by-value property to sale Price. Set the x-axis-label-width to 2.0, and reduce the x-font size to 7. Also, set show-legend to True. You're now ready to preview the bar line chart. 2,000 1,750 1,500 1,250 1,000 750 500 250 0
[175]
Including Charts and Graphics in Reports
Bubble chart The bubble chart allows you to view three dimensions of data. The first two dimensions are your traditional X and Y dimensions, also known as domain and range. The third dimension is expressed by the size of the individual bubbles rendered. The bubble chart utilizes the common properties defined above, including the XY series dataset properties. The bubble chart also defines the following properties: Options Property Group Property name
Description
max-bubble-size
This value defines the diameter of the largest bubble to render. All other bubble sizes are relative to the maximum bubble size. The default value is 0, so this value must be set to a reasonable value for rendering of bubbles to take place. Note that this value is based on pixels, not the domain or range values.
The bubble chart defines the following additional dataset property: Required Property Group Property name
Description
z-value-columns
This is the data source column to use for Z value, which specifies the bubble diameter relative to the maximum bubble size.
Bubble chart example In this example, you need to define a three dimensional SQL query to populate the chart. You'll use inventory information, and calculate Item Category Margin: SELECT "INVENTORY" "INVENTORY" "INVENTORY" "INVENTORY" "INVENTORY" "INVENTORY" FROM "INVENTORY" ORDER BY "INVENTORY"
"ITEMCATEGORY", "ONHAND", "ONORDER", "COST", "SALEPRICE", "SALEPRICE" - "INVENTORY"."COST" MARGIN
."ITEMCATEGORY" ASC
[176]
Chapter 7
Now that you have a SQL query to work with, add a Chart element to the Report Header and select Bubble [jg as the chart type. First, you'll populate the correct dataset fields. Set the series-by-field property to ITEMCATEGORY. Now, set the X, Y, a n d Z value c o l u m n s to ONHAND, SALEPRICE, a n d MARGIN.
You're now ready to customize the chart rendering. Set the x-title to on Hand, the y-title to Sales Price, the max-bubble-size to 100, and the show-legend property to True. The final result should look like this:
Scatter chart The scatter chart renders all items in a series as points within a chart. This chart type utilizes the common properties defined above, including the XY series dataset properties. The scatter chart also defines the following two properties: Options Property Group Property name
Description
dot-height
The height to render the individual points in pixels. The default value is 5.
dot-width
The width to render the individual points in pixels. The default value is 5.
[177]
Including Charts and Graphics in Reports
Scatter chart example For this example, you'll reuse the SQL query defined in your bubble chart example, as well as the default rendering properties configured. Simply select the Scatter chart type in the chart editor The chart below shows Sales Price and On Hand values: 1,000
O (D
«
a> re to
750
500
250
•
10
-A
m mm
15
20
25
30
On Hand Batteries
•
Computer Accessories
Electric C o m p o n e n t s
Electronics
R C Vehicles
XY Area, XY Bar and XY Line charts The XY Area, XY Bar, and XY Line charts graph an XY series dataset as an area, bar, or a simple line chart. These chart types utilize the common properties defined above, including the XY series dataset properties. The XY Bar chart also uses the property show-bar-borders, which is defined earlier in the bar chart. The XY Area and XY Line charts share the properties line-style, line-size, and show-markers, defined earlier in the line chart. In addition to the standard XY Series Dataset, XY charts may use a Time Series Dataset to render data. To use the TimeSeriesCollector, you can select it in the Primary DataSource drop-down list. The Time Series Dataset is similar to the Category Dataset, but instead of a category it defines a category-time-column. The field selected for the category-time-column must be of the type j ava. u t i l . Date. Also defined is the time-period-type, which defines at what interval of time should the results be grouped together. Valid values for this property include Millisecond, Second, Minute, Hour, Day, Week, Month, Quarter, and Year.
[178]
Chapter 7
XY charts example In this example, you'll reuse the SQL query defined in the bubble chart example, as well as the default rendering properties configured for each of the individual charts, XY Area g , XY Bar .l|J, and XY Line Chart g j . You'll also reuse the X and Y dataset configuration specified for the scatter chart.
10
15
20
On Hand Batteries A
Computer Accessories
Electric Components
Electronics
RC Vehicles
1 0
1 5
20
25
On Hand Batteries |
Compute Accessories
Batteries
Computer Accessories
Electric Components
Electionics
Electric Components
RC Vehicles
Electronics
RC Vehicles
Extended XY Line chart The Extended XY Line chart allows the rendering of three additional chart types — StepChart, StepAreaChart, and DifferenceChart. The Step chart types display an XY series dataset as a set of steps, and the Difference Chart renders two XY series and highlights the differences between the two. The Extended XY Line chart utilizes the common properties defined above, including the XY series dataset properties. The Extended XY Line chart also defines the following property: [179]
Including Charts and Graphics in Reports
Options Property Group Property name
Description
ext-chart-type
The type of chart to render. Valid values are StepChart, StepAreaChart, and DifferenceChart.
Extended XY Line chart example In this example, you'll reuse the SQL query defined in the bubble chart example, as well as the default rendering properties configured for each of the individual charts. Select Extended XY Line SI as the chart type and specify StepChart, StepAreaChart and DifferenceChart as the Chart Type to see the different renderings: 1.000
a
750
'C
a.
ID a) n
Cfl
500 250
i u
15
20
Oil Hantl - Ü-J - "! " "
-
• Oj nui'j
>
-
[c^^CdiLviaiï
Vchdc
1.000 S 'C a
(0 01 O
750 500 250
X
10
15
20
On H a n d I Safeties
•
Ganpüla-Acceswi«
Beetle C o n p a i s i ^
QEdinna
3C
1JOOO
a
750
'C o.
Ï) 0) n
Cfl
500 250
10
15
20
On Hantl " Samtenes
_
• C a n p u ï e " Accessaries
- ü l e O - c C a r m cri t r i S
- R.C V e t i d e
[180]
Chapter 6
You've now worked with all the major chart types within Pentaho Reporting. Under the covers, charts are simply dynamic images that are generated and included in your reports. You'll now learn more about including images within reports.
Radar chart The Radar chart renders a web-like chart that displays a categorical dataset. The Radar chart utilizes the common properties defined above, including the category series common properties. The Radar chart also defines the following properties: Options Property Group Property name
Description
thickness-primary-series
This value determines the line thickness of the web.
head-size
This value determines the size rendered for each data point. The value is a percentage of the entire chart.
radar-web-filled
If true, fills the web with the series color. This also shades the grid.
gridline-interval
The interval between gridlines in the radar chart. This value may be a fixed value length or percent. To enter a percent value, use the " % " sign at the end of the number.
Radar chart example In this example, reuse the SQL query and dataset sections from your area chart example. The result should look like this:
y
Batteries \ /
RC Vehicles
Computer Accessories
! \ \
i
i
1 ? /
Electronics
Electric C o m p o n e n t s
Sale Price • Cost
[181 ]
Including Charts and Graphics in Reports
Including static images in your report To include static images in your report, select the image report element Q^ from the report designer palette and place it in your report. Double-click on the element, or right-click on the element and select Edit Content to select the static image. This brings up a resource dialog, where you can browse to the specific file location. You may Link to or Embed the image in the PRPT file. An example of a static image, with the ElectroBarn logo, is provided in Chapter 3. The image report element uses Pentaho Reporting's ResourceManager API to load the image. The ResourceManager interface is located in the org. pentaho. reporting.libraries.resourceloader package.
Including dynamic images in your report To add dynamic images to your report, use the content-field report element ¡a^. The content field accepts different types of image inputs for rendering. The first approach is dynamically changing the image location within your dataset. If you have a field that contains a URL or file system location to your image, the content-field element will render the specified image. The second approach is to populate the content-field with an object of type j ava. awt. image for rendering. This approach would require a custom-implemented TableModel (as described in Chapter 5), or a custom function that returns an image object. The third approach is to populate the content-field with an object that contains the following method, which is determined through Java introspection: void draw(Graphics2D g2, Rectangle2D area) ;
In addition to this API, Pentaho Reporting also defines an extended org. pentaho. reporting . engine . classic . core . util. ReportDrawable A P I w i t h the following
methods, for more detailed access into the report rendering process: •
void draw(Graphics2D g2, Rectangle2D area);
•
void setConfiguration(Configuration
•
void setStyleSheet(stylesheet
[182]
config);
style);
Chapter 7 •
void setResourceBundleFactory(ResourceBundleFactory bundleFactory);
•
ImageMap getlmageMap(final Rectangle2D bounds);
A custom TableModel implementation or custom function would also be required to make this object available to the Reporting engine.
Summary In this chapter, you learned how to incorporate many chart types into your reports in many different ways. You learned how to configure a chart's dataset as well as customizing how each chart type looks in a report. You learned how to populate a category series dataset, as well as an XY series dataset, and make that data available to the various types of charts that render in your report. You also learned how to include static and dynamic images, as well as graphics, in your reports.
[183]
7
Parameterization, Functions, Formulas, and Internationalization in Reports In this chapter, you'll start off by learning how to parameterize a report. You'll then learn about all the predefined functions and expressions available for use within a report. From there, you'll learn about Pentaho Reporting's formula capabilities, including the correct syntax and available formula methods. Finally, you'll learn about the details involved in internationalizing a report.
Report parameterization Report parameterization allows end users to customize results of Pentaho reports, by entering values that limit report datasets or trigger rendering decisions. Using the DataFactory API, Pentaho Reporting provides a mechanism to provide parameters to data sources. As presented in Chapter 5, there are many different options for providing data to Pentaho Reporting. Each data source type uses its underlying method for parameterizing queries. For instance, the default syntax for XPATH, Kettle, MDX, and Hibernate Query Language are supported through their respective DataFactory implementations. Each data source query syntax defines how to specify parameters, and Pentaho Reporting provides those parameters via the DataRow API.
Parameterization, Functions, Formulas, and Internationalization in Reports
The two exceptions from the default management of parameters include SQL and static data. When specifying a SQL statement in JDBC, you would normally specify a question mark to denote which parameters should be specified. Pentaho Reporting requires that you specify the parameters by name, so some parsing is done on the SQL query before passing the query to JDBC. You may specify parameters as $ { PARAM}, and the SQLReportDataFactory will replace each named parameter with a question mark (?) before making the prepared JDBC call. The NamedStaticDataFactory allows for Java class methods with parameters to be executed. The names provided when configuring the DataFactory are used when resolving the values from the DataRow provided.
Providing report parameters In Chapter 3, you implemented two example reports that used report parameterization. The first report parameterization was done as part of the End of the Day Cashiers report example. You defined a Sessions dataset to populate a drop down within Pentaho Report Designer, which determined the results of the report. The second parameterization example was in the definition of the sub-report in the Invoice report example. The sub-report defined the parameter $ {CUSTOMERID}, and the value was available to the sub-report, based on the current data row retrieved from the primary report. Both of these are examples of parameterization. To provide a master report with parameters, you need to access the parameter values collection from the master report. To do this, call MasterReport. getParameterValues (). Then you may add parameters to the report by calling ReportParameterValues . put (column, value). T h e ReportParameterValues
class implements the DataRow API, which makes it possible to pass these parameters to the various DataFactory implementations.
Available report parameter types Pentaho Reporting defines the following parameter types, which each render differently within Pentaho Report Designer and Pentaho's BI Server: •
Drop Down
•
Single Value List
•
Multi Value List
•
Radio Button
•
Check Box
[186]
Chapter 7
•
Single Selection Button
•
Multi Selection Button
•
Text Box
When embedding Pentaho Reporting into a custom application, it is the embedded program's responsibility to render parameters, as demonstrated in Chapter 3. All parameter types may specify a data source for population of possible selections, as well as for validation. It is possible to nest parameters by parameterizing the data sources, which are used to populate selections. For example, a top level drop-down parameter such as Country could drive a secondary radio button parameter such as Region. Queries are executed in the order in which they appear in the data source list. Multi Value List, Check Box, and Multi Selection Button parameter types allow the selection of multiple types. These parameter types return an array of values rather than a single value. Data sources, including SQL, have special logic that maps the array of values into the generated query.
Working with functions and expressions Pentaho Reporting provides many functions and expressions that may be used during report creation. A function in Pentaho Reporting is used to calculate a computed value. An expression in Pentaho Reporting is a function whose scope is limited to the current dataset row. A function may maintain state, having access to many rows of data. All functions share the following properties: •
Name: Used to reference the function or expression in elements, formulas, and other functions
•
Dependency Level: Used to determine the order in which to execute the functions
Listed below are the available functions and expressions, and how they are used. Chart related functions were covered in depth within Chapter 6, so there is no need to restate them in this list.
[187]
Parameterization, Functions, Formulas, and Internationalization in Reports
Common functions Common functions include the most commonly used functions within Pentaho Report Designer. Function name
Description
Open Formula
This function evaluates a LibFormula formula defined later in this chapter. Following is the property of this function: •
Page
Formula: The formula to evaluate.
This function returns the current page number. The following are properties of this function: • Reset on Group Name: If this value is set, the page total value is reset when the named group appears. • Page Increment: The amount by which to increase the count for each page. • Start Page Number: The page from which to start counting.
Total Page Count
This function calculates the total number of pages in a report. The following are properties of this function: • • •
Page of Pages
Reset on Group Name: If this value is set, the page total value is reset when the named group appears. Page Increment: The amount by which to increase the count for each page. Start Page Number: The page from which to start counting.
This function returns a string that displays the current page and the total page count. The following are properties of this function: • Format Pattern: The format string to render the current page and total pages into. The default value is " { 0 } / { l } " . °
{0}: To the current page.
°
{1}: To render the total page count.
•
Reset on Group Name: If this value is set, the page total value is reset when the named group appears.
•
Page Increment: The amount by which to increase the count for each page.
•
Start Page Number: The page from which to start counting.
[188]
Chapter 7
Report functions Report functions are related to the rendering of a report. Function name
Description
Is Export Type
This function returns True if the export type of the report string begins with the export type property provided. Following is the property of this function: • Export Type ID: The string to compare to the report export type string.
Row Banding
The row banding function manages changing background colors for rows in a report. The following are properties of this function: • Active Banding Color: The primary banding color • Apply to Element(s) Named: The name of the element to change the background color of. • Inactive Banding Color: The secondary banding color • Number of Rows: The number of rows to render before changing the banding color. • State On New Groups: If set to True, resets the banding color for each new group. • State On New Pages: If set to True, resets the banding color for each new page.
Hide Repeating
This function hides repeated elements of a specified field in the item band. The following are properties of this function: • Apply to Element(s) Named: The element to hide in the item band. • Field Name: The field to watch for changes. • Ignore All Group Breaks: If set to False, this function will reset itself on group breaks. • Ignore All Page Breaks: If set to False, this function will reset itself on page breaks.
Hide Page Header & Footer tyPe
This function will hide the page header and footer if the export is n ° t pageable. The following are properties of this function: • Disable Repeating Headers: Disables any repeating group headers and footers. • Hide Page Bands: If set to True, hides page bands. •
Export Descriptor: This property is used to determine whether the current report export type should disable page headers and footers. Its default value is table.
[189]
Parameterization, Functions, Formulas, and Internationalization in Reports Function name
Description
Show Page Footer
This function hides the page footer except for the last page. It has no additional properties.
Summary functions Summary functions calculate values during the first phase of report processing and make those values available during report rendering. Function name
Description
Sum
This function sums a field within a group during the prepare run stage of a report, making available the total group sum in later stages of report generation. The following are properties of this function: • Field Name: The field to sum. • Reset on Group Name: The name of the group that should be counted. If set to empty, counts all the groups within a parent group.
Count
This function counts the rows within a group during the prepare run stage of a report, making available the total group count in later stages of report generation. Following is the property of this function: • Reset on Group Name: The name of the group that should be counted. If set to empty, counts all the groups within a parent group.
Group Count
This function counts the occurrence of groups within a report during the prepare run stage of a report, making available the total group count in later stages of report generation. The following are properties of this function: • Group Name to Count: The name of the group that should be counted. If set to empty, counts all groups within a parent group. • Reset on Parent Group Name: The name of the group which resets the count. If set to empty, counts the sub-groups of the entire report.
[190]
Chapter 6 Function name
Description
Minimum
Determines the global minimum value of a specified field in a report. The following are properties of this function: • Field Name: The field which should be assigned the minimum value. • Reset on Group Name: If this value is set, the minimum aggregation value is reset when the named group appears.
Maximum
Determines the global maximum value of a specified field in a report. The following are properties of this function: • Field Name: The field which should be assigned the maximum value. • Reset on Group Name: If this value is set, the maximum aggregation value is reset when the named group appears.
Sum Quotient
This function sums a dividend and a divisor, and then divides the two for the result value, using the Sum function to sum the values. The following are properties of this function: • Field Name: The field to sum. • Reset on Group Name: The name of the group that should be counted. If set to empty, counts all the groups within a parent group. • Dividend Field: The field that holds the dividend of this division calculation. • Divisor Field: The field that holds the divisor of this division calculation. • Rounding Mode: Java's BigDecimal Rounding mode. Please see Java's documentation for values. • Scale: The scale of the quotient returned. The default value is 14.
Sum Quotient Percent
This function is an extension of the Sum Quotient function, and simply multiples the final result by 100. It shares the same properties as the Sum Quotient function.
[191 ]
Parameterization, Functions, Formulas, and Internationalization in Reports Function name
Description
Calculation
This function stores the result of a field calculated during the prepare run stage of report generation, allowing access later on in the report. The following are properties of this function: • Field Name: The field to store. •
Reset on Group Name: If this value is set, the aggregation value is reset when the named group appears.
Count for Page
This function is identical to the Count function, but also resets at the beginning of each page. It has no additional properties.
Sum for Page
This function is identical to the Sum function, but also resets at the beginning of each page. It has no additional properties.
Running functions Rurmirig functions calculate values during report rendering, allowing for incremental aggregation information throughout a report. Function name
Description
Sum (Running)
Calculates the sum total value of a specified field over a number of rows in a report. The following are properties of this function: • Field Name: The field to sum. • Reset on Group Name: If this value is set, the sum total value is reset when the named group appears.
Count (Running)
Maintains the value of the current number of rows in a dataset. Following is the property of this function: •
Group Count (Running)
Reset on Group Name: If this value is set, the count is reset when the named group appears.
This method counts the occurrence of groups within a report. The following are properties of this function: •
•
Reset on Group Name: The name of the group that should be counted. If set to empty, counts all the groups within a parent group. Reset on Parent Group Name: The name of the group which resets the count. If set to empty, counts the subgroups of the entire report.
[192]
Chapter 7 Function name
Description
Count Distinct (Running)
This method counts the distinct occurrences of a value within a specified field. The following are properties of this function: • Field Name: The field to count. • Reset on Group Name: If this value is set, the count value is reset to zero when the named group appears.
Average (Running)
Calculates the average value of a specified field over a number of rows within a report. The following are properties of this function: • Field Name: The field whose average to calculate. • Reset on Group Name: If this value is set, the average value is reset when the named group appears. • Rounding Mode: Java's BigDecimal Rounding mode. Please see Java's documentation for values. • Scale : The scale of the quotient returned, defaults to 14.
Minimum (Running)
Determines the minimum value of a specified field over a number of rows in a report. The following are properties of this function: • Field Name: The field to calculate a minimum value. • Reset on Group Name: If this value is set, the minimum value is reset when the named group appears.
Maximum (Running)
Determines the maximum value of a specified field over a number of rows in a report. The following are properties of this function: • Field Name: The field which should be assigned the maximum value. • Reset on Group Name: If this value is set, the maximum value is reset when the named group appears.
Percent of Total (Running)
Calculates the percentage value of a specified field, by summing all the data rows and dividing the current row by the total sum. The following are properties of this function: Field Name: The field whose average to be calculated. Reset on Group Name: If this value is set, the average value is reset when the named group appears. Rounding Mode: Java's BigDecimal Rounding mode. Please see Java's documentation for values. Scale Result To 100: Multiply the value by 100. Scale: The scale of the quotient returned. The default value is 14.
[193]
Parameterization, Functions, Formulas, and Internationalization in Reports
Advanced functions Advanced functions include functions that are specialized, and are not generally used. Function name
Description
Message Format
Formats a message, based on the current data row. The following are properties of this function: • Encoding: Use this encoding if URL Encode properties are set. • Null-String: What value to render if the field referenced is null. • Message Pattern: A string pattern to render, with row data referenced by ${FIELD}. • URL-Encode the result: To encode the final result. • URL Encode all Values: To encode the individual row data rendered within the message.
Resource Message
Returns a formatted message from a resource bundle.
Format
The following are properties of this function: •
• • Lookup
Resource-Key of Pattern: The format string to render, which may contain references to the current row fields, using the ${FIELD} syntax. ResourceBundle Identifier: The name of the resource bundle. Null String: The value to return if a field is null.
This function allows you to choose between different strings, a value based on key matching. The following are properties of this function: • Fall Back Value: If no keys match the field value, return this value. • Field Name: The field to compare keys, to determine the mapping. • Ignore Case When Matching: If set to True, ignores the case when making key comparisons. • Key Values: Values to compare to the field. Each key should have a corresponding Texts value. • Null Value: If the field is null, return this value. •
Text Values: It is a list of strings. A string is chosen from the list depending on which key matches the field value.
[194]
Chapter 7 Function name
Description
Indirect Lookup
This function allows you to choose between different columns, a value based on key matching. The following are properties of this function: • Fallback Forward-Field: If no keys match the field value, return this field's value. • Field Name: The field to compare keys, to determine the mapping. • Forwarding Field List: It is a list of fields. A field is chosen from the list depending on which key matches the field value. • Ignore Case when Matching: If set to True, ignores the case when making key comparisons. • Key Values: Values to compare to the field. Each key should have a corresponding forwarding field. • Null Value: If the field is null, return this value.
Resource Bundle Lookup
Returns a value from a resource bundle, based on a key provided by a field. The following are properties of this function: • Field Name: The field which contains the resource bundle key. • Resource-Bundle Identifier: The name of the resource bundle.
Open Formula (Advanced)
This function is a stateful version of the Formula Expression. The following are properties of this function: • •
Formula: The formula to evaluate. Initialization Formula: If specified, this formula will be evaluated when the Formula Function is called for the first time, instead of evaluating the default formula.
[195]
Parameterization, Functions, Formulas, and Internationalization in Reports
Image functions Image functions render various graphical objects, which may be used in conjunction with a content field element. Function name
Description
BarCode
This function generates a simple barcode ReportDrawable object, which may be rendered in a content field element. The following are properties of this function: • barHeight: The height of the bar in pixels • barWidth: The width of the bar in pixels • checksum: If set to True, includes the checksum in the barcode • rawDataField: The field containing the barcode value • rawTypeField: If type is not specified, use this field name to resolve the barcode type • showText: If set to True, shows the barcode text below the barcode • Type: The type of the barcode
Sparkline
This function generates a sparkline ReportDrawable object, which may be rendered in a content field element. The following are properties of this function: • • • • • • • • • • • • • • •
backgroundColor: The background color of the sparkline color: The foreground color of the sparkline counterclockwise: If rendering a pie, render the slices counter clockwise Field: An array of field names used to render the sparkline highColor: The color of the largest bars or pie slices highSlice: The threshold value of the largest slices lastColor: The color of the last bar chart lowColor: The color of the smallest bars or pie slices lowSlice: The threshold value of the smallest slices mediumColor: The color value of the medium bars or slices mediumSlice: The threshold value of the medium slices rawDataField: If specified, use this as the source field for the array of values, populating a sparkline graph spacing: The spacing of pixels between each data input, having a default value of 2 startAngle: The start angle of the pie sparkline Type: The type of sparkline to render—bar, line, or pie
[196]
Chapter 7 Function name
Description
Survey Scale
This function generates a survey scale ReportDrawable object, which may be rendered in a content field element.
i
i
i
i
i
*
V
The following are properties of this function: •
Field Name: The fields to render as tick marks on the scale
•
Highest Response Value: The maximum number to render on the scale
•
Lowest Response Value: The minimum number to render on the scale
•
Lower Range Bound Field: If set along with the upper bound field, a box will render over a certain range, based on the field value provided
•
Range Paint: The color to render the range in, which defaults to gray
•
Upper Range Bound Field: If set along with lower bound field, a box will render over a certain range
Script functions Scripting functions make it easy to customize your report through various scripting languages. Function name
Description
Bean-Scripting Framework (BSF)
This function uses Apache's Bean Scripting Framework to generate a result. Please see http : // j akarta. apache . org/ bsf for more information on the Bean Scripting Framework. The following are properties of this function: • Expression Programming Language: The programming language used in the expression. • Expression: An expression defined in the programming language specified. • Initialization Script: A script defined in the programming language specified, which is executed during the initialization of the scripting language environment.
[197]
Parameterization, Functions, Formulas, and Internationalization in Reports Function name
Description
Bean-Scripting-Host (BSH)
This function uses the BeanShell framework to generate a result. Please see http ://www. beanshell. org for more information on BeanShell. Following is the property of this function: • Expression: A bean shell expression, which must be in the form of getValue ( ) {FUNCTION}, returning the value. The DataRow object is accessible to the expression, allowing access to the current data row.
JavaScript
This function uses Javascript to generate a result. Please see http : //www. mozilla . org/rhino/ for more information on Rhino Javascript. Following is the property of this function: • Expression: A Javascript expression, which must be in the form of getValue ( ) {FUNCTION}, returning the value. The DataRow object is accessible to the expression, allowing access to the current data row.
Single Value Query
This function executes an existing named query against a data source, and returns a result from the first row. The following are properties of this function: • Field Name: If the query is parameterized, you must specify the fields that it needs to execute. • Result Column: The named column within the first row to return. If the property is not set, the first column is returned. • Query Name: The query to execute. •
query Timeout: the amount of time allowed for query execution.
Working with formulas In addition to providing functions within reports, formulas may also be used to generate dynamic content in a report. Formulas may be used to derive element property and style values. Also, the Open Formula and Open Formula (Advanced) functions defined earlier may be used to combine the formula and function mechanisms in a report. Formulas in Pentaho Reporting are based on the OpenFormula standard. This standard is similar to Excel Formula support, and is used in Open Office, as well as other tools such as Pentaho Metadata. This formula system is often referred to as LibFormula, which is the library name for reporting's formula sub-project.
[198]
Chapter 7
Formula syntax A formula evaluates to a final value. Formulas support a standard set of data types, along with operators and functions that may be used to derive new values. Here is a simple example formula: IF([COL1] > 10; "Big"; "Small");
This formula uses the I F function with parameters separated by semi-colons. The first parameter is a comparison, resulting in true or false. To reference an outside data column or named function, reference the column in brackets, as shown for COLI. If the comparison example evaluates to true, the second parameter in the I F function is returned. To specify a string, use double quotes, shown with "Big" and "Small". If the statement evaluates to false, the third parameter is returned. Also, the term NULL may be used to denote a null reference.
Formula data types Column data, as well as literal values, all get mapped to a formula data type. The following data types are supported. Different types may inherit from one another: Data Type
Description
Numeric
A Numeric value, represented in Java as a BigDecimal object. Literal values of this type may take the following forms: • 123 • 123.456 • 123el0 or 456E-10 •
Text
-1.2
A text value, represented in Java as a String object. Literal values of this type must be quoted with double quotes: "Text Here" To place a double quote within a string, reference it twice: " Here is a "" quote"
Logical
The Logical type inherits from the Numeric type. The values of this type are Boolean—either true or false. You may specify a logical value through the functions TRUE() and FALSE0.
Error
Various formula functions may fail. When this occurs, an error is created. Certain functions are available to determine if an error has occurred.
[199]
Parameterization, Functions, Formulas, and Internationalization in Reports Data Type
Description
Date
The Date type inherits from the Numeric type. This type is represented as a j ava. util. Date object within Java, and represents the Date portion of a complete date.
Time
The Time type inherits from the Numeric type. This type is represented as a j ava. util. Date object within Java, and represents the Time portion of a complete date.
DateTime
The DateTime type inherits from the Numeric type, as well as the Date and Time types. This type is represented as a j ava . ut i 1. Date object within Java. Functions such as DATEVALUE0 are available to generate a date object.
Array
Arrays may be declared in a formula, or generated by functions. You may specify one or two dimensional arrays with the following syntax: {R0W1|R0W2|ROW3...} And a row may be broken into multiple columns by semicolons. Here is an example: {1; 2 ; 3 | 4 ; 5 ; 6 | 7 ; 8 ; 9 }
Formula operators The following operators may be used within a formula expression. Note that all operators, except the percent operator, are infix operators, with the operator appearing between the values—for instance, Valuel OPERATOR Value2. Operator
Description
+
Adds two numbers together. Subtracts two numbers.
*
Multiples two numbers.
/
Divides two numbers.
=
Returns true if both values are equal. Returns true if values are not equal.
=
Returns true if the first value is larger than or equal to the second value.
Returns true if the first value is greater than the second value.
A
Returns the first value powered to the second value.
[200]
Chapter 7 Operator
Description
&
Concatenates two strings.
%
Divides a number by 100, converting it to percent. For instance, 100% will return 1.
Formula functions Pentaho Reporting defines many functions available for use within the formula system. Below is the exhaustive list, along with the detailed information about each function:
Date time functions These functions allow for creation and manipulation of Date, Time, and DateTime objects. Function name
Description
DATE(Year; Month; Day)
Creates a Date object based on the year, month, and day.
DATEDIF(StartDate; EndDate; Format)
Returns the difference between two dates, depending on the format code, which may be one of the following: • • • • • •
DATEVALUE(Text)
y: The difference in years. m: The difference in months. d: The difference in days. yd: The difference in days, ignoring the years. ym: The difference in months, ignoring the years. md: The difference in days, ignoring the months and years.
Parses a string into a date. The string must match one of the supported formats. By default, the following formats are supported: • M/d/yy
DAY(Date)
• yyyy-MM-dd Returns the day of the month.
DAYS(Datel; Date2)
Calculates the number of days between two dates.
HOUR(Time)
Returns the hour of the time.
MINUTE(Time)
Returns the minute of the time.
MONTH(Date)
Returns the numeric month of the year, where January = 1, and so on.
NOW()
Creates a DateTime object with the current time.
SECOND (Time)
Returns the second of the time. [201]
Parameterization, Functions, Formulas, and Internationalization in Reports Function name
Description
TIME(Hour; Minute; Second)
Creates a Time object, based on the hour, minute, and second value.
TIMEVALUE(Text)
Returns a sequential number for a text shown in a possible time entry format.
TODAY()
Creates a Date object with the current date.
WEEKDAY(Date)
Returns the day of the week, where Sunday = 1, and so on.
YEAR(Date)
Returns the year.
Logical functions These functions perform various Boolean logic operations. Function name
Description
AND(Expressionl; Expression2;...)
If all expressions evaluate to true, returns true, otherwise returns false. Note that any number of expressions may be ANDed together. Returns the Boolean value false.
FALSE() IF(Expression; ReturnTrue; ReturnFalse)
If the first parameter evaluates to true, return the second parameter, otherwise return the third parameter.
NOT(Expression)
Return false if the expression is true, true if the expression is false.
OR(Expressionl; Expression2;...)
Return true if any of the expressions evaluates to true. Note that any number of expressions may be ORed together.
TRUE()
Returns the Boolean value true.
XOR(Expressionl; Expression2;...)
Returns true if an odd number of expressions evaluate to true.
[202]
Chapter 7
Mathematical functions These functions offer various forms of numeric calculations. Function name
Description
ABS(Value)
Returns the absolute value.
ACOS (Value)
Returns the arccosine of a number.
ACOSH(Value)
Returns the inverse hyperbolic cosine of a number.
ASIN(Value)
Returns the arcsine of a number.
ATAN (Value)
Returns the arctangent of a number.
ATAN2(Valuel;Value2)
Returns the arctangent for the specified coordinates.
AVERAGE(Valuel; Value2;.
Returns the average value of all the parameters. These values may also be arrays. Each element of an array is evaluated to calculate the average.
AVERAGEA(Valuel; Value2;
Returns the average value of all the parameters. These values may also be arrays. Each element of an array is evaluated to calculate the average. Text and logical values are included in the calculation too.
COS(Valuel)
Returns the cosine of a number.
EVEN (Value)
Rounds the number up to the nearest even integer.
EXP(Valuel)
Calculates the exponent for basis e.
INT(Value)
Rounds a number down to the nearest Integer value.
LN(Valuel)
Calculates the natural logarithm of a number.
LOG(Value; Base)
Calculates the logarithm to any specified base.
LOGlO(Value)
Calculates the base-10 logarithm of a number.
MAX(Valuel; Value2;.
Returns the maximum value of all the parameters. These values may also be arrays. Each element of an array is evaluated, and the largest value is returned.
MAXA(Valuel; Value2;.
Returns the maximum value of all the parameters. These values may also be arrays. Each element of an array is evaluated, and the largest value is returned. Text and logical values are included in the calculation too.
[203]
Parameterization, Functions, Formulas, and Internationalization in Reports Function name
Description
MIN(Valuel; Value2;...)
Returns the minimum value of all the parameters. These values may also be arrays. Each element of an array is evaluated, and the smallest value is returned.
MINA(Valuel; Value2;...)
Returns the maximum value of all the parameters. These values may also be arrays. Each element of an array is evaluated, With and the smallest value is returned.
MOD(Valuel; Value2)
Calculates the remainder of division for Valuel divided by Value2.
ODD((Value)
Rounds the number up to the nearest odd integer.
PI()
Returns the value of the number Pi.
POWER(Value; Power)
Computes a number raised to the power by another number.
SIN(Value)
Returns the sine of a number.
SQRT(Value)
Returns the square root of a number.
SUM(Valuel; Value2;...)
Sums two or more values. These values may also be arrays. Every element of a one or two dimensional array will be summed together.
SUMA(Valuel; Value2; ...)
Sums two or more values. These values may also be arrays. Every element of a one or two dimensional array will be summed together. Text and logical values are included in the calculation too.
VAR(Valuel; Value2; ...)
Calculates the variance based on a sample.
Text functions These functions work with and manipulate strings. Function name
Description
EXACT(Textl; Text2)
Returns true if two Text values are exactly equal.
FIND(Search; Text[; Index])
Returns the index of the first occurrence of the search string in the Text, starting at the Index specified. The index parameter is optional.
LEFT(Text; Length)
Returns the left portion of a string up to Length characters.
LEN(Text)
Returns the length of the text. [204]
Chapter 7 Function name
Description
LOWER(Text)
Returns the text in all lower case.
MID (Text; Start; Length)
Returns a substring within the Text, starting at Start, and having the length of Length.
REPLACE (Text; Start; Length; New)
Replaces a portion of the Text, starting at Start, and ending at Length with the New text provided.
REPT(Text; Count)
Returns the Text Count times. For instance, if the Text was "test" and the Count was 3, the result would be "testtesttest".
RIGHT(Text; Count)
Returns the right portion of the string up to Length characters.
SUBSTITUTE(Text; Old; New[; Which])
Replaces the Old substring with the New substring in Text. If the Which index is provided, only the Nth Old substring will be replaced.
T(Value)
If the value is of type Text, returns the value, otherwise returns an empty string.
TEXT(Value)
Converts the value to Text. Boolean values are converted to "TRUE" and "FALSE".
TRIM (Text)
Trims any whitespace at the beginning and end of the Text.
UNICHAR(Number)
Converts a code number into a Unicode character or letter.
UNICODE(Text)
Returns the numeric code for the first Unicode character in a text string.
UPPER(Text)
Returns the text in all upper case.
URLENCODE(Text; Encoding)
Encodes the text based on the encoding specified. If no encoding is specified, ISO-8859-1 is used.
[205]
Parameterization, Functions, Formulas, and Internationalization in Reports
Reporting Specific functions These functions interact with the reporting engine in some way: Function name
Description
ISEXPORTTYPE(ExportDescriptor)
Returns true if the current export type starts with the provided ExportDescriptor text.
ISEMPTYDATAO
Returns true if the report result set has zero rows.
METADATA(Field; Domain; Name[; Type])
This function returns a metadata value of a Field based on its Domain and Name. This function is demonstrated in Chapter 12. Returns the current row number of the current group. If no GroupName is specified, returns the global row number.
ROWCOUNT(GroupName)
Return the value of a property provided through the ReportEnvironment API. To create a property in your environment, set a configuration property using the format org . pentaho.reporting.engine.classic. core.environment.
ENV (Property)
Miscellaneous functions Many additional functions are available that offer rich capabilities within Pentaho Reporting. Function name
Description
CHOOSE(Index; Valuel; Value2;.
Returns the parameter referenced by the index.
COUNT(Valuel; Value2;...)
Returns the number of values. This function will count individual elements within arrays as well.
COUNTA(Valuel; Value2;...)
Returns the number of non-empty values within an array or arrays. This function will count non arrays always, even if they are empty.
COUNTBLANK(Reference)
Returns the number of empty values within a reference that represents an array of values.
HASCHANGED(Text)
Returns true if the field with the name of Text has changed.
ISBLANK(Value)
Returns true if the value is null.
[206]
Chapter 7 Function name
Description
ISERR(Value)
Returns true if the value is an error, but not the NA error.
ISERROR(Value)
Returns true if the value is an error.
ISEVEN (Value)
Returns true if the value is even.
ISLOGICAL(Value)
Returns true if the value is a logical type.
ISNA(Expression)
Returns true if the expression has generated the NA error object.
ISNONTEXT(Value)
Returns true if the value is not text.
ISNUMBER(Value)
Returns true if the value is a number.
ISODD(Value)
Returns true if the value is odd.
ISREF(Value)
Returns true if the value is a reference.
ISTEXT(Value)
Returns true if the value is a text type.
NA()
Returns the Error NA, or Not Available.
CSVTEXT(Array[; DoQuoting[; Separator[; Quote]]])
Generates a comma separated value list. If DoQuoting is set to true, quote all the strings. By default, the separator is a comma, this can be overridden by setting the Separator parameter. By default, the strings are quoted using a double quote, this can be overridden by setting the Quote parameter.
INDEX(Array; RowNumber; ColumnNumber)
Returns the value at the specified array index.
VALUE(Text)
Converts a Text string to a Numeric value.
As you can see, there are many functions to choose from when defining formulas within reports. In Chapter 3, multiple formulas were used in examples to create rich, dynamic reports.
Internationalization and localization of reports To internationalize a report, you must use the resource elements available within Pentaho Reporting when creating your report. Each resource element defines a resource base and a resource key reference. Normally, the resource base refers to the name of the message properties file in which localized names are kept. For default handling of resource bundles in Java, please see Java's I18N Tutorial on resource bundles:
[207]
Parameterization, Functions, Formulas, and Internationalization in Reports http://j ava.sun.com/docs/books/tutorial/il8n/resbundle/concept.html
Once you've built your report, you'll want to configure your application to access the resource bundle files appropriately. Pentaho Reporting defines a ResourceBundleFactory API, which allows you to customize how these files are loaded. By default, a report is configured to use the Default ResourceBundleFactory implementation, which uses Java's ResourceBundle implementation. This implementation resolves the provided resource base value on the Java classpath. Another solution is to use the LibLoaderResourceBundleFactory, which uses LibLoader's approach to loading files. LibLoader is an extendible framework for loading resources. Utilizing LibLoader's default ResourceLoaders, you may load data from the filesystem, URLs, ZIP files, as well as the classpath. If neither of these implementations fits your needs, you may implement your own ResourceBundleFactory. This factory interface defines the following methods: •
public ResourceBundle getResourceBundle(String
•
public Locale g e t L o c a l e O ;
key);
If using a factory other than the default, you may specify the factory by calling setResourceBundleFactory () on the master report object. The ResouceBundleFactory is also responsible for determining the specific locale to use when rendering the report. The Def aultResourceBundleFactory uses the default system locale, but also contains a setLocale () method for configuring the locale if necessary. If you are not planning on implementing your own ResourceBundleFactory, the recommended approach for configuring the locale of a report is to provide it through the ReportEnvironment API. The Def aultReportEnvironment class defines a setLocale () method for configuring the report's locale. This is demonstrated in the example below.
Localizing fields Using the resource-field element within your report allows you to localize dynamic data to a certain extent. Instead of providing a static resource key, this element type specifies the field data source where the key is generated from. The only limitation to this approach is that you must have a defined bundle with the key to localized mappings already in place. For a complete solution to dynamic localization, you may want to investigate using the indirect Lookup function, in order to dynamically choose different localized columns in a database for populating a specific dynamic field. [208]
Chapter 7
Localization example Now that you're familiar with the various components involved in setting up an internationalized report, it's time to walk through an example. First, launch the Pentaho Report Designer and create a very basic report with a resource-label in the Report Header. Specify file:data/localization-example as the resource-identifier, and use localizedString as the value attribute. Export this report as localizationexample . prpt, and place it in the data folder for Chapter 2. You also need to create localized property files. For this example, create a default English message bundle file as data/localization-example . properties, with the following text: localizedString=My Localized Report
Create a Spanish message bundle file, localization-example_es . properties, with the following text: localizedString=Mi Informe Localizar
You'll now need to configure the chapter2SwingApp, in order to use the new report, along with the message bundles. First, edit the report reference to use f ile: data/ localization-example .prpt. You'll now need to configure the report environment with the correct locale. Add the following lines of code right after creating the MasterReport object: Locale locale = Locale.getDefault(); ( (DefaultReportEnvironment)report.getReportEnvironment()) . setLocale(locale);
Also, make sure to add the following imports: import java.util.Locale; import org.pentaho.reporting.engine.classic.core. DefaultReportEnvironment;
Run the example by typing ant run on the command line. You should see the label "My Localized Report" appearing in the report. Now change the creation of the Locale object to Spanish: Locale locale = new Locale("es");
Execute ant run again. This time you should see the new Spanish label in your report.
[209]
Parameterization, Functions, Formulas, and Internationalization in Reports
Summary In this chapter, you learned the details involved in report parameterization. You also learned about the various ways to dynamically render a report, including learning all the available functions and expressions, as well as learning the LibFormula syntax and function list. Finally, you learned how to internationalize your reports and the static text within a report, so you can build reports that are populated by internationalized data.
[210]
8
Adding Sub-Reports and Cross Tabs to Reports In this chapter, you'll learn the ins and outs of two advanced reporting topics — sub-reports and cross tabs. Sub-reports allow you to embed reusable reports within a master report. As you'll see with the help of examples, sub-reports can take on many forms—from multi-page detail reports to summary sub-reports that include charts. You'll also learn how to create a side-by-side sub-report example. Along with sub-reports, you'll learn how to incorporate cross tabs into your reports. Cross tabs allow you to compare multiple variables in a single table of data values.
Adding sub-reports In Chapter 3, you created a very simple single data row sub-report that included details about the current customer for invoicing purposes. In this chapter, you'll review other scenarios for using sub-reports and learn the technical details involved in including sub-reports in a master report. Sub-reports in Pentaho Reporting may be included in any band of a report, except for the page header and page footer bands. Sub-reports receive a DataRow of parameters, determined by the current state of their parent report when rendering the sub-report. These parameters may be used when executing a sub-report query or referenced directly in the sub-report. Within sub-reports, you define named queries that may reference the DataRow of parameters passed in, allowing a sub-report to query only the currently scoped data, not the entire data set available to the parent report.
Adding Sub-Reports and Cross Tabs to Reports
Sub-reports may be of any length, may be included in other sub-reports in a nested fashion, and may also be presented side-by-side one another in their parent report. When spanning multiple pages, special considerations must be made, including how to handle the master report's page header, page footer, and group headers. This chapter will cover all of these topics in the examples below.
Multi-page sub-report example In this first example, you'll build a report, which includes a large sub-report that may span multiple pages. Before you can begin with these examples, you need to create a new folder called chapters, and copy the JAR files from the chapter3/lib folder into chapters/lib. Also, copy the chapter2/build.xml file into the chapters folder. Finally, copy the chapter3 /data folder to chapters /data, so that you may reuse the already configured ElectroBarn data source. To begin with the example, you must first define your master report dataset. You'll reuse the ElectroBarn HSQLDB example to build this report. Launch the Report Designer and create a new report. Add a new JDBC dataset. Select the already defined ElectroBarn connection for this example, which was configured in Chapter 3. Now, define the following query: SELECT "ENDOFDAY" "ENDOFDAY" "ENDOFDAY" "ENDOFDAY" "ENDOFDAY" FROM "ENDOFDAY" ORDER BY "ENDOFDAY"
"SESSIONID" , "EMPLOYEEID", "ACTUALCHE CKTOTAL" "ACTUALCASHTOTAL", "CHE CKOUTTIME"
"SESSIONID" ASC
This simple query selects the high level sales clerk session information. Now that you've configured your dataset, it's time to define your master report. First, create an example page header and footer. Place a label in the Page Header and add the text Master Report Page Header. For the Page Footer, place a label and set the text to Master Report Page Footer. For both the header and the footer, check the sticky style attribute checkbox, which appears in the page behavior group of style attributes. This tells the reporting engine to render the master report's page header and footer on pages generated by the sub-report. Otherwise, these bands would not appear in every page of the generated report. Finish the master report by dragging and dropping the fields for SESSIONID and EMPLOYEEID in the Details band. Give both of tbese fields a label as well. Your report should look like the following: [212]
Chapter 7 150%
50
100
150
200
250
300
350
400
Master Report Page Header
Page Header
Report Header
Session ID: SESSIONID Employee ID: EMPLOYEEID
Details Li.I
Report Footer
Page Footer
Master Report Page Footer
It's now time to add a sub-report to the master report. Drag-and-drop a sub-report S element from the Palette into the Details band, below the Employee ID. When prompted, select the Banded option for this sub-report. Banded sub-reports act as an independent band within the report and take up the entire width. A Banded sub-report must appear below all other elements within a band. Therefore, if you add additional elements, the sub-report will appear below those added elements. Now, you're ready to begin editing the sub-report. Double-click on the sub-report element, or right-click and select the Edit sub-report menu option, in order to bring up the sub-report for editing. The first step to setting up the sub-report is to create a new data source query. Create the following ElectroBarn query as part of the sub-report: SELECT "PURCHASES"."SESSIONID", "PURCHASES"."PAYMENTTYPE", "PURCHASES"."PURCHASETIME", "PURCHASES"."PURCHASEID", "PURCHASEITEMS"."QUANTITY", "INVENTORY"."SALEPRICE", "INVENTORY"."ITEMNAME" FROM "PURCHASEITEMS" INNER JOIN "INVENTORY" ON "PURCHASEITEMS"."ITEMID" = "INVENTORY"."ITEMID" INNER JOIN "PURCHASES" ON "PURCHASEITEMS"."PURCHASEID" = "PURCHASES"."PURCHASEID" WHERE "PURCHASES"."SESSIONID" = ${SESSIONID} ORDER BY "PURCHASES"."PURCHASEID" ASC
[213]
Adding Sub-Reports and Cross Tabs to Reports
This query selects details for the current SESSIONID, and is used by this and subsequent sub-report examples. Now, you must customize the parameters that are available to the sub-report. You can do this by bringing up the sub-report parameters dialog. Right-click on the sub-report's Parameters tree item under the Data tab and select the Edit Sub-report Parameters... menu item. The following dialog will appear: L
xj
Sub-report Parameters
Import Parameters
Export Parameters
0 Outer Name SESSIONID
Q
0
Inner Name SESSIONID
Outer N a m e
I
Q
Inner N a m e
OK
Cancel
This example limits the visible fields to the SESSIONID. Click the add import parameter button, and edit the table row by typing SESSIONID for both the Outer Name and Inner Name, as displayed above. The Outer Name defines the name of the field within the master report, and the Inner Name defines the name as seen by the sub-report. In addition to importing parameters into a sub-report, sub-reports may make parameters available by exporting them to the master report. You're now ready to style the sub-report. In this sub-report, you'll show the individual sales details with summaries about each sale. To begin, add a label element, sub-Report Page Header, to the sub-report's Page Header. Also, add a label, Sub-Report Page Footer, to the Page Footer. Second, populate the Details band of the sub-report. Drag-and-drop the field for the ITEMNAME, as well as for the SALEPRICE and QUANTITY. Also, add an Open Formula function that multiplies SALEPRICE by QUANTITY, and call this ITEMPRICE. =[SALEPRICE]*[QUANTITY]
Add ITEMPRICE to the Details band by dragging and dropping the function into the canvas. To complete the details band, you'll want to band the detail rows with different colors. Select the Details band in the structure tree and name it details. Now, create a Row Banding Function, which appears in the Report functions group of functions. Set the Apply Element(s) Named property to details, along with setting the Active Banding Color and Inactive Banding Color properties to alternating shades of white and green. The design view of the sub-report Details band should look like this: [214]
Chapter 7 Details
IT EM N A M E
SALEPRICE
QUANTITY
ITEMPRICE
Now, add some summary information to the sub-report. Right-click on the Groups tree and edit the root group, naming it purchaseid and adding the group field PURCHASEID. Unselect the hide-on-canvas attribute for the Group Header and Group Footer bands. Drag-and-drop the PURCHASEID and PURCHASETIME fields into the Group Header, along with adding a rectangle background to distinguish this from other parts of the report. Also, add header columns for the Details band. Purchase Time: PURCHASETIME
Purchase ID: PURCHASEID Group Header Item M a n e
Sale Price
Quantity
Steffi P n c e
Create a Sum function called TotalSale, which sums the ITEMPRICE formula defined earlier. Set the Group Name property to purchaseid, which is the name of the group defined earlier. Drag-and-drop the TotalSale function into the far right of the report's Group Footer, along with some additional color, in order for the report to look nice. Total Soie: TotalSale
Group Footer
You're now ready to preview the report to see how the sub-report looks when combined with the master report. Notice that when you preview the sub-report, it also renders the master report. Also notice that when the sub-report renders, the master report's Page Header and Page Footer appear alongside the sub-report's Page Header and Page Footer. Experiment by unselecting the sticky style attribute on the Page Header and Page Footer of the master report, and preview to see that the header and footer do not appear. Save the report as chapter8/data/subreport_multipage . prpt. The sub-report definition is stored as part of the report bundle, so no additional files are necessary for storage. To complete this example, copy the chapter2/src/Chapter2SwingApp. java file into the chapter8/src folder and rename the class to MultipageSubreportApp. j ava, creating a simple Java application to demonstrate the sub-report. Update the Java application to reference your new report. Resource res = manager.createDirectly( new URL("file:data/subreport_multipage.prpt"), [215]
MasterReport.class);
Adding Sub-Reports and Cross Tabs to Reports
Now that you've updated the report definition, you're ready to run the example application. Add the following Ant target to your build. xml file:
Type ant runmultipagesubreport to preview the report, which should look something like this: Master Report Page Header Session ID: 1 Employee ID: 1 Purchase
ID: L
Time: Tue May 27 10:05:40 EDT 200S
Purchase
Item N a m e
Sale Price
Quantity
G r e e n Electronics. M P 3 Audio M i n i Player
75.99
1
75.99
Total Sale: Purchase
ID: 2
Item Price
75.93
Time: Tue May 27 10:26:21 EDT 200S
Purchase
Item N a m e
Sale Price
Quantity
Speedy Fly R C U A V Airplane
149.59
1
149.99
12 A A B a t t e r y P a c k
6.99
2
13.98
Total Sale: Purchase
ID: 3
Sale Price
T r i e d and T r u e P o r t a b l e C D Pia ver
24
99
Quantity 1
4
Purchase
Sale Price
Quantity
T r i e d and T r u e R a d i o A l a r m C l o c k
14.99
1
Purchase
Sale Price
Quantity
E l e c t r o RC C a r R a c e r
59.95
1
6
Purchase
Sale Price
Quantity
T r i e d and T r u e R a d i o A l a r m C l o c k
14.99
1
[216]
Item Price 14.99
Total Sale:
Master Report Page Footer
59.95
Time: Tue May 27 11:43:20 EDT 200S
Item N a m e
Sub-Report Page Footer
Item Price 59.95
Total Sale: ID:
14.99
Time: Tue May 27 11:27:44 EDT 200S
Item N a m e
Purchase
Item Price 14.99
Total Sale: ID: 5
24.99
Time: Tue May 27 11:15:17 EDT 200S
Item N a m e
Purchase
Item Price 24.99
Total Sale: ID:
163,97
Time: Tue May 27 10:53:46 EDT 200S
Purchase
Item N a m e
Purchase
Item Price
14.99
Chapter 7
Chart sub-report example In addition to embedding traditional reports into a master report, sub-reports are also useful for embedding summary or detailed information not available in the initial data source query of a master report. In this example, you'll reuse your previously defined master report, and instead of showing a multi-page sub-report, you'll display a pie chart summarizing the information. Open the already defined subreport_multipage. prpt file. Delete the already defined sub-report element and place a new Inline sub-report element in its place. Double-click on the sub-report element to launch the sub-report view. Define a new data source query for the sub-report by re-using the sub-report query defined earlier. Make sure to define SESSIONID as a sub-report input parameter. Now that you've defined the sub-report query, place a chart element in the report header of the sub-report. Select the Pie chart type. Edit the chart element by setting the value-column property to QUANTITY and the series-by-field property to PURCHASEID.
ÎÎ
.ii g
H li
Name name data-source ignore-nulls ignore-zeros no-data-message chart-title chart-title-field [title-font l-DMffiffl
slice-colors
•
S
mm
1
Primary DataSource
Ii
Value Chart Function 1 Data Collector 0 True True CHART.USER NO DATA .
SansSerif BOLD-14
[XY
f Secondary DataSource |
Pie DataSet Collector
name value-column
Data Collector 0 QUANTITY
se ries-by-field
[PURCHASEID]
group-by res et-g roup dependencyLevel
Save this report as Chapters/data/subreport_chart. prpt. Note that the sub-report information is stored as part of the PRPT bundle. Copy the MultipageSubreportApp. j ava file to a new class in chapters /src called chartsubreportApp. j ava. In the class, reference your new chart report. Resource res = manager.createDirectly( new URL("file:data/subreport_chart.prpt")/
[217]
MasterReport.class);
Adding Sub-Reports and Cross Tabs to Reports N o w , a d d the following A n t target to the build. xml file:
classname="Char
T y p e ant runchart subreport to view the results, w h i c h should look similar to this:
Master Report Pago Header Session ID: 1 Employee ID: 1
Session ID: 2 Employee ID: -
Master Report Page Footer
[218]
Chapter 7
Side-by-side sub-report example Another capability of sub-reports is to be able to place two or more sub-reports horizontally, beside one another, within a report band. The example below demonstrates this functionality by taking the charting example defined previously, and adding a summary table next to the pie chart for each session. Open up the subreport_chart. prpt, and add a sub-report element next to the chart sub-report:
Session ID: SESSIONID Employee ID: EMPLOYEEID
Details r-,
Sub-Re j ort
Sub-Report
Double-click on the new sub-report to begin editing. You'll use the same data source query as the chart for this sub-report, so define a new JDBC query with the copied SQL. You will also need to define SESSIONID as an input parameter to the sub-report. In this sub-report, you'll want to define a simple summary of each purchase. As in the first sub-report example, define a group with PURCHASEID as its field. Make the group's header visible in the report. Also, define the ITEMPRICE and TotalSale functions as defined in the first example. Drag-and-drop the PURCHASEID and PURCHASETIME fields, along with the TotalSale function, into the Group Header. In the Report Header, add the column headers. Finally, add a rectangle to the group header named GroupBackground, and add the following visible style formula to toggle the rectangle's visibility: =IF( ISODD(
[PURCHASEID] ); TRUE(); FALSE() )
Toggling the colors acts as a row banding mechanism. The row banding function used earlier works only on the Details band, hence the special formula expression. The report design should look something like this: Group Header
P u r c l i a s e PU
T i m e : PU RC H AS E T I M E
Total: T o t a l s ..
Preview the master report to see side-by-side sub-reports in action. Now, save this report as chapters/data/subreport_sidebyside . prpt. Copy the MultipageSubreportApp . java e x a m p l e class to chapter8/src/
sideBysideSubReportApp. java. Update the class with the new report filename. [219]
Adding Sub-Reports and Cross Tabs to Reports Resource res = manager.createDirectly( new URL("file:data/subreport_sidebyside.prpt"),
MasterReport.class);
A d d the following A n t target to y o u r build. xml file: T y p e ant runsidebysidesubreport to v i e w the results Employee ID: 1 Purchase: 1
Tiras: May 27 10:05:40 AM
Total $75.99
Purchase: 2
Tiras: May 27 10:26:21 A_M
Total $153.97
Purchase: 3
Tiras: May 27 10:53:45 A i l
Total $24.99
Purchase: 4
Tiras: May 27 11:15:17 A l i
Total S 14.99
Purchase: :
Tiras: May 27 11:27:44 A i l
Total $59.95
Purchase: 6
Tiras: May 27 11:43:20 A i l
Total S 14.99
Purchase: 7
Tiras: May 27 11:47:35 A i l
Total S 14.99
Purchase: S
Tirai: May 27 1 1:51:57 A i l
Total S259.S9
Purchase: 9
Tirai: May 27 12:01:20 PM
Total $95.94
Purchase: 10
Tiras: May 27 12:13:55 PM
Total S 14.99
Purchase: 11
Tiras: May 27 12:18:27 PM
Total S 105.94
Purchase: 12
Tiras: May 27 12:32:15 PM
Total $34.95
Purchase: 13
Tiras: May 27 12:59:45 PM
Total $15.45
Purchase: 14
Tiras: May 27 01:14:56 PM
Total $29.95
Session ID: 2 Employee ID: 2 Purchase: 15
Tiras: May 27 01:49:31 PM
Total S34.+2
Purchase: 15
Tiras: May 27 02:42:55 PM
Total S495.99
Purchase: 17
Tiras: May 27 02:51:14PM
Total S59.95
Purchase: IS
Tiras: May 27 03:52:48 PM
Total $71.97
Purchase: 19
Tiras: May 27 03:59:34 PM
Total $349.95
Purchase: 20
Tiras: May 27 04:07:54 PM
Total $19.95
Purchase: 21
Tiras: May 27 04:21:42 PM
Total $99.95
Purchase: 22
Tiras: May 27 04:40:42 PM
Total $29.95
Purchase: 23
Tiras: May 27 05:56:44 PM
Total $59.95
Master Report Page Footer
[220]
Chapter 7
Adding cross tabs Cross tabs allow you to view dimensional data in a report. Using cross tabs, you can easily view two or more fields and how they relate based on a measure. For instance, you may want to see how much sales each sales person is doing during the course of a week, and a cross tab allows you to present that data easily, as shown in the following table: Sales Person 1
Sales Person 2
Dayl
$1,240
$1,100
Day 2
$1,400
$1,000
Pentaho Reporting offers the ability to create cross tab-based reports. These are a special type of report that render differently than most standard reports. These reports also expect the data to be in a particular format. Traditionally, cross tab reports are driven by multidimensional queries. As highlighted in Chapter 5, Pentaho Reporting offers a Mondrian and olap4j DataFactory for providing multidimensional data to a report. Use the DenormalizedMDXDataFactory to populate a cross tab report. This Data Factory flattens out an MDX result set. The following MDX query: select [Employee].Members on rows, [Time].[All Times].Children on columns from [Sales] where [Measures].[Total Sales]
would result in the dataset as shown in the following table: Employee (All) All Employees All Employees
Employee Name
Time (All)
Time Sale Day
Total Sales
-
All Times
Dayl
$2,340
-
All Times
Day 2
$2,400
All Employees
Sales Person 1
All Times
Dayl
$1,240
All Employees
Sales Person 1
All Times
Day 2
$1,400
All Employees
Sales Person 2
All Times
Dayl
$1,100
All Employees
Sales person 2
All Times
Day 2
$1,000
Note that the first two rows are the summation of all the employee sales for the first two days. [221]
Adding Sub-Reports and Cross Tabs to Reports
Pentaho Reporting uses this dataset to populate a cross tab. First, you would define the measure in the Details band of the cross tab. You would then define the Employee dimension as the cross tab column group. Finally, you would define the Time dimension as the cross tab row group. In MDX, it is possible to select multiple dimensions on the same axis. For each dimension defined on an axis, you may add an additional cross tab row or cross tab column group. It is also possible to generate the same type of result set with standard SQL. Here is the same data selected as SQL instead of MDX: SELECT 'All Employees' AS ALLEMPLOYEES, "SALES_FACT"."EMPLOYEE" , "SALE S_FACT"."SALEDAY", SUM("SALES_FACT"."SALEPRICE") AS TOTAL_SALES FROM "SALES_FACT" GROUP BY "SALE S_FACT"."EMPLOYEE", "SALE S_FACT"."SALEDAY" ORDER BY "SALES_FACT"."EMPLOYEE" ASC, "SALE S_FACT"."SALEDAY" AS C
Note that this query doesn't sum the values at the All Employees level. Grouping sets, an advanced SQL concept, would need to be used to make that possible. Cross tabs may contain multiple rows and columns. For instance, if you placed both the Employee and Time dimensions in the row group of your cross tab, the results would look identical to the flattened result set displayed above.
Cross tab MDX example For this example, you'll need a simple Mondrian cube to work with. First define a quick fact table in HSQLDB, along with defining a Mondrian schema that maps to the table. You'll use the example above as the fact table. Add the following DDL to the electrobarn. script file, which is located in the chapters/data folder: CREATE TEXT TABLE SALES_FACT (EMPLOYEE VARCHAR,SALEDAY VARCHAR,SALETIME VARCHAR, SALEPRICE DOUBLE) SET TABLE INVENTORY SOURCE "salesfact.csv;ignore_first=true"
[222]
Chapter 7
The salesfact. csv file, along with the electrobarn. script file,
are provided as part of this book, or you can also download them online at: http://www.packtpub.com/files/code/3193_Code.zip
You also need to define the Mondrian Schema. Save the following Mondrian Schema X M L in your chapters/data folder as electrobarn. mondrian. xml:
«Dimension name="Employee"> «Hierarchy hasAll="true"> «Dimension name="Time"> «Hierarchy hasAll="true"> «Measure name="Total Sales" column="SALEPRICE" aggregator="sum"/>
This schema defines the Cube, Dimensions, and Measure discussed earlier. Now, it's time to build the report in Pentaho Report Designer. To begin, you'll define a Denormalized MDX data source, based on the Sales cube as defined above. Click the Data tab, right-click on the Data Sets tree item and select OLAP | Mondrian (Denormalized). Select the predefined ElectroBarn HSQLDB Data Source. Edit this data source to point to chapterS/data/electrobarn, which contains the recently added SALES_FACT table. Now, select the recently saved electrobarn. mondrian.
xml as the Mondrian Schema File. Define the following MDX Query as part of your Mondrian data set: select [Employee].Members on rows, [Time].[All Times].Children on columns from [Sales] where [Measures] . [Total Sales]
This query selects all values from the Employee dimension on rows, and all the members of the first level of the Time dimension on columns. Once the MDX data source is defined, you're ready to build the cross tab report.
[223]
Adding Sub-Reports and Cross Tabs to Reports
Cross tabs are still considered experimental in the Pentaho Report Designer, so to enable cross tab capabilities, you must enter the shortcut key CTRL-ALT-O. This adds a new Add Crosstab Group menu option to the Master Report tree element. To begin, right-click on the Master Report tree element and select Add Crosstab Group. This replaces the traditional group hierarchy in the tree with a cross tab group hierarchy, and also changes the canvas view as shown below: Master Report H
Page Header
•
Report Header crosstab
Now, you're ready to add the Session ID select input. Place a label at the top of the Report Header, in the space left available. Set the label text to select a Session:. Update the label's append-body-footer property to the following HTML and JavaScript: // this function removes cells and rows from // the generated HTML report for dynamic rendering function removeNodes(node) { if (node) { var next = node.nextSibling; node.parentNode.removeChild(node); removeNodes(next) ; [247]
Building Interactive Reports
// this function is triggered when a change occurs in the // selection list function filterChanged() { var select = $('selection'); var currentValue = select.options[select.selectedlndex].text; // remove cells to allow room for dynamic iframe reports var summary = $('summary'); removeNodes(summary.nextSibling); removeNodes(summary.parentNode.nextSibling); summary.colSpan = "7"; summary.className= ""; // update the chart component with the correct filter $('chart').innerHTML = ""; // update the pdf link with the correct filter summary.innerHTML = ""; var pdfLink = document.getElementByld('pdfLink'); pdfLink.sessionld.value = currentValue; }
This JavaScript references the HTML document object model locations of the sub-reports. In order for this to be successful, you need to specify the xml- id attribute for b o t h the sub-reports as chart a n d summary.
[248]
Chapter 11
The above JavaScript first removes cells from the HTML document, and then places two IFRAME elements within the HTML DOM. Pentaho Reporting renders a single HTML table as output, so sub-reports don't get wrapped by a single HTML parent element. The IFRAME elements must be used instead of direct HTML placements. This is to make sure that CSS styles, and relative directory paths of images within sub-reports, are both accessible. Add a label with a single space to the right side of the report. You'll add a View As PDF button at this location. Edit the append-body attribute of the empty label with the following HTML and JavaScript:
To demonstrate some of the event callback methods, specify the following JavaScript within the on-click attribute of the chart sub-report element, within the master report: alert ("You've clicked on the Chart");
Also, specify the following JavaScript within the on-double-click attribute of the chart sub-report element, within the master report: alert("You've double clicked on the chart");
The final master report should look like this in design mode within Report Designer: Select a S e s s i o n :
I
Session ID: SESSIONID
Report Header
s S u b - R e p ort
S u b - R e p ort
1
You're now ready to save the changes and deploy them to the server. Note that there are no changes necessary on the server side to enable this interactive report. In your command prompt, type ant war to build the web archive, and ant start_tomcat to restart the server.
[249]
Building Interactive Reports
When running the interactive report, your browser should show a selection list, as well as a View As PDF button: Select a Session:
ra
View As PDF
Session ID:1 Purchase: 1
Time: May 27 10:05:40 A M
Total:
$75.99
Purchase: 2
Time: May 27 10:26:21AM
Total:
SIS 3.97
Purchase: 3
Time: May 27 10:53:46 A M
Total:
524.99
Purchase: 4
Time: May 27 11:15:17 A M
Total:
514.99
Purchase: ;
Iiuie: May 27 11:27:44 A M
Total:
$59.95
Purchase: S
Time: May 27 1 1 : 4 3 2 0 A M
Total:
514.99
Purchase:
Time: May 27 11:47J 5 A M
Total:
514.99
Purchase: S
Time: May 27 11:51:57 A M
Total:
5269. S9
Purchase: 9
Iiuie: May 27 12:0120 PM
Total:
595.94
Purchase: 10
Time: May 27 12:13:55 PM
Total;
514.99
Purchase: 11
Iiuie: May 27 12:1S27PM
Total:
5106.94
Purchase: 12
Time: May 27 12:32:15 PM
Total:
534 95
Purchase: 13
Time: May 27 12:59:49 FM
Total:
516.46
Purchase: 14
Time: May 27 01:14:56 PM
Total:
529.95
Select another Session ID, and notice how the chart and summary sub-reports are dynamically updated. Finally, click the View as PDF button. Notice that the append-body attributes defined earlier do not render within the PDF document.
Summary In this chapter, you learned how to build interactive reports using Swing and HTML as outputs. You learned how to modify report definitions to generate hyperlink events, swing action events, and many different HTML JavaScript events. You built from the ground up a Swing demonstration that selectively shows details of sales sessions from the ElectroBarn data source, along with demonstrating feedback via the ReportMouseListenter API.
You also learned how to render an HTML report on a server, along with including external script files within the HTML rendered report. You learned how to modify the report HTML document object model dynamically when events are triggered from the report. You also learned to view an HTML report as a dashboard, finally allowing the HTML report to be rendered as PDF.
[250]
10
API-based Report Generation In this chapter, you'll learn about Pentaho Reporting's . prpt bundle file format, along with the details of Pentaho Reporting's Java API. You'll be introduced to the schemas of the various XML files that persist the data source, parameters, expressions, layout, and style of a report. With examples of Pentaho's Java API, you'll learn how easy it is to build a report programmatically. You'll walk through a complete example that demonstrates creating different reporting bands, as well as different elements within a report. Finally, you'll be introduced to the Pentaho Wizard Java API.
Understanding the serialized report format Pentaho Reports are saved as . prpt bundle files. This is a ZIP-based file format that includes all the necessary resources to render a report, also referred to as a bundle. The . prpt bundle file contains a set of XML files that are crucial to rendering a report, as well as additional resources such as embedded images and sub-reports. This format is based on the OpenDocument format. This section goes into detail about each of the primary files that make up a report, along with providing a simple example of a report written by hand. With the knowledge of the underlying file format, it is possible to generate reports outside of the Java environment. The key files that make up a report include settings . xml datadef inition. xml, along with individual data source files, layout. xml and styles. xml.
API-based Report Generation
settings.xml The settings . xml file contains global configuration properties for a report, as well as a placeholder for future runtime information. «property name="org.pentaho.reporting.engine.classic.core. function.LogFormulaFailureCause">true «runtime/> One example of a configuration setting is related to the execution of formula expressions. If you set the property org. pentaho. reporting. engine . classic . core. function. LogFormulaFailureCause to true, and you have your Log4J logging set to debug, you'll receive a stack trace, in addition to an error message, when the formula fails. Additional configuration properties are available, primarily for use in design tools such as Pentaho Report Designer. Rarely would you need to define a configuration property while generating a report.
datadefinition.xml and the datasources folder The datadef inition. xml file contains information about report input parameters, the report data source, as well as report functions and expressions. The root element in this X M L file is data-definition, and uses the http: / /reporting. pentaho. org/ namespace s/engine/classic/bundle/data/1. 0 namespace for X M L validation.
Parameters Parameters are defined as children to the data-definition/parameter-definition element. There are two types of parameters—plain parameters and list parameters. Plain parameters are represented in XML as a plain-parameter element. Plain parameters define four attributes:
[252]
Chapter 11 XML attribute
Description
name
The parameter name
mandatory
If set to true, a value for this parameter is required before the report is rendered
type default-value
The fully qualified lava type of the parameter The default value of the parameter
List parameters are represented in XML as a list-parameter element. In addition to sharing the same attributes as the plain parameter, list parameters also define the following attributes: XML attribute
Description
query
The query name providing the list of values to choose from.
key-column
The key column is returned as the result within a row that was selected.
value-column
The value column is displayed as the selection when presenting data to the user. The value- formula attribute may be used in place of the value - column.
value-formula
The value formula is displayed as the selection when presenting data to the user. The value- column attribute may be used in place of the value - formula.
strict-values
If set to true, validation is done on the parameter value to determine if it is part of the query results.
allow-multi-selection
If set to true, this attribute allows multiple selections of parameter values from the query results, creating an array of objects versus a single object.
Sub-reports define a different XML element hierarchy for their parameters. In the context of a sub-report, a parameter is passed in from the master report's context versus user or system input. Instead of using the parameter-definition element as a parent, sub-reports use a parameter-mapping element. Two sub-report parameter types are defined—import and export. Their XML element tags are import-parameter and export-parameter. They both define the following two attributes:
[253]
API-based Report Generation XML Attribute
Description
name
The name of the parameter. For imported parameters, this is the name within the master report. For exported parameters, this is the name within the sub-report.
alias
The alias of the parameter. For imported parameters, this is the name within the sub-report. For exported parameters, this is the name within the master report.
Data source reference A single reference to the report's data source is specified in the datadef inition. xml file, as a data-definition/data- source XML element. If multiple data sources are used in a single report, you must use a compound data source that combines different data sources. The data-source XML element defines the following attributes: XML attribute
Description
report-query
The named query used by the master report.
limit
If specified, defines the limit to number of rows returned by the primary query of the report.
timeout
If specified, defines the query timeout for the primary query of the report.
ref
A reference to the specified data source definition file.
Functions and expressions Every function and expression defined in a report is represented by an expression XML element. Expression elements have the following five attributes: XML attribute
Description
name
The name of the function or expression.
class
The class type of the function or expression. This is not required if specifying a formula.
deplevel
The dependency level of the function or expression, which determines the order of execution.
formula
If specified, defines a formula for execution.
initial
If specified, defines a formula for initial execution.
Expressions may also contain properties. These properties appear within a properties XML element as child property elements. Each property XML element contains the following attributes: [254]
Chapter 11 XML attribute
Description
name
The name of the property.
class
The class type of the property.
Finally, each property X M L e l e m e n t contains a text n o d e w i t h the value of the property. T h e following is a n e x a m p l e of a datadef inition. xml file that contains p a r a m e t e r s a n d a data source, as w e l l as a n expression: «expression name="SizeKilobytes" formula="=[Size] / 1024"/>
Data sources folder For each data source defined in a report, a data source file is created with the necessary information to connect to the data source, usually stored in the datasources folder within the . prpt bundle file. Defining every data source file is out of the scope of this chapter. The following example X M L is of an inline table data source: libloader [255]
API-based Report Generation 114287 libformula 331839 As mentioned earlier, a compound data source is often used to refer to multiple data sources in a single report. Here is an example of a compound data source definition: For each data source type, there is an equivalent XML format. These formats are documented within their XML schema files, which are accessible when downloading the source distribution of the reporting engine and extensions.
layout.xml The layout. xml file defines the primary structure of report bands and elements. Each band is represented as an XML element, and each band's elements are contained within the band. Multiple XML namespaces are used within the context of the layout XML document. The primary namespaces include: •
core, which defines core elements and attributes
•
layout, which defines the majority of the elements in this document
•
styles, which define inline styles
The styles namespace will be discussed in more detail in the styles.xml section that will follow. The core namespace document is located at http: //reporting. pentaho . org/namespaces/engine/attributes/core The layout namespace, which is specified as the default namespace for this document, is located at http: // reporting.pentaho.org/namespaces/engine/classic/bundle/layout/1.0 The layout X M L document contains a root layout X M L element. This element contains root level band information. The layout element may contain attributes defining report level metadata such as the title of the report. The following child X M L elements may be specified within the layout element:
[256]
Chapter 11 XML element
Description
preprocessor
Any number of preprocessor elements may be defined within the report layout element. Preprocessors contain a class attribute that specifies the fully qualified preprocessor Java class, and may contain property elements for the preprocessor. Preprocessors may manipulate a report before it is rendered. You'll see an example of a preprocessor in the Wizard Java API section of this chapter.
layout-processors
Certain functions that manipulate the layout of elements may appear within the layout-processors element of the layout document. For instance, the ItemHideFunction is considered a layout processor, so if defined, it will be serialized into this portion of the document.
report-header
The report-header element specifies the layout of the report header. This element contains a child element entitled root-level-content, which contains all references to child elements. Note that the report-header is a report element. Therefore, it may contain general element attributes and child elements, defined later in the Report elements section of this chapter.
group
The group element defines the entire hierarchy of groups and detail bands defined in a report. This element hierarchy is defined in more detail in the Group and detail band hierarchy section of this chapter.
report-footer
The report-footer element specifies the layout of the report footer. This element contains a child element entitled root-level-content, which contains all references to child elements. Note that the report-footer is a report element. Therefore, it may contain general element attributes and child elements, defined later in the Report elements section of this chapter.
Also note that the report itself is represented as a report element. Therefore, in addition to the attributes and child elements defined above, the report may also contain attributes and elements defined in report elements. (These are covered later in the Report elements section of this chapter.)
[257]
API-based Report Generation
Group and detail band hierarchy A group may contain either a group-body or data-body child XML element. A group-body contains the XML element group to represent a hierarchy of groupings. In addition to containing the group-body or data-body, a group XML element may also contain group-header and group-footer XML elements. The group-header and group-footer XML elements may contain a root-level-content XML element, which contains child layout elements. The data-body XML element contains the bands relevant to row level data in your report. This XML element may contain detail-header, details, no-data, and details-footer child XML elements. Each of these elements may contain a root-level-content XML element, which contains child layout elements.
Report elements Each report element defined in previous chapters is represented in XML, defining its properties, as well as where it is located within a band. The most common elements are highlighted here. All elements define the style : element- style child XML element, which contains styling information for the individual element. The most common style element is style : spatial- styles, which defines where in the band the element is located, as well as what size it should render as:
Here is a list of some of the primary report elements, along with specific details on creating them: XML element
Description
label
The label XML element renders a label. This element contains a core: value child element, which XML Text is used for the label value.
text-field
The text-field XML element renders a text field. This element contains acore:field attribute, which defines the field to render.
number-field
The number - field XML element renders a number field. This element contains a core: field attribute, which defines the field to render, as well as a core : format - string attribute, which defines the number format string to render. [258]
Chapter 11
XML element date-field
message
Description The date-field XML element renders a date field. This element contains acore:field attribute, which defines the field to render, as well as a core: f ormatstring attribute, which defines the date format string to render. The message XML element renders a message. This element contains a core rvalue child,
resource-label
The resource-label XML element renders a resource-label. This element contains a core : resource- identifier attribute referencing
resource-field
the message bundle, as well as a core: value attribute, which specifies the key to use in the bundle, The resource-field XML element renders a resource-field. This element contains a core : resource- identifier attribute referencing
resource-message
the message bundle, as well asacore:field attribute, which specifies the field that is used to determine the key to be resolved, The resource-message XML element renders a resource-message. This element contains a core : resource- identifier attribute referencing
rectangle
the message bundle, as well as a core: value attribute, which specifies the message, The rectangle XML element renders a rectangle. The size of the rectangle is determined by the style: spatial-sizes element defined above. A style : content-styles X M L element may
horizontal-line
be defined, which specifies attributes such as the boolean attributes draw-shape and fill-shape, as well as color attributes such as fill-color. Colors are represented in RGB hexadecimal notation, for instance #ff3333. The horizontal-line XML element renders a horizontal line. The length of the line is determined by the style: spatial-sizes XML element defined above. A style : content-styles XML element is defined to specify line style and color.
[259]
API-based Report Generation
XML element vertical-line
sub-report
content
content-field
Description The vertical-line XML element renders a vertical line. The length of the line is determined by the style: spatial-sizes XML element defined above. A style: content-styles XML element is defined to specify line style and color. A sub-report XML element renders a sub-report. The attribute href specifies where the sub-report is located within the .prpt bundle. This XML element may also contain information about its location and style via the style : element-style child XML element, as well as input and output parameter mappings via input-parameter and output-parameter XML elements. These mappings are configured with the master-fieldname and detail-fieldname attributes. A content XML element renders an image. The location of the image binary is determined by the core rvalue XML element. The scale and aspect ratio properties for a content element may be customized by specifying a style: content-styles element with the attributes scale and keep-aspect-ratio. A content-field XML element renders a dynamic image based on a field. The location of the dynamic content to render is determined by the core: field XML element. The scale and aspect ratio properties for a content-field element may be customized by specifying a style : content-styles element, with the attributes scale and keep-aspect-ratio.
Additional report element types are defined within Pentaho Reporting. Those listed in the table are the most common elements, along with some of their primary properties and styles.
[260]
Chapter 11
Example layout.xml file The following is a very simple layout. xml file, which renders a report header label, as well as a details band text field: Library Information«/core:value> < t e x t - f i e l d core:field="SizeKilobytes"> [261]
API-based Report Generation
styles.xml The styles. xml file defines what page format the report should be rendered as, style rules that dictate how a report should be rendered, global layout processors, a report watermark, and finally the page header and footer sections of a report. The styles. xml file contains the style root XML element, and includes namespaces relevant to rendering styles, including the core and layout namespaces defined earlier, as well as the style namespace as the default namespace, which is located at http://reporting.pentaho.org/namespaces/engine/classic/bundle/
style/i. o . The following child elements may be specified within the style
XML element: XML element
Description
page-definition
The page - definition XML element contains attributes defining the report's page properties. The attribute pagef ormat specifies the page format type. Examples include "LETTER" and "LEGAL". The attributes horizontal-span and vertical-span define how many pages a report should span across. The width and height attributes define the width and height of the paper. The orientation attribute defines whether the page should be laid out as portrait, landscape, or reverse-landscape. The attributes margin-top, margin-left, margin-bottom, and margin- right define the margin values for the report.
style-rule
Multiple style-rules may be defined in the report. A style rule has a name and parent attribute, which define the inheritance tree of a group of styles. Within the style-rule, style elements such as text - styles and spatial - styles are defined, which contain specific styling information.
[262]
Chapter 11 XML element
Description
layout : layoutprocessors
Certain functions that manipulate the layout of the entire report may appear in the layout-processors section of the styles document.
layout : ¡watermark
The watermark X M L element is rendered in the background, behind other bands in a report. This element contains a child element entitled rootlevel- content, which contains all references to child elements. Note that the watermark is a report element, so it may contain general element attributes and child elements, defined earlier.
layout : page-header
The page-header X M L element defines the contents of the header for each page. This element contains a child element entitled root - level-content, which contains all references to child elements. Note that the page-header is a report element, so it may contain general element attributes and child elements, defined earlier.
layout : page-footer
The page-footer X M L element defines the contents of the header for each page. This element contains a child element entitled root- level - content, which contains all references to child elements. Note that the page- footer is a report element, so it may contain general element attributes and child elements, defined earlier.
Example styles.xml file Here is a simple styles. xml file that contains a page definition, as w e l l as a label in the p a g e footer:
[263]
API-based Report Generation «element-style> Page Footer Label
Additional required files Additional files are required to complete the . prpt b u n d l e file, b u t are less central to the rendering of the report. This includes the META- INF/manif est. xml, content. xml, dataschema . xml, meta . xml, a n d the mimetype files. T h e META- INF/manif est. xml file contains a listing of all the files in the . prpt b u n d l e file, as w e l l as their content types: T h e content. xml file is intentionally left e m p t y , a n d m a y b e u s e d in future for global templates:
[264]
Chapter 11
The dataschema. xml file may contain additional metadata used to increase the richness of a data source. Normally, this document is empty.
The meta. xml file is part of the OpenDocument standard, and contains information about the . prpt bundle file, including the creation date: Sat Feb 07 20:23:03 EST 2009 Pentaho Reporting Classic«/meta:initialcreator> Pentaho Reporting Classic Sun Feb 08 16:49:16 EST 2009
The mimetype file is a simple text file that contains the mime type of the . prpt bundle file. application/vnd.pentaho.reporting.classic
Building and running a .prpt bundle example file Now that you've learned about all the different files that make up a . prpt bundle file, combine them to create a single report. First, create a folder and place all the examples above in their appropriate file names. This should include the primary files, settings, xml and datadef inition. xml, along with the datasources folder, datasources/inline-ds . xml, layout. xml, and styles . xml. Also, include the
additional required files and folders, the META- INF folder, along with the META- INF/ manifest. xml, content. xml, dataschema . xml, meta . xml, and the mimetype files.
Once you've placed these files within the same folder structure, select all the files in Windows Explorer and right-click on them. Select Send To... Compressed (zipped) Folder..., and save the file as example_xml. prpt.
[265]
API-based Report Generation
If you are working in Linux or Mac, you may use the zip command line tool to create the . prpt file bundle. Go into the directory where the files were created, and type zip -r example_xml.prpt *.
Now, open the example_xml. prpt file in Pentaho Report Designer and click the preview button. You should see a report that looks like the following:
Library Information libloader
111.6083984375
libformula
324.0615234375
Building a report using Pentaho Reporting's Java API Now that you've built a report using Pentaho Reporting's XML format, it's time to learn how to do a similar exercise, by building a report using Pentaho Reporting's Java API. To avoid going over the entire Javadoc of Pentaho Reporting, this chapter covers only the essentials. This includes references to important packages, making it easier to find the classes, factories, and interfaces that you need to build your report. Pentaho Reporting's Javadoc is available at http: //j avadoc . pentaho. com/reporting/
The first step in working with Pentaho Reporting's API is to initialize the reporting engine and create an empty MasterReport object. // Initialize the reporting engine ClassicEngineBoot.getlnstance().start(); // Create a report object MasterReport report = new MasterReport();
The ClassicEngineBoot and MasterReport classes are located in the org.pentaho.reporting.engine.classic.core Java package. Once you've created a report object, you're ready to step through the various components that make up an entire report. The following sections demonstrate setting up a data source, adding parameters to a report, including a function, adding layout bands to the report, adding elements to a report, and customizing the report page definition.
[266]
Chapter 11
Adding a data source In Chapter 5, you created many different DataFactory classes and added them to your reports. Here is a simple example of a DataFactory definition, along with code to bind it to the report: // Define a simple TableModel DefaultTableModel data = new DefaultTableModel( new Object [] [] { {"libloader", 114287}, {"libformula", 331839}
}.
new String[] {"Name", "Size"} ); // create a TableDataFactory final TableDataFactory dataFactory = new TableDataFactory(); // Add the table model to the factory dataFactory.addTable("default", tableModel); // Add the factory to the report report.setDataFactory(dataFactory);
When starting from scratch, you must also tell the report which named data source to use. You can do this by calling the following method: // set the main query to default for this report report.setQuery("default");
The default string is the name of the data source. Additional methods on the report object that relate to data source configuration include setQueryLimit ( int queryLimit) and setQueryTimeout ( int queryTimeout), which allow y o u to
specify the limit of rows returned in the result set, as well as the maximum length of time a result set has to execute before the report engine ends the query.
Defining parameters By defining parameter types and validation information about parameters, the reporting engine can validate incoming parameters. This information is also available to the system executing the report, allowing for user prompting. Parameters are managed using the ReportParameterDef inition API. This API is defined in the package org.pentaho.reporting.engine.classic.core.parameters, along with
all the other classes and interfaces discussed in this section.
[267]
API-based Report Generation
The ReportParameterDefinition API defines individual parameter
definitions, as well as the ReportParameterValidator class, which verify that the entries are valid. The following example demonstrates the use of Pentaho Reporting's default implementation, the DefaultParameterDef inition class. Individual parameters use the ParameterDef initionEntry API. Available implementations of entries include PlainParameter, DefaultListParameter and
DefaultFormulaListParameter. The following code demonstrates configuring a PlainParameter called Library Size: // Define a plain parameter PlainParameter entry = new PlainParameter("Library Size", Integer, class); // Make the parameter Mandatory entry.setMandatory(true); // Add the parameter to our parameter definition paramDef.addParameterDefinition(entry);
Including functions and expressions To add a function or expression to a Pentaho Report, simply create the function or expression instance a n d call report. addExpression (Expression expression).
All expressions that get added to a report must implement the Expression interface. All functions added to a report must implement the Function interface, which extends the Expression interface. Most functions discussed earlier in this book, along with the Expression and Function interfaces, are defined within the package org.pentaho.reporting.engine.classic.core.function or a sub-
package. Expression implementations use the JavaBean standard getters and setters for configuring their properties. The following code demonstrates creating a FormulaExpression instance and adding it to a report: // create a formula expression FormulaExpression formula = new FormulaExpression(); // configure the formulas properties formula.setName("SizeKilobytes"); formula.setFormula("=[Size] / 1024"); // add the expression to the report report.addExpression(formula);
[268]
Chapter 11
Defining the report's layout Similar to the layout. xml document described earlier in this chapter, defining the JavaBeans that make up the report layout include the common report bands such as the report header and footer, as well as the group band hierarchy that also includes the details band.
Common report bands For each band defined in a report such as report header, report footer, page header, and page footer, there are equivalent Java classes that are available, all extending from the common abstract class Band, located in the org. pentaho. reporting. engine. classic. core package. These bands are all located in the same package. Each band defines a set of JavaBean properties, but most simply use those defined in the Band abstract class. One of the primary methods defined in this class is addElement (Element element), which you'll use later when creating elements and adding them to their parent bands. A subset of Band implementations also implement the RootLevelBand interface, which allows the addition of sub-reports to the band via the addSubReport (SubReport subreport) method. Bands such as page header, page footer, and watermark do not allow rendering of sub-reports. Here is an example of setting the report header and report footer in a report: // Create report header and footer objects ReportHeader reportHeader = new ReportHeader(); ReportFooter reportFooter = new ReportFooter(); // add the report header and footer to the report report.setReportHeader(reportHeader); report.setReportFooter(reportFooter);
It can't get any easier than that!
Group band hierarchy Group bands also follow this simple JavaBean paradigm. Because it is possible to nest groups, the API is a little bit more advanced. The RelationalGroup class is used for regular relational groupings. The crosstabGroup is used for defining cross tabs within a report. The CrosstabGroup API is out of the scope of this chapter, but is well documented in Javadoc. The RelationalGroup class may contain a group header and group footer, as well as a GroupBody implementation. GroupBody is an abstract class that subGroupBody and GroupDataBody extend. The SubGroupBody allows for nested groups, and the GroupDataBody contains the itemBand, as well as three other less used bands, DetailHeader, DetailsFooter, and NoDataBand. [269]
API-based Report Generation
To configure a RelationalGroup class, you must provide a set of data row fields that define the grouping. This may be done via the addField (string field), setFields(List fields), orsetFieldsArray(String[]
fieldsArray) method
calls. In this example, you'll define a RelationalGroup and itemBand, and group by the Name field. Note that the itemBand class represents a details band in a report: // Create the root relational group RelationalGroup group = new RelationalGroup(); // Use "Name" as the root grouping group.addField("Name"); // Create a group data body GroupDataBody groupData = new GroupDataBody(); // Create an item band ItemBand itemBand = new ItemBand(); // place the item band within the group data body groupData.setltemBand(itemBand) ; // place the group data body within the root group group.setBody(groupData); // set the root group within the report report.setRootGroup(group);
Adding elements to the report Now that you've set up all the bands for your report, you're ready to start adding elements. Unlike the previous classes and interfaces introduced for bands, all elements share a single class implementation, Element, and are created by element factories. The Element class is located in the org. pentaho. reporting . engine .
classic. core package. The primary set of element factories are located in the org. pentaho.reporting.engine.classic.core.elementfactory package.
To use a factory, first instantiate the factory object, and then configure the JavaBean setters of the factory. Once you've built your element within the factory object, call createElement ( ) to retrieve the Element instance, which you will then add to your report.
[270]
Chapter 11 A s a demonstration of h o w to u s e a factory, the following c o d e instantiates a n Element u s i n g the LabelElementFactory class: // create a label element factory instance LabelElementFactory factory = new LabelElementFactory(); // configure the label's text factory.setText("Library Information"); // instantiate the label element Element label = factory.createElement(); In this example, y o u instantiated the factory, set a value for the label, a n d t h e n generated the label Element instance. Factories also expose style attributes as J a v a B e a n setters, so it's possible to configure the location, size, a n d font style of this element. // create a label element factory instance LabelElementFactory labelFactory = new LabelElementFactory(); // configure the label's text labelFactory.setText("Library Information"); // configure the label's location and size labelFactory.setX (If); labelFactory.setY(If); labelFactory.setMinimumWidth(lOOf); labelFactory.setMinimumHeight(201); // set the font to bold labelFactory.setBold(true) ; // instantiate the label element Element label = labelFactory.createElement(); N o w , a d d the label to your ReportHeader instance defined earlier: // add the label to the report header reportHeader.addElement(label); It is important to note that for the JavaBean properties not set, elements inherit their default values f r o m their parent band. For instance, y o u can specify the bold attribute on the ReportHeader instance, a n d all text elements will default to that value. // set the bold property to true, inherited by all // child text elements reportHeader.getStyle().setStyleProperty(TextStyleKeys.BOLD,
[271]
true);
API-based Report Generation
Java API example In this example, you'll take w h a t you've learned a n d incorporate it into a simple Java Application. You'll build f r o m the chapter2swingApp example. Create a n e w folder, chapterio, a l o n g w i t h a src a n d lib subdirectory. C o p y the jar files f r o m chapter2/lib into chapterlO/lib. Also, copy Chapter2SwingApp. java to chapter2/src/ChapterlOSwingApp. java. M a k e sure to r e n a m e the class to ChapterlOSwingApp. Finally, c o p y the build, xml file f r o m chapter2 to chapterio. Instead of h a v i n g chapteri oswingApp load a report file f r o m disk, create your own. Replace t h e / / load report definition section of the onPreview () m e t h o d w i t h the f o l l o w i n g Java source: // create a new report object MasterReport report = new MasterReport(); // add a table data source to the report DefaultTableModel tableModel = new DefaultTableModel( new Object [] [] { {"libloader", 114287}, {"libformula", 331839}
}.
new String[] {"Name", "Size"} ); final TableDataFactory dataFactory = new TableDataFactory(); dataFactory.addTable("default", tableModel); report.setDataFactory(dataFactory); // add a formula expression to the report FormulaExpression formula = new FormulaExpression(); formula.setName("SizeKilobytes"); formula.setFormula("=[Size] / 1024"); report.addExpression(formula) ; // add the report header and footer ReportHeader reportHeader = new ReportHeader(); ReportFooter reportFooter = new ReportFooter(); report.setReportHeader(reportHeader); report.setReportFooter(reportFooter) ; // add the item band, with a shortcut that // handles creating the default group ItemBand itemBand = new ItemBand(); report.setltemBand(itemBand); // create a label and add it to the header
[272]
Chapter 11 LabelElementFactory labelFactory = new LabelElementFactory(); labelFactory.setText("Library Information"); labelFactory.setX(If); labelFactory.setY(If); labelFactory.setMinimumWidth(lOOf) ; labelFactory.setMinimumHeight(201) ; labelFactory.setBold(true) ; Element label = labelFactory.createElement(); reportHeader.addElement(label) ; // Add a text field for the library name, added to // the item band TextFieldElementFactory textFactory = new TextFieldElementFactory(); textFactory.setFieldname("Name"); textFactory.setX(If) ; textFactory.setY(If) ; textFactory.setMinimumWidth(lOOf) ; textFactory.setMinimumHeight(201); Element nameField = textFactory.createElement(); itemBand.addElement(nameField); // Add a number field for the library size, added to // the item band NumberFieldElementFactory numberFactory = new NumberFieldElementFactory(); numberFactory.setFieldname("SizeKilobytes"); numberFactory.setX(lOlf) ; numberFactory.setY(If) ; numberFactory.setMinimumWidth(lOOf); numberFactory.setMinimumHeight(201); Element sizeField = numberFactory.createElement(); itemBand.addElement(sizeField);
Make sure to include the necessary imports: import javax.swing.table.DefaultTableModel; import org.pentaho.reporting.engine.classic.core.Element; import org.pentaho.reporting.engine.classic.core.ItemBand; import org.pentaho.reporting.engine.classic.core.MasterReport; import org.pentaho.reporting.engine.classic.core.ReportFooter; import org.pentaho.reporting.engine.classic.core.ReportHeader; import org.pentaho.reporting.engine.classic.core.TableDataFactory; import org.pentaho.reporting.engine.classic.core.elementfactory. LabelElementFactory;
[273]
API-based Report Generation import org.pentaho.reporting.engine.classic.core.elementfactory. NumberFieldElementFactory; import org.pentaho.reporting.engine.classic.core.elementfactory. TextFieldElementFactory; import org.pentaho.reporting.engine.classic.core.function. FormulaExpre s s i on;
As the final step, you must also remove the try/catch statement, which no longer applies to the creation of this report. You're now ready to build and run the example. Update the build. xml file, modifying the run target.
classname
Type ant run on command line to view the results. You should see a report like this:
L i b r a r y Information libLoader
111.6083984375
libformula
324.0615234375
Wizard Java API In addition to building reports via Pentaho Reporting's traditional API, it is also possible to build a report using Pentaho's Wizard API. This API is defined in the wizard-core library, w i t h i n the org. pentaho. reporting. engine .classic . wizard
package and sub-packages. The Defaultwizardspecif ication class, defined in the
model package, allows you to quickly populate a report with groupings and details. The Wizard API may incorporate predefined styles, allowing your organization to easily generate dynamic reports that fit your company's style requirements.
[274]
Chapter 11
Once a wizardspecif ication is defined, you can easily populate a report with just two lines of code: WizardProcessorUtil.applyWizardSpec(styledReport, wi zardSpec); WizardProcessorUtil.ensureWizardProcessorlsAdded(styledReport, null) ; T h e applyWizardSpec inserts the wi zardSpec into the styledReport, a n d
the ensureWizardProcessorlsAdded method adds a WizardProcessor as a ReportPreProcessor to the styledReport, b y calling the AbstractReportDefinition.addPreProcessor(ReportPreProcessor
preprocessor) method. In addition to defining a wizardspecif ication instance, a data source must already be configured before rendering a report. To learn more about the Wizard API, please review the Javadoc at http: / / j avadoc. pentaho.com/reporting/org/pentaho/reporting/wizard-core/
Summary In this chapter, you walked through Pentaho Reporting's . prpt bundle file format, and learned about the various XML documents that combine to render a report. You learned how to define parameters, data sources, and expressions in the datadef inition. xml file. You also learned how to lay out and style a report within the layout. xml and styles. xml files. You combined all the files to generate an example . prpt bundle file, and loaded the result in Report Designer to verify that it renders as expected. This chapter also covered the basics of building a MasterReport via Pentaho Reporting's easy to use Java API. You saw examples of defining parameters, adding data sources, and defining expressions. You also learned about how to build the group hierarchy, and add elements to reports via Pentaho Reporting's element factory approach. You then walked through a full example of a simple report, demonstrating how easy it is to build a report from scratch, using just a few lines of code. Finally, you received a brief introduction to Pentaho's Wizard API, which makes API-based report generation an easy task.
[275]
11
Extending Pentaho Reporting In this chapter, you'll learn how to extend Pentaho Reporting through various APIs available within the reporting engine. You'll first begin with implementing your own report functions and expressions. From there, you'll design your own formula functions, as well as BeanShell expressions. Finally, you'll complete the chapter with an example of writing a custom report element.
Implementing report functions and expressions As you learned in Chapter 7, Pentaho Reporting comes with many already defined functions and expressions. All expressions implement the Expression Java interface, and all functions implement the Function Java interface—both are located in the org. pentaho. reporting . engine . classic . core . function package. A n
expression is stateless, and only has access to its current dataset row. Functions are stateful, and may maintain state across rows of data.
Implementing expressions To implement an expression, you must define a class that implements the Expression interface, as well as associated metadata, so the expression may appear in Pentaho's Report Designer.
Extending Pentaho Reporting
Defining an expression class The Expression interface defines the methods necessary for an expression to be evaluated. T h e Expression Javadoc, available at http : //j avadoc . pentaho .
com/reporting/, provides details on each method within the interface. An AbstractExpression class is provided, located in the same Java package as the Expression interface, which implements the common interface requirements of all expressions. This includes handling of common properties such as name, dependency level, and preserve, as well as managing the reporting runtime, which includes access to the data row and resource bundle factory. To implement your own expression, extend the AbstractExpression class, add JavaBean getters and setters for the properties you are interested in for configuration of the Expression, and implement the Ob j ect getValue () method, which is part of the Expression API. The getValue method will be called during report evaluation on every row and band, in order to execute the Expression. Also, you must provide a default constructor for your class. The reporting engine will instantiate a single expression object during report execution. Note that only certain class types may be used as properties for expressions. For more information on which class types are supported, see the ConverterRegistry class, located in the org.pentaho.reporting.engine.classic.core.util.beans package, which defines the supported class types along with their converter classes.
Defining expression metadata If you would like your expression to appear in the Report Designer, you'll need to create additional files that describe your expression. The first file that must be defined is the expression properties bundle. This bundle is a standard Java resource bundle file that contains specific name value pairs. The file should be located in the same directory as the Expression implementation, and be named Bundle.properties.
Two properties—display-name and grouping—must be defined for each expression. The display-name property defines how the expression is presented in the Report Designer, and the grouping property defines which group the expression is located in within the Add Function dialog. Each property name must begin with expression..—for e x a m p l e expression.ExampleExpression.display-name=Example Expression.
[278]
Chapter 11
For each JavaBean property defined within the Expression implementation, the display-name and grouping properties must be defined as well. The names of these properties should appear in the bundle as expression. .property..—for e x a m p l e expression.ExampleExpression.property.name.display-name=Name.
In addition to defining the bundle, you must also provide expression metadata in XML. This is done using Pentaho Reporting's metadata XML namespace. The element should be defined in an XML file as a child element called expression, with a root node of meta-data. The expression XML element should contain the following XML attributes: Expression attribute
Description
Class
The fully qualified class name of the Expression implementation.
Bundlename
The fully qualified path of the resource bundle defined above.
Result
The fully qualified class name of the value returned by the method getValue ( ).
hidden
This attribute can be set to true or false. If true, the element will not appear in the Report Designer.
Also, the expression e l e m e n t should contain a property X M L e l e m e n t for each J a v a B e a n property defined in the element. T h e property e l e m e n t should contain the f o l l o w i n g X M L attributes: Property attribute
Description
name
The name of the lavaBean property.
mandatory
Set mandatory to true if this attribute must not be null.
value-role
The role this value is used for. This helps determine the type of editor to display in the Report Designer. The following are valid options—Value, Resource, ElementType, Query, Field, and Group.
hidden
This attribute can be set to true or false. If true, the element will not appear in the Report Designer.
[279]
Extending Pentaho Reporting
To register the XML file with the reporting engine, you need to define a Module class. The Module interface is defined in Pentaho Reporting's libbase subproject within the org . pentaho . reporting. libraries . base . boot package. T h e AbstractModule
class is created to simplify defining a new module. An implemented module should contain a default constructor with a call to the AbstractModule loadModulelnf o ( )
method. This loads the necessary module configuration files, which are defined below. To load your expression metadata file, define the following method: public void initialize(final SubSystem subSystem) throws Modulelnitiali zeException
Within the method, make a call to ElementMetaDataParser. initializeOptional ExpressionsMetaData (String xmlFile) with a reference to your metadata XML
file defined above. In addition to defining your Module class, you must also define a module. properties file that describes your module. This properties file should contain the following properties: Property name
Description
module.name
The name of the module.
module.producer
The author of the module.
module.description
The description of the module.
module.version.maj or
The major version number of the module.
module.version.minor
The minor version number of the module.
module.version.patchlevel
The patch level version number of the module.
dependency.core.module
This is the name of the module in which you require to exist before loading. In most cases, this should be set to org.pentaho.reporting. engine.classic.core. ClassicEngineCoreModule
dependency.core.dependency-type
This describes the type of dependency, usually set to required.
dependency.core.version.maj or
The major version number of the dependency.
dependency.core.version.minor
The minor version number of the dependency.
dependency.core.version.patchlevel
The patchlevel version number of the dependency.
[280]
Chapter 11
These properties must be defined within the properties file with a colon separating the property a n d value, as : .
Once you've defined your Module implementation, you must also register the module with the reporting engine. To do this, create a properties file at the root of your JAR, containing your module called classic-engine . properties, with a property called org.pentaho.reporting.engine.classic.extensions. modules . . Module, setting its value to the full module class name including its package. The reporting engine searches the classpath for this file, and loads the modules listed. You may use a single Module to define multiple expressions and other extensions within Pentaho Reporting.
I I
An example expression This example will demonstrate creating an expression by implementing the RegexExpression class. This expression will take a data field, run it through a regular expression, and then render a message containing groups from tbe regular expression. First, you'll need to set up the Chapter 11 project. Create a folder chapterii, and copy the chapterio/lib folder into the new project. Also, create an src folder. Now, create the file RegexExpression. java in the src folder, and stub out a class. import org.pentaho.reporting.engine.classic.core.function. AbstractExpression; public class RegexExpression extends AbstractExpression { public RegexExpression() { } // add properties here // add getValue here
} Now that you've stubbed out the expression class, you're ready to give it a set of properties. Add two properties that are relevant to this expression. The first is regex, which will contain a defined regular expression. The second is field, which will contain the data field to parse. Add the following lines of code after the / / add properties here c o m m e n t : private String regex; private String field; public void setRegex(String regex) { this.regex = regex;
} public String getRegex() { [281]
Extending Pentaho Reporting return regex;
} public void setField(String field) { this.field = field; } public String getFie Id () { return field;
} It's n o w time to write the getValue () m e t h o d of the expression. This m e t h o d uses the t w o expression properties a n d returns a result. A d d the f o l l o w i n g lines of c o d e after t h e / / add getValue here c o m m e n t : public Object getValue() { // wrap the regex code in a try catch, so that an // error message can be presented if the parsing failed, try { // create a pattern based on the regex input final Pattern p = Pattern.compile(regex); // lookup the field, and if not null, create a matcher final Object o = getDataRow().get(getField()); if (o == null) { return null;
} final Matcher m = p.matcher(o.toString()); // find the first match in the string m.find(); // return the first group found within the match return m.group(l); } catch (Exception e) { // return the error message instead return e.getMessage ();
}
}
To complete the RegexExpression class, y o u m u s t also a d d the f o l l o w i n g imports to the b e g i n n i n g of the class: import java.util.regex.Pattern; import java.util.regex.Matcher;
[282]
Chapter 11 N o w that you've defined the Expression class, y o u m u s t also define a properties file describing the expression. Create the RegexExpressionBundle. properties file in the src folder, a n d a d d the f o l l o w i n g contents: # The name and grouping of the expression expression.RegexExpression.display-name=Regex expression.RegexExpression.grouping=Other
Expression
# The field property expression.RegexExpression.property.field.display-name = Field Name expression.RegexExpression.property.field.grouping=Other # The regex property expression.RegexExpression.property.regex.di splay-name=Regex expression.RegexExpression.property.regex.grouping=Other # common properties, name and dependencyLevel expression.RegexExpression.property.name.display-name=Name expression.RegexExpression.property.name.grouping=Common expression.RegexExpression.property.dependencyLevel.di splayname=Dependency Level expression.RegexExpression.property.dependencyLevel.grouping=Common To finish defining all the necessary m e t a d a t a for the expression, create a sr c/me ta-express ions .xml file, w h i c h contains details a b o u t the expression: «expression bundle-name="RegexExpressionBundle" result="java.lang.String" hidden="false"> «property name="dependencyLevel" mandatory="false" value-role="Value" hidden="false"/> «property name="field" mandatory="true" value-role="Field" hidden="false"/> «property name="regex" mandatory="true" value-role="Value" hidden="false"/> «property name="name" mandatory="true" value-role="Name" hidden="false"/> To complete this example, y o u n e e d to define a reporting m o d u l e that will m a n a g e the initialization of the expression a n d other e x a m p l e s that appear later in this chapter. First, create the file chapteriiModule. j ava in the src folder, w h i c h loads the meta-expressions . xml file. [283]
Extending Pentaho Reporting import org.pentaho.reporting.engine.classic.core.metadata. ElementMetaDataParser; import org.pentaho.reporting.libraries.base.boot.AbstractModule; import org.pentaho.reporting.libraries.base.boot. ModuleInitiali zeException; import
org.pentaho.reporting.libraries.base.boot.subsystem;
public class ChapterllModule extends AbstractModule { // Constructor.
This loads the module specification
public ChapterllModule() throws ModulelnitializeException { loadModulelnfo();
} // initialize the module by loading the expression metadata public void initialize(final subsystem subsystem) throws ModulelnitializeException { ElementMetaDataParser.initiali zeOptionalExpressionsMetaData( "meta-expressions.xml");
N o w , create a src/module . properties file w i t h the following content: module.name: chapterllmodule module.producer : Pentaho Reporting for Java Developers module.description : Example classes to demonstrate extending Pentaho Reporting. module.version.major : 1 module.version.minor : 0 module.version.patchlevel : 0 dependency.core.module : org.pentaho.reporting.engine.classic.core. ClassicEngineCoreModule dependency.core.dependency-type : required dependency.core.version.major : 3 dependency.core.version.minor : 5 dependency.core.version.patchlevel: 0
To register the module with the reporting engine, you must define a properties file that the engine looks for and loads. Create the classic-engine. properties file within the chapterii/src folder, and add the following property: # Module definition org.pentaho.reporting.engine.classic.extensions.modules. chapterllmodule.Module=ChapterllModule
[284]
Chapter 11 You're n o w ready to build your m o d u l e into a J A R file. Create a build. xml in the root of the project, a n d a d d the following xml: «project name="Chapter 11 Examples" default="jar"> «include name="*.jar" />
destdir="classes"
«exclude name="**/*.java"/> After creating the build file, r u n ant j ar at the root of the project. T h e chapterii. j ar will b e created in the dist folder. N o w c o p y this J A R file into the Report Designer's lib folder, a n d restart the Report Designer. Y o u should see the function appear in the designer:
[285]
Extending Pentaho Reporting Add Function .. Common Report Summary Running Advanced Chart Data Image Script Deprecated Other Q
Regex Expression
Add
Now it's time to create a very basic report to demonstrate the Regex Expression. Create a report with a table data source, with the following values: Field Please call 513-523-1222 at your earliest convenience. Hie number 518-123-5555 is unlisted. To place an order, call 941-563-1324.
Drag-and-drop the Field into the details band. Also, add a label with the text "Fields" in the report header. Now, add a Regex Expression to the report. Set the Field Name equal to Field, and the regex equal to (\d{3} -\d{3} - \d{4}). This regular expression will find the first phone number in the field. Drag the expression into the details band, and run a preview of the report. Also, add a label in the report header called Phone Number. Your results should look something like the following:
Field
Phone Number
Please call 5 1 3 - 5 2 3 - 1 2 2 2 at your earliest convenience.
513-523-1222
The number 5 1 8 - 1 2 3 - 5 5 5 5 is. unlisted.
518-123-5555
To place an order, call 9 4 1 - 5 6 3 - 1 3 2 4 .
941-563-1324
Save this report as chapterii. prpt —you'll be using it later in this chapter.
[286]-
Chapter 11
Implementing functions As mentioned earlier, functions are stateful expressions. The Function interface extends the Expression interface, as well as the ReportListener interface defined in the org . pentaho . reporting . engine . classic . core . event package. Functions
receive event notifications while the report is being generated, allowing functions to detect progress in report generation. See the ReportListener Javadoc for the various callbacks that the Function interface receives. An additional class called Functionutilities, located in the org .pentaho. reporting . engine . classic . core . function package, provides useful m e t h o d s
for accessing elements within a report, as well as determining the exact state of report generation. Knowing that the report is in the prepare run state is important for functions calculating values. This is possible with the Functionutilities . isDef inedPrepareRunLevel () method call. Please see the Functionutilities Javadoc for additional information on the utility functions available. Functions must provide the same exact metadata that an expression defines, as described above. There are many examples of Function and Expression implementations in the reporting engine core project that demonstrate everything from row banding to open formula evaluation.
Implementing a formula function As described in Chapter 7, formulas are used in many places within a report for dynamic evaluation. Pentaho Reporting allows the definition of custom formula functions so that developers may extend the capability of the formula subsystem. To define a formula function, you must implement the Function interface located in the org . pentaho . reporting . libraries . formula . function package, as w e l l
as a FunctionDescription defined in the same package. Note that this is a different Function interface as described earlier. The two methods a formula function must implement are: // This is the name of the function as it appears in the formula public String getCanonicalName(); // this method evaluates a result based on the incoming parameters public TypeValuePair evaluate(FormulaContext context, ParameterCallback parameters) throws EvaluationException;
[287]
Extending Pentaho Reporting T h e TypeValuePair class simply contains a variable value a n d its type. T h e FormulaContext class p r o v i d e s access to the f o r m u l a system, a n d the Parameter-Callback class p r o v i d e s information about the p a r a m e t e r s b e i n g p a s s e d into the current function. T h e FunctionDescription interface describes details a b o u t the function, including its inputs a n d output type. T h e AbstractFunctionDescription class is available to simplify the i m p l e m e n t a t i o n of your FunctionDescription class. W h e n u s i n g the AbstractFunctionDescription, y o u m u s t i m p l e m e n t the f o l l o w i n g m e t h o d s in y o u r description class, a l o n g with a properties b u n d l e file: Method
Description
Default Constructor
The default constructor of your description class must call AbstractFunctionDescription's super(String canonicalName, String messageBundle) parent constructor to initialize properly.
FunctionCategory getCategory()
Defines which FunctionCategory the formula function should appear in. Normally, custom functions should return UserDefinedFunctionCategory. CATEGORY.
int getParameterCount ()
Defines the number of parameters accepted by this function.
Type getParameterType(int Position)
Returns the parameter type of a parameter expected at a specific position.
public Type getValueType()
Returns the result value type.
public boolean isParameterMandatory(int position)
Returns true if a parameter is required at a specific position.
T h e properties b u n d l e contains information about the function. Required properties include: Property
Description
display-name
The canonical name of the formula function.
Description
The description of the formula function.
parameter..display-name
The display name of the Nth parameter.
parameter..description
The description of the Nth parameter.
[288]
Chapter 11 Finally, to register the function with libformula, y o u n e e d to create a libf ormula. properties file at the root of the m o d u l e J A R , a n d a d d the property org. pentaho. reporting.libraries.formula.functions.information.. class, w h i c h references the i m p l e m e n t e d Formula class, as w e l l as org. pentaho. reporting.libraries.formula.functions.information.. description, w h i c h references the i m p l e m e n t e d FormulaDescription class.
Regex formula function example In this example, you'll define a function called regex, w h i c h takes a regular expression a n d a n input string, returning the first m a t c h i n g group of the regular expression. To b e g i n the e x a m p l e , create a class n a m e d RegexFunction. j ava in the src folder, a n d a d d the f o l l o w i n g content to the file: import java.util.regex.Matcher ; import java.util.regex.Pattern; import org.pentaho.reporting.libraries.formula.EvaluationException; import org.pentaho.reporting.libraries.formula.FormulaContext; import org.pentaho.reporting.libraries.formula.LibFormulaErrorValue; import org.pentaho.reporting.libraries.formula.function.Function; import org.pentaho.reporting.libraries.formula.function. ParameterCallback; import org.pentaho.reporting.libraries.formula.lvalues.TypeValuePair; import org.pentaho.reporting.libraries.formula.typing.TypeRegistry; import org.pentaho.reporting.libraries.formula.typing.coretypes. TextType; public class RegexFunction implements Function { // This method evaluates the regular expression function public TypeValuePair evaluate(FormulaContext context, ParameterCallback parameters) throws EvaluationException { // throw an exception if the function doesn't have // both parameters if (parameters.getParameterCount() != 2) { throw new EvaluationException( LibFormulaErrorValue.ERROR_ARGUMENTS_VALUE);
} final TypeRegistry typeRegistry = context.getTypeRegistry(); final String paraml = typeRegistry.convertToText(parameters. getType(O), parameters.getValue(0)); final String param2 = typeRegistry.convertToText(parameters. getType(l), parameters.getValue(1));
[289]
Extending Pentaho Reporting try { // create a pattern based on the regex input final Pattern p = Pattern.compile(paraml); final Matcher m = p.matcher(param2) ; // find the first match in the string m.find(); // return the first group found within the match return new TypeValuePair(TextType.TYPE, m.group(l)); } catch (Exception e) { // return the error message as the result return new TypeValuePair(TextType.TYPE,e.getMessage()) ;
}
}
public String getCanonicalName() { return "REGEX";
}
}
Now that you've defined an implementation of the Function class, you must also provide a FunctionDescription class. Create a RegexFunctionDescription. java
file in your src folder, and enter the following text: import org.pentaho.reporting.libraries.formula.function. AbstractFunctionDescription; import org.pentaho.reporting.libraries.formula.function. FunctionCategory; import org.pentaho.reporting.libraries.formula.function.userdefined. UserDefinedFunctionCategory; import org.pentaho.reporting.libraries.formula.typing.Type; import org.pentaho.reporting.libraries.formula.typing.coretypes. TextType; public class RegexFunctionDescription extends AbstractFunctionDescription { public RegexFunctionDescription() { // make sure to call the super constructor, with // the function name and the function resource bundle super("REGEX", "Regex-Function");
} // place this function in the user defined category public FunctionCategory getCategory() { return UserDefinedFunctionCategory.CATEGORY;
}
[290]
Chapter 11 // this function requires two parameters, // regex and input string public int getParameterCount() { return 2;
} // both of the parameters are of type text public Type getParameterType(int position) { return TextType.TYPE;
} // the output type is of type text public Type getValueType() { return TextType.TYPE;
}
// both parameters are required for execution public boolean isParameterMandatory(int position) { return true;
}
}
Y o u m u s t also define a resource b u n d l e for the function. Create a Regex-Function. properties file in the src folder, a n d enter the following text: di splay-name=REGEX description=Executes a regular expression on a string, returning the first found group parameter.0.display-name=Regular Expression parameter.0.description=A Java Regular Expression string, with a grouping defined within the string, parameter.1.display-name = String Input parameter.1.description=A string to parse. To register the f o r m u l a function w i t h libformula, y o u m u s t also provide a libf ormula. properties file in the src folder, w i t h the following information: org.pentaho.reporting.libraries.formula.functions.information.Regex. class=RegexFunction org.pentaho.reporting.libraries.formula.functions.information.Regex.de scription=RegexFunctionDescription You're n o w ready to build the chapterli project w i t h the n e w f o r m u l a function. T y p e ant j ar, a n d place the generated J A R file in the Report Designer's classpath. L a u n c h the Report Designer, a n d u s e the earlier defined report example. A d d a n O p e n F o r m u l a function with the following formula: =REGEX("(\d{3}-\d{3}-\d{4})";[Field])
[291]
Extending Pentaho Reporting
In the Details band, drag-and-drop the expression below the already defined RegexExpression. Congratulations! Your new formula results should look identical to the regex expression example defined earlier.
Implementing BeanShell expressions Another approach to implementing your own report expressions is using the BSHExpression report expression, which uses BeanShell to evaluate an expression. BeanShell is a Java code interpreter, so you can write Java for direct execution within a report with this expression. The BSHExpression contains a property called expression, which should contain the necessary BeanShell script. This script must contain the ob j ect getValue () method, which is called to evaluate the expression. Imports and additional functions may be included in the expression. The expression also has access to the DataRow class instance named dataRow. This allows for easy access to the current row of data for the expression to use.
Example BSHExpression Open up the already defined chapter 11. prpt, defined earlier in this chapter, within Report Designer. Now add a Bean-Scripting-Host (BSH) expression, which is located within the Script function group. Set the expression property to the following BeanShell syntax: import java.util.regex.*; Object getValue() { try { final Pattern p = Pattern.compile("(\\d{3}-\\d{3}-\\d{4})"); final Matcher m = p.matcher(dataRow.get("Field")); // find the first match in the string m.find() ; // return the first group found within the match return m.group(l); } catch (Exception e) { // appropriate way to log a error / warning message? return e.getMessage();
Drag-and-drop the expression onto the details band, below the other expressions. You should see results similar to the first and second examples above. To learn more about BeanShell, please visit http: //www. beanshell. org/.
[292]
Chapter 12
Implementing a report element With Pentaho Reporting's API, it is possible to implement your own report elements. In this section, you'll walk through the necessary steps to implement a basic report element. You'll learn how to define an ElementType, XML read and write handlers, as well as all the metadata necessary to have your report element appear in the Report Designer.
Defining an ElementType class The first step in defining a new report element is implementing the ElementType interface, located in the org.pentaho.reporting.engine.classic.core.metadata
package. This interface defines a set of methods that allow the creation and rendering of an element within a report. // the getMetaData method returns the element type's // metadata, including the element name, attributes and styles public ElementMetaData getMetaData(); // Inherited from the DataSource interface, the getValue // method generates a renderable object that will appear // in a report. public Object getValue(final ExpressionRuntime runtime, final Element element) // the getDesignValue returns a design time rendering of the // element. This is useful if you have an element // without access to its source data. public Object getDesignValue(ExpressionRuntime runtime, final Element element); // the configureDesignTimeDefaults method is used in // designers when an element is first added to a report, public void configureDesignTimeDefaults(Element element, Locale locale);
The getValue method must return a Java object that the report engine knows how to process for rendering. This includes the types j ava. lang. String, j ava. awt. Shape, org.pentaho.reporting.engine.classic.core.util.ReportDrawable, along with
any class that defines the following method, which is executed via introspection: public void draw(Graphics2D, Rectangle2D)
The ReportDrawable interface defines the draw method, as well as additional methods providing access to the report configuration, the current stylesheet, and the resource bundle factory. Also defined is the getimageMap method, which allows the ReportDrawable implementation to define a clickable map over the content. [293 ]
Extending Pentaho Reporting
[ . % '
Hie Report Engine renders in multiple formats, and each format
I
handles the rendering of Java graphics differently. For instance, PDF rendering, which uses iText, translates the rendered items within the Graphics2D context into PDF elements.
I I I
In the getvalue method, the current element instance is provided for access to its attributes a n d styles. See the org . pentaho . reporting . engine . classic . core .
Element Javadoc API for details on how to access attributes and styles.
Defining element metadata Now that you've defined the main ElementType class, you need to define the metadata to go along with the element. Element metadata is similar to expression metadata defined earlier. The element should be defined in an XML file with a root node of meta-data, as a child XML element called element. This XML file should use the namespace: http://reporting.pentaho.org/namespaces/engine/classic/ metadata/i. o. The element XML element should contain the following attributes: XML attribute
Description
Name
The name of the element type.
Hidden
This attribute can be set to true or false. If true, the element will not appear in the Report Designer.
Deprecated
This attribute can be set to true or false. This attribute is not used at this time.
container
This attribute can be set to true or false. If true, the element is recognized as a container type element.
bundl e - name implementation
The fully qualified location of the resource bundle. The fully qualified class name of the ElementType implementation.
The element XML may also contain child elements, defining attributes and styles. T h e attribute XML element contains the following XML attributes:
Attribute
Description
Namespace
The namespace of the attribute.
Name
The name of the attribute.
Mandatory
This attribute can be set to true or false. This attribute is not used at this time.
[294]
Chapter 12 Attribute
Description
Hidden
This attribute can be set to true or false. If true, the attribute will not appear in the Report Designer.
Computed
This attribute can be set to true or false. If true, this attribute will not be serialized.
design-time-value
If computed, and design-time-value is set, the attribute will still be serialized.
Deprecated
This attribute can be set to true or false. This attribute is not used at this time.
prefer-bulk
This attribute determines where in the element XML the attribute is serialized.
value-type
The fully qualified Java class name of the attribute value.
value-role
The role this value is used for. This helps determine the type of editor to display in the Report Designer. The following are valid options —Value, Resource, ElementType, Query, Field, and Group.
propertyEditor
Defines the java . beans . PropertyEditor class for this attribute.
bundle-name
Defines the fully qualified bundle name for this attribute.
In addition to defining custom attributes and styles, defined elements may also import existing groups of attributes and styles. To reference these groups, first you must include the global XML file within the root meta-data XML element:
Within the child element, you must specify an attribute-group-ref child XML
element, or a style-group-ref XML element, to include a group. Set the ref XML attribute to the named group. Examples of common attribute groups include common-attributes and interactivity. Examples of common styles include borders, common, layout, a n d replaced-content. See the global-meta-elements .
xml for additional groups. Elements, along with their attributes and styles, may refer to resource bundles for defining localized property information. For element properties, the syntax is element. . < P R O P E R T Y > = < V A L U E > . For attributes and styles, the syntax is element. . attribute . < A T T R I B U T E _ NAMESPACE> . < A T T R I B U T E _ N A M E > . < P R O P E R T Y > . Localized properties for elements, styles, and attributes include:
[295 ]
Extending Pentaho Reporting Property
Description
display-name
The name displayed in the Report Designer.
grouping
The group in which the item appears.
grouping.ordinal
The defined group location relative to other groups.
ordinal
The ordinal location of this item related to other items in the Report Designer.
description
The description of the item.
deprecated
A deprecation message if the item is deprecated.
icon
A reference to the element icon, displayed in the Report Designer. This property does not apply to attributes and styles.
Once you've defined the meta-elements. xml file, as well as its resource bundle, you must inform the reporting engine that these elements are available. You may do this by calling the following method within your module's initialize method: ElementMetaDataParser.initiali zeOptionalElementMetaData("metae1ement s.xml") ;
Defining read and write handlers Now that you've defined the ElementType class, as well as the metadata relating to the element, you're ready to define the element's read and write handlers, so you can serialize the element state to XML. You'll do this by defining an ElementReadHandler, as well as a BundleElementWriteHandler. T h e ElementReadHandler interface is located in the org. pentaho. reporting. engine . classic . core . modules . parser . bundle . layout package, a n d the BundleElementWriteHandler is located in the org . pentaho . reporting . engine . classic . core . modules . parser . bundle . writer package. Luckily for US, the
reporting engine defines abstract classes that do most of the serialization work, based on the metadata you defined for your element. Read and write handlers are registered through the module's configuration. properties file. A demonstration using the AbstractElementReadHandler and
the AbstractElementWriteHandler class is provided in the following section.
An example report element This example will demonstrate what you just learned by walking through a full implementation of a new ElementType, a star shape, and seeing it run within the Report Designer. [296]
Chapter 12
The first step is defining the starType class, which implements the ElementType interface. Create StarType . java in the chapterll/src folder, w i t h the
following code: import java.awt.Polygon; import java.util.Locale; import org.pentaho.reporting.engine.classic.core.Element; import org.pentaho.reporting.engine.classic.core.function. Expre s s i onRunt i me; import org.pentaho.reporting.engine.classic.core.metadata. ElementMetaData; import org.pentaho.reporting.engine.classic.core.metadata.ElementType; import org.pentaho.reporting.engine.classic.core.metadata. ElementTypeRegistry; import org.pentaho.reporting.engine.classic.core.style. ElementStyleKeys; import org.pentaho.reporting.engine.classic.core.util.StringUtil; // This ElementType implementation renders a Star in a report public class StarType implements ElementType { // the default namespace for this element private static String NAMESPACE = "http://reporting.pentaho.org/namespaces/pr4j d" ; // a reference to the element metadata, defined in the // meta-elements.xml file private transient ElementMetaData elementType; // a default constructor public StarType() { } // load the default metadata about the star element type public ElementMetaData getMetaData() { if (elementType == null) { elementType = ElementTypeRegistry.getlnstance(). getElementType("star");
} return elementType;
} // renders a star, using inner-percent, start-angle, // and points as custom attributes public Object getValue(final ExpressionRuntime runtime, final Element element) { if (element == null) {
[297 ]
Extending Pentaho Reporting throw new NullPointerException( "Element must never be null.");
} // read in the star's custom parameters final float innerPercent = parseParam(element, "inner-percent", 0.5f); final float startAngle = parseParam(element, "start-angle", Of) ; final int points = (int) parseParam(element, "points", 5); // render a star based on the parameters int outerRadius = 100; int innerRadius = (int) (outerRadius * innerPercent); double startingRotation = (startAngle - 90) * Math.PI / 18 0; double anglelncrement = 2.0 * Math.PI / points; double currRadians = startingRotation; int minX = Integer.MAX_VALUE; int minY = Integer.MAX_VALUE; final Polygon p = new Polygon(); for (int i = 0; i < points; i++) { // gotta love trig double outerX = outerRadius + outerRadius * Math. cos(currRadians); double outerY = outerRadius + outerRadius * Math. sin(currRadians); double innerX = outerRadius + innerRadius * Math.cos(currRadians + anglelncrement / 2); double innerY = outerRadius + innerRadius * Math.sin(currRadians + anglelncrement / 2); p.addPoint((int) outerX, (int) outerY); p.addPoint((int) innerX, (int) innerY); currRadians += anglelncrement; // keep track of the smallest x and y values minX = Math.min((int)outerX, minX); minY = Math.min((int)outerY, minY);
}
// move the star's points to 0,0 for // appropriate rendering if (minX > 0 || minY > 0 ) { final Polygon p2 = new Polygon(); for (int i = 0; i < p.npoints; i++) { p2.addPoint(p.xpoints[i] - minX, p.ypoints[i] - minY); [298]
Chapter 12
} return p2; } else { return p;
}
}
// returns the design time value of this element, rendered // in the Report Designer public Object getDesignValue(final ExpressionRuntime runtime, final Element element) { return getValue(runtime, element);
} // this method is called when a star is first added to // a report within the Report Designer. Set up // the default values here. public void configureDesignTimeDefaults(final Element element, final Locale locale) { element.getStyle().setStyleProperty(ElementStyleKeys.SCALE, Boolean.TRUE); element.getStyle().setStyleProperty( ElementStyleKeys.DRAW_SHAPE, Boolean.TRUE); element.getStyle () .setStyleProperty (ElementStyleKeys.MIN_WIDTH, new Float (100)); element.getStyle().setStyleProperty( ElementStyleKeys.MIN_HEIGHT, new Float(100)); element.setAttribute(NAMESPACE, element.setAttribute(NAMESPACE, element.setAttribute(NAMESPACE,
"inner-percent", 0.5f); "start-angle", Of); "points", 5);
} // this is a utility function that parses the // custom attributes private float parseParam(final Element element, final String attrName, final float defaultValue) { final float val; final Object attrib = element.getAttribute( NAMESPACE, attrName); if (attrib != null) { if (attrib instanceof Number) { final Number n = (Number) attrib;
[299 ]
Extending Pentaho Reporting val = n.floatValue(); } else { val = StringUtil.parseFloat( String.valueOf(attrib),defaultValue);
} } else { val = defaultValue;
} return val;
} // clone is required, because the reporting engine may // create new instances of the StarType when new reports // are rendered. public Object clone() throws CloneNotSupportedException { return super.clone();
}
}
Note that you've defined three c u s t o m attributes— inner-percent, start-angle, a n d points. T h e s e three attributes c o m b i n e to define any shape of star the report m a y need. N o w y o u n e e d to define the e l e m e n t metadata, defining the three c u s t o m attributes, as w e l l as including groups of attributes that are c o m m o n across elements. Create a meta-elements . xml file in the src folder w i t h the following content: «element name="star" hidden="false" bundle-name="metadata" implementation"StarType"> «attribute-group-ref ref="common-attributes"/> «attribute-group-ref ref="interactivity"/> «attribute pr4j d"
namespace="http://reporting.pentaho.org/namespaces/ name="inner-percent" mandatory="true" hidden="false" value-type="j ava.lang.Number" value-role="Value"/>
[300]
Chapter 12
You must also define a localized bundle that describes the element and its attributes. Create a metadata. properties file in the src folder with the following content: element.star.display-name=star element.star.grouping=s element.star.grouping.ordinal=1100 element.star.ordinal=98 element.star.description= element.star.deprecated= element.star.icon=star.png element.star.attribute.pr4j d.inner-percent.display-name=inner-percent element.star.attribute.pr4j d.inner-percent.grouping=star element.star.attribute.pr4j d.inner-percent.grouping.ordinal = 3 5 0 element.star.attribute.pr4j d.inner-percent.ordinal = 10 element.star.attribute.pr4j d.inner-percent.description= element.star.attribute.pr4j d.inner-percent.deprecated= element.star.attribute.pr4j d.start-angle.display-name=start-angle element.star.attribute.pr4j d.start-angle.grouping=star element.star.attribute.pr4j d.start-angle.grouping.ordinal = 350 element.star.attribute.pr4j d.start-angle.ordinal = 2 0 element.star.attribute.pr4j d.start-angle.description= element.star.attribute.pr4j d.start-angle.deprecated=
[301 ]
Extending Pentaho Reporting element.star.attribute.pr4j d.points.di splay-name=points element.star.attribute.pr4j d.points.grouping=star element.star.attribute.pr4j d.points.grouping.ordinal = 3 50 element.star.attribute.pr4j d.points.ordinal = 3 0 element.star.attribute.pr4j d.points.description= element.star.attribute.pr4j d.points.deprecated= You'll n e e d to place the star. png i m a g e file referenced in the resource b u n d l e in the src folder so that the Report Designer displays a n icon next to the star element. T h i s file is p r o v i d e d on the b o o k ' s w e b site, or y o u can m a k e y o u r o w n file u s i n g a p r o g r a m such as G i m p . T h e i m a g e should b e 14 b y 14 pixels a n d should b e saved in the P N G format. N o w y o u n e e d to define X M L read a n d write h a n d l e r s for the star element. You'll first define the read handler. Create the file starReadHandler. j ava in the src folder, with the f o l l o w i n g contents: import org.pentaho.reporting.engine.classic.core.modules.parser. bundle.layout.elements.AbstractElementReadHandler; import
org.pentaho.reporting.libraries.xmlns.parser.ParseException;
// this class handles reading in of the star element public class StarReadHandler extends AbstractElementReadHandler { // all you need to do is pass the name of the element // to the parent class public StarReadHandler() throws ParseException { super("star");
}
}
T h e AbstractElementReadHandler does the w o r k of loading in all the report element's attributes a n d styles. Y o u n o w n e e d to create the file starWriteHandler. j ava in the src folder w i t h the following code: import java.io.IOException; import org.pentaho.reporting.engine.classic.core.Element; import org.pentaho.reporting.engine.classic.core.modules.parser. bundle.writer.BundleWriterException; import org.pentaho.reporting.engine.classic.core.modules.parser. bundle.writer.BundleWriterState; import org.pentaho.reporting.engine.classic.core.modules.parser. bundle.writer.elements.AbstractElementWriteHandler; import org.pentaho.reporting.libraries.docbundle. WriteableDocumentBundle ;
[302]
Chapter 12 import import import
org.pentaho.reporting.libraries.xmlns.common.AttributeList; org.pentaho.reporting.libraries.xmlns.writer.XmlWriter; org.pentaho.reporting.libraries.xmlns.writer.XmlWriterSupport;
// manages writing the star element type to .prpt bundle public class StarWriteHandler extends AbstractElementWriteHandler { // namespace for XML elements private static final String NAMESPACE = "http://reporting.pentaho. org/namespaces/pr4jd"; // default consructor public StarWriteHandler() { } // writes the star element to the xmlWriter public void writeElement(final WriteableDocumentBundle bundle, final BundleWriterState state, final XmlWriter xmlWriter,final Element element) throws IOException, BundleWriterException { if (bundle == null) { throw new NullPointerException();
} if (state == null) { throw new NullPointerException();
} if (xmlWriter == null) { throw new NullPointerException();
} if (element == null) { throw new NullPointerException();
} // add the attribute namespace if not already there final AttributeList attList = createMainAttributes(element, xmlWriter); if (xmlWriter.isNamespaceDefined(NAMESPACE) == false) { attList.addNamespaceDeclaration("pr4jd", NAMESPACE);
} // write the star element, within the pr4jd namespace xmlWriter.writeTag(NAMESPACE, "star", attList, XmlWriterSupport.OPEN); writeElementBody(bundle, state, element, xmlWriter); xmlWriter.writeCloseTag();
[303 ]
Extending Pentaho Reporting
It's now time to update the earlier defined chapteriiModule to initialize the element, and notify the reporting engine about the read and write handler classes. Open up chapteriiModule. j ava, and add the following line to the initialize method: ElementMetaDataParser.initiali zeOptionalElementMetaData("metae1ement s.xml") ;
You also need to create the module's configuration. properties file with the information regarding the read and write handlers. This file should be created in the src folder. Add the following text to the configuration file: # define the prefix for this configuration org.pentaho.reporting.engine.classic.core.modules.parser.bundle. element-factory-prefix.pr4j d=pr4j d. # define the pr4jd namespace for this configuration pr4j d.namespace.pr4j d=http://reporting.pentaho.org/namespaces/pr4j d # define the pr4jd namespace for the metadata org.pentaho.reporting.engine.classic.core.metadata.namespaces. pr4j d=http://reporting.pentaho.org/namespaces/pr4j d # define the star read handler pr4j d.tag.pr4j d.star=StarReadHandler # define the star write handler org.pentaho.reporting.engine.classic.core.modules.parser.bundle. writer.element-write-handler.star=StarWriteHandler
You're now ready to build the project and see some stars. Type ant j ar to build the chapterll. jar file. Place the chapterll. jar file in the lib folder of the Report
Designer, and start the Report Designer. You should see the star element within the list of elements. Drag-and-drop a star element into the report header. In addition to adjusting the star's custom properties, you may also use the built-in styles to configure the border and colors, as well as properties such as aspect ratio. These capabilities are available because you defined a shape object as the element value. Set the star's inner-percent to 0.75, and points to 16. Under the Style tab, set fill to true and fill-color to yellow. Add a label over the star, and preview the report in PDF. You should see something like this:
[304]
Chapter 12
r
r^
,
Pentaho Reporting
Save your report, and reopen it. The star was saved into the . prpt file with the defined XML write handler, and reopened using the defined XML read handler. Due to the table rendering technique used when generating HTML, Excel, and RTF outputs, by default Shape objects are not rendered during report generation. You may enable Shape rendering by setting the report configuration property org. pentaho. reporting. engine .classic . core.modules.output.table.html.ShapeAsContent to true via a JVM system setting. Table Tenderers do not allow overlapping of elements, so in the previous example, the Pentaho Reporting label would be hidden until it was moved below the star.
Summary In this chapter, you learned a great deal about Pentaho Reporting Engine extension points. You learned the details of implementing a report expression, including defining the Expression class, as well as all of the necessary metadata to view the expression in the Report Designer. With the RegexExpression example, you were able to execute your own expression in the Report Designer. You also learned about report functions and how they differ from expressions. Next, you learned how to implement your own formula functions, as well as the necessary metadata to execute the formula function within the Report Designer. You took the same regex example and placed it within the formula system. You then used the BSHExpression to add your own custom code directly into a report within the Report Designer. The chapter ended with an introduction to building report elements, and you created a star element that defines its own set of properties and renders different types of stars within reports.
[305 ]
12
Additional Pentaho Reporting Topics This chapter covers a potpourri of useful, short Pentaho Reporting subjects that couldn't fit into earlier chapters. You'll start off by learning about Pentaho's Business Intelligence Server, which acts as a centralized reporting server where users can publish, schedule, and create ad hoc reports. From there, you'll learn how to use Pentaho Reporting for mobile reporting. The chapter continues with a look at the MetaTableModel API, which provides data source metadata to a report. Also included in this chapter is a brief introduction to Pentaho Reporting's OutputProcessor API for generating custom report output types. The chapter concludes with additional information about the Pentaho Reporting community and where to go for help.
Using Pentaho Reporting with Pentaho's Business Intelligence Server As part of Pentaho's suite of products, Pentaho offers an open source Business Intelligence Server. The BI Server is a web application which allows users to publish and manage reports within an enterprise Business Intelligence system. The BI Server offers many capabilities, including the management and execution of Pentaho Reports. Combining Pentaho Reporting and Pentaho's BI Server, information technologists may utilize Pentaho Reporting in their environment without writing any code. In addition to the publishing and execution of reports, the open source BI Server allows for scheduling, background execution, security, and much more. With Pentaho's Enterprise BI Server, additional capabilities are available, including enterprise auditing as well as server management. In this section, you'll get a taste of the capabilities within the BI Server related to Pentaho Reporting.
Additional Pentaho Reporting Topics
Downloading and Installing the Bl Server To download Pentaho's open source BI Server, go to http: //sourceforge. net/ pro j ects/pentaho and download version 3.5 of the Business Intelligence Server. The file to download begins with biserver-ce-, Pentaho Reporting 3.5 is included in this release of the BI Server. The BI Server is a large download, and comes bundled with much more than Pentaho Reporting. The download includes an Apache Tomcat web server, which includes the Pentaho web application, a sample HSQLDB database, as well as an administration console for managing users and database connections. Before you start the server, you need to enable a publish password so that you can send reports from the Report Designer application to the server. Unzip the distribution, and go into the bi-server-ce/pentaho-solutions/systemfolder. Edit the publisher_conf ig. xml file, updating the empty publisher-password XML element with a password such as: password Now go back to the bi-server-ce folder and execute start-pentaho. bat. This will start the sample HSQLDB database, as well as Tomcat. Once you've started the server, you may visit http: //localhost : 8 08 0/pentaho in your browser to view the Pentaho User Console, where BI related content is hosted, created, and executed. DE File
Edit
View v
^ File
View
B Tools
History
Bookmarks
fi
IO
loo I s
Qil
Help ]~v~| [ i G l ^ Open Source BI
http ¡//localhost ;8080/pentaho/Home
Help
j ©pentaho-
Éû E Q S
81 D e v e l o p e r E x a m p l e s
E3 S t e e l W h e e l s
©
p e n t a h o j open source business intelligs
IL? EL
New Report
New Analysis View
Transferring data from localhost,.
[308 ]
Manage Content
Chapter 12
To complete starting up the BI Server, go into the administration-console folder and run startup .bat. This starts the administration console application, which is hosted within a Jetty web server. It is accessible by visiting http: //localhost: 8 09 9 in your browser. The default username and password are admin and password.
Publishing a report to the BI Server Now that you have the BI Server running, you're ready to publish a report to the server. Open one of the example reports within Pentaho Report Designer. You can access the sample reports through the main menu by going to the Help | Welcome screen and double clicking on a report in the samples tree. All of these reports are based on the same sample database provided in the BI Server. Select File | Publish. You'll see the following dialog: f
I1 Server URL http://localhost:8080/pentaho/ Publish Password:
Pentaho Credentials User:
joe Password:
0
Remember these Settings OK
[309 ]
Cancel
Additional Pentaho Reporting Topics
Make sure the URL is set to http: //localhost: 8 08 0/pentaho. Enter your user credentials for the BI Server. The example user joe with the default password password is provided. Click OK. You should see a repository browser dialog: Publish To Server Report Name: My R e p o r t
Report Description: My R e p o r t
Location: /steel-wheels Name
r l
Up I
Browse
Date Modified
Type
analysis
File F o l d e r
05/2512009 09:28 PM
charts
File F o l d e r
0 5 / 2 5 / 2 0 0 9 09:28 PM
dashboards
File F o l d e r
0 5 / 2 5 / 2 0 0 9 09:28 PM
reports
File F o l d e r
0 5 / 2 5 / 2 0 0 9 09:28 PM
Publish Settings Report Output Type:
•w
•
Lock Output Type
Publish Password:
OK
Cancel
Name the report, and traverse into the steel-wheels folder. Note that you cannot publish reports in the root of the repository. Enter your recently created publish password and click the OK button. The report is sent to the server via HTTP. You can now log into the BI Server and execute the report. Report definitions published to the server are stored in the server's solution repository, and are given default author read and write permissions. Report definitions may be deleted by going to the BI Server's solution navigator, rightclicking on the file, and selecting Delete.
[310 ]
Chapter 12
Scheduling reports Once a report has been published, you may choose to create a recurring schedule for the report to execute. This feature is even more useful if you configure the report for email, which is described below. To schedule a report, right-click on the report within the Pentaho User Console solution navigator and select Schedule.... This brings up the following dialog: New Schedule Name: iRecurring S c h e d u l e
I
Group: 'My Schedules
|
Description: ' D e m o n s t r a t i o n of Recurring Schedule
I
Recurrence: Weekly C Start Time I OS C
00 C
PMC
Recurrence pattern Recur every week on: ISunday Dïhursday
® M o n d a y C Tuesday DWednesday Friday
OSaturday
Range of recurrence Start: | p 3 / 2 7 / 2 0 0 9
| ® N o end date OEndby:
|Q3/27/200B
| OK
Cancel
Enter a name, group, and description. Groups allow you to organize your schedules, so you can enter any group name that you prefer. You may choose from a set of recurrence options. As an example, choose Weekly, and check Monday at 8PM, beginning with the current date.
[311 ]
Additional Pentaho Reporting Topics
Now that you've created a schedule based on a published report, you should expect to see the generated report in your workspace after execution. Select View | Workspace from the main menu. The workspace contains all of your schedules, including results generated from those schedules: P e n t a h o User Console - Mozilla Firefox File
Edit
View
History O
Bookmarks Ó
View
Tools
Help
|$)|http://localhost:8080/pentaho/Home
Pentaho User Console File
Tools
H E 3
Open Source Bl
££ I O Administration Console
Help
i b
mm
©pentahc
i s i My W o r k s p a c e
I i Ö Bl Developer Examples E E3 Steel Wheels Ö
This page shows reports that you have submitted to run in background on the server. You can cancel ones that have not run yet, and you can view or delete ones that have.
Analysis
£3 Charts £3 Dashboards Ö
Reporting
I Date
_| Actions
Income Statement | 3'27/09 9:06 PM | Cancel Y Complete H I Date
I
Siz.e I Type
I Actions
Income Statement | 3^27/09 9:06 PM | 177502 | application/pdt | View | Delete Y My Schedules Job Name Recurring Schedule
Job Group
Description
Last Run / Next Run
State
Actions
joe
My Schedules : Example of a Recurring Schedule
Never Mon Mar 30 09:00:00 GMT-400 2009
Normal
Suspend | Run Now
r All Schedules (Admin Only) Job Name Files
Job Group
Description
13 PentahoSystemVersionCheck
DEFAULT
Recurring Schedule
joe
[¡^Income Statement [^inventory Report Invoices by Customer [^Regional Variance Report
My Schedules : Example of a Recurring Schedule
S Sales by Product Una S Sales by Territory
Last Run / Next Run
State
Actions
Fri Mar 27 21:40:32 GMT-400 2009 Sat Mar 28 21:40:32 GMT-400 2009
Normal
Suspend | Run Now
Never Mon Mar 30 09:00:00 GMT-100 2009
Normal
Suspend | Run Now
• Public Schedules:
Gl Top 10 Customers
In addition to defining custom schedules, administrators may define a public recurring schedule and attach reports to that schedule, so business users may easily register for pre-canned reports.
[312 ]
Chapter 12
Configuring permissions As an administrator of the Pentaho BI Server, you may choose to limit a user's usage of the BI Server. This is possible by configuring permissions on folders and individual published reports. Right-click on a folder or a report and select Properties. Now select the Share tab: Properties
General
Advanced
Share
U s e r s and Roles: A d m i n (Role) c t o (Role) d e v [Role) A u t h e n t i c a t e d (Role)
Add.
Remove
Permissions for A d m i n : 3 All Permissions 0
Create Update Execute Delete Grant Permissions Schedule
OK
Cancel
From this view, you can manage individual users and role permissions for the file or folder selected. Each item in the repository has a set of permissions for various actions such as Execute, Create, and Schedule. Later in this section you'll learn how to add and manage roles and users for the BI Server.
Report emailing and bursting To enable advanced features within the BI Server such as report bursting and emailing, you must wrap your report in an action sequence. Action sequences are created using the Pentaho Design Studio, and can be thought of as a simple programming environment for advanced business users. The Pentaho Design Studio is based on the Eclipse project. You can download the Design Studio from Pentaho's SourceForge project page. [313 ]
Additional Pentaho Reporting Topics
Once you've downloaded and unzipped the Design Studio, you'll walk through creating a simple emailed report. Launch the Design Studio by executing PentahoDesignStudio. bat. This brings up a design environment. To begin, you need to create a project that will host your action sequences. Select File | New | Project..., and create a project using the General | Project wizard. *
For Linux users, you will also need to create a workspace directory before defining your project.
Once you've created your new project, create a new action sequence by selecting BI Platform | New Action Sequence in the main menu. Select your recently created project as the container, and name your action sequence. Finally, select Send Email as the template for the action sequence and click OK. This will open the new action sequence on the Define Process tab. File
Edit
Navigate
Search
Project
J ri- ] a]»' qv S Package ,,,
£1
Hierarchy!
Run
BI Platform
Window
Help
a? [*JH
* o H * ^jsHfc*] D
•
' I S example
• Process Actions
Ä
-s- •
IÜI EmailComponent
Process Outputs
outputs
1, General 2, Define Process XML Source Test [ S Problems
=
¿\console
•
0 errors, 0 warnings, 0 infos Description
Ftesource
| Path
Location
I no
The action sequence is created with predefined action inputs, along with an EmailComponent ready to send out an email. You'll need to update the inputs with your own values, and add a report to the action sequence to complete the example. [314 ]
Chapter 12
Click the to input parameter, and enter in the default email ID you'd like the report to be sent to. You may also adjust the from, subject, and message input parameters, which define who the report will be sent from, along with email details. Now you need to add a report component to the action sequence, which generates a report from the PRPT file. Select the add image-button under Process Actions, and select Report | Pentaho Report. Click the Browse... button under the Report Specification text field, and locate your PRPT file. Also, enter "pdf" as the Report Format. Finally, set the Output Report Name for reference later. The configured report component should look something like this: JSJXJ
J a v a EE - p r o j e c t / u n t i t l e d . x a c t i o n - Eclipse P l a t f o r m File
Edit
Navigate
Search
Project
Run
Window
Help
J« S I ^ - O - i t - 1 3 - e - l
1 R - H
IQJ Project Explorer \
4> • \ 9 J 4 \
-Ï3
£ } j ^untitled Xaction ¿
H S
BI Platform
Process Inputs
project
® '
^
Process Action: Pentaho Report
0 - L D inputs L j resources I Pentaho Report
*
Report Spedfication
Process Actions
O {> I s - X
Report Parameters
I file : C i VîookVJiapter 3 \fla ta invoice. prp t
3 I Browse,.. |
» ten Pentaho Report EmailComponent
{} 1> * • X
Report Format I pdf (application/pdf)
J
Output Report Name Process Outputs
| output
V C j outputs
Paginate Use Content Repository
1. General 12, Define Process XML Source Test l l
Problems
Tasks | E3 Properties
tfi
Servers |
Data Source Explorer | [fcg Snippets |
0 items Description
*•
Ts
| Path
I Location | Type
|
11 0
Make sure that your report component appears above the EmailComponent in the process list. To complete the action sequence, click on the EmailComponent, and scroll to the bottom of the component screen. Click the Attachments add image-button and select the Output Report Name defined in the previous step. Now save your changes. The file is saved with an . xaction extension. You're now ready to deploy the action sequence to the server. To do this, copy the .xaction file along with the PRPT file into the bi-server/pentaho-solutions/ steel-wheels folder. [315 ]
Additional Pentaho Reporting Topics
Before executing the report on the server, you need to configure the BI Server's email settings. Open the bi-server/pentaho - solutions/system/smtp-email/ email_conf ig. xml file, and update the SMTP configuration with your SMTP server settings. Once you've made your changes, run Tools | Refresh | System Settings in the user console as an admin user. Also, to have the action sequence appear in the solution navigator, you will need to run Tools | Refresh | Repository Cache. Once you've successfully published the new action sequence to the server, log into the BI Server and browse to the solution location where the report was saved. Execute the action sequence. You should see a success message, as well as receiving the email. To broaden this example to burst the report to multiple individuals, you would need to set up a method for accessing multiple email addresses, as well as adding a loop within the action sequence to email the report multiple times. The email list might be stored as an action sequence string-list input parameter, or possibly stored in a database accessible through the use of an action sequence SQLLookupRule component, which you can add to an action sequence in Design Studio by selecting Get Data From | Relational in the Process Actions menu. To add the loop within the Design Studio, select Loop in the Process Actions menu, and select your list or result set as the loop on field. To learn more about the Design Studio, please see the Design Studio documentation located on Pentaho's wiki: http: //wiki .pentaho. com/display/ServerDoc2x/ Design+Studio.
Managing database connections and users Managing database connections and users for the Pentaho BI Server is done through the Pentaho Administration Console. This application appears in the BI Server under the administration-console folder. If you haven't already, you can launch the Administration Console by typing startup. bat. This starts a web server on port 8099. Open a browser and go to http: //localhost: 8 0 99. A basic authentication dialog will appear. The default username and password for the administration console are admin and password.
[316 ]
Chapter 12
The home page of the Administration Console looks like this: tj?
Administration Console - Mozilla Firefox
File
J
Edit
View
History
0
fi
Bookmarks
Tools
[_J(5][j
