TIBCO Jaspersoft Studio User Guide

S1M12019_Jaspersoft%20Studio%20User%20Guide%20v6.3

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 362

Download
Open PDF In Browser	View PDF

TIBCO JASPERSOFT® STUDIO USER GUIDE
RELEASE 6.3

http://www.jaspersoft.com

Copyright ©2005-2016, TIBCO Software Inc. All rights reserved. Printed in the U.S.A. TIBCO, the TIBCO
logo, TIBCO Jaspersoft, the TIBCO Jaspersoft logo, TIBCO Jaspersoft iReport Designer, TIBCO JasperReports
Library, TIBCO JasperReports Server, TIBCO Jaspersoft OLAP, TIBCO Jaspersoft Studio, and TIBCO Jaspersoft
ETL are trademarks and/or registered trademarks of TIBCO Software Inc. in the United States and in
jurisdictions throughout the world. All other company and product names are or may be trade names or
trademarks of their respective owners.
This is version 0616-JSP63-11 of the TIBCO Jaspersoft Studio User Guide.

TABLE OF CONTENTS
Chapter 1 Getting Started with Jaspersoft Studio
1.1 Introduction to Jaspersoft Studio
1.2 Installing Jaspersoft Studio
1.2.1 Software Requirements
1.2.2 Hardware Requirements
1.2.3 Available Packages
1.2.4 Updating Your Workspace to Jaspersoft Studio 6.2 and Higher
1.2.5 Compatibility Between Versions
1.2.6 Accessing the Source Code
Chapter 2 Creating a Simple Report

11
11
12
12
13
13
13
17
18
19

2.1 Creating a New Report
2.2 Adding and Deleting Report Elements
2.2.1 Adding Fields to a Report
2.2.2 Deleting Fields
2.2.3 Adding Other Elements
2.3 Previewing a Report
2.4 Creating a Project Folder

19
23
23
24
24
24
25

Chapter 3 User Interface and Design View

3.1 Eclipse Interface
3.1.1 Learning More About Eclipse
3.2 User Interface Components
3.3 The Design Tab
3.4 Understanding Bands
3.4.1 Band Types
3.5 Specifying Report Properties
3.5.1 Columns
3.5.2 Advanced Options
3.6 Exporting Reports with Jaspersoft Studio
3.6.1 Compiling the Report
3.6.2 Preview and Exporting
3.6.3 Choosing Report Templates for PDF

TIBCO Software Inc.

28
28
28
29
30
30
31
33
33
34
34
34
35

TIBCO Jaspersoft Studio User Guide

Chapter 4 Report Elements
4.1 Common Element Properties
4.1.1 The Palette
4.1.2 Element Properties
4.2 Inserting, Selecting, and Positioning Elements
4.2.1 Inserting Elements
4.2.2 Selecting Elements
4.2.3 Positioning Elements
4.2.4 Positioning Elements in Containers
4.3 Formatting Elements
4.4 Graphic Elements
4.4.1 Line
4.4.2 Rectangle and Ellipse
4.4.3 Images
4.4.4 Padding and Borders
4.5 Text Elements
4.5.1 Static Text
4.5.2 Text Fields
4.6 Frames
4.7 Inserting Page and Column Breaks
4.8 Working with Composite Elements
4.8.1 Creating and Editing Composite Elements
4.8.2 Exporting and Importing Composite Elements
4.9 Anchors, Bookmarks, and Hyperlinks
4.9.1 Anchors and Bookmarks
4.9.2 Hyperlinks
4.9.3 Hyperlink Types
4.9.4 Creating a Hyperlink
4.10 Advanced Elements and Custom Components
4.11 Custom Visualization Component
Chapter 5 Fields
5.1 Understanding Fields
5.2 Registration of Fields from a SQL Query
5.3 Registration of JavaBean Fields
5.4 Fields and Text Fields
5.5 Data Centric Exporters
5.5.1 Configuring a Report's Metadata for PDF 508 Tags
5.5.2 Configuring a Report's Metadata for Use With the JSON Data Exporter
Chapter 6 Parameters
6.1 Managing Parameters
6.2 Default Parameters
6.3 Using Parameters in Queries
6.3.1 Using Parameters in a SQL Query
6.3.2 Using Parameters with Null Values

37
38
38
38
39
39
40
40
41
45
48
48
48
48
48
49
49
49
50
51
51
51
54
55
56
57
59
60
60
61
63
63
65
66
68
68
68
71
75
75
77
79
79
79

TIBCO Software Inc.

6.3.3 IN and NOTIN Clauses
6.3.4 Relative Dates
6.3.5 Passing Parameters from a Program
6.4 Parameters Prompt
Chapter 7 Variables
7.1 Defining or Editing a Variable
7.2 Base Properties of a Variable
7.3 Other Properties of a Variable
7.3.1 Evaluation Time
7.3.2 Calculation Function
7.3.3 Increment Type
7.3.4 Reset Type
7.3.5 Incrementer Factory Class Name
7.4 Built-In Variables
7.5 Tips & Tricks
Chapter 8 Expressions
8.1
8.2
8.3
8.4
8.5
8.6
8.7

Expression Types
Expression Operators and Object Methods
Using an If-Else Construct in an Expression
Using Unicode Characters in Expressions
Using Java as a Language for Expressions
Using Groovy as a Language for Expressions
Using JavaScript as a Language for Expressions

Chapter 9 Fonts
9.1 Font Extensions Reference
9.1.1 The Fonts Page
9.1.2 The Font Family Dialog
9.1.3 Font Sets
9.2 Example of Using Font Extensions
9.2.1 Creating Font Extensions and Font Sets
9.2.2 Using Font Extensions in a Report
9.3 Deploying Font Extensions to JasperReports Server
Chapter 10 Data Adapters
10.1 Creating and Editing Data Adapters
10.1.1 Creating a Data Adapter
10.1.2 Importing and Exporting Data Adapters
10.1.3 Copying a Data Adapter
10.2 Using Data Adapters in Reports and Datasets
10.2.1 Data Adapter For a Report
10.2.2 Data Adapters and Report Deployment
10.2.3 Default Data Adapter
10.3 Working with Database JDBC Connections
10.3.1 Creating a Database JDBC Connection
10.3.2 Troubleshooting a Database JDBC Connection

TIBCO Software Inc.

80
80
83
84
87
87
87
88
88
89
89
90
90
90
91
93
93
94
96
97
97
98
99
101
101
101
103
106
107
108
112
115
119
120
120
121
122
122
122
123
123
125
125
127

TIBCO Jaspersoft Studio User Guide

10.3.3 Using a Database JDBC Connection
10.4 Working with a MongoDB Data Adapter
10.4.1 Creating a Native MongoDB Connection
10.4.2 Creating a MongoDB JDBC Data Source
10.5 Working with a Native Cassandra Connection
10.5.1 Creating a Native Cassandra Data Adapter
10.5.2 Using a Cassandra Connection
10.6 Working with a Collection of JavaBeans Data Adapter
10.6.1 Implementing the Factory Class for a Collection of JavaBeans
10.6.2 Creating a Data Adapter from a Factory Class
10.6.3 Registering the Fields
10.7 Working with XML Data Adapters
10.7.1 Creating a Node Set for an XML Document
10.7.2 Creating an XML Data Adapter
10.7.3 Registration of Fields for an XML Data Adapter
10.7.4 XML Data Adapters and Subreports
10.8 Working with XML/A Data Adapters
10.8.1 Registration of fields in XML/A Providers
10.9 Working with CSV Data Adapters
10.9.1 Registration of the Fields for a CSV Data Adapter
10.10 Using the Empty Record Data Adapter
10.10.1 Understanding the Empty Record Implementation
10.11 Working with the JRDataSource Interface
10.11.1 Understanding the JRDataSource Interface
10.11.2 Implementing a New JRDataSource
10.11.3 Using a Custom JasperReports Data Source with Jaspersoft Studio
10.12 A Look at TIBCO Spotfire Information Links
Chapter 11 Creating Queries
11.1 Using the Dataset and Query Dialog
11.2 Working with the Query Builder
11.2.1 Query Outline View and Diagram View
11.2.2 Selecting Columns
11.2.3 Joining Tables
11.2.4 Data Selection Criteria (WHERE Conditions)
11.2.5 Acquiring Fields
11.2.6 Data Preview
Chapter 12 Accessing JasperReports Server from Jaspersoft Studio
12.1 Connecting to JasperReports Server
12.1.1 Advanced Connection Settings
12.1.2 Using Single Sign-on with JasperReports Server
12.2 Publishing a Report to JasperReports Server
12.2.1 Publishing Report Resources
12.2.2 Choosing a Data Source for a Published Report
12.2.3 Example of Publishing a Report
12.3 Working with JasperReports Server Templates

129
131
132
134
136
136
138
138
139
140
141
141
141
143
145
146
148
149
149
152
152
153
153
154
154
156
157
161
161
163
163
165
166
167
168
168
169
170
171
172
174
174
174
177
179

TIBCO Software Inc.

12.3.1 Creating a Custom JasperReports Server Template
12.3.2 Report Template Styles in Jaspersoft Studio
12.4 Creating and Uploading a Topic for Ad Hoc Views
12.5 Managing Repository Objects through Jaspersoft Studio
12.5.1 Adding, Modifying and Deleting Resources
12.5.2 Running a Report
12.5.3 Editing a Report
12.6 Creating and Uploading Chart Themes
12.7 Working with Domains
12.8 Understanding the repo: Syntax
12.9 Adding a Date/Time Stamp to Scheduled Output in JasperReports Server
Chapter 13 Working with Tables
13.1 Creating a Table
13.2 Editing a Table
13.2.1 Editing Table Properties
13.2.2 Editing Table Styles
13.2.3 Editing Cell Contents
13.2.4 Editing Table Data
13.2.5 Editing Table Source
13.3 Table Structure
13.3.1 Table Elements
13.3.2 Table Cells
13.4 Working with Columns
13.4.1 Table Properties for Managing Columns
13.4.2 Working with Individual Columns
13.4.3 Column Groups
Chapter 14 Working with Charts
14.1 Creating a Simple Chart
14.2 Setting Chart Properties
14.3 Spider Charts
14.4 Chart Themes
14.4.1 Using the Chart Theme Designer
14.4.2 Editing Chart Theme XML
14.4.3 Creating a JasperReports Extension for a Chart Theme
14.4.4 Applying a Chart Theme
Chapter 15 HTML5 Charts in Commercial Editions
15.1 Overview of HTML5 Charts
15.2 Simple HTML5 Charts
15.2.1 Creating an HTML5 chart
15.2.2 Editing HTML5 Charts
15.2.3 Creating Hyperlinks
15.2.4 Setting Advanced Options for HTML5 Charts
15.3 Scatter Charts
15.4 Dual-Axis, Multi-Axis, and Combination Charts

TIBCO Software Inc.

179
182
183
184
185
186
186
187
189
190
191
195
195
201
201
201
202
203
204
204
204
205
206
206
206
207
209
209
214
214
218
218
218
218
219
221
221
227
227
230
232
233
234
238

TIBCO Jaspersoft Studio User Guide

15.5 Hyperlinks in HTML5 Charts
15.5.1 Creating Hyperlinks in HTML5 Charts
15.5.2 Working with Bucket Properties and Hidden Measures
15.5.3 Working with Report Units
Chapter 16 Working with Crosstabs
16.1 Example of Creating a Crosstab
16.2 Working with Crosstab Properties
16.3 Using the Crosstab Editor
16.3.1 Formatting Columns, Rows, and Cells
16.3.2 Editing Row or Column Group Properties
16.3.3 Adding and Deleting Row and Column Groups
16.3.4 Working with Measures
16.4 Working with Crosstab Parameters
Chapter 17 Working With the Map Component
17.1 Working with Map Properties
17.2 Viewing Authentication Properties
17.3 Working with Markers
17.3.1 Marker Properties
17.3.2 Adding Markers Manually
17.3.3 Adding Markers Using the Map
17.3.4 Adding Markers Using a Dataset
17.3.5 Modifying Markers
17.4 Working with Paths
17.4.1 Defining Path Styles
17.4.2 Defining a Path Manually
17.4.3 Defining a Path Using a Dataset
17.4.4 Modifying Paths and Path Styles
17.5 Properties for Markers and Paths
Chapter 18 Working with TIBCO GeoAnalytics Maps

251
252
257
258
258
259
261
263
267
269
269
271
272
273
273
275
276
280
281
281
283
284
285
285
289

18.1 Configuring a Basic Map
18.2 Using Expressions for Properties
18.3 Understanding Layers
18.4 Working with Markers
18.4.1 Static Markers
18.4.2 Dynamic Markers
18.5 Working with Paths

290
292
293
294
294
297
300

Chapter 19 Working with Subreports

303

19.1 Creating a New Report via the Subreport Wizard
19.2 Understanding Subreports
19.2.1 Subreports
19.2.2 Subreport Elements
19.2.3 The Expression Property
19.2.4 Specifying the Data Source
19.2.5 Subreport Parameters

241
241
245
249

303
306
306
307
308
309
309

TIBCO Software Inc.

Chapter 20 Report Templates
20.1 Template Structure
20.2 Creating and Customizing Templates
20.2.1 Creating a New Template
20.2.2 Customizing a Template
20.3 Saving Templates
20.3.1 Creating a Template Directory
20.3.2 Exporting a Template
20.3.3 Creating a Template Thumbnail
20.4 Adding Templates to Jaspersoft Studio
Chapter 21 Report Books
21.1 Creating the Report Book Framework
21.2 Creating and Adding Reports to the Report Book
21.2.1 Creating a Report for the Report Book
21.2.2 Adding a Report to the Report Book
21.3 Refining the Report Book
21.3.1 Sorting on Additional Fields
21.3.2 Adding Section Introductory Pages
21.4 Configuring the Table of Contents
21.5 Report Book Pagination
21.6 Publishing the Report Book
Chapter 22 Preferences and Configuration
22.1 Properties
22.2 JasperReports Samples
22.3 Units of Measure in Jaspersoft Studio
22.3.1 Configuration
22.3.2 Changing the Field Unit of Measure
22.3.3 Alias and Auto-complete
22.3.4 Approximations
22.4 Export and Import
22.4.1
22.5 Setting Compatibility with Earlier Versions of JasperReports Library
Appendix A Concepts of JasperReports
A.1 JRXML Sources and Jasper Files
A.1.1 The Report Lifecycle
A.2 Data Sources and Print Formats
A.3 Using JasperReports Extensions in Jaspersoft Studio
A.4 A Simple Program

313
313
315
315
317
318
318
319
321
321
323
323
325
325
325
326
326
327
328
329
330
331
331
331
331
332
332
332
333
333
335
335
339
339
339
345
345
346

Glossary

347

Index

357

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

TIBCO Software Inc.

CHAPTER 1

GETTING STARTED WITH JASPERSOFT STUDIO

Jaspersoft Studio is the latest incarnation of the well-known iReport Editor. Because it is built on the Eclipse
platform, Jaspersoft Studio is a more complete solution that allows users to extend its capabilities and
functionality.
This chapter contains the following sections:
•
•
•

1.1

Introduction to Jaspersoft Studio
Installing Jaspersoft Studio
Exporting Reports with Jaspersoft Studio

Introduction to Jaspersoft Studio
Jaspersoft Studio is an Eclipse-based report designer for JasperReports Library and JasperReports Server; it's
available as an Eclipse plug-in or as a stand-alone application. Jaspersoft Studio allows you to create
sophisticated layouts containing charts, images, subreports, crosstabs, and more. You can access your data
through a variety of sources including JDBC, TableModels, JavaBeans, XML, Hibernate, Big Data (such as
Hive), CSV, XML/A, as well as custom sources, then publish your reports as PDF, RTF, XML, XLS, CSV,
HTML, XHTML, text, DOCX, or OpenOffice.
TIBCO JasperReports® Server builds on TIBCO JasperReports® Library as a comprehensive family of Business
Intelligence (BI) products, providing robust static and interactive reporting, report server, and data analysis
capabilities. These capabilities are available as either stand-alone products, or as part of an integrated end-to-end
BI suite utilizing common metadata and provide shared services, such as security, a repository, and scheduling.
The server exposes comprehensive public interfaces enabling seamless integration with other applications and
the capability to easily add custom functionality.
This section describes functionality that can be restricted by the software license for JasperReports
Server. If you don’t see some of the options described in this section, your license may prohibit you from
using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft.

The heart of the TIBCO Jaspersoft® BI Suite is the server, which provides the ability to:
•
•
•
•

Easily create new reports based on views designed in an intuitive, web-based, drag and drop Ad Hoc
Editor.
Efficiently and securely manage many reports.
Interact with reports, including sorting, changing formatting, entering parameters, and drilling on data.
Schedule reports for distribution through email and storage in the repository.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

•

Arrange reports and web content to create appealing, data-rich Jaspersoft Dashboards that quickly convey
business trends.

For users interested in multi-dimensional modeling, we offer Jaspersoft® OLAP, which runs as part of the server.
While the Ad Hoc Editor lets users create simple reports, more complex reports can be created outside of the
server. You can either use Jaspersoft® Studio or manually write JRXML code to create a report that can be run
in the server. We recommend that you use Jaspersoft Studio unless you have a thorough understanding of the
JasperReports file structure.
You can use the following sources of information to learn about JasperReports Server:
•

•

Our core documentation describes how to install, administer, and use JasperReports Server and Jaspersoft
Studio. Core documentation is available as PDFs in the doc subdirectory of your JasperReports Server
installation. You can also access PDF and HTML versions of these guides online from the Documentation
section of the Jaspersoft Community website.
Our Ultimate Guides document advanced features and configuration. They also include best practice
recommendations and numerous examples. You can access PDF and HTML versions of these guides online
from the Documentation section of the Jaspersoft Community website.
Our Online Learning Portal lets you learn at your own pace, and covers topics for developers, system
administrators, business users, and data integration users. The Portal is available online from Professional
Services section of our website.
Our free samples, which are installed with JasperReports Library, Jaspersoft Studio, and JasperReports
Server, are documented online.

JasperReports Server is a component of both a community project and commercial offerings. Each integrates the
standard features such as security, scheduling, a web services interface, and much more for running and sharing
reports. Commercial editions provide additional features, including Ad Hoc charts, flash charts, dashboards,
Domains, auditing, and a multi-organization architecture for hosting large BI deployments.

1.2

Installing Jaspersoft Studio
Jaspersoft Studio is available as an Eclipse Rich Client Package (RCP), downloadable from the following
location:
http://community.jaspersoft.com/project/jaspersoft-studio/releases.

1.2.1

Software Requirements
Jaspersoft Studio requires the Java Runtime Environment (JRE). To compile the report scriptlets, a full
distribution of Java is required. The JSS installer includes the required version of Java.
During the JSS download, you must accept the Java license agreement and select the correct operating system.
Jaspersoft Studio supports the following common operating systems:
•
•
•

Windows 7/8, 32 or 64 bit
Linux, 32 or 64 bit
MacOS X, 64 bit

TIBCO Software Inc.

Chapter 1 Getting Started with Jaspersoft Studio

1.2.2

Hardware Requirements
Jaspersoft Studio needs a 64-bit or 32-bit processor and at least 500 MB of Hard Disk space. The amount of
RAM needed is dependent upon report complexity. A value of 1 GB dedicated to Jaspersoft Studio is
recommended, 2 GB is suggested.

1.2.3

Available Packages
The Eclipse RCP package is available in the following formats for community and commercial versions.
Linux versions:
•
•

TIBCOJaspersoftStudio-x.x.x.final-linux-x86.tgz
TIBCOJaspersoftStudio-x.x.x.final-linux-x86_64.tgz

Mac:
•

TIBCOJaspersoftStudio-x.x.x.final-mac-x86_64.dmg

Windows:
•
•

TIBCOJaspersoftStudio-x.x.x.final-windows-installer-x86.exe
TIBCOJaspersoftStudio-x.x.x.final-windows-installer-x86_64.exe

x.x.x represents the version number of Jaspersoft Studio.
Note that on a 64-bit operating system you can install the 32-bit version of Jaspersoft Studio (although the 64bit is recommended), but you cannot install the 64- bit version of Jaspersoft Studio on a 32-bit operating system.
For community only, unsupported versions for the Eclipse RCP on Windows and Debian are available as a
convenience for users who are in a restricted environment and can't download or install an .exe. file:
•
•
•
•

TIBCOJaspersoftstudio_x.x.x.final_amd64.deb
TIBCOJaspersoftstudio_x.x.x.final_i386.deb
TIBCOJaspersoftStudio-x.x.x.final.win32.x86_64.zip
TIBCOJaspersoftStudio-x.x.x.final.win32.x86.zip

The community version is also available as an unsupported Eclipse plug-in, called the Jaspersoft Studio plugin.
You can install it from the Eclipse Marketplace or download using the Eclipse Update Manager. See the
following article on the community website for more information about working with the Jaspersoft Studio
plugin.
http://community.jaspersoft.com/wiki/contributing-jaspersoft-studio-and-building-sources

1.2.4

Updating Your Workspace to Jaspersoft Studio 6.2 and Higher
Due to incompatibilities between Eclipse 4.5 and earlier versions of the Jaspersoft Studio workspace, the
workspace format has been updated in Jaspersoft Studio 6.2. The new workspace format can't be used with
Jaspersoft Studio 6.1.1 or earlier.
If you are updating to 6.2 or higher from Jaspersoft Studio 6.1.1 or earlier, you are prompted to choose a new
workspace when you launch Jaspersoft Studio. When you choose a new workspace, a new, empty workspace is
created and set as the workspace for your Jaspersoft Studio instance. This workspace will be used for versions
6.2 and higher. Your previous workspace remains unchanged and can still be used for versions 6.1.1 or earlier.
To update the reports and data from your earlier version of Jaspersoft Studio to version 6.2 or higher, you can
import some or all of your projects, server connections, data adapters, and project settings into your new
workspace.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Importing projects:
1. (Optional) To import a version of the MyReports project, you must first delete the existing MyReports
folder from your current workspace. You can do this, for example, if you have just upgraded to 6.2 or
higher and have created a new empty workspace. To delete MyReports in your current workspace, navigate
to the workspace location in your file system and delete or move the MyReports directory.
2.

Select File > Import ...

Select Existing Projects into Workspace from the General category.

Figure 1-1 Selecting projects in Import dialog
4.

Browse to the workspace with you want, click OK, and then click Next.
The Import dialog opens.

TIBCO Software Inc.

Chapter 1 Getting Started with Jaspersoft Studio

Figure 1-2 Import Projects dialog
5.

To work on a copy without modifying the originals, select Copy projects into workspace.

Click Finish.
The projects you selected are imported into your current workspace.

Your workspace contains server connections, global data adapters, and your Jaspersoft Studio preferences in
addition to your projects. You must import each type separately.
Importing server connections:
1. Select File > Import ....
2.

Select External JasperReports Server Connections from the Jaspersoft Studio category.

Browse to the workspace with you want, click OK, and then click Next.
The Select the Server Connections dialog opens.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Figure 1-3 Select the Server Connections dialog
4.

Choose the connections you want.

Click Finish to import the connections.
The selected server connections are imported into your Jaspersoft Studio instance.

Importing data adapters and settings:
1. Select File > Import ....
2.

Select External Properties and Data Adapters from the Jaspersoft Studio category.

Browse to the workspace with you want, click OK, and then click Next.
The Select the Data Adapters dialog opens.

Figure 1-4 Select the Data Adapters dialog

TIBCO Software Inc.

Chapter 1 Getting Started with Jaspersoft Studio

Choose the data adapters you want. You do not need to import the built-in adapters (One Empty Record
and Sample DB).

Click Next.

Figure 1-5 Select the properties dialog
6.

1.2.5

Choose the properties you want and click Finish.
The selected data adapters and properties are imported into your Jaspersoft Studio instance.

Compatibility Between Versions
When a new version of JasperReports is distributed, some classes usually change. These modified classes
typically impact the XML syntax and the JASPER file structure.
Before JasperReports 1.1.0, this was a serious problem and a major upgrade deterrent, since it required
recompiling all the JRXML files in order to be used with the new library version. Things changed after the
release of Version 1.1.0, in which JasperReports assured backwards compatibility, that is, the library is able to
understand and execute any JASPER file generated with a previous version of JasperReports.
With JasperReports 3.1, the JRXML syntax moved from a DTD-based definition to XML-based schema. The
XML source declaration syntax now references a schema file, rather than a DTD. Based on what we said
previously, this is not a problem since JasperReports assures backwards compatibility. However, many people
are used to designing reports with early versions of iReport then generating the reports by compiling JRXML in

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

JasperReports. This was always a risky operation, but it was still valid because the user was not using a new tag
in the XML. With the move to an XML schema, the JRXML output of iReport 3.1.1 and newer can only be
compiled with a JasperReports 3.1.0 or later. All versions of Jaspersoft Studio produce output that is only
compatible with later versions of JasperReports Library.
For information on exporting or compiling a report to an earlier version of JasperReports Library, see 22.5,
“Setting Compatibility with Earlier Versions of JasperReports Library,” on page 335.

1.2.6

Accessing the Source Code
The last version of the source code is available from http://community.jaspersoft.com/project/jaspersoftstudio/releases by clicking Browse Source Code, which lets you access the Subversion (SVN) repository
(read only mode) where the most up-to-date version is available. You can download and compile this source
code, but since it is a work in progress it might contain new, unreleased features and bugs. All the information
necessary to download the Source Code, configure a development environment on the Eclipse IDE, and compile
and run the source code are described in the tutorial "Contributing to Jaspersoft Studio and building from
sources".

TIBCO Software Inc.

CHAPTER 2

CREATING A SIMPLE REPORT

JasperReports Library is a powerful tool, and Jaspersoft Studio exposes much of its functionality to help you
design reports. This chapter introduces the basic steps for defining a report and includes the following sections:
•
•
•
•

2.1

Creating a New Report
Adding and Deleting Report Elements
Previewing a Report
Creating a Project Folder

Creating a New Report
To create a new report:
1.

Go to File > New > Jasper Report or click

on the main toolbar.

The New Report Wizard window displays the Report Templates page. Jaspersoft Studio includes a
number of pre-installed templates; you can also create your own. See Chapter 20, “Report Templates,” on
page 313 for more information.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Figure 2-1 New Report Wizard
2.

Select the Coffee template and click Next. The New Report Wizard shows the Report file page.

Figure 2-2 New Report Wizard > Report file

TIBCO Software Inc.

Chapter 2 Creating a Simple Report

Navigate to the folder you want the report in and name the report. To create a new folder, see “Creating a
Project Folder” on page 25.

Click Next.
The Data Source dialog opens. This is where you choose the data that will fill the report.The drop-down
menu shows the pre-installed data adapters as well any data adapters you have added. The following
adapters are pre-installed:
•
•

One Empty Record - Empty rows: Data adapter that lets you create a report without data. You
might use this option to define the layout of a report and connect it to a data source later.
Sample DB - Database JBDC Connection: Data adapter that connects to an SQL database
provided with the Jaspersoft Studio installation. If you are getting your data from a JDBC database, you
must also supply an SQL query.
You can create a data adapter separately or click New... to create a data adapter directly from this dialog.
Adapters can be created globally (embedded in the workspace) or local to a specific project. Using a
local adapter makes it easier to deploy the report to JasperReports Server. See 10.1, “Creating and
Editing Data Adapters,” on page 120 for more information.

Choose Sample DB - Database JDBC Connection. Enter the query select * from orders.

Figure 2-3 New Report Wizard > Data Source
6.

Click Next. The Fields window appears. The Dataset list shows all the discovered fields.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Figure 2-4 New Report Wizard > Fields
7.

Select the following fields and click the right arrow to add them to your report.

• ORDERID
• SHIPNAME
• SHIPADDRESS
• SHIPCITY
• SHIPREGION
Click Next. The Grouping window appears.

Click Next and Finish.
Jaspersoft Studio now builds the report layout with the selected fields included as shown.

Figure 2-5 New Report in the Design Tab

TIBCO Software Inc.

Chapter 2 Creating a Simple Report

2.2

Adding and Deleting Report Elements
You can add and delete fields and other elements to your report.

2.2.1

Adding Fields to a Report
To add fields to an already created report:
1. Select the main node of the report from the Outline view.
2.

Select the Report tab in the Properties view and click the Edit query, filter and sort options button in
the Dataset section.

Figure 2-6 Dataset section in properties view
The Dataset and Query Dialog opens.

Figure 2-7 Dataset and Query Dialog

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Add more fields by clicking the Read Fields button. All the fields discovered are added as new fields in
the report.
You can also change your query in the same dialog. If a new query discovers fewer fields than used in the
existing report, the fields not included the new query are removed from your report.

Click OK to return to the Design tab.

Expand Fields in the Outline view to see all the fields now available for your report.

Figure 2-8 Fields
6.

2.2.2

To add a field to your report, click the field and drag it into the Design.
When the field object is dragged inside the detail band, Jaspersoft Studio creates a text field element and
sets the text field expression for that element.

Deleting Fields
To delete a field from a report, right click the field in the Design and select Delete.

2.2.3

Adding Other Elements
To add other elements, such as lines, images, or charts, drag the element from the Palette into the Design. See
4.2.1, “Inserting Elements,” on page 39 for more information.

2.3

Previewing a Report
Click the Preview tab at the bottom of the report. The preview compiles the report in the background with data
retrieved by the query through your JDBC connection. The Detail band repeats for every row in the query
results, creating a simple table report:

TIBCO Software Inc.

Chapter 2 Creating a Simple Report

Figure 2-9 Report Preview
Each subreport is saved in a separate report file. Reflecting standard Eclipse design, saving or
previewing a report that contains subreports does not update the subreports. When you edit a subreport,
you must first build the subreport and then save the file in order for the subreport changes to be visible
when you preview the report that contains it.
•
•

2.4

To build a subreport explicitly, use the Build All button on the toolbar, or type Ctrl-B. Alternatively,
select Project > Build Automatically to have Jaspersoft Studio do it for you.
To save a subreport, use File > Save or File > Save As.

Creating a Project Folder
Project folders help you organize your reports.
To create a project folder:
1. Choose File > New > Project. The Select a wizard dialog appears.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Figure 2-10 Select a Wizard
2.

Enter Jasper in the Wizards bar to filter actions to those related to Jaspersoft Studio

Select JasperReports Project. Click Next. The New JasperReports Project wizard appears.

Enter a name for your project and click Finish. The Project Explorer displays your project.

Figure 2-11

TIBCO Software Inc.

CHAPTER 3

USER INTERFACE AND DESIGN VIEW

Jaspersoft Studio is based on the Eclipse platform. If you have worked with Eclipse, you are likely familiar with
the user interface. Figure 3-1 shows a preview of the Jaspersoft Studio interface, with the main areas
highlighted. Some views have additional menus and actions, accessed through icons in the upper right of the
view.

Figure 3-1 Jaspersoft Studio User Interface

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

3.1

Eclipse Interface
In Eclipse terminology, the initial layout of the Jaspersoft Studio interface is called a perspective. The default
Jaspersoft Studio perspective contains an editor area and views. Some views appear by themselves, while others
are stacked together in tabbed notebooks. You can open and close views and drag them to different positions in
the Eclipse workbench.
•
•
•

3.1.1

To open a window you have closed, select Window > Open View from the menu. Select the window you
want to open from the drop-down list.
To reset the interface to the default perspective, select Window > Reset Perspective.
To save a perspective, select Window > Save Perspective As and enter a name for your perspective.

Learning More About Eclipse
If you are not familiar with Eclipse, there are many excellent resources available:
•
•
•

The Eclipse help is a good place to start. You can access Eclipse help by selecting Help > Subclipse Subversion Eclipse Plugin.
If you are setting up Eclipse for a team, search the internet for a phrase such as "configuration management
for Eclipse".
To work with version control such as CSV, Git, or SVN, use the corresponding Eclipse perspective
included with Jaspersoft Studio. To add a different perspective, click
at the upper right of the Eclipse
interface and select the perspective you want from the Open Perspective dialog. Once a perspective has
been added, you will see an icon for it at the top right. Use this perspective for all interactions with your
version control repository, such as checking out projects, synchronizing files, and resolving conflicts. For
information about working with a particular package, use an internet search such as "Eclipse Subversion".
To return to the Jaspersoft Studio perspective, click

3.2

User Interface Components
Jaspersoft Studio has a multi-tab editor, which includes three tabs that allow you to interact with your reports in
different ways: Design, Source, and Preview:
•
•
•

The Design tab is the main one selected when you open a report file and it allows you to graphically create
your report.
The Source tab contains the JRXML source code for your report.
The Preview tab lets you run the report preview after having selected a data source and output format.

You can explore the data using the following views:
•
•
•

•

The Repository Explorer view maintains the list of JasperReports Server connections and available data
adapters.
The Project Explorer view maintains the list of the projects in the current workspace, usually a Jaspersoft
Studio project.
The Outline view shows the complete structure of the report in a tree. When the Design or Source tab is
active, clicking an element in the Outline view highlights that element in the editor. The Outline tab is
empty when the Preview tab is active.
The Properties view lets you view and edit the properties of the element that is currently selected in the
report editor or in the Outline view. The properties shown depend on the type of element. For example, the
Properties view for a table shows four tabs: Appearance, Dataset, Table, and Advanced, while the Properties
view for a line shows Appearance, Borders, Line, Inheritance, and Advanced. Some properties are read-only,

TIBCO Software Inc.

Chapter 3 User Interface and Design View

but most are editable. When the root node of a report is selected in Outline view, the Properties view shows
the properties for the report.
Unlike many other views, you can open multiple instances of the Properties view at one time and you can
pin a selection to a specific Properties view instance. This allows you to view or edit the properties for a
specific element while working with other elements in your report, or with another report entirely.
•

The Problems view shows a list of problems and errors that can, for example, block the correct compilation
of a report.
The Report state summary provides statistics on report compilation/filling/execution. Errors are shown here
as well.

•

This comparison table shows the differences in terminology between iReport and Jaspersoft Studio.
Table 3-1 Comparison of Features in iReport and Jaspersoft Studio

3.3

iReport

Jaspersoft Studio

JasperReports Server Repository

Repository Explorer

Report Inspector

Outline view

Report Designer

Report editing area

Problems List

Problems view

Elements palette

Designer Palette

Formatting tools

Available via context menu on the element

Property sheet

Properties view

Styles library

---

Project Explorer

iReport Output window

Report State summary

The Design Tab
You design a report using the Design tab, which is divided into different horizontal portions, named bands,
where you can place report elements. When the report design is combined with the data to generate the print,
each band is printed multiple times based on its function (and according to the rules that the report designer has
set). For instance, the page header is repeated at the beginning of every page, while the detail band is repeated
for each record.
Jaspersoft Studio provides a graphical interface for creating JRXML files. The layout is visual, so you can
ignore the underlying structure of the JRXML. You can specify the precise page locations of different types of
text and data, such as title, footers, detailed records, groups, and summary information. Some portions of a page
defined in this way are reused, others stretch to fit the content, and so on. Additional tools let you add charts
and subreports, set up an optional query retrieve data out of a data source, and more.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

3.4

Understanding Bands
The Design tab is divided into nine predefined bands to which new groups are added. In addition, Jaspersoft
Studio manages a heading band (group header) and a recapitulation band (group footer) for every group.
A band is as wide as the page width (right and left margins excluded). However, its height, even if it is
established during the design phase, can vary during print creation according to the contained elements; it can
“lengthen” toward the bottom of a page in an arbitrary way. This typically occurs when bands contain
subreports or text fields that have to adapt to the content vertically. Generally, the height specified by the user
should be considered “the minimal height” of the band. Not all bands can be stretched dynamically according
to content; in particular the column footer, page footer, and last page footer bands are statically sized.
The sum of all band heights (except for the background) has to always be less than or equal to the page height
minus the top and bottom margins.

3.4.1

Band Types
The following table contains brief descriptions of the available bands:

Band Name

Description

Title

The title band is the first visible band. It is created only once and can be printed on a
separate page. It is not possible during design to exceed the report page height (top and
bottom margins are included). If the title is printed on a separate page, this band height is
not included in the calculation of the total sum of all band heights.

Page Header

The page header band allows you to define a page header. The height specified during the
design phase usually does not change during the creation process, except for the insertion
of vertically resizable components such as text fields. The page header appears on all
printed pages in the position defined during the design phase. Title and summary bands do
not include the page header when printed on a separate page.

Column Header

The column header band is printed at the beginning of each detail column. Usually labels
containing the column names of a tabular report are inserted in this band.

Group Header

A report can contains zero or more group bands which permit the collection of detail records
in real groups. A group header is always accompanied by a group footer (both can be
independently visible or not). Different properties are associated with a group. They
determine its behavior from the graphic point of view. It is possible to always force a group
header on a new page or in a new column and to print this band on all pages if the bands
below it overflow the single page (as a page header, but at group level). It is possible to fix a
minimum height required to print a group header: if it exceeds this height, the group header
band is printed on a new page (please note that a value too large for this property can
create an infinite loop during printing).

Group Footer

The group footer band completes a group. Usually it contains fields to view subtotals or
separation graphic elements, such as lines.

TIBCO Software Inc.

Chapter 3 User Interface and Design View

3.5

Band Name

Description

Column Footer

The column footer band appears on at the end of every column. Its dimension are not
resizable at run time (not even if it contains resizable elements such as subreports or text
fields with a variable number of text lines).

Page Footer

The page footer band appears on every page where there is a page header. Like the
column footer, it is not resizable at run time.

Last Page
Footer

If you want to make the last page footer different from the other footers, it is possible to use
the special last page footer band. If the band height is 0, it is completely ignored, and the
layout established for the common page is used for the last page.

Summary

The summary band allows you to insert fields containing total calculations, means, or any
other information you want to include at the end of the report.

Background

The background enables you to create watermarks and similar effects, such as a frame
around the whole page. It can have a maximum height equal to the page height.

Specifying Report Properties
To view or edit report properties, select the report root node in the Outline view. The report properties are
shown in the Properties view.
To change the page dimensions of a report, click the Report tab in the Properties view for the report, then click
Edit Page Format. In the Page Format dialog that appears, you can edit the width, height, units, orientation
and margins of the report.
The unit of measurement used by Jaspersoft Studio and JasperReports is the pixel. However, it is possible to
specify report dimension using other units of measurement, such as centimeters, millimeters, or inches. Note that
because the dimensions management is based on pixels, some rough adjustments can take place when viewing
the same data using different units of measurement. The following table shows standard page sizes and their
dimensions in pixels.
Page Type

Dimensions in Pixels

Letter

612x792

Note

540x720

Legal

612x1008

2380x3368

1684x3368

1190x1684

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Page Type

Dimensions in Pixels

842x1190

595x842

421x595

297x421

210x297

148x210

105X148

A10

74X105

2836x4008

2004x2836

1418x2004

1002x1418

709x1002

501x709

ARCH_E

2592x3456

ARCH_D

1728x2593

ARCH_C

1296x1728

ARCH_B

864x1296

ARCH_A

648x864

FLSA

612x936

FLSE

612x936

HALFLETTER

396x612

11X17

792x1224

LEDGER

1224x792

TIBCO Software Inc.

Chapter 3 User Interface and Design View

By modifying width and height, it is possible to create a report of whatever size you like. Although Jaspersoft
enables you to create pixel-perfect reports, the page orientation options, Landscape or Portrait, are there because
they are used by certain report exporters. The page margin dimensions are set by means of the four options on
the Page Margin tab.

3.5.1

Columns
Pages, one or more of which make up a report, present bands that are independent from the data (such as the
title or the page footers) and other bands that are printed only if there are one or more data records to print (such
as the group headers and the detail band). These last sections can be divided into vertical columns in order to
take advantage of the available space on the page. A column does not concern the record fields, but it does
concern the detail band. This means that if you have a record with ten fields and you desire a table view, ten
columns are not needed. However, the element must be placed correctly to have a table effect. Ten columns are
returned when long records lists (that are horizontally very narrow) are printed.
Next, let's set up columns in a report as an example. Create a new report from File > New > Jasper Report.
Choose as template BlankA4 and name it ColumnExample. Use Sample DB - Database JBDC Connection
for the data adapter, with the following SQL query: select * from orders. Fields from the database are
discovered. Double-click SHIPNAME, to add it to the report field and click Next twice. Finally, click Finish.
From the outline view drag the SHIPNAME field in the report in the detail band, resize the detail band, and
remove the unused bands. Go to the Preview tab to see the compiled report.
By default the number of columns is 1, and its width is equal to the entire page, except the margins. The space
between columns is zero by default. Most of the page is unused. If multiple columns are used, this report would
look better. On the Page Format dialog set the number of columns to two and compile the report to see the
changes.
Jaspersoft Studio automatically calculates maximum column width according to the margins and the page width.
If you want to increase the space between the columns, increase the value of the Space field.
The restricted area is used to mark every column after the first, to show that all the elements should be placed in
the first column; the other columns are replicated automatically during compilation. If you want you can also
put elements in the other columns, but in most cases you need only the first. It is not recommended that you use
parts of the report as margins and columns after the first, if they have to be considered as though they were a
continuation of the first.
Multiple columns are commonly used for print-outs of very long lists (for example, a phone directory). It is
important to remember that when you have more than one column, the width of the detail band and of linked
bands is reduced to the width of the columns.
The sum of the margins, column widths, and space between columns has to be less than or equal to the page
width. If this condition is not met, the compilation results in an error.

3.5.2

Advanced Options
From the Properties view of the report there are many other options for the report configuration. Select the
report root node from the outline view, and in the Properties view you see:
•

Report Name: It is a logical name, independent from the source file's name, and is used only by the
JasperReports library (for example, to name the produced Java file when a report is compiled).

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

•

•
•

•

3.6

Title on a new page: This option specifies that the title band is to be printed on a new page, which forces
a page break at the end of the title band. In the first page only the title band is printed. However this page
is still included in total page count.
Summary on a new page: This option is similar to Title on a new page except that the summary band
is printed as the last page. If you need to print this band on a new page, the new page only contains the
summary band.
Summary with page header and footer: This option specifies if the summary band is to be accompanied
by the page header and the page footer.
Floating column footer: This option forces the printing of the column footer band immediately after the
last detail band (or group footer) rather than the end of the column. This option is used, for example, when
you want to create tables using the report elements.
When no data type: When an empty data is supplied as the print number (or the SQL associated with the
report returns no records), an empty file is created (or a stream of zero bytes is returned). This default
behavior can be modified by specifying what to do in the case of absence of data. The possible values for
this field are:
• No Pages: This is the default value; the final result is an empty buffer.
• Blank Page: This returns an empty page.
• All Sections No Detail: This returns a page containing all bands except for the detail band.

Exporting Reports with Jaspersoft Studio
In addition to generating and viewing reports, Jaspersoft Studio allows you to export reports into many formats,
including PDF, XLS, HTML and others.

3.6.1

Compiling the Report
When you select the Preview tab in the designer bottom bar, Jaspersoft Studio performs a set of operations to
create the final report. The first operation compiles the JRXML source file in a Jasper file. This first step can fail
if the elements are not correctly positioned (for example, if an element is placed outside of a band), or if an
expression in the report has errors and cannot be compiled.
If the compilation runs successfully, the produced Jasper file is loaded and filled using the active connection or
data source. This second operation can also lead to errors. This can happen if the referenced database is not
active, an invalid query has been provided, or a null field produced an error in an expression during the filling
process. If all operations complete without error, the report is displayed in the integrated viewer. Errors are
shown in the Report State window, after clicking the Errors button.
If errors occur during the compilation, the tab focus changes from Preview to Design.

3.6.2

Preview and Exporting
If the compilation completes and there are no errors in the file, the preview is shown. From there you can
browse the generated report and change its visualization, change the data source or export the report. Note that
after changing the data source the report is recompiled automatically. You can also change the preview format
as well as save the report in different formats.
When you set a preview format, the report is automatically regenerated in the chosen format, and the
corresponding viewer application is opened.

TIBCO Software Inc.

Chapter 3 User Interface and Design View

3.6.3

Choosing Report Templates for PDF
If you are exporting your report to PDF, choose a report template based on the size of the output.
•
•

•

For most PDF exports, you can use Actual Size, which supports a maximum size of 14400px by 14400px.
For reports with an output height exceeding 14400 px, use a paginated report template that is wide enough
for your report. For example, if you have a long report with width less than 842px, you can use the
paginated A4 Landscape theme. A report designer can create additional custom templates in Jaspersoft
Studio.
Reports with output width exceeding 14400 px will be truncated in PDF.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

TIBCO Software Inc.

CHAPTER 4

REPORT ELEMENTS

The basic building block of a report is the element. An element is a graphical object, such as a text string or a
rectangle. In Jaspersoft Studio, the concept of line or paragraph does not exist, as it does in word processing
programs. Everything is created by means of elements, which can contain text, create tables, display images, and
so on. This approach follows the model used by the majority of report authoring tools.
Jaspersoft Studio relies on all the basic elements provided in the JasperReports library:
•
•
•
•
•
•
•
•
•
•
•

Line
Rectangle
Ellipse
Static text
Text field (or simply Field)
Image
Frame
Subreport
Crosstab
Chart
Break

Combining these elements, you can produce every kind of report. JasperReports also allows developers to
implement their own generic elements and custom components for which they can add support in Jaspersoft
Studio to create a proper plug-in.
This chapter contains the following sections:
•
•
•
•
•
•
•
•
•

Common Element Properties
Inserting, Selecting, and Positioning Elements
Formatting Elements
Graphic Elements
Text Elements
Frames
Working with Composite Elements
Anchors, Bookmarks, and Hyperlinks
Custom Visualization Component

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

4.1

Common Element Properties
All elements have a set of common properties. Other properties are specific to element type. An element's
properties determine its appearance and position on the page. You can access the properties of a selected
element in the Properties view (by default in the upper right area of the UI). In Jaspersoft Studio you place
elements within bands (containers). Depending on the elements it contains, you can change the vertical size of a
band.

4.1.1

The Palette
Elements appear in the Palette, located by default in the top right of the UI.

Figure 4-1 Elements in the Palette
The palette contains three subpalettes:
•
•
•

4.1.2

Basic Elements contains the elements and components available in all editions of Jaspersoft Studio.
Composite Elements contains elements created as combinations of other elements, such as Page Number and
Time. You can add your own composite elements to any palette.
Components Pro contains elements only available in commercial versions of Jaspersoft Studio. This
subpalette is not visible in the community edition.

Element Properties
Element properties are divided into categories, visible via tabs in the Properties view. The attributes available
depend on the element type.

TIBCO Software Inc.

Chapter 4 Report Elements

Figure 4-2 Properties view for a rectangle
•
•
•

The Appearance tab allows you to set the location, size, color, and text style of the element.
The Borders tab allows you to set the padding and border style, color, and width of the element.
An element tab allows you to set evaluation time along with properties specific to the element type. For
example:
• The Static Text tab allows you to define unchangeable text for a field, and control its appearance.
• The Text Field tab allows you to format and position a text field element.
• The Image tab allows you to set image alignment, fill, and scale properties.
Some elements have more than one element-specific tab. For example, the Chart component has the Chart
and Chart Plot tabs, and the Map component has the Map, Authentication, Markers, and Paths tabs.

•

The Inheritance tab allows you to view any attributes inherited from another level, and override those
attributes when possible.
The Hyperlink tab, available for image, text field, and chart elements, allows you to define a hyperlink in
an element.
The Advanced tab displays detailed information about the element.

•
•

Frequently, the value of an attribute is undefined, and it has a common default value. This means that the
element does not have a specific behavior defined, but gets a behavior from somewhere else. For example, the
default value of the attribute "background color" is undefined in most of cases, but when a non-transparent
element is added to a report in the design tab, you can see that it has a white background. The value of the
background color attribute is inherited from a lower level.

4.2

Inserting, Selecting, and Positioning Elements

4.2.1

Inserting Elements
When you insert an element, you can let Jaspersoft Studio autosize it, or you can size it as you insert it. Setting
the size of an element when you insert it is useful for tabular elements such as tables and crosstabs.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

To let Jaspersoft Studio autosize an element:
• Drag an element from the palette to place it in the report editing area.
To size an element at insertion time:
•

4.2.2

Selecting Elements
•
•
•

•

4.2.3

Click on the element in the palette. The cursor changes
to show that an element is selected. Click and
drag in the report editing area to size and place the element. If you insert a crosstab or table using click and
drag, the columns fill the whole crosstab or table.

Click to select an element in the report editing area.
Drag to adjust the element's position or change its size by selecting it and dragging a corner of the selection
frame.
To select several elements at the same time drag the cursor in a rectangle around them. When two or more
elements are selected, only their common properties are displayed in the Properties view. If the values of the
properties are different, the value fields are blank (usually the field is shown empty). To edit properties
unique to one element, select only that element.
Shift-click to select the parent of the current object. For example, shift-click an element contained directly
in a band to select the band.

Positioning Elements
Jaspersoft Studio offers a number of ways to place the elements in your report with precision.

4.2.3.1 Using the Grid
To show a grid for aligning elements in the page, go to View > Show Grid from the main menu. To force the
elements to snap to the grid, also select Snap to Grid.
4.2.3.2 Using Bands
The top and left values that define the element’s position are always relative to the parent container (a band or
frame).
If you want to move an element from one band to another or to a frame, drag the element node from the Outline
view to the new band (or frame) node.
In the report editing area, you can drag an element from one band to another band, but the element’s parent
band does not change. In general, an element must stay in its band, but there are exceptions to this rule. For
example, you can move an element anywhere in the report without changing or updating the parent band.
4.2.3.3 Guides
When dragging or resizing an element, Jaspersoft Studio suggests places to align it based on the elements
currently in the Design tab, the band bounds, and any guides. When the element you're moving or resizing is in
line with another element in the report, a guideline appears, allowing you align the elements. To force elements
to align with guidelines, select View > Snap to Guides from the main menu.
You can drag and change the position of a guideline at any time with no effect on the element’s position.
To remove a guideline, drag it to the upper-left corner of the report editing area.

TIBCO Software Inc.

Chapter 4 Report Elements

4.2.3.4 The Properties View
You can use the Properties view to edit an element’s properties. By default the Properties view is at the right
side of the UI. The Properties view is for more than just elements. You'll use it to edit all the components of a
report. When you select something in the designer or the Outline view, the Properties view shows the options
specific to that object.

4.2.4

Positioning Elements in Containers
Some elements that can contain many other elements are called containers. Containers include bands, frames,
table cells, and crosstab cells. The following tools help you position items inside containers:
•
•

Sizing tools – Let you size an element to fit the height, width, or entire container.
Container layouts – Let you set how elements are automatically arranged in a container.

Elements inside containers must obey the following rules.
•
•
•

Elements in table cell, and crosstab cells must be fully contained by the parent in the design time.
Otherwise, an error will occur at compilation time.
Elements in bands can extend horizontally past the document margins and/or overflow the top of the band.
Otherwise, an error will occur at compilation time.
Frames are able to adapt their size to content.

4.2.4.1 Container Layouts
A container layout is a design-time tool that adjusts the size and the position of elements when they are added
to or removed from a container. The concept of layout is specific to Jaspersoft Studio and works only at design
time. Layouts don't make a report stretchable or resizable. At run-time, depending on the design, JasperReports
Library may still let elements overlap or change their position relative to other elements.
There are four container layouts:
•
•
•
•

Free layout (default)
Horizontal layout
Vertical layout
Grid layout

To choose a layout:
•

Right-click in the container select Arrange in Container from the menu, then select the layout you want.
or

•

Click on the container and then select the option you want from the Layouts menu on the Appearance tab
of the Properties view. This is the only way to return to Free Layout after you have selected a different
layout.

4.2.4.2 Working with Grid Layout
Grid layout positions elements in a container in a grid of rows and columns. By setting properties on individual
elements, you can control the element's placement in the grid, as well as influence the overall height of the rows
and width of the columns. Elements can span multiple rows and/or columns. If you resize the container during
design, the elements are resized based on their properties.
When grid layout is selected for a container, such as a band, elements inside the container have a Layout
section on the Appearance tab of the Properties dialog. The following table shows the properties you can set on
a element in a container with grid layout. The property name to use in source view is included in the
description.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Property

Value

Description

Row
Number

Relative (default) or an
integer between 0 and
1000

Number of the row from which this element starts. 0 is the first row.
When set to Relative, increments the last evaluated row by 1.

Relative (default) or an
integer between 0 and
250

Number of the column from which this element starts. 0 is the first
column. When set to Relative, increments the last evaluated column
by 1.

Column
Number

com.jaspersoft.layout.grid.y

com.jaspersoft.layout.grid.x
Row
Span

Integer between 0 and
1000; default = 1

Number of rows that the element spans.

Column
Span

Integer between 0 and
250; default = 1

Number of columns that the element spans

Fixed
Size

Boolean; default = false.

Set to true to manually size the element. Set to false to have the
element size automatically using the element's settings

com.jaspersoft.layout.grid.colspan

com.jaspersoft.layout.grid.rowspan

com.jaspersoft.layout.grid.fixed
Row
Weight

Number; default = 1

Number that specifies how much space the element's row takes
relative to other rows. Not available when Fixed Size is True.
com.jaspersoft.layout.grid.weight.x

Column
Weight

Number; default = 1

Number that specifies how much space the element's column takes
relative to other rows. Not available when Fixed Size is True.
com.jaspersoft.layout.grid.weight.y

To use grid layout:
1. This example uses a vertical image, that is, an image much taller than it is wide. You can use any vertical
image, for example, a company logo rotated vertically. To create the exact image used in this example,
create a report with the Green Leaf template. This creates a leaf_banner_green.png file in your workspace.
In your file system, use a graphics editor to rotate the image 90°. Note that this will rotate the image in any
report where it is used.

Create a report using the BlankA4 template and the Empty data source. Do not reuse the report created in
the previous step.

Add your vertical image to the title band of your report.

Add a chart to the title band of your report, to the right of your image.

Resize the title band to fit a chart.

TIBCO Software Inc.

Chapter 4 Report Elements

Figure 4-3 Title band before applying grid layout
6.

Right-click in a blank space in the Title band and select Arrange in Container > Grid Layout, or select
the Title band and select Grid Layout in the Properties view.
The two elements are arranged to fill the band equally.

Figure 4-4 Title band with grid layout
7.

Resize the elements so that the chart takes up most of the space. To do this, select the chart. In Properties
view, in the Layout section of the Appearance tab, set Column Weight to 5.
The elements adjust so that the chart width is five times the image width.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Figure 4-5 Grid layout with column weight
8.

Now add a static text element to the far right of the title band.
The static text is added at the end of the first row.

Figure 4-6 Adding an element to a grid layout

Position the static text. To do this, select the static text. In Properties view, in the Layout section of the
Appearance tab, set the following:
•
•

Set Row Number to 1 to move the element to the second row. You could also have added the static
text directly below the first row, but setting the row explicitly gives you more control.
Set Column Span to 2 to have the element span both columns. You could instead set the Column
Number to 2 to move the static text under the chart.

TIBCO Software Inc.

Chapter 4 Report Elements

Figure 4-7 Using two rows in grid layout
10. Set the relative heights of the rows. To do this, select the chart and set Row Weight to 10 in the Layout
section of the Appearance tab of Properties view. You could actually do this by changing the settings on
any of the three elements, but in this case, the chart is the main element and you want other elements to
adjust to it.

Figure 4-8 Using row weight in grid layout

4.3

Formatting Elements
Formatting tools help organize the elements in the report. Right-click the element you want to work on and
select a tool from the context menu.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Figure 4-9 Formatting Tools Menu
The tools in the context menu are specific to the selected item(s). The following tables explain the tools.
A container is the band, frame, or cell that contains the element.

Table 4-1 Formatting Tools
Icon

Tool Name

Description

Multiple Select?

Send
Backward

Moves the element behind its current layer.

Yes

Send to Back

Moves the element to the bottom layer.

Yes

Align to Left

Aligns the left sides to that of the primary element.

Yes

Align to
Center

Aligns the centers to that of the primary element.

Yes

Align to Right

Aligns the right sides to that of the primary element.

Yes

Align to Top

Aligns the top sides (or the upper part) to that of the
primary element.

Yes

Order Tools

Align in Container Tools

TIBCO Software Inc.

Chapter 4 Report Elements

Icon

Tool Name

Description

Multiple Select?

Align to
Middle

Aligns the middles to that of the primary element.

Yes

Align to
Bottom

Aligns the bottom sides (or the lower part) to that of
the primary element.

Yes

Match Width

Adjusts width to that of primary element.

Yes

Match Height

Adjusts height to that of primary element.

Yes

Match Size

Resizes to that of primary element.

Yes

Fit to Width

Adjusts elements to fill width of container.

Yes

Fit to Height

Adjusts elements to fill height of container.

Yes

Fit to Both

Adjusts elements to fill width and height of container.

Yes

Horizontal
Layout

Centers selected elements vertically.

Yes

Vertical
Layout

Centers selected elements horizontally.

Yes

Grid Layout

Positions elements in a grid based on properties set
on each element.

Yes

Stretch to
Content

Resizes element to fit the content

N/A

PDF 508 Tags

Adds tags required for PDF 508C compliance

XLS Tags

Adds tags that define how data is exported to the
Microsoft Excel format

Size Components Tools

Size to Container Tools

Arrange in Container Tools

Miscellaneous Tools

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

4.4

Graphic Elements
Graphic elements like lines and shapes are used to make reports more attractive and readable. You can also add
these by dragging them from the palette to the report editing area.

4.4.1

Line
In Jaspersoft Studio, a line is defined by a rectangle for which the line represents the diagonal. By default, the
foreground color is used as the default color and a 1-pixel-width line is used as the line style.
You can customize the look, style, and direction of the line in the element’s Properties view.

4.4.2

Rectangle and Ellipse
The rectangle element is usually used to draw frames around other elements. By default, the foreground color
setting is used and a normal 1 pixel width
The ellipse is the only element that has no attributes specific to it. The ellipse is drawn in a rectangle that
defines the maximum height and width. By default, the foreground color is used, and a normal 1-pixel-width
line is used as line style. The background is filled with the background color setting if the element has not been
defined as transparent.

4.4.3

Images
An image is the most complex of the graphic elements. You can insert raster images (such as GIF, PNG and
JPEG images) in the report, but you can also use an image element as a canvas object to render, for example, a
Swing component, or to leverage some custom rendering code.
Dragging an image element from the Palette into the report editing area launches the Create new image
element dialog. This is the most convenient way to specify an image to use in the report. Jaspersoft Studio
does not save or store the selected image anywhere, it just uses the file location, translating the absolute path of
the selected image into an expression to locate the file when the report is executed. The expression is then set as
the value for the Image Expression property.
You can add an image by explicitly defining the full absolute path of the image file in your expression. This is
an easy way to add an image to the report, but, overall, it has a big impact on the report’s portability, since the
file may not be found on another machine (for instance, after deploying the report on a web server or running
the report on a different computer).

4.4.4

Padding and Borders
For the image and text elements you can visualize a frame or define a particular padding (the space between the
element border and its content) for the four sides. Border and padding are specified by selecting the element in
the report editing area, and using the Properties view.
In the Properties view, click the Borders option. This includes the following controls:
•
•

Padding allows you to define padding widths for each of the four sides, or to apply the same value to all
sides.
Borders allow you to select their color, style, and width, as well as choose where it appears.

As always, all the measurements are shown in pixels.

TIBCO Software Inc.

Chapter 4 Report Elements

4.5

Text Elements
Two elements are specifically designed to display text in a report: static text and text field. Static text is used
for creating labels or to print static text set at design time, that is not meant to change when the report is
generated. That said, in some cases you still use a text field to print labels too, since the nature of the static text
elements prevents the ability to display text dynamically translated in different languages when the report is
executed with a specific locale and it is configured to use a resource bundle leveraging the JasperReports
internationalization capabilities.
A text field is similar to a static text string, but the content (the text in the field) is provided using an
expression (which can be a simple static text string itself). That expression can return several kinds of value
types, allowing the user to specify a pattern to format that value. Since the text specified dynamically can have
an arbitrary length, a text field provides several options about how the text must be treated regarding alignment,
position, line breaks and so on. Optionally, the text field is able to grow vertically to fit the content when
required.
By default both text elements are transparent with no border, with a black text color. The most used text
properties can be modified using the text tool bar displayed when a text element is selected. Text element
properties can also be modified using the Properties view.
Text fields support hyperlinks as well. See 4.9.4, “Creating a Hyperlink,” on page 60 for more information.

4.5.1

Static Text
The static text element is used to show non-dynamic text in reports. The only parameter that distinguishes this
element from a generic text element is the Text property, where the text to view is specified: it is normal text,
not an expression, and so it is not necessary to enclose it in double quotes in order to respect the conventions of
Java, Groovy, or JavaScript syntax.

4.5.2

Text Fields
A text field allows you to print an arbitrary section of text (or a number or a date) created using an expression.
The simplest case of use of a text field is to print a constant string (java.lang.String) created using an
expression like this:
"This is a text"

A text field that prints a constant value like the one returned by this expression can be easily replaced by a
static field; actually, the use of an expression to define the content of a text field provides a high level of
control on the generated text (even if it’s just constant text). A common case is when labels have to be
internationalized and loaded from a resource bundle. In general, an expression can contain fields, variables and
parameters, so you can print in a text field the value of a field and set the format of the value to present. For this
purpose, a text field expression does not have to return necessarily a string (that’s a text value): the text field
expression class name property specifies what type of value is returned by the expression. It can be one of
the following:
Valid Expression Types
java.lang.Object

TIBCO Software Inc.

java.sql.Time

java.lang.Long

TIBCO Jaspersoft Studio User Guide

Valid Expression Types
java.lang.Boolean

java.lang.Double

java.lang.Short

java.lang.Byte

java.lang.Float

java.math.BigDecimal

java.util.Date

java.lang.Integer

java.lang.String

java.sql.Timestamp

java.io.InputStream

An incorrect expression class is frequently the cause of compilation errors. If you use Groovy or JavaScript you
can choose String as expression type without causing an error when the report is compiled. The side effect is
that without specifying the right expression class, the pattern (if set) is not applied to the value.
Let’s see what properties can be set for a text field:

4.6

Blank when null

If set to true, this option avoids printing the text field content if the expression result is
a null object that would be produce the text “null” when converted in a string.

Evaluation time

Determines in which phase of the report creation the Text field Expression has
to be elaborated.

Evaluation group

The group to which the evaluation time is referred if it is set to Group.

Stretch with
overflow

When it is selected, this option allows the text field to adapt vertically to the content, if
the element is not sufficient to contain all the text lines.

Pattern

The pattern property allows you to set a mask to format a value. It is used only when
the expression class is congruent with the pattern to apply, meaning you need a
numeric value to apply a mask to format a number, or a date to use a date pattern.

Frames
A frame is an element that can contain other elements and optionally draw a border around them. Since a frame
is a container of other elements, in Outline view the frame is represented as a node containing other elements.
A frame can contain other frames, and so on recursively. To add an element to a frame, just drag the new
element from the palette inside the frame. Alternatively you can use Outline view and drag elements from a
band into the frame. The position of an element is always relative to the container position. If the container is a
band, the element position is relative to the top of the band and to the left margin. If the container (or element
parent) is a frame, the element coordinates are relative to the top left corner of the frame. Since an element
dragged from a container to another does not change its top/left properties, when moving an element from a
container to another its position is recalculated based on the new container location.
The advantages of using a frame to draw a border around a set of elements, with respect to using a simple
rectangle element, are:
•

When you move a frame, all the elements contained in the frame move.

TIBCO Software Inc.

Chapter 4 Report Elements

•

4.7

While using a rectangle to overlap some elements, the elements inside the rectangle are not treated as if
they overlap (respect to the frame), so you don't have problems when exporting in HTML (which does not
support overlapped elements).
Finally, the frame automatically stretches according to its content, and the element position type
property of its elements refer to the frame itself, not to the band, making the design a bit easier to manage.

Inserting Page and Column Breaks
Page and column breaks are used to force the report engine to make a jump to the next page or column. A
column break in a single column report has the same effect as a page break.
In the Design tab, they are represented as a small line. If you try to resize them, the size is reset to the default,
this because they are used just to set a particular vertical position in the page (or better, in the band) at which
Jaspersoft Studio forces a page or column break.
The type of break can be changed in the Properties view.

4.8

Working with Composite Elements
Composite elements are one or more pre-configured elements that you can use in your reports. You can
configure properties such as the size, color, or font of an element, or create a text field with a complex
expression you frequently use, and then save it as a composite element. Jaspersoft Studio also ships with several
pre-existing composite elements, such as page number and total pages.
Some element types are hard to reuse in other reports, in particular, those elements that depend on the
availability of a specific subdataset having certain fields. You cannot include elements based on a dataset in a
composite element. In particular, composite elements can not include charts, tables, lists and crosstabs.
Composite elements can include notes, text fields, static text, images, breaks, rectangles, ellipses, lines, frames
(must contain only permitted elements), barcodes, HTML elements, and other composite elements.
If your composite element contains elements that use expressions (text-field expressions or print-when
expressions), the objects you are referencing in those expressions (such as variables, fields or parameters) should
available in the report in which you use the composite elements. If the objects are not present, you may receive
an error when compiling or previewing the report.
Composite elements cannot include elements based on a dataset, such as charts or crosstabs.

4.8.1

Creating and Editing Composite Elements
To create a composite element:
1. Open or create a report.
For example:
a.

Go to File > New > Jasper Report or click

b.
c.

In the New Report Wizard, select Blank A4 in the Report Templates window and click Next.
Select a name and location for your file (for example, Composite Element Sample Report in MyReports)
and click Next.

TIBCO Software Inc.

on the main toolbar.

TIBCO Jaspersoft Studio User Guide

d. Choose One Empty Record in the Data Source window and click Finish.
Place the elements you want in the Title band and format and position them.
Composite elements must be created from the Title band.

For example, to create a footer that includes your company name and the page number:
a.

Drag the Static Text element to the Title band in your report and type My Company. Then align the
company name to the to the left by right-clicking the Static Text element and selecting Align in
Container > Align to Left Margin.
Drag the Page Number element to the Title band in your report. Align the Page Number to the right by
right-clicking the Page Number element and selecting Align in Container > Align to Right Margin.
Then, with the Page Number element selected, go to the Text Field tab in the Properties view and
click
to align the text right.

Select both elements, right-click, and choose Align Components > Align Top.

Select all the elements you want in your composite.

(Optional) To have your elements move together, right-click and select Enclose into Frame from the
context menu.

Make sure all elements are still selected.

Figure 4-10 Selected Elements For Composite Element Creation
6.

Right-click and select Save as Composite Element.
The Composite Element Settings dialog box opens.

Figure 4-11 Composite Element Settings Dialog Box
7.

Enter the following information:
•

Name: Enter a unique name you want to appear in the palette.

TIBCO Software Inc.

Chapter 4 Report Elements

•
•

8.
9.

Description (optional): Enter a description. If the element uses text fields or expressions, it may be
useful to mention these, or the expected data adapter, in the description.
Icon (optional): Choose the icon that will show in the palette for this composite element. You can
choose an icon in JPG, PNG, or GIF format. If you click Browse to locate an icon, and you want to use
a PNG or a GIF, you must choose the correct format at the bottom right of the file open dialog. If you

do not choose an icon, Jaspersoft Studio uses the default icon
.
• Position in Palette: Select one of Basic Elements, Composite Elements, or Components Pro.
Click Finish.
Click OK on the confirmation message.
The new composite element is saved as a .jrtool file in the same location as your report. An icon is added to
the bottom of the subpalette you selected.

Figure 4-12 Composite Element in the Palette
To edit the contents of a composite element:
1. Right-click on the composite element in the palette and select Open in Designer.
The composite element opens in the Designer as a .jrtool file.
2.

You can add and remove elements and change element formatting. If you add elements, remember to select
all elements and create a frame.

Save the file.

To edit the name or location of a composite element:
1. Right-click on the composite element in the palette and select Edit.
The Composite Element Settings dialog box opens.
2.

Change the name, description, icon, or position in palette.

Click Finish.

Click OK on the confirmation message.

To delete a composite element you have created:
1. Right-click on the composite element in the palette and select Delete.
The element is removed from the palette.
You cannot delete the composite elements that are shipped with Jaspersoft Studio.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

4.8.2

Exporting and Importing Composite Elements
You can share composite elements between Jaspersoft Studio installations using import/export.
To export one or more composite elements:
1. Right-click on a custom composite element in the palette.
2.

Select

Export Composite Elements from the context menu.

Figure 4-13 Exporting Composite Elements
3.

Select the elements you want to export in the Export Composite Elements dialog.

4.
5.

Click Finish.
When prompted, navigate to the location where you want to save the export file, and click OK.
The selected composite elements are saved as a .zip file in the location you chose.

To import a composite element set:
1. Right-click on any element in the palette.

Import Composite Elements from the context menu.

Select

3.
4.

Navigate to the location where your zip file is stored, select the file you want to upload, and click Open.
Choose a name, optional description, and optional icon in the Import Composite Element dialog and select
the palette where you want the composite element to appear. The name in the palette must be unique.

TIBCO Software Inc.

Chapter 4 Report Elements

Figure 4-14 Importing Composite Elements

4.9

If there are additional elements in the file, click Next and configure the next element as in the previous
step.

When you have configured all your imported elements, click Finish.
The composite elements are placed in the palette with the settings you configured.

Anchors, Bookmarks, and Hyperlinks
JasperReports Library provides a powerful combination of settings to define hyperlinks. While a hyperlink
usually opens a specific URL, JasperReports broadens the concept, extending it to a more complex object that
can be used for more complicated functionality, such as executing a report in JasperReports to perform a drilldown or drill-up operation, pointing to a page within a PDF document, and so on.
Image, text field, and chart elements can be used both as anchors in a document and as hypertext links to
external sources or to other local anchors.
This section describes hyperlinks for images, text fields, and charts. Hyperlinks for HTML5 charts are
defined differently, as described in 15.5, “Hyperlinks in HTML5 Charts,” on page 241.

To set anchor, bookmark, or hyperlink properties, select an image, text field, or chart element and go to the
Hyperlink tab in the Properties view.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Figure 4-15 Anchor, Bookmark, and Hyperlink Properties
This window is divided in two sections:
•
•

4.9.1

Anchor and Bookmark
Hyperlink

Anchors and Bookmarks
An anchor identifies a specific position in a document. If you plan to export your report to PDF, you can
optionally set a bookmark level to have the anchor show up as a PDF bookmark. The Anchor and Bookmark
area lets you set the following:
•

•

Anchor Name Expression – Expression for the name of the anchor. This name can be referenced by other
hyperlinks. Click the
button to open the Expression Editor, where you can write or build the
expression.
Bookmark Level – Bookmark level when the report is exported to PDF. If you plan to export your report
as a PDF, set a bookmark level to populate the bookmark tree, making the final document navigation much
easier. To make an anchor available as a bookmark, simply choose a bookmark level higher than 1.
Defining different levels creates nested bookmarks.
Bookmarks can also be displayed in JasperReports Server when the report is displayed in the interactive
viewer. To display bookmarks in the server, set the following property:

This property can be set on the report level or globally in the JasperReports Server
WEB-INF\classes\jasperreports.properties file.
In JasperReports 5.6 and later the same table of contents is also available in the JasperPrint object, and
can be explored by calling the method:
List getBookmarks()

TIBCO Software Inc.

Chapter 4 Report Elements

4.9.2

Hyperlinks
Hyperlinks let you link a location in a report to another destination. The most important property of a hyperlink
is its type, which determines the format of the target. Jaspersoft Studio supports the following types of
hyperlink: The exact properties of a hyperlink depend on the hyperlink type. The following properties may
appear for a hyperlink:
•

•

•
•
•

Link Target – Specifies where to open the link target. The Link Target is similar to the target attribute of
an HTML link. The dropdown box shows the following options: Self, Blank, Top, Parent. You can also
possible specify a target name, which actually makes sense only when the hyperlink is used in a web
environment.
Link Type – The following link types are supported in Jaspersoft Studio: Reference, Local Anchor, Local
Page, Remote Anchor, Remote Page, and ReportExecution. You can also defined your own custom
hyperlink types.
Target Expressions – Expressions that determine the location of the link target. May include:
• Hyperlink Anchor Expression – Anchor in document to use as hyperlink target.
• Hyperlink Page Expression – Page in document to use as hyperlink target.
• Hyperlink Reference Expression – Location of remote document. For link of type Reference, use a
URL; for a link of type Remote Anchor or Remote Page, use a file reference.
Hyperlink When Expression – Expression that determines when the hyperlink is implemented. A
hyperlink is only available if the Hyperlink When expression returns the Boolean value True (default).
Tooltip Expression – String to use as a tooltip when a user hovers the cursor over the hyperlink.
Parameters – Parameters that specify information about the target; only available for ReportExecution
hyperlinks and custom hyperlink types.

ReportExecution is implemented as a custom hyperlink type in JasperReports Library.
4.9.2.1 Linking to a URL
To link to a URL, http://www.jaspersoft.com/, select Reference from the Link Type dropdown in the Properties
view. Hyperlinks of type Reference are rendered in all output formats that support web links, including
Microsoft Excel and Word.
When working with a hyperlink of type Reference, you can add parameters via the Hyperlink Reference
Expression. For example, the following expression uses the values of the city and country fields to
dynamically build a URL:
"http://www.someurl.com/search?city=" + $F{city} + "&country= " + $F{country}

4.9.2.2 Linking to a Report
Several hyperlink types link to an existing report. These types are primarily supported in PDF and HTML
formats:
•

•

LocalAnchor – Links between two locations into the same document. It can be used, for example, to link
the titles of a summary to the chapters to which they refer. To define the local anchor, it is necessary to
specify a hyperlink anchor expression, which will have to produce a valid anchor name, for example,
"title".
LocalPage – Point to a specific page in the current report. In this case, it is necessary to specify the page
number you are pointing to by means of a hyperlink page expression, for example Integer.valueOf(2).
The expression must return an Integer object.
RemoteAnchor – Points to an anchor that resides in an external document. In this case, the location of the
external file must be specified in the Hyperlink Reference Expression field, and the name of the anchor
must be specified in the Hyperlink Anchor Expression field.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

•

RemotePage – Points to a particular page of an external document. In this case the location of the external
file must be specified in the Hyperlink Reference Expression field, and the page number must specified in
the Hyperlink Reference Expression.

Similar to links of type Reference, you can specify additional parameters for these hyperlink types by appending
them to the expression string.
4.9.2.3 Creating a Link Between Reports on a JasperReports Server Instance
Hyperlinks of type ReportExecution execute one JasperReports Server report from another JasperReports Server
report, for example, when drilling down to a report in the context of JasperReports Server. Instead of a hyperlink
reference or similar expression, ReportExecution hyperlinks use JasperReports parameters to specify the target.
The following report-execution parameters are available:
•
•
•
•
•

_report (required) – String that points to the JasperReports Server report to execute. Usually a path on

JasperReports Server, enclosed in quotes, such as "/public/Samples/Reports/myReport"
_page (optional) – Specifies a page to display in the target report. Only one of _page and _anchor should
be used. If both are used, _page takes precedence and _anchor is ignored.
_anchor (optional) – Specifies a named anchor to display in the target report.
_output (optional) – Specifies an output format for the report, such as PDF, DOCX, etc. Default is HTML.
If the destination report contains one or more input controls, their value can be set by specifying the name
of the input control as a parameter name and providing a value.
ReportExecution hyperlinks are an example of custom hyperlink extensions in JasperReports Library.
More generally, these parameters can be used by URL Handlers, especially JasperReports Library
extensions, to manipulate and generate hyperlinks.

Creating a ReportExecution hyperlink by dragging:
The easiest way to configure a ReportExecution hyperlink in Jaspersoft Studio is to drag a report unit from
the JasperReports Server repository explorer over an element that supports hyperlinks (such as a textfield).

Figure 4-16 Dragging a report from the server into the Report Design

TIBCO Software Inc.

Chapter 4 Report Elements

The auto-configured hyperlink automatically sets the type to ReportExecution and configures the _report
parameter. Moreover, if the JasperReports Server Report has input controls, they are added to the list of
parameters, ready to be populated with a proper value expression, as shown below.

Figure 4-17 Configuring Hyperlink Parameters

4.9.3

Hyperlink Types
Jaspersoft Studio provides six types of built-in hypertext links: Reference, LocalAnchor, LocalPage,
RemoteAnchor and RemotePage. Other types of hyperlinks can be implemented and plugged into JasperReports.
The following table describes the hyperlink types.
Reference

The Reference link indicates an external source that is identified by a normal URL. This
is ideal to point, for example, to a servlet to manage a record drill-down tool. The only
expression required is the hyperlink reference expression.

LocalAnchor

To point to a local anchor means to create a link between two locations into the same
document. It can be used, for example, to link the titles of a summary to the chapters to
which they refer.
To define the local anchor, specify a hyperlink anchor expression that produces a valid
anchor name.

LocalPage

If instead of pointing to an anchor you want to point to a specific current report page,
you need to create a LocalPage link. In this case, it is necessary to specify the page
number you are pointing to by means of a hyperlink page expression (the expression
has to return an Integer object).

RemoteAnchor

If you want to point to a particular anchor that resides in an external document, you use
the RemoteAnchor link. In this case, the URL of the external file referenced must be
specified in the Hyperlink Reference Expression field, and the name of the anchor must
be specified in the Hyperlink Anchor Expression field.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

RemotePage

This link allows you to point to a particular page of an external document. Similarly, in
this case the URL of the external file pointed to must be specified in the Hyperlink
Reference Expression field, and the page number must be specified by means of the
hyperlink page expression. Some export formats have no support for hypertext links.

ReportExecution

This type of hyperlink is used to implement JasperReports Server’s drill-down feature.

Some export formats have no support for hypertext links.

4.9.4

Creating a Hyperlink
Some types of datasets let you assign a hyperlink to the value represented in the chart; in the report output,
clicking the chart opens a web page or navigates to a different location in the report.
The click-enabled area depends on the chart type. For example, in pie charts, the hyperlink is linked to each
slice of the pie; in bar charts, the click-enabled areas are the bars themselves.
Image, text field, and chart elements can be used both as anchors into a document and as hypertext links to
external sources or local anchors.
To create a hyperlink:
1. Click the Hyperlink tab in the Properties view.
2.

In the Link Target drop-down, choose one of the following target types:
•
•
•

Self: This is the default setting. It opens the link in the current window.
Blank: Opens the target in a new window. Used for output formats such as HTML and PDF.
Top: Opens the target in the current window but outside eventually frames. Used for output formats
such as HTML and PDF.
• Parent: Opens the target in the parent window (if available). Used for output formats such as HTML
and PDF.
In the Link Type drop-down, choose whether the link type is None, Reference, LocalAnchor, LocalPage,
RemoteAnchor, RemotePage, or ReportExecution.
See “Hyperlink Types” on page 59 for an explanation of the different choices.

4.10

button next to Hyperlink Tool Expression to create a tooltip for your hyperlink.

Click the

Save your report.

Advanced Elements and Custom Components
Besides the built-in elements seen up to now, JasperReports supports two technologies that enable you to plugin new JasperReport objects respectively called “custom components” and “generic elements.” Both are
supported by Jaspersoft Studio. Without a specific plug-in offered by the custom element provider, there is not
much you can do with it; you can just set the common element properties. Therefore, a custom element
developer should provide a plug-in for Jaspersoft Studio through which you can, at least, add the element to a
report (maybe adding a palette item) and modify the element properties (implementing what is required to
display the additional properties in the Properties view when the element is selected.

TIBCO Software Inc.

Chapter 4 Report Elements

4.11

Custom Visualization Component
The custom visualization component lets you leverage JavaScript in Jaspersoft Studio and JasperReports Server.
You can create JavaScript modules and use them in your reports to extend their functionality. The main purpose
of the custom visualization component is to render SVG (Scalable Vector Graphics) images. Your modules can
leverage third-party JavaScript libraries, such as JQuery. For example, perhaps you want to create reports with
dynamic behaviors for interaction and animation; you could leverage D3 (d3js.org) to bind data to the
Document Object Model (DOM) and manipulate the SVG. Such a report is shown in , “D3-enabled report,” on
page 61.
Please note that this component is only supported by the Jaspersoft Community
(community.jaspersoft.com). For this release, TIBCO Jaspersoft Technical Support and Engineering do
not support it.

D3-enabled report
The custom visualization component is a powerful and flexible feature, suitable for advanced users of
JasperReports Library. Using the component requires advanced coding skills in the following technologies:
•
•
•
•

JavaScript
CSS
HTML/DHTML
Optionally, any third-party library you want to expose in Jaspersoft Studio and JasperReports Server.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Before creating reports that use your third-party library, you must configure various applications to work
together; you must:
1.

Install PhantomJS (phantomjs.org), which renders your JavaScript module's visual component.

Configure Jaspersoft Studio and JasperReports Server to use PhantomJS.

Create a JavaScript module that renders an SVG. This main module, as well as any JavaScript it relies on,
are optimized and combined into a single JavaScript file (using a RequireJS build file (build.js). Jaspersoft
Studio simplifies the optimization process to generate the JavaScript implementation of the component.
Place your JavaScript files somewhere that Jaspersoft Studio can find it, such as attaching it to the report
unit or placing it on the classpath.

Next, create and deploy reports that rely on your custom visualization component to render SVG images. Drag
the Custom Visualization component from the Elements palette into the Design tab, and create a report-level
property of type com.jaspersoft.jasperreports.components.customvisualization.require.js; it
must specify the main JavaScript file for your custom visualization. The custom visualization component
appears as a rectangular area of your report. A single custom visualization component can be used by any
number of reports that require the same JavaScript functionality. When exported to HTML format, these reports
can be interactive (assuming that your module attaches events to the DOM).
You can also create a custom component descriptor in JSON, which lets you add the following to your
component:
•
•
•

A component UI – You can specify the property names and types and the data items used by the
component.
A thumbnail image – Used when the component is presented in the component choose, which appears
when a component is dragged into the design view.
Location of implementation files – You can specify the location of the JavaScript file and CSS file which
implement the component.

This component can help you leverage any number of JavaScript libraries, such as:
•
•
•
•

D3.js
Raphäel
Highcharts
JQuery

For more in-depth information, please see the articles on our Community wiki that describe the custom
visualization component.

TIBCO Software Inc.

CHAPTER 5

FIELDS

In a report, there are three groups of objects that can store values:
•
•
•

Fields
Parameters
Variables

Jaspersoft Studio uses these objects in data source queries. In order to use these objects in a report, they must be
declared with a discrete type that corresponds to a Java class, such as String or Double. After they have been
declared in a report design, the objects can be modified or updated during the report generation process.
This chapter contains the following sections:
•
•
•
•

5.1

Understanding Fields
Registration of Fields from a SQL Query
Registration of JavaBean Fields
Fields and Text Fields

Understanding Fields
A print is commonly created starting from a data source that provides a set of records composed of a series of
fields. This behavior is exactly like obtaining the results of an SQL query.
Jaspersoft Studio displays available fields as children of the Fields node in the document outline view. To
create a field, right-click the Fields node and select Create Field. The new field is included as an undefined
entry on the Properties tab. You can configure the field properties by selecting it.
Select the Object tab to name your field, enter a description, and choose a class.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Figure 5-1 Object Tab in Properties View of a Field
Select the Advanced tab to enter advanced properties for the field.

Figure 5-2 Advanced Tab in Properties View of a Field
A field is identified by a unique name, a type, and an optional description. You can also define a set of
name/value pair properties for each field. These custom properties are not generally used by JasperReports, but
they can be used by external applications or by some custom modules of JasperReports (such as a special query
executor).
Jaspersoft Studio determines the value for a field based on your data source. For example, when using an SQL
query to fill a report, Jaspersoft Studio assumes that the name of the field matches the name of a field in the
query result set. You must ensure that the field name and type match the field name and type in the data source.
You can systematically declare and configure large numbers of fields using the tools provided by Jaspersoft
Studio. Because the number of fields in a report can be quite large (possibly reaching the hundreds), Jaspersoft
Studio provides different tools for handling declaration fields retrieved from particular types of data sources.
Inside each report expression (like the one used to set the content of a text field) Jaspersoft Studio specifies a
field object, using the following syntax:
$F{}

where must be replaced with the name of the field. When using a field expression (for example,
calling a method on it), keep in mind that it can have a value of null, so you should check for that condition.
An example of a Java expression that checks for a null value is:
($F{myField} != null) ? $F{myFiled}.doSomething() : null

This method is generally valid for all the objects, not just fields. Using Groovy or JavaScript this is rarely a
problem, since those languages handle a null value exception in a more transparent way, usually returning an
empty string.

TIBCO Software Inc.

Chapter 5 Fields

In some cases a field can be a complex object, like a JavaBean, not just a simple value like a String or an
Integer. A trick to convert a generic object to a String is to concatenate it to an empty string this way:
$F{myfield}+ “”

All Java objects can be converted to a string; the result of this expression depends on the individual object
implementation (specifically, by the implementation of the toString() method). If the object is null, the result
returns the literal text string “null” as a value.

5.2

Registration of Fields from a SQL Query
An SQL query is the most common way to fill a report. Jaspersoft Studio provides several tools for working
with SQL, including a query designer and a way to automatically retrieve and register the fields derived from a
query in the report.
Before opening the query dialog, be sure you select the correct connection/data source. All operations performed
by the tools in the query dialog use this data source.
To open the query dialog (Figure 5-3) right-click the name of your report in the Outline view and choose
Dataset and Query....

Figure 5-3 Query Dialog

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Jaspersoft Studio doesn't require a query to generate a report. It can obtain data from a data source that is not
defined by a query execution. JasperReports supports multiple query languages including:
•
•
•
•
•
•
•
•

CQL
HiveQL
JSON
MongoDBQuery
PLSQL
SQL
XLS
XPath

If the selected data source is a JDBC connection, Jaspersoft Studio tests the access connection to the data source
as you define the query. This allows Jaspersoft Studio to identify the fields using the query metadata in the
result set. The design tool lists the discovered fields in the bottom portion of the window. For each field,
Jaspersoft Studio determines the name and Java type specified by the JDBC driver.
If your query accesses tables containing large amounts of data, scanning the data source for field names could
take a while. In this case you might consider disabling the Automatically Retrieve Fields option to quickly
finish your query definition. When you've completed the query, click the Read Fields button to start the fields
discovery scan.
All fields used in a query must have a unique name. Use alias field names in the query for fields having
the same name.

The field name scan may return a large number of field names if you are working with complex tables. To
reduce unnecessary complexity, we suggest that you review the list of discovered names and remove fields
you're not using in your report.When you click OK all the fields in the list are included in the report design.
Although you can remove them later in the outline view, it’s a good idea at this point in the design process to
remove any field names that you won’t be using.

5.3

Registration of JavaBean Fields
One of the most advanced features of JasperReports is its ability to manage data sources that aren't based on
simple SQL queries. One example of this is JavaBean collections. In a JavaBean collection, each item in the
collection represents a record. JasperReports assumes that all objects in the collection are instances of the same
Java class. In this case the “fields” are the object attributes (or even attributes of attributes).
By selecting the Java Bean tab in the query designer, you can register the fields that correspond to the
specified Java classes. We assume you know the Java classes that correspond to the objects that you use in your
report.

TIBCO Software Inc.

Chapter 5 Fields

Figure 5-4 JavaBeans Tab
Suppose you're using objects of this Java class:
com.jaspersoft.ireport.examples.beans.PersonBean

To register fields for the class:
1.
2.

Put the class name in the name field and click Read attributes. Jaspersoft Studio scans the class.
Check the scan results to make sure Jaspersoft Studio has captured the correct object attributes for the class
type.

Select the fields you want to use in your report and click Add.

Jaspersoft Studio creates new fields corresponding to the selected attributes and adhesion to the list. The
description, in this case, stores the method that the data source must invoke to retrieve the value for the
specified field.
Jaspersoft Studio parses a description such as address.state (with a period between the two attributes) as an
attribute path. This attribute path is passed to the function getAddress() to locate the target attribute, and then
to getState() to query the status of the attribute. Paths may be arbitrary and long, and Jaspersoft Studio can
recursively parse attribute trees within complex JavaBeans and in order to register very specific fields.
We have just discussed the two tools used most frequently to register fields, but we’re not done yet. There are
many other tools you can use to discover and register fields, for instance, the HQL and XML node mapping
tools.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

5.4

Fields and Text Fields
To print a field in a text element, you must set the expression and the textfield class type correctly. You may
also need to define a formatting pattern for the field.
To create a corresponding text field, drag the field you want to display from the Outline view into the design
panel. Jaspersoft Studio creates a new text field with the correct expression (for example, $F{fieldname}) and
assigns the correct class name.

5.5

Data Centric Exporters
Jaspersoft Studio supports two data-oriented export formats designed to be used programmatically when another
application embeds TIBCO Jaspersoft products:
•
•

CSV: exports the report's data to a list of comma-separated values (CSV).
JSON: exports the report's data to a JavaScript Object Notation (JSON) object.

In both cases, the metadata defines the structure of the exported data.
Jaspersoft Studio also supports other types of field-level metadata:
•
•

PDF 508 Tags are used to create report output in Adobe Acrobat format that provides functionality in
accordance with the Americans with Disabilities 508 specification.
XLS Tags are used to define how data is exported to the Microsoft Excel format. In addition to numerous
layout settings, you can define XLS metadata that define the structure of the data when exported.

This section describes how to work with metadata for PDF 508 Tags and for the JSON exporter.

5.5.1

Configuring a Report's Metadata for PDF 508 Tags
To add 508 functionality to a report, you must add tags to the report elements. Jaspersoft Studio has menu items
that let you explicitly insert tags for headings, tables, and table-like elements. For more information about tags
for 508 functionality in JasperReports Library, see the JasperReports Library Ultimate Guide.

5.5.1.1 Tagging Headings
You can tag text fields or static text elements as headings. You can include a range of static text elements
and/or text fields in the same heading.
To tag a single element as a heading:
1. Right-click the text field or static text and select PDF 508 Tags > Heading > Heading n > Full from the
context menu.
The setting is displayed in the upper left-hand corner of the element in design view. It is underlined to
show the element is the full heading.

Figure 5-5 A static text element tagged as Full

TIBCO Software Inc.

Chapter 5 Fields

To tag multiple elements as a heading:
1. Right-click the first text field or static text element in your heading section and select PDF 508 Tags >
Heading > Heading n > Start from the context menu.
2.

Right-click the last text field or static text element in your heading section and select PDF 508 Tags >
Heading > Heading n > End from the context menu.
In design view, the start of a multi-element heading is shown in the upper left-hand corner of the Start
element, and the end is shown in the lower right-hand corner of the End element.

Figure 5-6 Text fields tagged as start and end
To remove a heading tag from an element:
1. Right-click the text field or static text element in your heading section and select PDF 508 Tags >
Heading > Heading n > None from the context menu.
5.5.1.2 Using Automatic Table Tagging
In version 6.2, we added the net.sf.jasperreports.components.table.generate.pdf.tags property.
When this property is enabled, tags are automatically generated for the tables in your report. This property can
be set at the global, report, or table level.
To set this property globally:
1. Select Window > Preferences to open the Preferences dialog box.
2. Navigate to Jaspersoft Studio > Properties.
3.
4.

Click Add to open the Properties dialog.
Enter the following values:
•
•

Property Name – net.sf.jasperreports.components.table.generate.pdf.tags
Value – Enter true to enable table tagging or false to disable table tagging.
Setting the property globally inserts tags when you export a report to PDF directly from Jaspersoft Studio.
If you are publishing your reports to another environment, such as JasperReports Server, you must
enable this property in the jasperreports.properties file in your environment. See the JasperReports
Server Administrator Guide for more information about enabling this property for JasperReports Server.

To set this property for a report or table:
1. For a table, right-click in the table. For a report, right-click on the root node in outline view.
2.
3.

Select PDF 508 Tags > Autotag Table from the context menu.
Select one of the following options:
•
•
•

Default – Inherits the property settings from a higher level. If the property has been set explicitly at a
higher level, the current setting is shown on the menu, for example Default (Enabled).
Enabled – Enables the property for this table or report. This setting overrides any value set at a higher
level.
Disabled – Disables the property for this table or report. This setting overrides any value set at a
higher level.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

When the net.sf.jasperreports.components.table.generate.pdf.tags is set at the table level, the
setting is displayed in the upper left-hand corner of the table in design view.

Figure 5-7 Table with tagging enabled
5.5.1.3 Manually Tagging Tables and Lists
Automatic table tagging only works with table elements. If you have a table-like element in your report, such as
a list or a tabular arrangement of fields, it cannot be tagged automatically. However, you can manually insert
list or table tags using the context menu. Like tables, manual tagging only works with text fields and static text.
You manually tag lists and tables using a CSS-type structure. The general steps necessary to tag tables are
shown.
To manually tag a tabular arrangement of elements as a table:
1. Tag the first element in your table: PDF 508 Tags > Table > Start.
2. Tag the start and end of each row:
a.
3.

Tag the first element in your row: PDF 508 Tags > Table Row > Start.

b. Tag the last element in your row: PDF 508 Tags > Table Row > End.
To make a row a header row, add header tags to the start and end:
a.

Tag the first element in each header row: PDF 508 Tags > Table Header > Start.

Tag the last element in each header row: PDF 508 Tags > Table Header > End.

Tag each detail element in each row: PDF 508 Tags > Table Details > Full.

Tag the final element in your table: PDF 508 Tags > Table > End.

To manually tag elements as a list:
1. Tag the first element in your list: PDF 508 Tags > List > Start.
2.

Tag each list item: PDF 508 Tags > List Item > Full.

Tag the final element in your list: PDF 508 Tags > List > End.

5.5.1.4 Setting Export Parameters
Once you have inserted your 508C tags correctly, you must set the PDF export parameters in your report.

Click on the report preview.

The first time the report runs, it will not have tags. To speed up the initial run, select One Empty Record.

Select PDF from the format menu and wait for the report to run.

If necessary, click to open the panel on the left of the preview window.

Click

to view the exporter parameters.

TIBCO Software Inc.

Chapter 5 Fields

Figure 5-8 PDF Export Parameters tab in report preview
6.

Select Is Tagged.

Enter a language code in the Tag Language field.

Figure 5-9 508C tags in PDF Export Parameters tab
8.

5.5.2

Select the correct data adapter and run your report.

Configuring a Report's Metadata for Use With the JSON Data Exporter
JasperReports Server's REST API includes a JSON (JavaScript Object Notation) data exporter that enables you
to feed pure data into applications you integrate with the server. During report generation, this exporter skips all
layout-related steps and returns a dataset. The structure of this data is determined by metadata you define in
your report. You can also define expressions to determine how data from a specific filed is exported.
Note: The ability to define metadata and export data in JSON format is sometimes referred to as the
JasperReports Data API.
You can define a structure by separating the names of the levels you want to create with periods (.). For
example, consider a report with three fields configured with these JSON properties:
Field Expression

JSON Path

$F{salesamount}

store.sale.amount

$F{salesyear}

store.sale.year

$F{cust.name}

store.cust.name

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

When exported to JSON, the data is structured with three distinct paths:
store
sale
amount
year
cust
name

Example exported data would be similar to:
[
{store:
[
{
sale:[{amount:"19000", year:2014}],
cust:[{name:"Acme"}],
}
]
}
]

Note that when you preview your report as JSON, the data is not formatted to be human readable, as above.
You may want to use one of the many JSON formatting tools to review the output of your JSON tagged report,
you can copy the JSON output from the Preview tab.
It's important to define paths that create a structure that the application receiving the data can interpret.
To define JSON export object metadata in your report:
1. Open a report that includes the fields you want to export to your application.
2.

Right-click a field in the Design tab, and select JSON tags > JSON Metadata Path.
If the field you selected appears in a frame, you're warned that JasperReports Library may ignore the
property. This warning relates only to older versions of the library; it remains in the product for backwardscompatibility. For current versions of JasperReports Server, JasperReports Server, and Jaspersoft Studio,
properties defined in frames aren't ignored.

If you receive this warning, click OK. The JSON Exporter Property Configuration window appears.

In the Path field, enter a string that specifies the way the data from this field should be exported. For
example, if you are working with a field that returns a sales amount value, you might enter
store.sale.amount.

If the data being returned necessitates it, check the Repeat value if missing check box.
This option is helpful if your source data doesn't include values for every row of data returned. Selecting
this option instructs Jaspersoft Studio to simply use the last value passed when a value is missing, which
may prevent problems in the application receiving the JSON object.

If you want to manipulate the data being exported, check the Use custom expression for exported
value check box, click
, and define an expression.

7.
8.

Click OK.
Select each field you want to export to JSON and define its metadata.

Click File > Save.

10. Click Preview.

TIBCO Software Inc.

Chapter 5 Fields

11. If the JSON Metadata preview isn't selected, click the arrow next to the current preview format, and select
JSON Metadata.

Figure 5-10 Selecting the JSON Metadata Preview
12. Review the structure of the data to ensure your application can interpret it.
13. If the data isn't structured correctly, click Design and edit each field's JSON export properties.
14. When you're satisfied with the data returned by Jaspersoft Studio, you can publish your report to
JasperReports Server and begin testing your own application's ability to use the data passed by the server.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

TIBCO Software Inc.

CHAPTER 6

PARAMETERS

Parameters are values usually passed to the report from the application that originally requested it. They can be
used for configuring report features at generation time (like the value to use in an SQL query), or to supply
additional data that's not provided by the data source (like a custom report title, an application-specific path for
images).
Report parameters have many functions in a report. They can be used in the "where" condition of an SQL query,
or to provide additional data to the report (like the value of a title or name of the user that executed the report).
A parameter is defined by a name and a Class, which is a Java class type. For example a parameter of type
java.sql.Connection may be used to populate a subreport, while a simple java.lang.Boolean parameter may be
used to show or hide a section of the report.
This chapter contains the following sections:
•
•
•
•

6.1

Managing Parameters
Default Parameters
Using Parameters in Queries
Parameters Prompt

Managing Parameters
Parameters are the best communication channel between the report engine and the execution environment (your
application).
A parameter can have a default value defined by means of the default expression property. This expression is
evaluated by JasperReports only when a value for the parameter has not been provided by the user at run time.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Figure 6-1 Parameters in Outline View
To manage parameters, use the outline view. Add a parameter by right-clicking on the item Parameters and
choosing Create Parameter. To delete a parameter from the outline view right click on it and select Delete.
The parameters with light gray names are created by the system and can not be deleted or edited.
Right-click any parameter and choose Show Properties to view and edit the properties of the parameter.

Figure 6-2 Parameters - Properties
Parameters have the following properties on the Object tab:
•
•

Name – Name of the parameter.
Class – Class type of the parameter.

TIBCO Software Inc.

Chapter 6 Parameters

•

Default Value Expression – Pre-defined value for the parameter. This value is used if no value is
provided for the parameter from the application that executes the report. The type of value must match the
type declared in the Class field.
You may legally define another parameter as the value of Default Value Expression, but this method
requires careful report design. Jaspersoft Studio parses parameters in the same order in which they are
declared, so a default value parameter must be declared before the current parameter.

•

Description – A string describing the parameter. The description is not used directly by JasperReports, but
may be passed to an external application.
Is for Prompting – Enable this to have Jaspersoft Studio prompt for the parameter when the report is
executed. May also be passed to an external application.

•

On the Advanced tab, you can use the Properties field to specify pairs of type name/value as properties for
each parameter. This is a way to add extra information to the parameter for use by external applications. For
example, you can use properties to include the description of the parameter in different languages or to add
instructions about the format of the input prompt.

6.2

Default Parameters
JasperReports provides some built-in parameters (internal to the reporting engine). You can read the built-in
parameters, but you can't modify or delete them. Some important built-in parameters are:
•

REPORT_CONNECTION - For a report using JDBC, this parameter holds the JDBC connection used to run the

SQL query.
•
•

REPORT_DATA_SOURCE - This parameter contains the data source used to fill the report (if available)
REPORT_LOCALE - This parameter contains the Locale used to fill the report.

Some built-in parameters are specific to a query language. For example if you're using the Hibernate query
language, the reports automatically includes the HIBERNATE_SESSION parameter that holds the Hibernate
session for the HQL query.
The built-in parameters are:
Table 6-1 JasperReports Default Parameters
Parameter

Description

REPORT_CONTEXT
REPORT_PARAMETERS_MAP

This is the java.util.Map passed to the fillReport method; it contains
the parameter values defined by the user.

JASPER_REPORT
REPORT_CONNECTION

This is the JDBC connection passed to the report when the report is created
through an SQL query.

REPORT_MAX_COUNT

This is limits the number of records filling a report. If no value is provided,
no limit is set.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Parameter

Description

REPORT_DATA_SOURCE

This is the data source used by the report when it's not using a JDBC
connection.

REPORT_SCRIPTLET

This represents the scriptlet instance used during report creation. If no
scriptlet is specified, this parameter uses an instance of
net.sf.jasperreports.engine.JRDefaultScriptlet.

REPORT_LOCALE

This is specifies the locale used to fill the report. If no locale is provided, the
system default is used.

REPORT_RESOURCE_BUNDLE

This is the resource bundle loaded for this report.

REPORT_TIME_ZONE

This is used to set the time zone used to fill the report. If no value is
provided, the system default is used.

REPORT_FORMAT_FACTORY

This is an instance of a
net.sf.jasperreports.engine.util.FormatFactory. The user can
replace the default one and specify a custom version using a parameter.
Another way to use a particular format factory is by setting the report
property format factory class.

REPORT_CLASS_LOADER

This parameter can be used to set the class loader to use when filling the
report.

REPORT_URL_HANDLER_
FACTORY

Class used to create URL handlers. If specified, it replaces the default.

REPORT_FILE_RESOLVER

This is an instance of
net.sf.jasperreports.engine.util.FileResolver used to resolve
resource locations that can be passed to the report in order to replace the
default implementation.

REPORT_TEMPLATES

This is an optional collection of styles (JRTemplate) that can be used in
addition to those defined in the report.

SORT_FIELDS
FILTER

REPORT_VIRTUALIZER

This defines the class for the report filler that implements the
JRVirtualizer interface for filling the report.

IS_IGNORE_PAGINATION

You can switch the pagination system on and off with this parameter (it
must be a Boolean object). By default, pagination is used except when
exporting to HTML and Excel formats.

TIBCO Software Inc.

Chapter 6 Parameters

6.3

Using Parameters in Queries
Generally, you can use parameters in a report query whether or not the language supports them.
JasperReports executes queries, passing the value of each parameter used in the query to the statement.
This approach has a major advantage with respect to concatenating the parameter value to the query string—you
don't have to take care of special characters or sanitize your parameter. The database can do it for you. At the
same time, this method limits your control of the query structure. For example, you can't specify a portion of a
query with a parameter.

6.3.1

Using Parameters in a SQL Query
You can use parameters in SQL queries to filter records in a where condition or to add/replace pieces of raw
SQL or even to pass the entire SQL string to execute.
In the first case the parameters act as standard SQL parameters. For example:
SELECT * FROM ORDERS WHERE ORDER_ID = $P{my_order_id}

In this example the my_order_id parameter contains the ID of the order to be read. This parameter can be
passed to the report from the application running it to select only a specific order. Please note that the parameter
here is a valid SQL parameter, meaning that the query can be executed using a prepared statement like:
SELECT * FROM ORDERS WHERE ORDER_ID = ?

and the value of the parameter my_order_id is then passed to the statement.
In this query:
SELECT * FROM ORDERS ORDER BY $P!{my_order_field}
my_order_field cannot be treated as an SQL parameter. JasperReports considers this parameter a placeholder
(note the special syntax $P!{}) is replaced with the text value of the parameter.

Using the same logic, a query can be fully passed using a parameter. The query string would look like:
$P!{my_query}

A query can contain any number of parameters. When passing a value using the $P!{} syntax, the value of the
parameter is taken as is, the user is responsible of the correctness of the passed value (SQL escaping is not
performed by JasperReports in this case). When using a parameter in a query, a default value must be set for the
parameter to allow Jaspersoft Studio to execute the query to retrieve the available fields.

6.3.2

Using Parameters with Null Values
The parameter form $P{parametername} doesn't work correctly with null values. In an operation in which your
value could be null, use the form $X{EQUAL,fieldname,parametername}.
For example:
1.

$P{param}: "select * where num_column > $P{num_param}"

In this case $P should be used, because we don't have $X{GREATER,…}, and Null has no meaning for the
operation “greater than”.
2.

$X{EQUAL, column_name, param_name}

Let's compare two expressions:
"select * where num_column = $P{num_param}"

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

and
"select * where $X{EQUAL, num_column, num_param}"

Both generate the same output if parameter value is not Null: "select * where num_column = 1"
However, if the parameter has a Null value the output is different:
• $P: "select * where num_column = null"
• $X: "select * where num_column IS null"
Databases don't understand the key difference "= null", but "is null". So if you want your query with
the condition "=" to work with null values, you need to use $X{EQUAL/NOTEQUAL, column, parameter}.

6.3.3

IN and NOTIN Clauses
JasperReports provides a special syntax to use with a where condition: the IN and NOTIN clauses.
The IN clause checks whether a particular value is present in a discrete set of values. Here is an example:
SELECT * FROM ORDERS WHERE SHIPCOUNTRY IS IN ('USA','Italy','Germany')

The set here is defined by the countries USA, Italy and Germany. Assuming we are passing the set of countries
in a list (or better a java.util.Collection) or in an array, the syntax to make the previous query dynamic in
reference to the set of countries is:
SELECT * FROM ORDERS WHERE $X{IN, SHIPCOUNTRY, myCountries}

where myCountries is the name of the parameter that contains the set of country names. The $X{} clause
recognizes three parameters:
•
•
•

Type of function to apply (IN or NOTIN)
Field name to be evaluated (SHIPCOUNTRY)
Parameter name (myCountries)

JasperReports handles special characters in each value. If the parameter is null or contains an empty list,
meaning no value has been set for the parameter, the entire $X{} clause is evaluated as the always true
statement “0 = 0”.

6.3.4

Relative Dates
You can create a report that filters information based on a date range relative to the current system date using a
parameter of type DateRange. A date range parameter can take either a date or a text expression that specifies a
date range relative to the current system date.
A relative date expression is always calculated in the time zone of the logged-in user. However, the
start day of the week can be configured independent of locale.

6.3.4.1 Relative Date Keywords
The text expression for the relative date must be in the format +/- where:
•

– Specifies the time span you want to use. Options include: DAY, WEEK, MONTH, QUARTER, SEMI,
and YEAR.

•
•

<+/-> – Specifies whether the time span occurs before (-) or after (+) the chosen date.
– Specifies the number of the above-mentioned time spans you want to include in the filter.

For example, if you want to look at Sales for the prior month, your expression would be MONTH - 1.

TIBCO Software Inc.

Chapter 6 Parameters

Relative dates don't currently support keywords like "Week-To-Date" (from the start of the current week to
the end of the current day). However, you can set a relative date period in a query in JRXML using
BETWEEN, which has the syntax:
$X{BETWEEN, column, startParam, endParam}
For example, to create a week-to-date query, set startParam to WEEK and endParam to DAY. You can do
this for other time ranges, such as Year-To-Day, Year-To-Week, and so forth.

6.3.4.2 Creating a Date Range Parameter
The class attribute of a JasperReports date range parameter must have one of the following values:
•

net.sf.jasperreports.types.date.DateRange (Date only) – Accepts text strings with relative date

keywords as described above and date strings in YYYY-MM-DD format. For example:

•

net.sf.jasperreports.types.date.TimestampRange (Date and Time) – Accepts text strings with

relative date keywords as described above and date strings in YYYY-MM-DD HH:mm:ss format. For
example:

6.3.4.3 Using Date Ranges in Queries
You must use $X{} functions with date ranges, because $P{} does not support the date-range types (DateRange
and TimestampRange).
To use date ranges, create a parameter with type date range and use it as the third argument in the $X{}
function. To set the default value expression of a date range parameter, use the DateRangeBuilder() class to
cast the expression to the correct type:
•

new net.sf.jasperreports.types.date.DateRangeBuilder("DAY-1").toDateRange()

– casts a keyword text

string to a DateRange.
•

new net.sf.jasperreports.types.date.DateRangeBuilder("WEEK").set(Timestamp.class).toDateRange()

–

casts a keyword text string to a TimestampRange.
•

new net.sf.jasperreports.types.date.DateRangeBuilder("2012-08-01").toDateRange()–

casts a date in

YYYY-MM-DD format to a DateRange.
•

new net.sf.jasperreports.types.date.DateRangeBuilder("2012-08-01 12:34:56").toDateRange()–

casts a

date in YYYY-MM-DD HH:mm:ss format to a TimestampRange.
The following JRXML example shows data from the previous day:

This JRXML example shows results prior to the end of last month:

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

The following table shows two additional examples of relative dates.
Problem

Solution

Set up a relative date parameter called StartDate that takes the value: QUARTER. QUARTER evaluates to the
first day (the first instant, really) of this quarter.
Find all purchases made
previous to this quarter

SQL: select * from orders where $X{LESS, order_date,
StartDate}

Find all purchases made in
this quarter

select * from orders where $X{EQUAL, order_date, StartDate}

6.3.4.4 Using Relative Dates in Input Controls
When you create an input control for a DateRange or TimestampRange parameter, the user can either type a
relative date expression or enter a specific date (either by typing or by using the calendar widget).
Use BETWEEN to set up input controls that allow the user to specify a range (other than a day) using either a
relative date expression or actual dates. To do this:
•
•
•
•

Define two date range parameters, for example, StartDate and EndDate.
Optionally, set default values for one or both parameters using defaultValueExpression.
Use a $X{} expression with a BETWEEN function in your query.
Create a date type input control for each parameter, for example, StartDate and EndDate.

The following JRXML example uses the BETWEEN keyword in the $X() function to find all data from the
previous 20 years:

You can use the getStart() and getEnd() methods to get the precise beginning and end of a relative date.
Both of these methods return a date instead of a date range. The following example shows how to get the
precise start date as a default value expression.

TIBCO Software Inc.

Chapter 6 Parameters

6.3.4.5 Publishing Reports with Relative Dates to JasperReports Server
Jaspersoft Studio automatically enables support for date range expressions on connections to JasperReports
Server 5.0 and higher. To verify that date range expressions are enabled:
1.

Right-click on the server connection in the Repository and select Edit.

In the Server profile wizard, display the Advanced settings and select Supports DateRange
Expressions.

When Supports DateRange Expressions is enabled, input controls for date range parameters work correctly
when published to JasperReports Server.

6.3.5

Passing Parameters from a Program
Jaspersoft Studio passes parameters from a program “caller” to the print generator using a class that extends the
java.util.Map interface. For example:
...
HashMap hm = new HashMap();
...
JasperPrint print = JasperFillManager.fillReport(
fileName,
hm,
new JREmptyDataSource());
...

fillReport is a key method that allows you to create a report instance by specifying the file name as a

parameter, a parameter map, and a data source. (This example uses a dummy data source created with the class
JREmptyDataSource and an empty parameter map created using a java.util.HashMap object.)
Let’s see how to pass a simple parameter to a reporting order to specify the title of a report.
The first step is to create a parameter in the report to host the title (that is a String). We can name this parameter
REPORT_TITLE and the class is java.lang.String (Figure 6-3).

Figure 6-3 Definition of REPORT_TITLE

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

All the other properties can be left as they are. Drag the parameter into the Title band to create a text field to
display the REPORT_TITLE parameter.

Figure 6-4 Design Panel with REPORT_TITLE in the Title Band
To set the value of the REPORT_TITLE parameter in our application, modify the code of the previous source
code example by adding:
...
HashMap hm = new HashMap();
hm.put(“REPORT_TITLE”,”This is the title of the report”);
...
JasperPrint print = JasperFillManager.fillReport(
fileName,
hm,
new JREmptyDataSource());
...

We have included a value for the REPORT_TITLE parameter in the parameter map. You don't need to pass values
for all the parameters. If you don’t provide a value for a certain parameter, JasperReports assigns the value of
Default Value Expression to the parameter with the empty expression evaluated as null.
When printing the report, Jaspersoft Studio includes the String This is the title of the report in the
Title band. In this case we just used a simple String. But you can pass much more complex objects as
parameters, such as an image (java.awt.Image) or a data source instance configured to provide a specified
subreport with data. The most important thing to remember is that the object passed in the map as the value for
a certain parameter must have the same type (or at least be a super class) of the type of the parameter in the
report. Otherwise, Jaspersoft Studio fails to generate the report and returns a ClassCastException error.

6.4

Parameters Prompt
If you set a parameter to be used as a prompt, when executing the report, Jaspersoft Studio asks for the value of
the parameter.
To create a parameter prompt:
Create a simple report with the template Blank A4, name ParameterExample and data adapter One
Empty Record - Empty Rows.
1. In this report create a parameter and rename it (from its Properties view) to MESSAGE, with type
java.lang.String, and select the Is For Prompting) checkbox.
2.

Drag the parameter from the outline view into the Title band. Jaspersoft Studio creates a text field to
display the parameter value. You should have something like the following image.

TIBCO Software Inc.

Chapter 6 Parameters

Figure 6-5 Parameter in Title Band
To compile and preview the report:
1. Click the Preview tab.
Be sure the Input Parameter window is open. If not, click the gray right-arrow to the left of the Preview
screen.
2.

Add a value for the MESSAGE parameter. For this example, type Parameter Example.

Press the Play button. The message is printed in the title band.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Figure 6-6 Preview Tab with Parameter Value
Jaspersoft Studio provides input dialogs for parameters of type String, Date, Time, Number, and Collection.

TIBCO Software Inc.

CHAPTER 7

VARIABLES

You can use variables to store partial results and do complex calculations with the data extracted from a data
source. You can then use these values in other parts of the report, including other variables.
This chapter contains the following sections:
•
•
•
•
•

7.1

Defining or Editing a Variable
Base Properties of a Variable
Other Properties of a Variable
Built-In Variables
Tips & Tricks

Defining or Editing a Variable
As with many other elements, all defined variables are visible in the Outline view, where you can create a new
variable and edit its properties in the Properties view.
To define a new variable:
1. In the Outline view, right click the Variables item and select Create Variable. A new variable is added to
the list of variables.
2.

Click to select the new variable. The Properties view shows information about the new variable.

3.
4.

In the Properties view, click the Object tab.
Update the variable properties. See “Base Properties of a Variable” on page 87 for information on these
options.

Jaspersoft Studio has some built-in variables that are present in every report. These variables can't be edited.
You'll notice their names are light gray; other variables are black. For more information see “Built-In
Variables” on page 90

7.2

Base Properties of a Variable
At a minimum, all variables must have the following defined:
•

Name: A string used to refer to a variable. It is necessary to use this variable inside other expressions like
the evaluation of a Text Field or the computation of another variable. Use the following syntax to refer to a
variable: $V{variable_name}.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

•
•

7.3

Type: Necessary because a variable is an object that is probably used in other expressions, so its type must
be known to be manipulated correctly.
Expression: The function used to define the variable value, it can be composed of more fields and
variables, which could be logic operators, math operators and so on. Jaspersoft Studio provides an
expression editor. To open it, click the button to the right of the expression text field. The expression is
evaluated on each iteration (every time a record is read from the data source). If no calculation function is
defined, the result of the expression is assigned to the variable. So it's important that the result has a type
compatible with the one in the variable.
Initial Value: The value assumed from the variable at the beginning, before the first computation of its
expression. The initial value is an expression itself, so it can be defined through the expression editor.
It's not mandatory, but it's good practice to define an initial value. For example, if you have a variable
called variable1 with the expression new Integer(5), at every iteration, the variable is assigned the
integer value 5. In this context the initial value isn't important. But if you change the expression to $V
{variable1}+5, at every iteration the variable is incremented by 5. In this case, an initial value is
necessary because if the variable1 is undefined at the first iteration, all future evaluations will break.

Other Properties of a Variable
The most complex property of a variable is its temporal value. Because its expression is evaluated at every
iteration, it's important to understand which value has a variable, and at which time. This can be complicated,
considering that a variable can use other variables inside its expression. For these reasons there are mechanisms
that can be used to simplify the evaluation or reading of the variable value during iterations.

7.3.1

Evaluation Time
Evaluation time is not an attribute of the variable but of elements that can use the variable in their expressions
(like a Text Field). Evaluation time determines when the value of the variable should be read. A variable can
potentially change value at every iteration, so a value read at one time may be different from the value read
another time.
For every element using a variable in its expression, it's possible to say when to evaluate the variable. And
because an expression can contain multiple variables, this parameter also influences when these variables are
read.
The possible evaluation times are:
•
•
•
•
•
•

Report: The expression is evaluated ad the end of the report.
Page: The expression is evaluated at the end of every page of the report.
Column: The expression is evaluated at the end of each column (for a single column report, this is the
same as Page).
Group: The expression is evaluated after the break of the specified group (available only if at least one
group is defined).
Band: The expression is evaluated after the end of the band where the element with this evaluation time is
placed.
This is a very specific case, introduced to wait until the other elements in the band are completely created.
Typically the value of the variables are read at the start of the band. But suppose, for example, you have a
subreport with an output parameter to print in the main report. To print this parameter it must be read after
the subreport is computed, so the value can be printed when the band is completely created. In this case the
Band evaluation time is necessary.

TIBCO Software Inc.

Chapter 7 Variables

•

7.3.2

Auto: This is used when the expression contains variables and fields that need to be evaluated at different
times. The variables are evaluated at a time corresponding to their Reset Type (see below for more
information), instead the fields are always evaluated at time -now. This type is useful when report elements
have expressions that combine values evaluated at different times (for example, percentage out of a total).
Now: The value of the expression is evaluated after the read of every record, so at every iteration, this is the
default behavior.

Calculation Function
A calculation function is an attribute that specifies when a variable can be used in association with the
expression to determine the value of the variable. When using a calculation function, the value of the variable is
not determined directly by its expression. Instead, it's passed to the calculation function that uses it to determine
its value.
There are many calculation functions built-in to Jaspersoft Studio:
•
•
•
•
•
•
•
•
•

7.3.3

Sum: At every iteration the variable value is summed. This is one of the cases where the initial value is
really important.
Count: At every iteration the variable value is incremented by one unit (this is only if the expression isn't
null).
Distinct Count: At every iteration the variable value is incremented by one unit, but only if the value of
the expression was never returned before.
Average: The value of the variable is the arithmetic average of all values received in input from the
expression.
Lowest: The variable takes the value of the lowest element received from the expression.
Highest: The variable takes the value of the highest element received from the expression.
Standard Deviation: The standard deviation of all the values received from the expression.
First: The variable takes the value from the first value returned by the expression.
System: No calculation is done and the expression is not evaluated, the value of the variable is the last
value set on it. This is useful to store partial results or the final result of a computation.

Increment Type
As stated above, when a calculation function is defined, the value of the expression passed to the function that
calculates the variable. By default this occurs for every record read, but sometimes a different behavior is
desired. The increment type parameter enables you to change the "time" at which the calculation function is
used.
The possible values for this attribute are:
•
•
•
•
•

Report: The Calculation Function is called only at the end of the report, passing to it the expression's
value at that moment.
Page: The Calculation Function is called at the end of each page, passing to it expression's value at each of
those moments.
Column: The Calculation Function is called at the end of each column (for a one-column report, this is the
same as Page).
Group: The Calculation Function is called at the start of every occurrence of the specified group. This
option is visible only if at least one group is defined.
None: The Calculation Function is called after the read of every record, this is the default behavior.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Remember the expression is evaluated at every record read, independent of the increment type selected, but the
calculation function is used only when the times match those defined in the increment type.

7.3.4

Reset Type
The reset type specifies when a variable should be reset to its initial value (or to null if no initial value is
defined). This is useful when the variable is used to compute a partial value, like a sum or an average of only
some of the records read.
The possible values for this attribute are:
•
•
•
•
•

7.3.5

Report: The variable is initialized only one time at the beginning of the report creation.
Page: The variable is initialized on each page.
Column: The variable is initialized again in each new column (for a one-column report, this is the same as
Page).
Group: The variable is initialized at the start of every occurrence of the specified group. This option is
available only if at least one group is defined.
None: The variable is never initialized, so the initial value expression is ignored.

Incrementer Factory Class Name
The calculation functions are useful, but limited to numeric types. You may have a case where something more
specific is needed. Suppose you have a String type field and you want to concatenate the value read. You can
do this by defining a new Incrementer. An incrementer is a piece of Java code that extends the
JRIncrementerFactory interface, and can build a personalized calculation function to do what you need.
Every calculation function receives the expression value and the variable value and returns the result of the
incrementation, so there is everything needed to do the calculation and return the right value.

7.4

Built-In Variables
Jaspersoft Studio makes some built-in variables available to you. See the table below. These variables can't be
edited. You'll notice their names are light gray; other variables are black.

Variable Name

Description

PAGE_NUMBER

Contains the current number of pages in the report at report time.

COLUMN_NUMBER

Contains the current number of columns.

REPORT_COUNT

Contains the number of records processed.

PAGE_COUNT

Contains the current number of records processed in the current page.

COLUMN_COUNT

Contains the current number of records processed during the current column
creation.

TIBCO Software Inc.

Chapter 7 Variables

7.5

Tips & Tricks
Pay attention to the variable type. For example if your expression returns a number but the variable type is
string (the default type) then its value is always zero.
The form of the expression is very important for the computation of a value, especially when the variable itself
is used in the expression. Consider the following example:
A field with name Money_Gained with an integer value, which could be null, is read from the data source.
A variable Total1 with the expression:
IF(EQUALS($F{Money_Gained}, null), $V{Total1}, $V{Total1}+$F{Money_Gained})

initial value zero, and no calculation function;
A variable Total2 with the expression
$V{Money_Gained} == null ? $V{Total2} : $V{Total2}+$F{Money_Gained}

initial value zero, and no calculation function;
The two expressions seem equivalent. They both add the money gained to the variable when it's not null
(remember that if there's no calculation function, the value of the expression is assigned to the variable). The
check if the Money_Gained has a null value is necessary because the sum of a number with the value null is
null. So adding null to Total1 or Total2 changes the variable to null. But even with this check when Money_
Gained becomes null for the first time even Total1 is null, instead Total2 has the correct value.
This happens because these two expressions have different interpreters, the first is interpreted by Groovy, the
second by Java. The Java behavior evaluates the condition and then selects the correct branch. The Groovy
behavior computes the two branches, then evaluates the expression, and finally returns the correct branch. Doing
this adds the null value to Total1 before doing the check, and makes Total1 null. To avoid this, use the
variable in the main branch only, for example Total1 could be rewritten as:
$V{Total1} + IF(EQUALS($F{Money_Gained}, null),0,F{Money_Gained}).
The syntax is still interpreted by Groovy, but now the variable is out of the IF branches, so even if they are
both evaluated, the variable maintains its value.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

TIBCO Software Inc.

CHAPTER 8

EXPRESSIONS

Many settings in a report are defined by formulas, such as conditions that can hide an element, special
calculations, or text processing that requires knowledge of a scripting language.
Formulas can be written in at least three languages, two of which (JavaScript and Groovy) can be used without
knowledge of programming methods.
All formulas in JasperReports are defined through expressions. The default expression language is Java, but if
you're not a programmer, we recommend JavaScript or Groovy, because those languages hide a lot of the Java
complexity. The language is a property of the document. To set it, select the document root node in the Outline
view and choose your language in the Language property in the Properties view.
An expression is a formula that operates on some values and returns a result, like a formula in a spreadsheet cell.
A cell can have a simple value or a complex formula that refers to other values. In a spreadsheet you refer to
values contained in other cells; in JasperReports you use the report fields, parameters, and variables. Whatever is
in your expression, when it's computed, it returns a value (which can be null).

8.1

Expression Types
An expression's type is determined by the context in which the expression is used. For example, if your
expression is used to evaluate a condition, the expression should be Boolean (true or false); if you're creating an
expression to display in a text field, it's probably a String or a number (Integer or Double). Using the right type
is crucial; JasperReports requires precision when choosing an expression type.
Some of the most important Java types are:
java.lang.Boolean

Defines an Object that represents a Boolean value such as true
and false

java.lang.Byte

Defines an Object that represents a byte

java.lang.Short

Defines an Object that represents an short integer

java.lang.Integer

Defines an Object that represents integer numbers

java.lang.Long

Defines an Object that represents long integer numbers

java.lang.Float

Defines an Object that represents floating point numbers

java.lang.Double

Defines an Object that represents real numbers

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

java.lang.String

Defines an Object that represents a text

java.util.Date

Defines an Object that represents a date or a timestamp

java.lang.Object

A generic java Object

If an expression is used to determine the value of a condition that determines, for instance, whether an element
should be printed, the return type is java.lang.Boolean. To create it, you need an expression that returns an
instance of a Boolean object. Similarly, if an expression shows a number in a text field, the return type is
java.lang.Integer or java.lang.Double.
Neither JavaScript nor Groovy is particularly formal about types, since they are not typed languages; the
language itself treats a value in the best way by trying to guess the value type or by performing implicit casts
(conversion of the type).

8.2

Expression Operators and Object Methods
Operators in Java, Groovy and JavaScript are similar because these languages share the same basic syntax.
Operators can be applied to a single operand (unary operators) or on two operands (binary operators). The
following table shows a number of operators, but it is not a complete list. For example, there is a unary operator
to add 1 to a variable (++), but it is easier to use x + 1.
Table 8-1 Expression operators
Operator

Description

Example

Sum (it can be used to sum two numbers or to concatenate two strings)

A + B

Subtraction

A - B

Division

A / B

Rest, it returns the rest of an integer division

A % B

Boolean operator OR

A || B

Boolean operator AND

A && B

Equals

A == B

Not equals

A != B

Boolean operator NOT

Regarding the Equals operator: in Java, the == operator can only be used to compare two primitive
values. With objects, you need to use the special method “equals”; for example, you cannot write an
expression like "test" == "test", you need to write "test".equals("test").
Regarding the Equals operator: in Java, the != operator can only be used to compare two primitive
values.

TIBCO Software Inc.

Chapter 8 Expressions

Within an expression, you can use the syntax summarized in Table 8-2, “Syntax for referring to report
objects,” on page 95 to refer to the parameters, variables, and fields defined in the report.
Table 8-2 Syntax for referring to report objects
Syntax

Description

$F{name_field}

Specifies the name_field field ("F" means field).

$V{name_variable}

Specifies the name_variable variable.

$P{name_parameter}

Specifies the name_parameter parameter.

$P!{name_parameter}

Special syntax used in the report SQL query to indicate that the parameter does not
have to be dealt as a value to transfer to a prepared statement, but that it represents
a little piece of the query.

$R{resource_key}

Special syntax for localization of strings.

$X{functionName,
col_name, param1,
[param2]}

Syntax for complex queries, such as comparing a column value to a parameter
value. Based on the function in the first argument, JasperReports constructs a SQL
clause. The following functions are available:
•

Functions expecting three arguments for $X{} – EQUAL, NOTEQUAL, LESS,
LESS] (less than or equal to), GREATER, [GREATER (greater than or equal to),
IN, NOTIN. For example:
$X{EQUAL, order_date, date_parameter}

•

Functions expecting four arguments for $X{} –
BETWEEN (excludes both endpoints)
BETWEEN] (includes right endpoint)
[BETWEEN (includes left endpoint)
[BETWEEN] (includes both endpoints)
For example:
$X{BETWEEN, order_date, start_date_param, end_date_param}

In summary, fields, variables and parameters represent objects; specify their type when you declare them within
a report.
Although expressions can be complicated, usually it is a simple operation that returns a value. There is a simple
if-else expression that is very useful in many situations. An expression is just an arbitrary operation that any
stage must represent a value. In Java, these operators can be applied only to primitive values, except for the sum
operator (+). The sum operator can be applied to a String expression with the special meaning of concatenate.
For example:
$F{city} + “, ” + $F{state}

results in a string like:
San Francisco, California

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

Any object in an expression can include methods. A method can accept zero or more arguments, and it can
return or not a value. In an expression you can use only methods that return a value; otherwise, you would have
nothing to return from your expression. The syntax of a method call is:
Object.method(argument1, argument2, )

Some examples:
Expression

Result

“test”.length()

“test”.substring(0, 3)

“tes”

“test”.startsWith(“A”)

false

“test”.substring(1, 2).startsWith(“e”)

true

The methods of each object are usually explained in the JasperReports Library Javadocs, which that are
available at http://jasperreports.sourceforge.net/api/.
You can use parentheses to isolate expressions and make the overall expression more readable.

8.3

Using an If-Else Construct in an Expression
A way to create an if-else-like expression is by using the special question mark operator. For example:
(($F{name}.length() > 50) ? $F{name}.substring(0,50) : $F{name})

The syntax is () ? : . It is extremely useful, and can be
recursive, meaning that the value on true and false can be represented by another expression which can be a
new condition:
(($F{name}.length() > 50) ?
(($F{name}.startsWidth(“A”)) ? “AAAA” : “BBB”)
:
$F{name})

This expression returns the String AAAA when the value of the field name is longer than 50 characters and starts
with A, returns BBB if it is longer than 50 characters but does not start with A, and, finally, returns the original
field value if neither of these conditions is true.
Despite the possible complexity of an expression, it can be insufficient to define a needed value. For example, if
you want to print a number in Roman numerals or return the name of the weekday of a date, it is possible to
transfer the elaborations to an external Java class method, which must be declared as static, as shown in the
following example:
MyFormatter.toRomanNumber( $F{MyInteger}.intValue() )

The function operand toRomanNumber is a static method of the MyFormatter class, which takes an int as
argument (the conversion from Integer to int is done by means of the intValue() method; it is required only
when using Java as language) and gives back the Roman version of a number in a lace.
This technique can be used for many purposes; for example, to read the text from a CLOB field or to add a
value into a HashMap (a Java object that represents a set of key/value pairs).

TIBCO Software Inc.

Chapter 8 Expressions

8.4

Using Unicode Characters in Expressions
You can use Unicode syntax to write non-Latin-based characters (such as Greek, Cyrillic, and Asian characters).
For these characters, specify the Unicode code in the expression that identifies the field text. For example, to
print the Euro symbol, use the Unicode \u20ac character escape. The expression \u20ac is not simple text; it is
a Java expression that identifies a string containing the € character.
If you use this character in a static text element, “\u20ac” will appear. The value of a static field is not
interpreted as a Java expression.

8.5

Using Java as a Language for Expressions
Java was the first language supported by JasperReports and is still the most commonly-used language as well as
being the default.
Following are some examples of Java expressions:
•
•
•
•

“This is an expression”
new Boolean(true)
new Integer(3)
(($P{MyParam}.equals("S")) ? "Yes" : "No")

The first thing to note is that each of these expressions represents a Java Object, meaning that the result of each
expression is a non-primitive value. The difference between an object and a primitive value makes sense only in
Java, but it is very important: a primitive value is a pure value like the number 5 or the Boolean value true.
Operations between primitive values have as a result a new primitive value, so the expression:
5+5

results in the primitive value 10. Objects are complex types that can have methods, can be null, and must be
“instanced” with the keyword “new” most of the time. In the second example above, for instance (new Boolean
(true)), we must wrap the primitive value true in an object that represents it.
By contrast, in a scripting language such as Groovy and JavaScript, primitive values are automatically wrapped
into objects, so the distinction between primitive values and objects wanes. When using Java, the result of our
expression must be an object, which is why the expression 5+3 is not legal as-is but must be fixed with
something like this:
new Integer( 5 + 3 )

The fix creates a new object of type Integer representing the primitive value 10.
So, if you use Java as the default language for your expressions, remember that expressions like the following
are not valid:
•
•
•

3 + 2 * 5
true
(($P{MyParam} == 1) ? "Yes" : "No")

These expressions don’t make the correct use of objects. In particular, the first and the second expressions are
not valid because they are of primitive types (integer in the first case and boolean in the second case) which
do not produce an object as a result. The third expression is not valid because it assumes that the MyParam
parameter is a primitive type and that it can be compared through the == operator with an int, but it cannot. In
fact, we said that parameters, variables, and fields are always objects and primitive values cannot be compared
or used directly in a mathematical expression with an object.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

8.6

Using Groovy as a Language for Expressions
The modular architecture of JasperReports provides a way to plug in support for languages other than Java. By
default, the library supports bsh, Groovy and JavaScript.
Groovy is a full language for the Java 2 Platform. Inside the Groovy language you can use all classes and JARs
that are available for Java. The following table compares some typical JasperReports expressions written in Java
and Groovy:
Table 8-3 Groovy and Java code samples
Expression

Java

Groovy

Field

$F{field_name}

Sum of two
double fields

new Double($F{f1}.doubleValue() + $F{f2}.doubleValue())

$F{f1} + $F
{f2}

Comparison
of numbers

new Boolean($F{f}.intValue() == 1)

$F{f} == 1

Comparison
of strings

new Boolean($F{f} != null && $F{f}.equals("test"))

$F{f} ==
"test"

The following is a correct Groovy expression:
new JREmptyDataSource($F{num_of_void_records})
JREmptyDataSource is a class of JasperReports that creates an empty record set (meaning with the all fields set

to null). You can see how you can instance this class (a pure Java class) in Groovy without any problem. At the
same time, Groovy allows you to use a simple expression like this one:
5+5

The language automatically encapsulates the primitive value 10 (the result of that expression) in a proper object.
Actually, you can do more: you can treat this value as an object of type String and create an expression such
as:
5 + 5+ ”my value”

Whether or not such an expression resolves to a rational value, it is still a legal expression and the result is an
object of type String with the value:
10 my value

Hiding the difference between objects and primitive values, Groovy allows the comparison of different types of
objects and primitive values, such as the legal expression:
$F{Name} == “John”

This expression returns true or false, or, again:

$F{Age} > 18

Returns true if the Age object interpreted as a number is greater
than 18.

“340” < 100

Always returns false.

TIBCO Software Inc.

Chapter 8 Expressions

“340”.substring(0,2) < 100

Always returns true (since the substring method call produces the
string “34”, which is less than 100).

Groovy provides a way to greatly simplify expressions and never complains about null objects that can crash a
Java expression throwing a NullPointerException. It really does open the doors of JasperReports to people
who don’t know Java.

8.7

Using JavaScript as a Language for Expressions
JavaScript is a popular scripting language with a syntax very similar to Java and Groovy. JavaScript has a set of
functions and object methods that in some cases differ from Java and Groovy. For example, the method
String.startsWith(...) does not exist in JavaScript. You can still use Java objects in JavaScript. An
example is:
(new java.lang.String("test")).startsWith("t")

This is a valid JavaScript expression creating a Java object (in this case a java.lang.String) and using its
methods.
JavaScript is the best choice for users who have no knowledge of other languages. The other significant
advantage of JavaScript is that it is not interpreted at run time, but instead generates pure Java byte-code. As a
result, it offers almost the same performance as Java itself.

TIBCO Software Inc.

TIBCO Jaspersoft Studio User Guide

100

TIBCO Software Inc.

CHAPTER 9

FONTS

The best way to define and use a font in JasperReports Library is to create and use a font extension. Font
extensions force JasperReports to work with external TTF, SVG, WOFF, or EOT fonts instead of using built-in
or system fonts. This ensures that a specific font behaves in the same way wherever the report is executed.
Using system fonts usually results in unacceptable changes in report format when the report is deployed on
another system. Subtle differences in font size and spacing can affect not only the appearance of the text but the
layout of the report itself. You may lose part of the text in a text element or the font might not be available at
all. Font extensions help avoid these problems:
•
•
•

A font can be available in one operating system but not in another. In this case, the default font is used for
the element, but it may not support the expected character set.
The Java virtual machine can map logical font family names to different physical fonts.
A font that is available in different operating systems can be slightly different from one operating system to
another.

You can incorporate additional information in a font extension, such as: bold and italic fonts, the text encoding
for the font, and a list of locales where the font should be used. You can also use font extensions to embed your
fonts in PDF files.
In addition, you can combine several font extensions into a font set. For example, if you have data in English
and Japanese, you can create a single font set that combines fonts for those languages.

9.1

Font Extensions Reference
You work with font extensions using the Fonts page in the Preferences dialog.

9.1.1

The Fonts Page
The Fonts page displays all your font extensions and font sets, and lets you create, copy, edit, delete, and
reorder fonts and font sets.
To access the Fonts page:
1. Select Window > Preferences. The Preferences dialog is displayed.
2.

In the Preferences dialog, select Jaspersoft Studio > Fonts.
The Fonts page is displayed.

TIBCO Software Inc.

101

TIBCO Jaspersoft Studio User Guide

Figure 9-1 Fonts page
The Fonts page shows the following:
•

•
•
•
•
•
•
•
•
•

102

Font List – The list of font extensions and font sets. Font sets are prepended with +; click to expand and
show the font extensions contained in the font set. When you create a font set, the default font for the set is
the font that appears highest in the list when the font set is created. Inside a font set, non-default fonts are
applied in the order they appear in the font list.
Add from URL – Specify a URL location for a zip file of the fonts you want to add as extensions. To add
all the Noto fonts from Google, click and select the Noto URL.
Add from Path – Specify a folder containing the fonts you want to add as extensions.
Duplicate – Create a copy of the selected font extension(s) and/or font set(s). Each copy has a unique
name, which can be edited.
Delete – Delete the selected font extension(s) and/or font set(s). This does not remove the original font files
from your system.
Up – Move the selected font extension and/or font set up in the list of fonts.
Down – Move the selected font extension and/or font set down in the list of fonts.
Create Set – Combine the selected font extensions into a font set.
Edit – Edit the selected font extension or set. For a font extension, displays The Font Family Dialog. For a
font set, displays the Font Set dialog.
Export – Export the selected font extension or set.

TIBCO Software Inc.

Chapter 9 Fonts

9.1.2

The Font Family Dialog
The Font Family dialog lets you configure an existing font extension and create and configure font sets. This
dialog has three pages.
To access the Font Family dialog:
Select a font extension in the Fonts list and click Edit.

9.1.2.1 Font Family Page
The Font Family page lets you define the basic configuration of the font or font set.

Figure 9-2 Font Family dialog – Font Family
The Font Family page shows the following:
•

•

Family Name – Name JasperReports Library uses to identify the font extension or font set. When you
create a font extension from an external font file, by default, the font name is used for the family name. This
can be edited.
Hidden – Flag that determines whether the font is shown as an available font extension "above the line" in
the Font property of a report element. Use the Hidden flag to hide internal fonts from the user. See 9.2.2,
“Using Font Extensions in a Report,” on page 112 for more information.

TIBCO Software Inc.

103

TIBCO Jaspersoft Studio User Guide

•

Normal/Bold/Italic/Bold Italic – Tabs that let you configure the individual files that define the specified
attributes. For each attribute, you can configure the following:
• [Font Format] – File location for the specific font and attribute. To change or add a file, use the
Browse button to navigate to the file location for the specific font and attribute. You can only select
one file for each tab.
• PDF Font Name (deprecated) – The name of the font when exported to PDF. This can be a predefined PDF font or the name of the font file. Not necessary when using font extensions.
PDF Details – Settings used for the font when exported to PDF. Deprecated for static text and textfields.
• PDF Encoding (deprecated) – The font encoding to use for the font. Defaults to Identity-H. To avoid
Identity-H printing issues, set this to the correct encoding for your font.
• Embed this font in PDF document (deprecated) – Flag that specifies whether to embed the font in a
generated PDF or not. Embedding fonts is recommended to ensure consistency across platforms.

9.1.2.2 Font Mapping Page
The Font Mapping page lets you specify a font mapping to use when one or more font files are not installed in
the target environment. The order of the font names indicates the order in which the web browser should search
for the replacement font. Once a replacement font is found, the browser stops searching and renders the text. If
no font mapping is available for HTML, then web fonts are used.
To access the Font Mapping Page:
Click Next on the Font Family page.

Figure 9-3 Font Family dialog – Font Mapping
If a mapping is present, then web fonts are not used. Do not define a font mapping unless you want to
override the web font functionality.

104

TIBCO Software Inc.

Chapter 9 Fonts

The Font Mapping page shows the following:
•
•
•
•

•

Default Mapping – A string that defines a mapping for the font. For example, a serif font might be set to:
'My font family', 'Times New Roman', 'Times', 'Serif'.
Add button – Adds the string in the Default Mapping field to the list of mappings.
Delete button – Deletes the currently highlighted mapping.
Export Type – Sets the file type (html, xhtml, or rtf). Click on a value to display a down arrow, then click
on the arrow to select a type from the cascading menu. Defaults to html. You can define different mappings
for different file types.
Mapped Font Name – Click on a value to edit the name of the mapped font.

9.1.2.3 Locale Mapping Page
The Locale Mapping page lets you set the locales where this font family is used. If you have different font
extensions that support different languages, (for example, a font for Western European and a font for Japanese),
you can set the locales for these fonts. It is preferable to use font sets.
To access the Font Locale Page:
Click Next on the Font Mapping page.

Figure 9-4 Font Family dialog – Locale

TIBCO Software Inc.

105

TIBCO Jaspersoft Studio User Guide

The Locales page shows the following:
•
•
•

9.1.3

Locale – List of locales supported by the font.
Add button – Add a locale where the font is supported.
Delete button – Delete the selected locale.

Font Sets
Font sets let you group font extensions in supersets that can include several languages and/or scripts. When you
use a font set, the font family resolution occurs during text processing on a per-character basis, allowing you to
include characters from different languages or character sets in the same text element. For example, if you have
data that includes Japanese and English entries, you can create a single font set that contains Western European
and Japanese fonts and use that font set for your data.

9.1.3.1 The Font Set Dialog
When you create or edit a font set, the Font Set dialog lets you edit the name for the font set.
Accessing the font set dialog:
• To create a font set, select the font extensions you want to combine, and click Create Font Set. Enter a
name for the set and click OK.
• To edit the name of an existing font set, select the set and click Edit.

Figure 9-5 Font Set dialog
9.1.3.2 The Font Set Family Dialog
The Font Set Family dialog lets you control the mapping between fonts and characters sets for a font set. In
many cases, multiple fonts inside a font family may support the same character set or "script". In this case,
JasperReports Library uses a greedy algorithm to display as much contiguous text as possible in a single font. If
you want to ensure that a specific font extension is used for a specific script, you can set the included/excluded
scripts for the fonts in your font set.
To access the Font Set Family dialog:
Expand a font set in the Fonts list, then double-click a font inside the set.

106

TIBCO Software Inc.

Chapter 9 Fonts

Figure 9-6 Font Set Family dialog
The Font Set Family dialog shows the following:
•
•
•

9.2

Primary – Toggle that sets the primary font for the font set.
Include Scripts – Language/character sets that should use this font extension when the font set is applied.
Click Add to add a script; highlight a dis
Exclude Scripts – Language/character sets that should never use this font extension when the font set is
applied.

Example of Using Font Extensions
This example shows how to create font extensions for two font and then combine them in a font set.

TIBCO Software Inc.

107

TIBCO Jaspersoft Studio User Guide

9.2.1

Creating Font Extensions and Font Sets
To access the Fonts page:
1. Select Window > Preferences. The Preferences dialog box is displayed.
2.

In the Preferences dialog box, select Jaspersoft Studio > Fonts.
The Fonts page is displayed:

Figure 9-7 Fonts preferences
To create a font extension:
This example uses two external Google fonts, Amaranth (a Latin-only font) and Lobster (supports Latin and
Cyrillic characters). If you don't have these fonts available, you can work with other fonts. However, you must
have the correct license to embed your fonts in a PDF.

108

Make sure the font files for the fonts have been downloaded and decompressed. You can also use fonts from
a URL.

Click Add from Path to open the Fonts path dialog.

TIBCO Software Inc.

Chapter 9 Fonts

Figure 9-8 Adding fonts from a path
3.

Click ... and browse to the folder that contains the fonts you want, then click Finish.
Jaspersoft Studio loads all the fonts at that location, extracts the font family name embedded in the font
files, and displays all the extracted fonts in the Preferences dialog.
Once you have create a font extension, you can edit it by double-clicking its name in the font list or by
selecting it and clicking Edit. See 9.1.2, “The Font Family Dialog,” on page 103 for more information.

Next, combine these two font extensions in a single font set.
To create a font set:
1. In the Font section of the Preferences dialog, select the fonts you want in your set.

TIBCO Software Inc.

109

TIBCO Jaspersoft Studio User Guide

Figure 9-9 Selecting font extensions
2.

Click Create Font Set. The Font Set dialog is displayed.

Figure 9-10 Font Set dialog
3.

Enter a name for your font set and click OK. This example uses SampleFontSet.
The new font set is displayed in the font list.

Next, configure the fonts in the font set so that Lobster is only used for Cyrillic characters, even though it
supports Latin characters.
Configure fonts in a font set:
1. Expand the font set to display the names of the individual font extensions.

110

TIBCO Software Inc.

Chapter 9 Fonts

Figure 9-11 Fonts window with expanded font set
2.

Select Lobster and click Edit or double-click Lobster.
The Font Set Family dialog is displayed.

TIBCO Software Inc.

111

TIBCO Jaspersoft Studio User Guide

Figure 9-12 Font Set Family dialog

9.2.2

To prevent Lobster from being used by Latin characters, click Add next to the Exclude Scripts list.
The Scripts name dialog is displayed.

Select Latin in the Scripts Name dialog and click OK.
Latin is added to the list of excluded scripts.

Click OK to close the Scripts Name dialog; click OK again to close the Font Set Family dialog and click
OK a third time to close the Preference dialog.

Using Font Extensions in a Report
Once you have set up your font set, you can use it in a report.
Create a report with a local data adapter:
1. Export the One Empty Record adapter to your project. To do this:
a.

112

In the Repository Explorer, right-click the One Empty Record adapter and select Export to File.

TIBCO Software Inc.

Chapter 9 Fonts

Figure 9-13 Exporting a global data adapter
b.

Select the project you want and click OK.
A data adapter file is created in your project.

Go to File > New > Jasper Report or click

In the New Report Wizard window, select a blank template, such as the Blank A4 template, then click
Next.

Select the project folder with the data adapter file you just created, give the report a name, and click Next.

On the Data Source page, select the One Empty Record - [OneEmptyRecord.xml] adapter. Make sure to
select this adapter, which is local, and not the One Empty Record adapter which is selected by default.

on the main toolbar.

Figure 9-14 Selecting the local data adapter
6.

Click Finish.

TIBCO Software Inc.

113

TIBCO Jaspersoft Studio User Guide

Set the default data adapter for the report:
a.

Select the report node in Outline view.

In the Properties view for the report, on the Report tab, scroll down to Dataset > Default Data
Adapter and click ...

In the Open Data Adapter dialog, select Custom Value.

Enter OneEmptyRecord.xml in the Path entry box.

Figure 9-15 Default Data Adapter
e.

Click Finish.

Create a report with multi-lingual text:
1. Create a new report with a blank template
2.

Drag the Static Text element

Enter English and Cyrillic text in the element you just created:

into the Title band of the report.

Report Отчёт
4.

Select the element.

Expand the Font menu on the Static Text tab of the Properties View for the static text element.
The menu is divided into two sections. Installed font extensions or font sets appear above the line. Fonts
below the line are not installed as font extensions. In this example, Amaranth, Lobster, and SampleFontSet
are all above the line.

Figure 9-16 Font menu with font extensions

114

TIBCO Software Inc.

Chapter 9 Fonts

The default font used for a new static text element is SansSerif. This font does support for extended
characters, but because it's a Java logical font that is translated to a physical font by the JVM, you won't
know what font will be selected when the report is run.
6.

Select SampleFontSet from the Font menu and 24 from the size menu next to it. Then resize the static
text element so it is large enough to display the text.

Figure 9-17 Font set in design view
7.

Save and preview the report. The license for these fonts let you preview the report as a PDF.

Figure 9-18 Font set in preview

9.3

Deploying Font Extensions to JasperReports Server
When use font extensions in a report, the font extensions are not automatically available on the server. You
need to export your font extensions as a jar and upload them to the server. For reports in HTML, add the jar to
the server classpath and enable font support in jasperreports.properties. For reports in PDF, add the jar to the
report as a resource.
Deploy the report to JasperReports Server:
1.

Click

on the main menu bar.

2.
3.

In the Publish To JasperReports Server dialog, select the JasperReports Server instance you want and choose
a location for the report. This example uses Public > Samples > Reports.
Enter a name for the report on JasperReports Server. This example uses SampleFontSetReport.

Click Next.

Verify that OneEmptyRecord appears as a resource to publish on the next page, then click Next.

Verify that Don't use any Data Source is selected on the Configure the Data Source page. Making this
selection ensures that the uploaded adapter will be used for the report.

Click Finish. If the publishing process succeeds, a success dialog is displayed.

Click OK to exit the success dialog.

View the report on JasperReports Server:
1. Log in to the server, navigate to the report you just created, and run the report.
You will see that the report does not use the correct fonts. You need to export the fonts in Jaspersoft Studio
and upload them to the server.

TIBCO Software Inc.

115

TIBCO Jaspersoft Studio User Guide

When working with fonts, look carefully at your uploaded reports. For some fonts or character sets, you
will not see misformatted text; instead, the text will not be displayed at all.

Export the font set in Jaspersoft Studio:
1. In Window > Preferences > Jaspersoft Studio > Fonts, select the font set and the fonts within it and
click Export. For this example, select Amaranth, Lobster, and SampleFontSet.
2.

In the Export Font to Jar dialog, select a name and location for the exported file and click Save. For this
example, use SampleFontSet.jar.
The font set is exported as a jar in the location you chose. This is not a regular font jar; it is a jar file that
includes additional information used by Jaspersoft.

Add the font set as a jar on your JasperReports Server instance:
1. On the machine hosting your JasperReports Server instance, enable font support by adding the following to
your \WEB-INF\classes\jasperreports.properties file:
net.sf.jasperreports.web.resource.pattern.fonts=fonts/.*
You only have to enable font support once.

Add the exported font set jar to your WEB-INF\lib directory.

Stop and restart your JasperReports Server instance. See the JasperReports Server Installation Guide for
more information.

Upload the font set as a resource:
You can attach the resource directly to the report, or you can upload it to another location, for example the
report directory and link the report to it. Uploading a resource to another location makes it easier to reuse the
resource.

116

In the Repository Explorer in Jaspersoft Studio, navigate to the folder on your JasperReports Server instance
where you want to add this resource. For this example, it is the Public > Samples > Resources folder.

Right-click the folder and select New from the cascading menu.

TIBCO Software Inc.

Chapter 9 Fonts

Figure 9-19 Adding a resource in the Repository Explorer
3.

Select Jar in the Add Resource wizard and click Next.

Enter a name and ID for your jar and click Next.

Select Upload from File System, select the jar you want, and click Open.

Click Finish to upload the selected jar.

Add the resource to your report:
1. Right-click your report in the Repository Explorer and select New from the cascading menu.
2.

Select Link in the Add Resource Wizard and click Next.

3.
4.

Enter a name and ID for the link and click Next.
Click to open the Find Resource dialog.

Navigate to the jar you uploaded and click Open.

Click Finish to attach the jar to the report as a resource.

View the report on JasperReports Server:
1. Open a web browser, log in to the server, navigate to the report you just created, and run the report. You
should see the correct fonts. If you do not see your fonts, there has been a problem with uploading the jar to
the file system.
2.

Export the report as PDF. You should see the updated fonts. If not, there has been some problem uploading
and linking the resource.
When verifying font extensions and sets, it is best to run the report in JasperReports Server from a web
browser. Running the report from Repository Explorer in Jaspersoft Studio may not show the fonts
correctly.

TIBCO Software Inc.

117

TIBCO Jaspersoft Studio User Guide

118

TIBCO Software Inc.

CHAPTER 10 DATA ADAPTERS
A data adapter is a resource that specifies how and where to obtain data. Specifically, it is an object that
contains information about how to connect to or retrieve the data, and the logic to do that. Data adapters are
stored in XML files and simplify porting of the report configuration and data source creation between
JasperReports environments. Whether you use a report with a data adapter XML file in Jaspersoft Studio,
publish it to JasperReports Server or deploy it to a custom JasperReports environment, JasperReports Library can
use it to obtain the data you specify.
This chapter starts by telling you how to create and use data adapters based on the data adapter types available
in Jaspersoft Studio. Data adapters are designed to simplify the complexities of working with data in
JasperReports Library. However, data adapters are only one of the ways that JasperReports Library can get data
from a data source. As you get more familiar with Jaspersoft Studio, you may want to go a little deeper and
learn about data in JasperReports Library and the JRDataSource interface.
Usually data adapters are stored as XML files in the same project as the report to simplify deployment to
JasperReports Server or another environment. In Jaspersoft Studio, data adapters can also be stored in the
Repository Explorer, in which case they are visible from all the projects. If you plan to deploy the report outside
Jaspersoft Studio, it is better to store it in the project from the beginning.
This chapter has the following sections:
•
•
•
•
•
•
•
•
•
•
•
•

Creating and Editing Data Adapters
Using Data Adapters in Reports and Datasets
Working with Database JDBC Connections
Working with a MongoDB Data Adapter
Working with a Native Cassandra Connection
Working with a Collection of JavaBeans Data Adapter
Working with XML Data Adapters
Working with XML/A Data Adapters
Working with CSV Data Adapters
Using the Empty Record Data Adapter
Working with the JRDataSource Interface
A Look at TIBCO Spotfire Information Links

TIBCO Software Inc.

119

TIBCO Jaspersoft Studio User Guide

10.1

Creating and Editing Data Adapters

10.1.1

Creating a Data Adapter
You create data adapters using the Data Adapter Wizard. The exact steps and information you need to provide
vary with the type of adapter that you select. However, the initial steps are similar.
Data adapters can be created locally in projects or globally in the Repository Explorer.
•

•

Data adapters in projects are stored as XML files, which simplifies deployment to JasperReports Server. A
project-level data adapter cannot be seen from other projects, but you can easily copy it from one project to
another.
Global data adapters are saved as Eclipse settings and are visible to all projects. Global data adapters are
saved as Eclipse settings. To deploy a global adapter to JasperReports Server, you need to export it to an
XML file located in the same project as your report.

To create a data adapter in a project:
When you create a data adapter in a project, it is saved as an XML file in that project. Saving the XML file in
the same project as your reports makes it easier to deploy the data adapter to JasperReports Server.
1.
2.
3.

Click
on the main toolbar OR right-click a project in the Project Explorer and select New > Data
Adapter.
In the DataAdapter File window, choose the project where you want to save the data adapter file. This
should be the project that contains the report(s) you want to use with your data adapter.
Enter a name for your adapter and click Next.
The Data Adapters Wizard opens.

Figure 10-1 Data Adapter Wizard
4.

120

Select the data adapter type you want and click Next.

TIBCO Software Inc.

Chapter 10 Data Adapters

Enter a name for your adapter. This name is used when you select an adapter for a report.

Enter the properties needed by the adapter type you selected. For example, for a database JDBC connection
you need to select a JDBC driver and set the URL and database username and password. For a CSV file,
you need to enter a filename, column names, and the column separator.

(Optional) If you want to test the connection, click the Test button if available.

Click Finish to create the adapter.
The adapter is saved as an XML file in the project location you selected.

To create a global data adapter:
When you create a global data adapter, it is available to all reports. However, if you want to deploy it to
JasperReports Server, you must export it explicitly.

10.1.2

Click
in the Repository Explorer OR right-click Data Adapters in the Repository Explorer and choose
Create Data Adapter.
The Data Adapters Wizard opens.

2.
3.

Select the data adapter type you want and click Next.
Enter a name for your adapter and the properties needed by the adapter type you selected. To optionally test
the adapter, click the Test button.

Click Finish to create the adapter.

Importing and Exporting Data Adapters
Jaspersoft Studio enables you to import and export data adapter definitions to simplify the process of sharing
data source configurations.
To export a global data adapter as an XML file:
1. In the Repository Explorer, right-click your data adapter and select Export to File.
Jaspersoft Studio prompts you to name the file and select the destination for the exported information.

Figure 10-2 Export to File Dialog

TIBCO Software Inc.

121

TIBCO Jaspersoft Studio User Guide

Select a location in the same project as the report that will be using this adapter, enter a name for the file,
and click OK.
A simple XML file is created in the location you chose. The data adapter must be in the same project as
your report. To use the same adapter in more than one project, see 10.1.3, “Copying a Data Adapter,” on
page 122.

To promote a data adapter file to a global data adapter:
You can make any file-based data adapter into a global adapter by importing it.

10.1.3

1.
2.

Right-click on the Data Adapter node in the Repository Explorer, and choose Import from Workspace.
Select the data adapter(s) you want to import.

You can optionally select Overwrite Data Adapter if exists. Otherwise, if a duplicate data source name is
found during the import, Jaspersoft Studio appends a number to the imported data source name.

Click OK.
The import process adds all the selected data adapters to the current list.

Copying a Data Adapter
If you have saved your data adapter as an XML file, you can easily copy it between projects.
To copy a data adapter from one project to another:
1. In the Project Explorer, right-click your data adapter and select Copy OR use Ctrl-C.
2. Still in the Project Explorer, right-click the project or folder in your Jaspersoft Studio workspace that you
want to use and select Paste OR Ctrl-V.
The data adapter is copied to the new location.

10.2

Using Data Adapters in Reports and Datasets
You can use the Jaspersoft Studio user interface to select the data adapter to use for previewing reports and
datasets. However, this selection is specific to Jaspersoft Studio. When you want to deploy your reports to
JasperReports Server or to a custom JasperReports deployment, you must specify the data adapter or data source
you want to use.

10.2.1

Data Adapter For a Report
When you choose a data adapter during report creation, the drop-down lists all available adapters, with global
adapters on top and project file-based adapters below. The example below shows the global adapters available
with Jaspersoft Studio followed by a sample file-based adapter local to the project, named
SampleDataAdapter.xml.

122

TIBCO Software Inc.

Chapter 10 Data Adapters

Figure 10-3 List of Data Adapters During Report Creation
Data adapters are hierarchical. That is, if no adapter is directly defined for a subdataset, it looks for the adapter
of its parent dataset, then its parent's parent, and so forth.

10.2.2

Data Adapters and Report Deployment
When you use a drop-down to select a data adapter for a report or dataset, you are just setting the current
default data adapter used for preview. As you continue to design your report, you can easily change this data
adapter by selecting a different data adapter during preview, or by editing the dataset and changing the adapter.
If you do not select a data adapter during preview, Jaspersoft Studio defaults to whichever data adapter was
used most recently. If no data adapter is selected when you create a report, Jaspersoft Studio defaults to the preconfigured empty data adapter.
This data adapter is internal to Jaspersoft Studio. It is stored in an internal property
(com.jaspersoft.studio.data.defaultdataadapter) which cannot be used in JasperReports Server or
JasperReports Library. Therefore, when you publish or deploy a report, you need to specify the data source you
want to use in the deployed report. You can do this in the following ways:
•

•

10.2.3

When you publish a report to JasperReports Server, you can select a JasperReports Server data source to use.
See 12.2, “Publishing a Report to JasperReports Server,” on page 174 for more information. If you
choose this method to select a data source, any subdatasets in the report must use the same data source.
You can choose to set the default data adapter explicitly for the report and/or any subdatasets. You can set
this property separately for any dataset in the report. If this property is present, you cannot choose a
different adapter to preview the report.

Default Data Adapter
You can explicitly set the data adapter for a report or dataset using the
net.sf.jasperreports.data.adapter property.
Setting the default data adapter:
1. In Outline view, to set the data adapter for the report, click the report's root node. To set the data adapter for
a dataset, click the dataset.

TIBCO Software Inc.

123

TIBCO Jaspersoft Studio User Guide

In the Properties view, to set the data adapter for a report, go to the Report tab. To set the data adapter for a
dataset, go to the Dataset tab.

Click ... at the right of the Default Data Adapter property.
The Open Data Adapter dialog opens.

Figure 10-4 Open Data Adapter Dialog
4.

Choose the format to use for specifying the data adapter location:
•

•

Workspace resource – A file in your workspace, for example, value="../test/sampleadapter.xml"/>. This should be a file in the same project as your report. If you want to use a global
adapter, you need to export it to a file first. See 10.1.2, “Importing and Exporting Data Adapters,” on
page 121 for more information.
Absolute Path in the file system – A file path, for example,
value="file:///C:/Adapters/sample-adapter.xml"

•

URL – A remote URL that hosts the data adapter file, for example,
value="http://myserver:8080/sample-adapter.xml"

•

5.
6.

124

Custom value – A free-form string that identifies the location of the data adapter to use. You could
use this if you wanted to enter a string in the repo: syntax, for example,
value="repo:/reports/interactive/CustomersDataAdapter" See 12.8, “Understanding the
repo: Syntax,” on page 190 for more information.
If you selected Workspace resource or Absolute Path, click Browse to locate the file in the workspace
or in your file system. Otherwise, enter the URL or free-form string.
Click Finish.
The default data adapter is set for the dataset. It is represented in the JRXML file using the
net.sf.jasperreports.data.adapter property.

TIBCO Software Inc.

Chapter 10 Data Adapters

Figure 10-5 Dataset with Default Data Adapter
10.2.3.1 The JasperReports Data Adapter in the UI
When the JasperReports data adapter is present, it is shown as the bottom adapter on the list of available
adapters. In the example below, New Data Adapter has been set as the default data adapter:

Figure 10-6 List of Data Adapters Including Default Data Adapter

10.3

Working with Database JDBC Connections
A JDBC connection lets you use a database accessed through a JDBC driver (such as a relational DBMS). When
you use a JDBC connection in a report, you must specify a query.

10.3.1

Creating a Database JDBC Connection
To create a new JDBC connection:
1. Create the connection globally or locally:
•

To create the connection globally, right-click Data Adapters in the Repository Explorer and choose
Create Data Adapter.

TIBCO Software Inc.

125

TIBCO Jaspersoft Studio User Guide

•

To create the connection local to a project, click
, enter a name and location for the data adapter in
the DataAdapter File dialog box, and then click Next.
The Data Adapter wizard appears (see Figure 10-1, “Data Adapter Wizard,” on page 120).
2.

From the list, select Database JDBC connection to open the Data Adapter dialog.

Figure 10-7 Configuring a JDBC Connection
3.

Name the connection (use a significant name like Mysql – Test). This is the name that will appear on the
list of available connections when you create a report.

In the JDBC Driver field, specify the JDBC driver to use for your database connection. The drop-down
displays the names of the most common JDBC drivers.

Figure 10-8 JDBC Drivers List

126

TIBCO Software Inc.

Chapter 10 Data Adapters

If a driver is displayed in red, the JDBC driver class for that driver is not present in the class path and you
must obtain and install the driver before using it. See 10.3.3, “Using a Database JDBC Connection,” on
page 129.
As of version 5.6.1, JasperReports Server includes the TIBCO JDBC drivers for the following commercial
databases: Oracle, MS SQLServer and DB2. In some cases, these drivers provide functionality not
provided by the vendors' driver. However, there may be some differences in queries between the two
drivers. You can use the TIBCO drivers, or you can choose to install and use the driver supplied by the
database vendor.
If you upload your reports to JasperReports Server, make sure to use the same driver in both
JasperReports Server and Jaspersoft Studio.

Enter the connection URL. To have Jaspersoft Studio construct the URL, click the Wizard button. The
JDBC URL Wizard inserts the server name and the database name in the correct text fields.

Enter a username and password to access the database. If the password is empty, it is better if you specify
that it be saved. You can choose to save the password in one of two ways:
•

10.3.2

Clear text – This is not secure, but can sometimes be convenient when working in a developer or
staging environment.
• Eclipse secure storage – This is the correct option for security, but can be difficult to work with when
testing and saving adapters. In addition, it can make it difficult to share adapters with other developers
or deploy data adapters to JasperReports Server.
After you've inserted all the data, click the Test button to verify the connection. If everything's okay, you'll
see a message that the test was successful.

Click OK to exit the message.

Click Finish to create the connection.

Troubleshooting a Database JDBC Connection
When the tests fail, the most common exceptions are:
•
•
•

A ClassNotFoundError was thrown.
The URL is not correct.
Parameters are not correct for the connection (database is not found, the username or password is wrong,
etc.).

10.3.2.1 ClassNotFoundError
The ClassNotFoundError exception occurs whenever a data adapter fails to load a class it requires. In the
context of JDBC connections, the most likely cause is that the required JDBC driver is not present in the
classpath. In general, a data adapter has two classpaths it uses to find libraries. First the adapter looks at any
paths that were specified inside the data adapter when it was created. If it cannot load the libraries or classes it
needs using its internal paths, the data adapter uses the Jaspersoft Studio classpath to look for them.
The Jaspersoft Studio classpath is defined in your Eclipse project. As Jaspersoft Studio uses its own class loader,
it's enough to add resources such as jar files and directories containing classes to the Jaspersoft Studio classpath.
For example, suppose you want to create a connection to an Oracle database. Jaspersoft Studio does not ship the
vendor's driver for this database. If you choose the oracle.jdbc.driver.OracleDriver driver, when you test
the connection, you'll see the ClassNotFoundException, as shown in Figure 10-9. You need to add the JDBC
driver for Oracle, ojdbc14.jar, to the classpath.

TIBCO Software Inc.

127

TIBCO Jaspersoft Studio User Guide

Figure 10-9 ClassNotFoundError exception
To add a resource to the Jaspersoft Studio classpath:
If you add a resource to the Jaspersoft Studio classpath, it will be available to all data adapters. In addition to
JARs, you can add variables, libraries, class folders, and external class folders. To add a jar to the Jaspersoft
Studio classpath:
1.
2.

Click Project > Properties > Java Build Path>Libraries, and click Add JARsor Add External JARs.
Browse to locate the jar you want to add.

Select the file you want to add to the classpath.

Click OK.

To add a JAR file to a data adapter's classpath:
If you need to use the driver only for this data adapter, you can instead add the driver on the data adapter's
Driver Classpath tab.
1.

If the adapter is not already open, double-click its icon in the Repository Explorer or Project Explorer to
open it.

Click on the Driver Classpath tab.

Click Add and browse to locate the jar you want to add. If you want to add a different file type, use the
menu at the bottom right.

Click on the jar and Open.
The location of the file you chose is added to the driver classpath.

10.3.2.2 URL Not Correct
If a wrong URL is specified, you’ll get an exception when you click the Test button. You can find the exact
cause of the error using the stack trace provided in the exception.
Use the JDBC URL Wizard to build the JDBC URL and try again.

128

TIBCO Software Inc.

Chapter 10 Data Adapters

10.3.2.3 Parameters Not Correct for the Connection
If you try to establish a connection to a database with the wrong parameters (for example, invalid credentials or
inaccessible database), the database returns a message is fairly explicit about the reason behind the failure of the
connection.

10.3.3

Using a Database JDBC Connection
When you create a report with a JDBC connection, you specify a query to extract records from the database.
The query language you use depends on the connection type; the most common query type is an SQL query.
The use of JDBC or SQL connections is the simplest and easiest way to fill a report.

10.3.3.1 Fields Registration
In order to use SQL query fields in a report, you need to register them. You don't need to register all the
selected fields—only those actually used in the report. For each field, specify name and type. Table 10-1,
“Conversion of SQL and JAVA types ,” on page 129 shows SQL types and the Java objects they map to.
Table 10-1 Conversion of SQL and JAVA types
SQL Type

Java Object

SQL Type

Java Object

CHAR

String

REAL

Float

VARCHAR

String

FLOAT

Double

LONGVARCHAR

String

DOUBLE

Double

NUMERIC

java.math.BigDecimal

BINARY

byte[]

DECIMAL

java.math.BigDecimal

VARBINARY

byte[]

BIT

Boolean

LONGVARBINARY

byte[]

TINYINT

Integer

DATE

java.sql.Date

SMALLINT

Integer

TIME

java.sql.Time

INTEGER

Integer

TIMESTAMP

java.sql.Timestamp

BIGINT

Long

The table doesn't include special types like BLOB, CLOB, ARRAY, STRUCT, and REF, because these types
cannot be managed automatically by JasperReports. However, you can use them by declaring them generically
as Object and managing them by writing supporting static methods. The BINARY, VARBINARY, and
LONGBINARY types should be dealt with in a similar way. With many databases, BLOB and CLOB can be
declared as java.io.InputStream.
Whether an SQL type is converted to a Java object depends on the JDBC driver used.
For the automatic registration of SQL query fields, Jaspersoft Studio relies on the type proposed for each field
by the driver itself.

TIBCO Software Inc.

129

TIBCO Jaspersoft Studio User Guide

10.3.3.2 Filtering Records
The records in a report can be ordered and filtered. Set sort and filter options in the Report query dialog by
clicking the Dataset and Query button

Figure 10-10 Filter Expression Tab and Expression Editor
Clicking the Data Preview tab shows your filtered data.The filter expression must return a Boolean object: true
if a particular record can be kept, false otherwise.

130

TIBCO Software Inc.

Chapter 10 Data Adapters

Figure 10-11 Data Preview
If no fields can be selected with the Add field button, check to see if the report contains fields. If not, close the
query dialog, register the fields, and resume the sorting.
10.3.3.3 Using JDBC Connections for Subreports
You can also use a JDBC connection for a subreport or a personalized lookup function for decoding specific
data. For this reason, JasperReports provides a java.sql.Connection parameter called REPORT_CONNECTION.
You can use this parameter in any expression you like, with this parameters syntax:
$P{REPORT_CONNECTION}

This parameter contains the java.sql.Connection class passed to JasperReports from the calling program.

10.4

Working with a MongoDB Data Adapter
MongoDB is a big data architecture based on the NoSQL model that is neither relational nor SQL-based.
Jaspersoft Studio includes data adapters that allow reports to use a native MongoDB data connection or a
MongoDB JDBC data adapter. As of version 6.1.1 JasperReports Server also supports SSL and x509
authentication for MongoDB.

TIBCO Software Inc.

131

TIBCO Jaspersoft Studio User Guide

10.4.1

Creating a Native MongoDB Connection
To create a MongoDB data adapter with the native driver:
Follow these steps to create a MongoDB data source with the native MongoDB driver.
1.

Create the connection globally or locally:
•

To create the connection globally, right-click Data Adapters in the Repository Explorer and choose
Create Data Adapter.

•

From the list, select MongoDB Connection to open the Data Adapter dialog.

Figure 10-12 Configuring a MongoDB Connection
3.

Fill in the required fields:
• Name: The name that will appear on the list of available data adapters when you create or run a report.
• Mongo URI: The URI of your MongoDB data.
If you have configured your MongoDB source to be password protected, specify a valid username and
password.

Click Test to check the values you entered. If everything's okay, you'll see a success message.

Click OK to exit the message.

Click Finish to create the connection.
If you get a ClassNotFoundError exception, the most likely cause is that the required driver is not
present in the classpath. See 10.3.2.1, “ClassNotFoundError,” on page 127 for more information.

132

TIBCO Software Inc.

Chapter 10 Data Adapters

10.4.1.1 The Jaspersoft MongoDB Query Language
MongoDB is designed to be accessed through API calls in an application or a command shell. As a
consequence, it does not have a defined query language. In order to write queries for MongoDB data sources,
we have developed a query language based on the JSON-like objects upon which MongoDB operates. JSON is
the JavaScript Object Notation, a textual representation of data structures that is both human- and machinereadable.
The Jaspersoft MongoDB Query Language is a declarative language for specifying what data to retrieve from
MongoDB. The connector converts this query into the appropriate API calls and uses the MongoDB Java
connector to query the MongoDB instance. The following examples give an overview of the Jaspersoft
MongoDB Query Language, with SQL-equivalent terms in parentheses:
•

Retrieve all documents (rows) in the given collection (table):
{ 'collectionName' : 'accounts' }

•

From all documents in the given collection, select the named fields (columns) and sort the results:
{
'collectionName' : 'accounts',
'findFields' : {'name':1,'phone_office':1,'billing_address_city':1,
'billing_address_street':1,'billing_address_country':1},
'sort' : {'billing_address_country':-1,'billing_address_city':1}
}

•

Retrieve only the documents (rows) in the given collection (table) that match the query (where clause). In
this case, the date is greater-than-or-equal to the input parameter, and the name matches a string (starts with
N):
{
'collectionName' : 'accounts',
'findQuery' : {
'status_date' : { '$gte' : $P{StartDate} },
'name' : { '$regex' : '^N', '$options' : '' }
}
}

The Jaspersoft MongoDB Query Language also supports advanced features of MongoDB such as map-reduce
functions and aggregation that are beyond the scope of this document. For more information, see the language
reference on the Community website.
When you create a report or subdatasource from a native MongoDB connection, Jaspersoft Studio automatically
selects MongoDBQuery as the query language. You can explicitly view and set the query language using the
Dataset and Query Dialog.

TIBCO Software Inc.

133

TIBCO Jaspersoft Studio User Guide

Figure 10-13 Example Dataset and Query Dialog for a MongoDB Data Adapter

10.4.2

Creating a MongoDB JDBC Data Source
If you want to wrap your MongoDB data source in a domain or virtual data source, create a MongoDB JDBC
data source. The MongoDB JDBC driver can create a default normalized schema for your data or, if you prefer,
you can load a schema from the repository or your server file system.
This section describes functionality that can be restricted by the software license for JasperReports
Server. If you don’t see some of the options described in this section, your license may prohibit you from
using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft.

To create a MongoDB JDBC data source:
1. Create the connection globally or locally:
•

To create the connection globally, right-click Data Adapters in the Repository Explorer and choose
Create Data Adapter.

•

134

From the list, select Database JDBC Connection to open the Data Adapter dialog.

In the JDBC Driver field, select MongoDB (TIBCO Jaspersoft).

TIBCO Software Inc.

Chapter 10 Data Adapters

Figure 10-14 MongoDB JDBC Data Adapter Dialog
4.

Fill in the required fields:
•
•

Name: The name that will appear on the list of available data adapters when you create or run a report.
JDBC URL: The URL for your MongoDB instance. This is in the following format:
jdbc:tibcosoftware:mongodb://host:port;databaseName=db;SchemaDefinition=file
where:
•
•
•

5.
6.

host:port is the host and port of your MongoDB instance
db is the name of the database to use in your MongoDB instance
file (optional) is a location on your local disk where you want to store the schema definition.
When you first connect to a MongoDB server, the driver automatically creates a normalized
schema of the data and generates a SchemaDefinition for housing and sharing the normalized
schema. You can also specify the path of an existing schema on your local disk.
If you have configured your MongoDB source to be password protected, specify a valid username and
password.
(Optional) Click Connection Properties to specify any additional properties for your connection. For
example, if you're using MongoDB 3.0 and you want to enable SSL, enter:
EncryptionMethod=SSL;ValidateServerCertificate=false

To enable both SSL encryption and self-signed CA, enter the TrustStore and KeyStore paths and the
KeyStore password. For example:
EncryptionMethod=SSL;TrustStore=;KeyStore=;KeyStorePassword=;

TIBCO Software Inc.

135

TIBCO Jaspersoft Studio User Guide

Click Test to check the values you entered. If everything's okay, you'll see this message:

Figure 10-15 Test Confirmation Dialog
8.

Click OK to exit the message.

Click Finish to create the connection.
If you get a ClassNotFoundError exception, it may be due to one of the following:
•
•

10.5

You are not licensed to use the TIBCO MongoDB JDBC driver. This driver is only available in
commercial editions.
The required driver is not present in the classpath. See 10.3.2.1, “ClassNotFoundError,” on
page 127 for more information.

Working with a Native Cassandra Connection
The Apache Cassandra database provides scalability and high availability for certain applications of big data.
For more information about Cassandra, see http://cassandra.apache.org/.
The Cassandra data adapter relies on a driver that has certain limitations on how your data can be structured and
accessed:
•
•
•

The current version of Cassandra does not support NULL values in the data. All required fields must have
non-NULL default values.
The current version of the driver does not support aggregate functions (sum, min, max).
For query parameters, the current version of the driver supports $X(IN...), but no other $X functions.

The Cassandra data adapter supports queries in the Cassandra Query Language 3 (CQL3). To improve
performance, design your Cassandra data using the following guidelines:
•
•

10.5.1

Specify the ALLOW FILTERING suffix to speed up queries.
All fields referenced in WHERE clauses of a query should be indexed.

Creating a Native Cassandra Data Adapter
To create a new Cassandra adapter:
1. Create the connection globally or locally:
•

To create the connection globally, right-click Data Adapters in the Repository Explorer and choose
Create Data Adapter.

•

136

TIBCO Software Inc.

Chapter 10 Data Adapters

From the list, select Cassandra Connection to open the Data Adapter dialog.

Figure 10-16 Configuring a Cassandra Native Connection
3.

Fill in the required fields:
•
•

Name: The name that will appear on the list of available data adapters when you create a report.
Port: Use port 9042 with the Cassandra data source. Cassandra's default port of 9160 is for the Thrift
client that is commonly used with Cassandra. To use the Cassandra Query Language (CQL) with your
Cassandra data source, you may need to configure your Cassandra instance as follows:
start_native_transport: true
native_transport_port: 9042

• Keyspace: The keyspace of your Cassandra instance.
If you have configured your Cassandra source to be password protected, specify a valid username and
password. Due to compatibility issues, Cassandra authentication is supported only when you use Cassandra
1.12.18 and above. If the password is empty, it is better if you specify that it be saved. You can choose to
save the password in one of two ways:
•

Clear text – This is not secure, but can sometimes be convenient when working in a developer or
staging environment.
• Eclipse secure storage – This is the correct option for security, but can be difficult to work with when
testing and saving adapters. In addition, it can make it difficult to share adapters with other developers
or deploy data adapters to JasperReports Server.
Click Test to check the values you entered. Make sure that the port is set to 9042, because the connection
test will also work with the wrong port (9160). If everything's okay, you'll see a success message.

Click OK to exit the message.

Click Finish to create the connection.

TIBCO Software Inc.

137

TIBCO Jaspersoft Studio User Guide

If you get a ClassNotFoundError exception, the most likely cause is that the required driver is not
present in the classpath. See 10.3.2.1, “ClassNotFoundError,” on page 127 for more information.

10.5.2

Using a Cassandra Connection
When you create a report or subdatasource from a native Cassandra connection, specify a CQL query to extract
records from the database.

Figure 10-17 Data Preview
If no fields can be selected with the Add field button, check to see if the report contains fields. If not, close the
query dialog, register the fields, and resume the sorting.

10.6

Working with a Collection of JavaBeans Data Adapter
A collection of JavaBeans data adapter allows you to use JavaBeans as data for a report. In this context, a
JavaBean is a Java class that exposes its attributes with a series of get methods, with the following syntax:
public getXXX()

where (the return value) is a generic Java class or a primitive type (such as int, double, and so
on).

138

TIBCO Software Inc.

Chapter 10 Data Adapters

10.6.1

Implementing the Factory Class for a Collection of JavaBeans
The collection of JavaBeans data adapter uses an external class (named Factory) to produce some objects (the
JavaBeans) that constitute the data to pass to the report. To use a collection of JavaBeans as a data adapter in
Jaspersoft Studio, you must create an instance of the Factory class and provide a static method to instantiate
different JavaBeans and to return them as a collection (java.util.Collection) or an array (Object[]). The
following example shows how you might create write an instance of the Factory class.
Suppose that you have an collection of JavaBeans, where the data is represented by a set of objects of type
PersonBean. The following table shows the code for PersonBean, which contains two fields: name (the
person’s name) and age:
Table 10-2 PersonBean example
public class PersonBean
{
private String name = "";
private int age = 0;
public PersonBean(String name, int age)
{
this.name = name;
this.age = age;
}
public int getAge()
{
return age;
}
public String getName()
{
return name;
}
}

To use this collection of beans, you need to create an instance of the Factory class. Your class, named
TestFactory, must contain the actual data that is used by the report. In this case, it will be something similar
to this:
Table 10-3 PersonBean example - Class result
public class TestFactory
{
public static java.util.Collection generateCollection()
{
java.util.Vector collection = new java.util.Vector();
collection.add(new PersonBean("Ted", 20) );
collection.add(new PersonBean("Jack", 34) );
collection.add(new PersonBean("Bob", 56) );
collection.add(new PersonBean("Alice",12) );
collection.add(new PersonBean("Robin",22) );
collection.add(new PersonBean("Peter",28) );
return collection;
}
}

TIBCO Software Inc.

139

TIBCO Jaspersoft Studio User Guide

A data adapter based on this class would represent five JavaBeans of PersonBean type.

10.6.2

Creating a Data Adapter from a Factory Class
Once you have created your Factory class instance, you can create a data adapter that uses your collection of
JavaBeans.
1.

Create the connection globally or locally:
•

To create the connection globally, right-click Data Adapters in the Repository Explorer and choose
Create Data Adapter.

•

To create a connection to handle JavaBeans, select Collection of JavaBeans in the list of data adapter
types.
The fields necessary to create a collection JavaBeans appear.

Figure 10-18 Collection of JavaBeans Data Adapter
3.

Create a name for your adapter.

Enter the name of your Java class in the Factory class. For the example above, you would need to specify
the class name for TestFactory.

Enter the name of the static method in your Factory class. In the example above, this is
generateCollection.

By default, the field names in your JavaBeans become the field names in your data adapter. If your
JavaBeans definition has field descriptions, and you want to use these as names in Jaspersoft Studio, select
Use field description.
If necessary, you can add the path to your jar files.

140

TIBCO Software Inc.

Chapter 10 Data Adapters

10.6.3

Registering the Fields
One peculiarity of a collection of JavaBeans data adapter is that the fields are exposed through get methods.
This means that if the JavaBean has a getXyz() method, xyz becomes the name of a record field (the JavaBean
represents the record).
In this example, the PersonBean object shows two fields: name and age. Register them in the fields list as a
String and an Integer, respectively.
Create a new empty report and add the two fields by right-clicking the Fields node in the outline view and
selecting Add field. The field names and the types of the fields are: name (java.lang.String) and age
(java.lang.Integer).
Drag the fields into the Detail band and run the report. (Make sure the active connection is the
TestFactoryAdapter.) To refer to an attribute of an attribute, use periods as a separator. For example, to access
the street attribute of an Address class contained in the PersonBean, the syntax would be address.street.
The real call would be .getAddress().getStreet().

Figure 10-19 Layout of a Report Based on JavaBeans
If you selected Use field description when you specified the properties of your data adapter, the mapping
between JavaBean attribute and field value uses the field description instead of the field name.
Jaspersoft Studio provides a visual tool to map JavaBean attributes to report fields. To use it, open the query
window, go to the tab JavaBean Data Source, insert the full class name of the bean you want to explore, and
click Read attributes. The tab displays the attributes of the specified bean class.
•
•

10.7

If an attribute is also a Java object, you can double-click the object to display its other attributes.
To map a field, select an attribute name and click the Add Selected Field(s) button.

Working with XML Data Adapters
JasperReports supports data adapters for XML documents.

10.7.1

Creating a Node Set for an XML Document
An XML document is typically organized as a tree, and doesn't match the table-like form required by
JasperReports. For this reason, you have to use an XPath expression to define a node set. The specifications of
the XPath language are available at http://www.w3.org/TR/xpath. Some examples can help you understand how
to define the nodes.

TIBCO Software Inc.

141

TIBCO Jaspersoft Studio User Guide

The XML file below is an address book in which people are grouped in categories, followed by a second list of
favorite objects. In this case, you can define different node set types. First you'll need to decide how you want
to organize the data in your report.
Table 10-4 Example XML file

Davolio
Nancy

Fuller
Andrew

Leverling

Peacock
Margaret

To select only the people contained in the categories (that is, all the people in the address book), use the
following expression:
/addressbook/category/person

Four nodes are returned as shown in the following table.
Table 10-5 Node set with expression /addressbook/category/person

Davolio
Nancy

Fuller
Andrew

Leverling

Peacock
Margaret

142

TIBCO Software Inc.

Chapter 10 Data Adapters

If you want to select the people appearing in the favorites node, the expression to use is
/addressbook/favorites/person

Two nodes are returned.

Here's another expression. It's a bit more complex, but it shows all the power of the Xpath language. The idea is
to select the person nodes belonging to the work category. The expression to use is the following:
/addressbook/category[@name = "work"]/person

The expression returns only one node, the one with an ID equal to 4, as shown here:

Peacock
Margaret

10.7.2

Creating an XML Data Adapter
After you've created an expression to select a node set, you can create an XML data adapter.
1.

Create the connection globally or locally:
•

To create the connection globally, right-click Data Adapters in the Repository Explorer and choose
Create Data Adapter.

•

From the list, select XML document to open the Data Adapter dialog.

TIBCO Software Inc.

143

TIBCO Jaspersoft Studio User Guide

Figure 10-20 Configuring an XML Data Adapter
3.

Enter a name for your adapter.

XML file is the only required field. Choose an XML file or enter the URL where your XML data is located.

(URL only.) If you entered a URL in the XML file field, click the Options button to open the Http
Connection Options dialog box.

Figure 10-21 HTTP Connection Options
In this dialog you can enter the following options:
•
•

144

Username and Password (optional) – The username and password to use if your CSV location
requires authentication.
Request Type – Select GET (default) or POST.

TIBCO Software Inc.

Chapter 10 Data Adapters

•

To add a parameter to the request URL, click Add in the URL Parameters tab. Enter the name and
value of your parameters in the Parameter dialog and click OK. For multiple parameters, add each
parameter separately.
• For a POST request, to add parameters to the body of the POST, click Add in the POST Parameters tab.
Enter the name and value of your parameters in the Parameter dialog and click OK. For multiple
parameters, add each parameter separately.
When you have configured your request, click OK.
Choose whether to provide a set of nodes using a pre-defined static XPath expression, or set the XPath
expression directly in the report.
We recommend using a report-defined XPath expression. This enables you to use parameters inside the
XPath expression, which acts like a real query on the supplied XML data.
Optionally, you can specify Java patterns to convert dates and numbers from plain strings to more
appropriate Java objects (like Date and Double). For the same purpose, you can define a specific locale
and time zone to use when parsing the XML stream.

10.7.3

Registration of Fields for an XML Data Adapter
In addition to the type and name, the definition of a field in a report using an XML data adapter requires an
expression inserted as a field description. As the data adapter aims always to be one node of the selected node
set, the expressions are relative to the current node.
To select the value of an attribute of the current node, use the following syntax:
@

For example, to define a field that must point to the id attribute of a person (attribute id of the node person), it's
sufficient to create a new field, name it, and set the description to:
@id

It's also possible to get to the child nodes of the current node. For example, if you want to refer to the lastname
node, child of person, use the following syntax:
lastname

To move to the parent value of the current node (for example, to determine the category to which a person
belongs), use a slightly different syntax:
ancestor::category/@name

The ancestor keyword indicates that you're referring to a parent node of the current node. Specifically, the first
parent of category type, of which you want to know the value of the name attribute.
Now, let’s see everything in action. Prepare a simple report with the registered fields shown here:
Field name

Description

Type

@id

Integer

lastname

String

firstname

String

name of category

ancestor::category/@name

String

TIBCO Software Inc.

145

TIBCO Jaspersoft Studio User Guide

Jaspersoft Studio provides a visual tool to map XML nodes to report fields; to use it, open the query window
and select XPath as the query language. If the active connection is a valid XML data adapter, the associated
XML document is shown in a tree view. To register the fields, set the record node by right-clicking a Person
node and selecting the menu item Set record node. The record nodes are displayed in bold.
Then one by one, select the nodes or attributes and select the pop-up menu item Add node as field to map
them to report fields. Jaspersoft Studio determines the correct XPath expression to use and creates the fields for
you. You can modify the generated field name and set a more suitable field type after the registration of the
field in the report (which happens when you close the query dialog).
Insert the different fields in the Detail band. The XML file used to fill the report is that shown:
The XPath expression for the node set selection specified in the query dialog is:
/addressbook/category/person

10.7.4

XML Data Adapters and Subreports
A node set allows you to identify a series of nodes that represent records from a JRDataSource point of view.
However, due to the tree-like nature of an XML document, it may be necessary to see other node sets that are
subordinate to the main nodes.
Consider the XML in Table 10-6, “Complex XML example,” on page 146. This is a slightly modified version
of Table 10-4, “Example XML file,” on page 142. For each person node, a hobbies node is added which
contains a series of hobby nodes and one or more e-mail addresses.
Table 10-6 Complex XML example

Davolio
Nancy
davolio1@sf.net
davolio2@sf.net

Music
Sport

Fuller
Andrew
af@test.net
afullera@fuller.org

Cinema
Sport

Leverling

146

TIBCO Software Inc.

Chapter 10 Data Adapters

leverling@xyz.it

Peacock
Margaret
margaret@foo.org

Food
Books

What we want to produce is a document that is more elaborate than those you have seen so far. For each person,
we want to present their e-mail addresses, hobbies, and favorite people.
You can create this document using subreports. You'll need a subreport for the e-mail address list, one for
hobbies, and one for favorite people (that is a set of nodes out of the scope of the XPath query we used). To
generate these subreports, you need to understand how to produce new data sources to feed them. In this case,
you'll use the JRXmlDataSource, which exposes two extremely useful methods:
public JRXmlDataSource dataSource(String selectExpression)
public JRXmlDataSource subDataSource(String selectExpression)

The first method processes the expression by applying it to the whole document, starting from the actual root.
The second assumes the current node is the root.
Both methods can be used in the data source expression of a subreport element to dynamically produce the data
source to pass to the element. The most important thing to note is that this mechanism allows you to make both
the data source production and the expression of node selection dynamic.
The expression to create the data source that feeds the subreport of the e-mail addresses is:
((net.sf.jasperreports.engine.data.JRXmlDataSource)
$P{REPORT_DATA_SOURCE}).subDataSource("/person/email")

This code returns all the e-mail nodes that descend directly from the present node (person).
The expression for the hobbies subreport is similar, except for the node selection:
((net.sf.jasperreports.engine.data.JRXmlDataSource)
$P{REPORT_DATA_SOURCE}).subDataSource("/person/hobbies/hobby")

Next, declare the master report’s fields. In the subreport, you have to refer to the current node value, so the field
expression is simply a dot (.),
Proceed with building your three reports: xml_addressbook.jasper, xml_addresses.jasper, and xml_
hobbies.jasper.
In the master report, xml_addressbook.jrxml, insert a group named “Name of category,” in which you
associate the expression for the category field ($F{name of category}). In the header band for Name of
category, insert a field to display the category name. By doing this, the names of the people are grouped by
category (as in the XML file).

TIBCO Software Inc.

147

TIBCO Jaspersoft Studio User Guide

In the Detail band, position the id, lastname, and firstname fields. Below these fields, add the two Subreport
elements, the first for the e-mail addresses, the second for the hobbies.
The e-mail and hobby subreports are identical except for the name of the field in each one. The two reports
should be as large as the Subreport elements in the master report, so remove the margins and set the report width
accordingly.
Preview both the subreports just to compile them and generate the relative .jasper files. Jaspersoft Studio
returns an error during the fill process, but that's expected. We haven't set an Xpath query, so JasperReports can't
get any data. You can resolve the problem by setting a simple Xpath query (it isn't used in the final report), or
you can preview the subreport using the empty data adapter (select it from the drop-down in the tool bar).
When the subreports are done, execute the master report. If everything is okay, the report groups people by
home and work categories and the subreports associated with each person.
As this example demonstrates, the real power of the XML data adapter is the versatility of XPath, which allows
navigation of the node selection in a refined manner.

10.8

Working with XML/A Data Adapters
XML/A (XML for Analysis) is an XML standard for accessing remote data in an OLAP schema. Jaspersoft
Studio supports an XML/A data adapter that can connect various XML/A providers such as JasperReports
Server and Microsoft SQL Server Analytic Services (SSAS). Because Jaspersoft Studio uses OLAP4J
(http://www.olap4j.org/), it may also be able to connect to other types of XML/A providers.
The remote server must also be configured for XML/A. For more information, including instructions for
configuring Jaspersoft OLAP, see the Jaspersoft OLAP User Guide .
To create an XML/A Data Adapter:
1. Right-click Data Adapters in the Repository Explorer, and select Create Data Adapter.
2.
3.

Select XML/A Server and click Next.
Enter a name for the data adapter.

Enter the URL for your XML/A provider. The type of server determines the value. For example:
•
•

148

If the XML/A server is JasperReports Server, the URL is something like:
http://:/jasperserver-pro/xmla
If the XML/A server is Microsoft SSAS 2012, the URL is something like:
http:///MSSQL_2012/msmdpump.dll

Enter a user name and password of a user that has sufficient access in the report server to return your data.

Click Get Metadata.
Jaspersoft Studio attempts to connect to the server and return information about its data sources, catalogs,
and cubes. If it's successful, default values appear in the drop-downs. If the connection fails, check the URL,
ensure that the remote server is available, and try again.

Select the data source, catalog, and cube that stores the data you want for your report.

Click Test.
Jaspersoft Studio connects to the server and read the cube you selected. If the connection fails, check the
URL, ensure that the remote server is available, and try again.

When the test succeeds, click OK to close the message and click Finish to close the New Data Adapter
wizard.

TIBCO Software Inc.

Chapter 10 Data Adapters

When you create a report using this data adapter, you may see a message indicating that the data adapter doesn't
support the ability to retrieve fields. This means Jaspersoft Studio doesn't have enough information to preview
your data. After you provide an MDX query, Jaspersoft Studio can automatically read fields and suggest their
datatypes.

10.8.1

Registration of fields in XML/A Providers
When you create an XML/A data adapter, you define the cube from which to read data. Jaspersoft Studio can
then inspect the remote server and suggest datatypes for the fields returned.
To register fields returned by an XML/A data adapter:
1.

With your report open in the Design tab, click

Select the data adapter that points to your XML/A provider from the drop-down in the upper-left corner.

to open the Dataset and Query window.

3.
4.

Select MDX from the Language drop-down.
Enter a valid MDX query in the text field.
To create a good MDX query, you must be familiar with both the language itself and the data you want to
work with. You can also use a tool (such as the Jaspersoft OLAP Workbench) to load your OLAP schema
and automatically generate MDX queries from it.

Click Read Fields.
Jaspersoft Studio returns the XML/A provider's data, including fields and parameters, and populates the
window's tabs with information. For more on how these tabs can be used to define the data in your report,
see Chapter 11, “Creating Queries,” on page 161.
Jaspersoft Studio also sets the class type of each field to an appropriate Java datatype. If Jaspersoft Studio
sets an incorrect datatype, you can set the correct type after the fields are added to your report.

10.9

When the data in the Data Preview tab looks like the data you want to fill your report, click OK to close
the Dataset and Query window.

Working with CSV Data Adapters
You can create a connection based on a CSV file or URL location.
To create a connection based on a CSV file:
1. Click the New button in the Connections/Datasources dialog and select CSV File from the list of data
adapter types.

TIBCO Software Inc.

149

TIBCO Jaspersoft Studio User Guide

Figure 10-22 CSV Data Adapter

150

Set a name for the connection.

In the CSV file field, choose a CSV file or enter the URL where your CSV data is located.

(URL only.) If you entered a URL in the CSV file field, click the Options button to open the Http
Connection Options dialog box.

TIBCO Software Inc.

Chapter 10 Data Adapters

Figure 10-23 HTTP Connection Options
In this dialog you can enter the following options:
•

Username and Password (optional) – The username and password to use if your CSV location
requires authentication.
• Request Type – Select GET (default) or POST.
• To add a parameter to the request URL, click Add in the URL Parameters tab. Enter the name and
value of your parameters in the Parameter dialog and click OK. For multiple parameters, add each
parameter separately.
• For a POST request, to add parameters to the body of the POST, click Add in the POST Parameters tab.
Enter the name and value of your parameters in the Parameter dialog and click OK. For multiple
parameters, add each parameter separately.
When you have configured your request, click OK.
Declare the fields in the data adapter.
•

•

If the first line in your file contains the names of the columns, click Get column names from the
first row of the file and select the Skip the first line check box . This forces JasperReports to skip
the first line (the one containing your column labels). In any case, the column names read from the file
are used instead of the declared ones, so avoid modifying the names found with the Get column
names button.
If the first line of your CSV file doesn’t contain the column names, set a name for each column using
the syntax COLUMN_0, COLUMN_1, and so on.
If you define more columns than the ones available, you’ll get an exception at report filling time.

JasperReports assumes that for each row all the columns have a value (even if they are empty).
6.

If your CSV file uses nonstandard characters to separate fields and rows, you can adjust the default setting
for separators using the Separators tab.

TIBCO Software Inc.

151

TIBCO Jaspersoft Studio User Guide

Figure 10-24 Separators Tab
7.

10.9.1

Click Finish.

Registration of the Fields for a CSV Data Adapter
When you create a CSV data adapter, you must define a set of column names as fields for your report. To add
them to the fields list, set your CSV data adapter as the active connection and open the Report query dialog.
Open the Dataset and Query Dialog and click the Read Fields button.
By default, Jaspersoft Studio sets the class type of all fields to java.lang.String. If you're sure the text of a
particular column can be easily converted to a number, a date, or a Boolean value, set the correct field type
yourself after the fields are added to your report.
The pattern used to recognize a timestamp (or date) object can be configured at the data adapter level by
selecting the Use custom date format check box.

10.10 Using the Empty Record Data Adapter
By default, Jaspersoft Studio provides a pre-configured empty data source that returns a single record.

152

TIBCO Software Inc.

Chapter 10 Data Adapters

To create a new empty data source with more records:
1. Double-click One Empty Record in the Repository Explorer. The Data Adapter Wizard appears with
Empty rows.

Figure 10-25 Data Adapter Wizard > Empty Record
2.

Set the number of empty records you need. Remember, whatever field you add to the report, its value is set
to null. Since this data adapter doesn’t care about field names or types, this is a perfect way to test any
report (keeping in mind that the fields are always set to null).

Click Finish.

10.10.1 Understanding the Empty Record Implementation
The empty record data adapter in Jaspersoft Studio uses the special JasperReports data source
JREmptyDataSource. This data source returns true to the next method for the record number (by default only
one), and always returns null to every call of the getFieldValue method. It's like having records without
fields, that is, an empty data source.
The two constructors of this class are:
public JREmptyDataSource(int count)
public JREmptyDataSource()

The first constructor indicates how many records to return, and the second sets the number of records to one.

10.11 Working with the JRDataSource Interface
All data adapters implement the JRDataSource interface. Some data adapters, such the JDBC data connections,
do this indirectly using a connection and a query; other data adapters, such as adapters for CSV files, XML
documents, and collections of JavaBeans, do this directly. This section is useful if you want to understand more
about the direct data adapters, or if you are interested in creating a custom data adapter.

TIBCO Software Inc.

153

TIBCO Jaspersoft Studio User Guide

10.11.1 Understanding the JRDataSource Interface
Data supplied by a JRDataSource is ideally organized into records as in a table. Every JRDataSource must
implement the following two methods:
public boolean next() – Returns true if the cursor is positioned correctly in the subsequent record, false

if no more records are available.
public Object getFieldValue(JRField jrField) – Moves a virtual cursor to the next record

Every time JasperReports executes the public boolean next() method, all the fields declared in the report
are filled and all the expressions (starting from those associated with the variables) are calculated again.
Subsequently, JasperReports determines whether to print the header of a new group, to go to a new page, and so
on. When next returns false, the report is ended by printing all final bands (Group Footer, Column Footer, Last
Page Footer, and Summary). The method can be called as many times as there are records present (or represented)
from the data source instance.
The method public Object getFieldValue(JRField jrField) is called by JasperReports after a call to
next results in a true value. In particular, it's executed for every single field declared in the report. In the call, a
JRField object is passed as a parameter. It's used to specify the name, the description and the type of the field
from which to obtain the value (all this information, depending on the specific data source implementation, can
be combined to extract the field value).
The type of the value returned by the public Object getFieldValue(JRField jrField) method has to be
adequate for that declared in the JRField parameter, except when a null is returned. If the type of the field was
declared as java.lang.Object, the method can return an arbitrary type. In this case, if required, a cast can be
used in the expressions. A cast is a way to dynamically indicate the type on an object, the syntax of a cast is:
(type)object

in example:
(com.jaspersoft.ireport.examples.beans.PersonBean)$F{my_person}

Usually a cast is required when you need to call a method on the object that belongs to a particular class.

10.11.2 Implementing a New JRDataSource
If the JRDataSource supplied with JasperReports doesn't meet your requirements, you can write a new
JRDataSource. This is not a complex operation. In fact, all you have to do is create a class that implements the
JRDataSource interface that exposes two simple methods: next and getFieldValue.
Table 10-7 The JRDataSource interface
package net.sf.jasperreports.engine;
public interface JRDataSource
{
public boolean next() throws JRException;
public Object getFieldValue(JRField jrField) throws JRException;
}

The next method is used to set the current record into the data source. It has to return true if a new record to
elaborate exists; otherwise it returns false.
If the next method has been called positively, the getFieldValue method has to return the value of the
requested field or null. Specifically, the requested field name is contained in the JRField object passed as a

154

TIBCO Software Inc.

Chapter 10 Data Adapters

parameter. Also, JRField is an interface through which you can get information associated with a field—the
name, description, and Java type that represents it.
Now try writing your personalized data source. You have to write a data source that explores the directory of a
file system and returns the found objects (files or directories). The fields you create to manage your data source
are the same as the file name, which should be named FILENAME; a flag that indicates whether the object is a
file or a directory, which should be named IS_DIRECTORY; and the file size, if available, which should be
named SIZE.
You data source should have two constructors: the first receives the directory to scan as a parameter; the second
has no parameters and uses the current directory to scan.
Once instantiated, the data source looks for the files and the directories present in the way you indicate and fills
the array files.
The next method increases the index variable you use to keep track of the position reached in the array files,
and returns true until you reach the end of the array.
Table 10-8 Sample personalized data source
import net.sf.jasperreports.engine.*;
import java.io.*;
public class JRFileSystemDataSource implements JRDataSource
{
File[] files = null;
int
index = -1;
public JRFileSystemDataSource(String path)
{
File dir = new File(path);
if (dir.exists() && dir.isDirectory())
{
files = dir.listFiles();
}
}
public JRFileSystemDataSource()
{
this(".");
}
public boolean next() throws JRException
{
index++;
if (files != null && index < files.length)
{
return true;
}
return false;
}
public Object getFieldValue(JRField jrField) throws JRException
{
File f = files[index];
if (f == null) return null;
if (jrField.getName().equals("FILENAME"))
{
return f.getName();
}
else if (jrField.getName().equals("IS_DIRECTORY"))
{

TIBCO Software Inc.

155

TIBCO Jaspersoft Studio User Guide

return new Boolean(f.isDirectory());
}
else if (jrField.getName().equals("SIZE"))
{
return new Long(f.length());
}
// Field not found...
return null;
}
}

The getFieldValue method returns the requested file information. Your implementation doesn't use the
information regarding the return type expected by the caller of the method. It assumes the name has to be
returned as a string. The flag IS_DIRECTORY as a Boolean object, and the file size as a Long object.
The next section shows how to use your personalized data source in Jaspersoft Studio and test it.

10.11.3 Using a Custom JasperReports Data Source with Jaspersoft Studio
Jaspersoft Studio provides a special connection for your personalized data sources. It's useful for employing
whatever JRDataSource you want to use through some kind of factory class that provides an instance of that
JRDataSource implementation. The factory is just a simple Java class useful for testing your data source and
filling a report in Jaspersoft Studio. The idea is the same as what you have seen for the collection of JavaBeans
data adapter — you need to write a Java class that creates the data source through a static method and returns it.
For example, if you want to test the JRFileSystemDataSource in the previous section, you need to create a
simple class like that shown in this code sample:
Table 10-9 Class for testing a custom data source
import net.sf.jasperreports.engine.*;
public class FileSystemDataSourceFactory {
public static JRDataSource createDatasource()
{
return new JRFileSystemDataSource("/");
}
}

This class, and in particular the static method that's called, executes all the necessary code for instancing the
data source correctly. In this case, you create a new JRFileSystemDataSource object by specifying a way to
scan the directory root ("/").
Now that you have defined the way to obtain the JRDataSource you prepared and the data source is ready to
be used, you can create the connection through which it can be used.
Create a new connection as you normally would (see “Working with Database JDBC Connections” on
page 125), then select Custom implementation of JRDataSource from the list and specify a data source
name like TestFileSystemDataSource (or whatever name you want), as shown below.

156

TIBCO Software Inc.

Chapter 10 Data Adapters

Figure 10-26 Configuring a Custom Data Adapter
Next, specify the class and method to obtain an instance of your JRFileSystemDataSource, that is,
TestFileSystemDataSource and test.
There is no automatic method to find the fields managed by a custom data source.

In this case, you know that the JRFileSystemDataSource provides three fields: FILENAME (String), IS_
DIRECTORY (Boolean), and SIZE (Long). After you have created these fields, insert them in the report’s Detail
band.
Divide the report into two columns and in the Column Header band, insert Filename and Size tags. Then add
two images, one representing a document and the other an open folder. In the Print when expression setting of
the Image element placed in the foreground, insert the expression $F{IS_DIRECTORY}, or use as your image
expression a condition like the following:
($F{IS_DIRECTORY}) ? “folder.png” : “file.png”

In this example, the class that instantiated the JRFileSystemDataSource was very simple. But you can use
more complex classes, such as one that obtains the data source by calling an Enterprise JavaBean or by calling a
web service.

10.12 A Look at TIBCO Spotfire Information Links
You can populate reports created in Jaspersoft Studio with data from TIBCO Spotfire. You can navigate your
Spotfire library, select Information Links and Spotfire Binary Data Files (SBDFs), and inspect their data. To load
Spotfire data, create a data adapter to connect to the data. The data adapter will return data in tabular form.

TIBCO Software Inc.

157

TIBCO Jaspersoft Studio User Guide

Before you publish the report to JasperReports Server, export your data adapter as an XML file so you can add
it to the server's repository.
This version of Jaspersoft Studio supports TIBCO Spotfire 6.5 and above. Earlier versions may also work
but have not been tested extensively.

To create a data adapter for a Spotfire Information Link:
1. In the Repository Explorer, right-click Data Adapters and select Create Data Adapter to display the Data
Adapter wizard.
2.

Enter a name for the data adapter.

Enter the URL to your Spotfire Web Player in this form:
http:///SpotfireWeb
where is the IP address or name of the computer hosting the Spotfire Web Player where
you access your Information Link.

Enter your Spotfire user name and password.

Click Browse next to the Resource ID field to locate and select your Information Link in the Spotfire
library.

Figure 10-27 Spotfire Library displayed in Jaspersoft Studio
You can also create reports against SBDFs; to do so, select one from your Spotfire library.

158

Click OK.

7.
8.

Click Test to test your connection.
If the test fails, check your URL, credentials, and resource ID.

When the test succeeds, click Finish.

TIBCO Software Inc.

Chapter 10 Data Adapters

It isn't uncommon for an Information Link to return millions of rows of data, which may take a some time for
Jaspersoft Studio to process when data is loaded, such as when previewing the report; the same may
hold true in JasperReports Server.

To create your report:
1. Click File > New > JasperReport.
2. Select template and enter a name for your report.
3.
4.

Click Next. The Data Source dialog appears.
Select the Spotfire Information Link data adapter you created above.

Select the fields to include in your data set.

6.
7.

Click Next.
Optionally select a field to define grouping.

8.
9.

Click Finish. Jaspersoft Studio displays the report in the Design tab.
Edit the report as needed. For example, add fields and components and configure your query and dataset.

10. Click Preview to ensure that the report is correctly configured.
11. When your report is ready, click File > Save.
To export your data adapter as an XML file:
1. In the Repository Explorer, right-click your Spotfire Information Link data adapter and select Export to
File.
2. Select the folder in your Jaspersoft Studio workspace that contains your report, enter a name for the data
adapter, and click OK.
To configure the report to use the exported data adapter:
1. In the Outline view, click the root node of your report to display the report properties.
2.
3.

Click Advanced.
Expand Misc and click the ellipsis to the right of Properties to open the Properties window.

Click Add to create a property that indicates the data adapter to use.

In the Property Name field, enter net.sf.jasperreports.data.adapter.

In the Value field, enter the name of the data adapter you exported (this is an XML file).

Click OK.
You're ready to publish your report.

To publish your report:
1. Click
at the top of the Design tab. You're prompted to select a location for publishing the report.
2.

Select a server connection and navigate its repository to the desired location.

Optionally enter a new label, name (ID), and description of the report unit.

Click Next. You're prompted to select a resource used by the report, including the data adapter you
exported above.

Click Next. You're prompted to select a data source.

Select Don't use any Data Source. Since the data adapter has already been defined, the report doesn't
need a separate data source.

Click Finish. Jaspersoft Studio adds your report to the repository.

TIBCO Software Inc.

159

TIBCO Jaspersoft Studio User Guide

While it's uploaded, Jaspersoft Studio modifies your JRXML so that it will run properly on the server. In
particular, it changes how the data adapter is specified. On the server, the data adapter is uploaded to the folder
you selected when you published the report.
To test your report, open the server's web UI, locate your report, and click it to run it.

160

TIBCO Software Inc.

CHAPTER 11 CREATING QUERIES
Jaspersoft Studio provides tools to help you define report fields and create a proper query (if a query is needed
to fetch the report data). You'll find these tools in the Dataset and Query dialog.
It also provides a drag-and-drop query builder for easily creating SQL queries. This allows users who aren't
familiar with SQL to quickly join tables and produce complex data filters and where conditions. SQL Builder
also provides a way for skilled users to explore the database and list the metadata such as schemas and available
tables.
This chapter contains the following sections:
•
•

11.1

Using the Dataset and Query Dialog
Working with the Query Builder

Using the Dataset and Query Dialog
Click the Dataset and Query icon

When working with a sub-dataset, open the dialog by right-clicking the dataset name inside the Outline view,
and selecting Dataset and Query....

Figure 11-1 Right-Click Menu

TIBCO Software Inc.

161

TIBCO Jaspersoft Studio User Guide

Use the Dataset and Query dialog to:
•
•
•
•
•
•
•
•

Select a data adapter with which to configure the dataset. Usually a data adapter is selected, but you can
change it.
Select a query language for the dataset you're editing. (This can be the main dataset or a sub-dataset that
populates a chart or a table.)
Enter a query. A tool is available for several languages including SQL, XPath and JSON.
Retrieve the fields from the selected Data Adapter. These can be provided directly by the Data Adapter or
by executing the query and reading the response metadata.
Add, edit, or remove fields and parameters.
Edit sort options.
Provide an expression to filter dataset records.
Preview your data, if supported by the selected data adapter.

Figure 11-2 Data Preview Tab
Defining all the fields of a report by hand can be tedious. JasperReports requires all report fields to be named
and configured with a proper class type. The Dataset and Query dialog simplifies the process by automatically
discovering the available fields provided by a data adapter, without using a query. To execute a query you need
to use the proper data adapter: for example to execute an SQL query you must use a JDBC data adapter. The
Read Fields button starts the discovery process: the fields found are listed in the Fields tab and added to the
report. Click OK to close this window.
Some query languages, like XPath, do not produce a result that resemble a table, but more complex structures
that require extra steps to correctly map result data to report fields. An example of this is the multidimensional
result coming from MDX results (MDX is the query language used with OLAP and XML/A connections): in
this case each field is mapped by specifying an expression stored in the field description. For some languages,

162

TIBCO Software Inc.

Chapter 11 Creating Queries

such as instance XPath and JSON query, the Query dialog displays a tool that simplifies the creation of both the
query and the mapping.

11.2

Working with the Query Builder
When your language is SQL, the Query Builder is called the SQL Builder. The tool requires a JDBC data
adapter.
The builder has two parts. On the left a tree-view shows all the available schemas and relative objects like
tables, views, etc. found by using the JDBC connection provided by the data adapter. On the right there are
three tabs that present the query in different ways.
The first Text tab contains a text area for writing a query. You can drag tables and other objects from the
metadata view into the text area, so you don't have to write the entire qualified names of those objects.
Although the SQL builder doesn't support arbitrary complex queries (which may use database-specific syntax),
this text area can be used for any supported query, including stored procedures if supported by the report query
executer.
If a query has already been set for the report, this text area shows it when the query dialog is open.
Use the Outline and Diagram tabs to visually build the query. The current version of Jaspersoft Studio doesn't
support back-parsing of SQL. For this reason, you should use Outline and Diagram editing mode only to create
new queries, otherwise the new query replaces any existing query. If you do attempt to overwrite an existing
query, Jaspersoft Studio alerts you.

Figure 11-3 Query Overwrite Warning

11.2.1

Query Outline View and Diagram View
The purpose of SQL is to select data from the tables of the database. SQL allows you to join tables, so that you
can get data from more than one table at a time.

TIBCO Software Inc.

163

TIBCO Jaspersoft Studio User Guide

Figure 11-4 Outline View
The Outline view is a good tool for people with a basic understanding of SQL. It works in conjunction with
the Diagram view, which represents the simplest way to design a query. In the outline view the query is split
in its main parts introduced by the relative keyword. Those parts include:
SELECT introduces the portion of query where are listed all the columns that form a record of the final result set

(which is basically a list of records).
FROM contains the list of tables involved in our queries and if specified the rules to join that tables.
WHERE is the portion of query that describes the filters and conditions that the data must satisfy in order to be
part of the final result, conditions can be combined by using the OR and AND logical operators and can be

aggregated by using parentheses.
GROUP BY indicates a set of fields used to aggregate data and is used when an aggregation function is present in
the SELECT. For example, the following query counts the number of orders placed in each country.
SELECT
count(*) as number_of_orders,
Orders.country
FROM
Orders
GROUP BY
Orders.country

HAVING works in a i bit like WHERE, but it's used with aggregate functions. For example the following query

filters the records by showing only the countries that have at least 40 orders:
ORDER BY specifies a set of columns for sorting the result set.
SELECT
count(*) as number_of_orders,
Orders.country

164

TIBCO Software Inc.

Chapter 11 Creating Queries

FROM
Orders
GROUP BY
Orders.country
HAVING
count(*) > 40

The Diagram view shows the tables in the query with the relative join connections and the selected fields. This
view is very useful especially to select the relevant fields and easily edit the table joins by double-clicking the
connection arrows.

Figure 11-5 Diagram View

11.2.2

Selecting Columns
You can drag columns from the database explorer into the SELECT node or other nodes in the outline view.
Make sure the columns you select are from tables present in the FROM part of your query.
You can also select fields by their check boxes in the diagram view.
Finally you can add a column by right-clicking the SELECT node in the outline view and selecting Add
Column. A new dialog prompts you to pick the column from the those in the tables mentioned in the FROM
clause. If a column you want to add is not a table column, but a more complex expression, for instance an
aggregation function like COUNT(*), add it by right-clicking the SELECT node in the outline view and selecting
Add Expression.
When a column is added to the query as part of the SELECT section, you can set an alias for it by doubleclicking it.

TIBCO Software Inc.

165

TIBCO Jaspersoft Studio User Guide

Figure 11-6 Setting an Alias
Aliases are useful when you have several fields with the same name coming from two different tables.

11.2.3

Joining Tables
You can join tables you've added by selecting shared fields. You can create the relationship the Diagram view
by dragging a column of the first table onto the column of the table you're joining to. You can edit this type of
join by double-clicking the join arrows. Currently a single join condition is supported.

Figure 11-7 Column Dialog
You can also edit joins in the outline view by right-clicking a table name and selecting Add or Edit Table
Join.

166

TIBCO Software Inc.

Chapter 11 Creating Queries

Figure 11-8 Join Table

11.2.4

Data Selection Criteria (WHERE Conditions)
Use a WHERE clause to specify the criteria to be for each record's part in the query result. Right click the WHERE
node in the outline view and select Add Condition to add a new condition.
If you know in advance which column should be involved in the condition, you can drag this column on the
WHERE node to create the condition. In both cases the condition dialog appears.

Figure 11-9 Add Condition
You can organize conditions by creating condition groups, and then combining them with or and and
operators. At least one condition must be true for an OR group. All conditions must be true for the AND operator.
You can double-click to change the value of either of these group operators.
If the value of a condition is not fixed, you can express it by using a parameter with the expression: $P
{parameter_name}.
When using collection type parameters, the $X{}expressions allow you to use operators like IN and NOT IN,
which determine whether a value is present in the provided list. The $X{} syntax also allows you to use other
operators like BETWEEN for numbers, Date Range and Time Range type of parameters. See 8.2, “Expression
Operators and Object Methods,” on page 94 for more information about the $X{} syntax.

TIBCO Software Inc.

167

TIBCO Jaspersoft Studio User Guide

11.2.5

Acquiring Fields
When your query is ready, it's time map the columns of the result set to fields of the report. When using SQL,
this is a pretty straight forward operation.
Press the Read button to execute the query. If the query is valid and no errors occur Jaspersoft Studio adds a
field for each column with the proper class type to the fields list.

11.2.6

Data Preview
Use the Data Preview tab to generate a ghost report that maps the fields to the fields tab using your query and
selected Data Adapter. This tool is independent of the query language and a good way to debug a query or
check which records the dataset returns.

Figure 11-10 Data Preview Tab

168

TIBCO Software Inc.

Chapter 12 Accessing JasperReports Server from Jaspersoft Studio

CHAPTER 12 ACCESSING JASPERREPORTS SERVER
STUDIO

FROM

JASPERSOFT

This section describes functionality that can be restricted by the software license for JasperReports
Server. If you don’t see some of the options described in this section, your license may prohibit you from
using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft.

You can connect Jaspersoft Studio to JasperReports Server and move reports between the two. Jaspersoft Studio
uses web services to interact with the server.
Connecting with JasperReports Server enables you to:
•
•
•
•
•
•
•
•
•
•

Browse the repository on the server from Jaspersoft Studio.
Add reports and subreports to the repository from Jaspersoft Studio.
Drag and drop images and other resources from the repository to Jaspersoft Studio.
Add and delete folders and resources on the server from Jaspersoft Studio.
Modify resource properties on the server from Jaspersoft Studio.
Link input controls to reports on the server.
Import and export data sources (JDBC, JNDI, and JavaBean).
Download, edit, and upload JRXML files.
Connect to multiple servers for access to both test and production environments.
Create a report in Jaspersoft Studio based on a Domain in JasperReports Server (commercial edition only).

This chapter contains the following sections:
•
•
•
•
•
•
•
•
•

Connecting to JasperReports Server
Publishing a Report to JasperReports Server
Working with JasperReports Server Templates
Creating and Uploading a Topic for Ad Hoc Views
Managing Repository Objects through Jaspersoft Studio
Creating and Uploading Chart Themes
Working with Domains
Understanding the repo: Syntax
Adding a Date/Time Stamp to Scheduled Output in JasperReports Server

TIBCO Software Inc.

169

TIBCO Jaspersoft Studio User Guide

12.1

Connecting to JasperReports Server
To connect Jaspersoft Studio to the server:
1. Start Jaspersoft Studio.
2.

Open the Repository Explorer, then click the Create a JasperReports Server Connection icon

The Server profile wizard appears.

Figure 12-1 Server Profile Wizard
3.

Enter the URL, user names and password for your server. If the server hosts multiple organizations, enter the
name of your organization as well.
The defaults are:
•

URL:
• Commercial editions: http://localhost:8080/jasperserver-pro/
• Community edition: http://localhost:8080/jasperserver/
• Organization: There is no default value for this field. If the server hosts multiple organizations, enter
the ID of the organization to which you belong.
• User name: jasperadmin
• Password: jasperadmin
Note that if you are upgrading from a previous version of Jaspersoft Studio, the old URL
(http://localhost:8080/jasperserver-pro/services/repository ) still works.
4.
5.

170

Click Test Connection.
If the test fails, check your URL, organization, user name, and password.

TIBCO Software Inc.

Chapter 12 Accessing JasperReports Server from Jaspersoft Studio

Connection problems can sometimes be caused by Eclipse's secure storage feature, which improves your
security by storing passwords in an encrypted format. For more information, refer to our Eclipse Secure
Storage in Jaspersoft Studio Community wiki page.
6.

If the test is successful, click Finish.
The server appears in the Repository Explorer.

Figure 12-2 Repository Explorer

12.1.1

Advanced Connection Settings
You can configure additional properties for your JasperReports Server connection using the Advanced Settings
in the Server profile wizard. The following options are available:
•

•
•
•
•

•
•
•
•
•
•
•

JasperReports Library Version – Sets the version of the JRXML output generated by Jaspersoft Studio.
When you connect to a JasperReports Server instance that is earlier than your version of Jaspersoft Studio,
use this setting to convert your JRXML to the version used by the server. You can view server information,
including the server version, on the info tab.
Connection Timeout [ms] – Sets the connection timeout in milliseconds.
HTTP Chunked Requests – Enables chunked transfer encoding. Disable this option if your firewall
blocks incomplete response chunks.
Use SOAP protocol only – Sets communication between Jaspersoft Studio and the server to use the
SOAP format. Can't be used with single sign-on.
Use Single Sign On – Lets you connect to a connect to a JasperReports Server instance that has been
configured to work with the Central Authentication Service (CAS) protocol. See 12.1.2, “Using Single
Sign-on with JasperReports Server,” on page 172 for more information.
Supports DateRange Expressions – Lets you upload queries with relative dates to JasperReports Server.
See 6.3.4, “Relative Dates ,” on page 80for more information.
Synchronize DataAdapter Properties – Synchronizes the net.sf.jasperreports.data.adapter
property with the Jaspersoft Studio data adapter setting.
Format of Attachements – Sets the message attachment format to MIME or DIME.
Workspace Folder – Lets you designate the folder in the workspace where you want to store files
downloaded from this JasperReports Server instance.
Locale – Sets the locale to use for the Jaspersoft Studio connection to the server.
Time Zone – Sets the timezone to use for the Jaspersoft Studio connection to the server.
Info tab – Shows information about the JasperReports Server instance, including version number, edition,
license expiration, licensed features, and data and timestamp format.

TIBCO Software Inc.

171

TIBCO Jaspersoft Studio User Guide

12.1.2

Using Single Sign-on with JasperReports Server
You can use single sign-on (SSO) to connect to a JasperReports Server instance that has been configured to
work with the Central Authentication Service (CAS) protocol. For information about configuring CAS for
JasperReports Server, see the JasperReports Server External Authentication Cookbook.
Configure JasperReports Server:
1. Before you begin, configure your JasperReports Server instance for CAS, as described in the JasperReports
Server External Authentication Cookbook.
Add the CAS server to your Jaspersoft Studio workspace:
1. In Jaspersoft Studio, select Window > Preferences.
2.

In the Preferences window, navigate to Jaspersoft Studio > Jaspersoft Server Setting > Single Sign
On Server.

Figure 12-3 Single Sign On Servers in Preferences Dialog
3.

In the Single Sign On Servers pane, click Add.

Enter the URL of your CAS server along with the username and password you want to use for access.

Figure 12-4 SSO Server Settings Dialog

172

TIBCO Software Inc.

Chapter 12 Accessing JasperReports Server from Jaspersoft Studio

Click OK.
The CAS server is added to the list of available single sign-on servers.

Click OK.

Configure your JasperReports Server connection to use CAS:
1. In Jaspersoft Studio, open the Repository Explorer, then click the Create a JasperReports Server
Connection icon
.
2.

Select Advanced Settings.

Enable the Use Single Sign On option.
The Account section of the Server profile wizard changes.

Figure 12-5 Setting Single Sign-on in the Server Profile Wizard

TIBCO Software Inc.

173

TIBCO Jaspersoft Studio User Guide

12.2

If the server hosts multiple organizations, enter the ID of the organization to which you belong. This can be
the root organization (in which case you can leave this entry bar blank) or another organization.

Select the CAS server you want to use for this connection from the SSO Server menu.

Click Test Connection to test the connection. This may take some time, especially the first time you
connect.

Click OK in the confirmation dialog.

Click OK to create the connection.

Publishing a Report to JasperReports Server
You can easily publish your reports from Jaspersoft Studio to any JasperReports Server connection. Publishing
to the server uploads the JRXML for the report, along with any resources that the report needs such as images
and query resources. You must also configure the data source for the report on the server.

12.2.1

Publishing Report Resources
The reports you create in Jaspersoft Studio can have embedded resources, such as such as images, query
resources, and data adapters using net.sf.jasperreports.data.adapter. You can use the following
columns in Select Resources to publish page of the Report Publishing Wizard to control the resources you
upload:
•

•

12.2.2

Overwrite – Controls whether or not you overwrite a resource if it already exists. This setting is important
when you republish a report that has been published before. Click on the value in this column to display a
drop-down menu with the following choices:
• Overwrite – Creates a new resource or overwrites an existing resource with the current version.
• Ignore – Ignores the resource.
• Overwrite Only Expression – Updates the expression for the resource. Enter the new value in the
Expression column. Does not create or overwrite the resource.
Expression – When Overwrite or Overwrite Only Expression is selected, lets you choose the
expression you want to use. Click on the value in this column and then click ... to open the Expression
Editor and edit the expression that specifies the location where the file is saved. By default, resources such
as images are published to a repository location, and the uploaded report uses the repo: syntax to refer to
the report location.
Type – When Overwrite is selected, specifies the existing resource to overwrite. Click on the value in this
column to display a drop-down menu with the following choices:
• Save to Folder – Save to a location anywhere on your JasperReports Server instance. When you
choose this option, you are prompted to navigate to the location you want.
• Link to Resource – Links to an existing resource on your JasperReports Server instance. When you
choose this option, you are prompted to navigate to the resource you want. If you modify a report and
the report is set to Overwrite, changes overwrite only the path, not the resource.
• Use Local Resource – Save as a resource inside the report unit on JasperReports Server.

Choosing a Data Source for a Published Report
In JasperReports Server, data is usually specified using a JasperReports Server data source. Like a data adapter, a
JasperReports Server data source does not contain data; instead it contains the information JasperReports Library
needs to construct a JRDataSource when the report is run. Choosing a JasperReports Server data source instead

174

TIBCO Software Inc.

Chapter 12 Accessing JasperReports Server from Jaspersoft Studio

of a data adapter when you publish a report to JasperReports Server lets you take advantage of features specific
to JasperReports Server or to use a JNDI connection configured on your application server.
When you upload a report from Jaspersoft Studio to JasperReports Server, you can choose one of the following
options:
•
•
•

Data Source from Repository – Use an existing JasperReports Server data source for your report.
Local Data Source –Create a JasperReports Server data source or upload a Jaspersoft Studio data adapter
file to use in your report.
No Data Source – Make no changes to the data adapter information in your report.

12.2.2.1 Data Source from Repository
The Data Source from Repository option lets you choose an existing data source from the JasperReports
Server repository.
To use the Data Source from Repository option:
•

Make sure the data source is available in JasperReports Server. If you want to create a data source, select
Local Data Source instead.
If you are using a JDBC or JNDI data source, make sure that your connection uses the same driver as
your Jaspersoft Studio data adapter. For example, if you connect to an Oracle database from a
commercial edition, you can download and use the native Oracle driver or you can use the TIBCO Oracle
JDBC driver that is included with Jaspersoft Studio. If your driver in JasperReports Server does not match
the driver used in Jaspersoft Studio, you could see different data in your uploaded report.

•

Click

•
•

you want to save the report. Then click OK. If you are prompted to upload resources, select your settings.
Select Data Source from Repository when prompted.
Click ... and select the correct JasperReports Server data source from the repository.

to publish your report and select a JasperReports Server instance and repository location where

12.2.2.2 Local Data Source
The Local Data Source option lets you create a new data source in JasperReports Server to use with your
report, or to upload a data adapter from Jaspersoft Studio to JasperReports Server. To use this option to create a
new data source:
•

•

•
•
•
•
•
•

If you want to use a JNDI data source, first set up the JNDI connection for your database in your
application server. Make sure to use the same JDBC driver for your Jaspersoft Studio adapter and the JNDI
connection in JasperReports Server.
Click
to publish your report and select a JasperReports Server instance and repository location where
you want to save the report. Then click OK. If you are prompted to upload resources, select your settings.
Select Local Data Source when prompted.
Click ... to open the Add Resource wizard.
Select the type of data source you want to create , for example, Datasource JDBC, and click Next.
On the Resource Editor page, enter a name and unique ID for the data source. You can also enter an
optional description. Then click Next.
On the next page, manually fill in the required information for the data source you want to create.
Click Finish to create the data source and use it in your uploaded report.

TIBCO Software Inc.

175

TIBCO Jaspersoft Studio User Guide

For some types of data sources, such as JDBC, JNDI, and bean data sources, you can publish a data adapter from
Jaspersoft Studio and set it as the data source for the report:
•

•

•
•
•
•

•
•
•

Make sure that the data adapter you want to upload is saved locally as an xml file in the same project as
your report. See 10.1.2, “Importing and Exporting Data Adapters,” on page 121 for information about
exporting a global data adapter to your project; see 10.1.3, “Copying a Data Adapter,” on page 122 for
information about copying a data adapter from one project to another.
Click
to publish your report. Select a JasperReports Server instance and repository location where you
want to save the report. Then click OK.
If you are prompted to upload resources, select your resource settings and click OK.
Select Local Data Source when prompted.
Click ... to open the Add Resource wizard.
Select the type of data source you want to create and click Next. Only some data source types can be
imported from data adapters in Jaspersoft Studio, such as Datasource Bean, Datasource JDBC, and
Datasource JNDI.
On the Resource Editor page, click Import from Jaspersoft Studio. If this button is not available, you
can't import the data source type you selected.
The Import dialog shows a list of local and global adapters. Make sure to select a local adapter, which will
include the name of a file. Click OK then Finish to select the adapter.
Click Finish to publish the report and selected data adapter to the repository.
If you are using a custom data adapter or any other adapter that uses one or more jars that aren't
included in JasperReports Server, add the jar(s) to a location on your server classpath.

12.2.2.3 No Data Source
Use No Data Source when you have configured net.sf.jasperreports.data.adapter in your JRXML, as
described in 10.2.3, “Default Data Adapter ,” on page 123. Setting net.sf.jasperreports.data.adapter
lets you use multiple data adapters in the same report, for example, using a different data adapter for a subreport.
To use this option:
•
•

•
•

176

Set the default data adapter(s) for the datasets and subdatasets used in your report, as described in 10.2.3,
“Default Data Adapter ,” on page 123.
Follow these guidelines when setting default data adapters in a report that you want to publish:
• Do not use global data adapters. The default data adapter must reference a local file in the same project
as your report, or a data adapter already in your repository.
• Where possible, use inheritance to reduce the number of times you actually set the default data adapter.
If your report uses a specific adapter multiple times, try to structure the report so that the data adapter is
set for a single dataset and other datasets inherit it. For example, if you have a crosstab and a table that
use the same data adapter, you could create a subreport that contains the table and crosstab. Then if you
set your data adapter as the default for the subreport, the table and crosstab inherit this adapter. Reusing
the data adapter improves performance when you run the report.
Publish your report and select No Data Source when prompted.
When you publish the report, the default data adapters are uploaded to the repository.

TIBCO Software Inc.

Chapter 12 Accessing JasperReports Server from Jaspersoft Studio

12.2.3

Example of Publishing a Report
To publish a report to the server:
1. Open a report.
2.

Click the Publish Report button

in the upper-right corner of the Designer. The Report Publishing

Wizard opens.

Figure 12-6 Report Publishing Wizard
3.

Locate the directory for storing your report.

Name the report unit. The report unit contains all report files.

Click Next. The Select Resources window opens. This window displays any resources required by your
report, such as images, query resources, and embedded data adapters.

TIBCO Software Inc.

177

TIBCO Jaspersoft Studio User Guide

Figure 12-7 Select Resources
6.

Select any resources you want to upload with your report and check the box if you want to overwrite
previous versions of those resources. Click Next. The Configure the data source window opens.

Figure 12-8 Configure Data Source

178

Select a data source configuration. See 12.2.2, “Choosing a Data Source for a Published Report,” on
page 174 for more information.

Click Finish. The report is uploaded to the server. If there are no errors, an appropriate message is shown.

TIBCO Software Inc.

Chapter 12 Accessing JasperReports Server from Jaspersoft Studio

12.3

Working with JasperReports Server Templates
This section describes functionality that can be restricted by the software license for Jaspersoft Studio. If
you don’t see some of the options described in this section, your license may prohibit you from using
them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft.

JasperReports Server includes several templates that affect the layout of your reports. You can add custom
templates to your JasperReports Server instance by uploading a JRXML file to a Templates directory. In
addition to font and color choice, templates can contain images such as logos. In a JasperReports Server
template, the absolute path of an image is in the repository and cannot be overwritten. Other users can apply
your template by selecting Custom Report Template when they create a report from an Ad Hoc View.
JasperReports Server templates are different from report templates in Jaspersoft Studio. See Chapter 20,
“Report Templates,” on page 313 for more information.

12.3.1

Creating a Custom JasperReports Server Template
It's easiest to start with a template in JasperReports Server and change its properties (such as colors, fonts, and
logos) in Jaspersoft Studio. Then, publish the new template to the server. This example shows how to change
the font for a chart title.
To create a template:
1. Connect to JasperReports Server as superuser.
2.

In the Repository Explorer, navigate to the Public/Templates directory.

Figure 12-9 Accessing the Templates directory from Jaspersoft Studio
3.

Right-click A4 Landscape and choose Open in Editor.

TIBCO Software Inc.

179

TIBCO Jaspersoft Studio User Guide

Figure 12-10 Default A4 landscape template
The document will look empty, but if you click the Source tab, you see that attributes are set at the
JRXML level. Note the attributes for ChartTitle: