Jasper Sample

jasper Jasper Sample Shows how different features of the library could be used to generate a complex document. How to group data at different levels and perform aggregate calculations using report groups. 0.1.0 Sanda Zaharia shertage@users.sourceforge.net Grouping Data in JasperReports

A report's content can be better organized if the report data are grouped by meaningful criteria. For instance, a shipping report becomes more relevant when its data are grouped by product type, or by customer's country, etc.
And as a bonus, grouped data allow statistic calculations to be performed and additional statistic information to be added to the report at runtime.
As seen above, there are multiple reasons of grouping and aggregating data before they are represented. In JasperReports there are two ways to accomplish this:

If a report query is declared, it could be customized to retrieve already aggregated data from the data source (A SQL query could use the GROUP BY clause and statistical functions, for example). The main advantage is that the JR engine needs no more to prepare data before representing it, and the report is running faster in this case. The main disadvantage is that one cannot use the group imbrication, along with group header and footer facilities, so the data presentation can be realized in simplified layouts only.
If a rich presentation context of data grouping is required, one could use the report <group/> elements. Groups represent a flexible way to organize data on a report. In this case, the engine iterates through records in the data source and retrieves only those according to the grouping criteria.

A report group has three components:

Group expression - contains the data grouping criteria. When the value of the group expression changes during the iteration through the data source at report-filling time, a group rupture occurs and the corresponding <groupFooter> and <groupHeader> sections are inserted into the resulting document.
Group header section - a multiband section containing header additional information.
Group footer section - a multiband section containing footer additional information.

Note:

The order of groups declared in a report template is important because groups contain each other. One group contains the following group, and so on. When a larger group encounters a rupture, all subsequent groups are reinitialized.
You can declare as many groups as you want in a report.
In order to get an accurate data representation, the data in the data source should be already ordered according to the group expressions used in the report. One can either perform data sorting through the report query, or use the <sortField/> element.

Group Attributes

Any group in a report can be customized through its attributes:

name - Acts as a group identifier. This attribute is mandatory, and should be unique per report.
isStartNewColumn - Instructs the engine to start a new column when a new group starts. The default value is false.
isStartNewPage - Instructs the engine to start a new page when a new group starts. The default value is false.
isResetPageNumber - If true, when a new group starts, the built-in PAGE_NUMBER variable will be reset. The default value is false.
isReprintHeaderOnEachPage - Instructs the engine to print the group header on each page containing the group data. The default value is false.
minHeightToStartNewPage - Represents the minimum amount of vertical space at the bottom of the page or column, measured in pixels, that prevents the group from starting a new page of its own.
footerPosition - Specifies the rendering position of the group footer on the page. Possible values are: Normal, StackAtBottom, ForceAtBottom, CollateAtBottom. The default value is Normal.
keepTogether - If true, prevents the group from splitting on its first break attempt. The default value is false.

Data Grouping and Report Variables

Report variables are special objects built on top of a report expression in order to apply the code reusability during the report design stage. Report templates are a lot simplified when expressions frequently used throughout the report template are declared in a single place as objects that can be referenced by their name as unique identifier.
Another great advantage of declaring expressions as variables is the ability to perform various calculations based on their corresponding expression.
A report variable is characterized by the following attributes:

name - The variable's name used as unique identifier. It is mandatory.
class - The class name of the variable's values. The default class is java.lang.String
resetType - Indicates when the variable should be reinitialized during the report-filling process. Possible values are:None, Report, Page, Column, Group. The default value is Report.
resetGroup - If the resetType is set to Group, indicates the name of the group which triggers the variable reinitializing each time it breaks.
incrementType - Indicates when the variable should be incremented during the report-filling process. Possible values are:None, Report, Page, Column, Group. The default value is None.
incrementGroup - If the incrementType is set to Group, indicates the name of the group which triggers the variable increment each time it breaks.
calculation - Indicates the built-in calculation type to be performed on the variable expression value. Possible values are:Nothing, Count, DistinctCount, Sum, Average, Lowest, Highest, StandardDeviation, Variance, System, First. The default value is Nothing.
incrementerFactoryClass - The name of the incrementer factory class.

Note: With every iteration through the data source, variables are evaluated/incremented in the same order as they are declared. Therefore, the order of variables as they appear in the report template is very important.
For more about report variables one can consult also the tutorial.

Being familiarized with variables, it's time to focus back on data grouping. Report variables are very useful objects in a report, that can operate on any collection of data. Since groups are aggregating data in meaningful collections, variables could be used to perform operations at group level too. As seen above, they can be reset or incremented any time a group breaks, and can be used to perform various built-in calculations over parameters, other variables and/or field values in a group.
Related to groups, there is a special built-in counting variable, used to count the number of records in a group. This type of variables are always named with the related group's name followed by the _COUNT suffix. In this sample we'll find some usage examples of this group counting variables.

The Jasper Sample

This sample illustrates how groups can be used to produce documents with complex data grouping in a multicolumn layout. The reports/FirstJasper.jrxml file describes a shipping report presented in a 2-column layout, with data organized according to several specific grouping criteria.
The 2-column layout is given by the columnCount="2" attribute setting in the <jasperReport/> element.

Further, one can see the report query retrieving data ordered by the ShipCountry field:

]]>

Next in the report are defined some variables related to groups:

]]>

Now let's take a look at the groups themselves:

According to the group expression above, the FirstLetterGroup groups data with the same first letter of the ShipCountry field. All countries starting with the same letter will be grouped together. When the first letter changes, the FirstLetterGroup group will break.
One can see also, from attribute settings, that this group will start in a new column, each time printing its header too, and requires a minimum 200px amount of vertical space in order to prevent starting on a new page by its own.
Another interesting element here is the built-in variable FirstLetterGroup_COUNT which counts the number of records in the group. One could notice the variable's name consisting in the related group's name followed by the _COUNT suffix.
Other report variables, such as FreightSumFirstLetterGroup and FreightSumReport were used too, in order to perform statistic calculations.

Now let's jump to the next group in the report. The FirstLetterGroup group contains records for all countries starting with the same letter. It means that for groups containing more than one country, records for different countries are mixed together, and this might be not a very good idea. Obviously, a better data grouping procedure is required. For instance, to create a child group inside the FirstLetterGroup for each distinct country starting with that letter. So, the information will become more readable and significant than before.
This is what the second group in the report does, the CountryGroup:

Here one can observe another built-in counting variable: CountryGroup_COUNT. Again some other report variables are used to perform various calculations: DateHighestCountryGroup, FreightSumCountryGroup, FreightSumFirstLetterGroup. The group header will also be reprinted on each new page.

At this stage we can represent data in a user-friendly form, well separated by countries and country first letters, in a 2-columns layout. What else could be done to separate data better than that?
Well, there is one more thing. What if for a given country there are thousands of records? One after one, after one, and so on. Thousands of records looking the same, with nothing special to separate them, increasing a lot the eye's effort... It doesn't sound very good, indeed.
This is why the third group in the report is present. It is an empty dummy group that breaks after every 5 records, introducing a supplementary amount of vertical space between the resulting 5-records groups:

Once finished the data grouping work, the report template continues with its usual sections, such as title, title, pageHeader, columnHeader, detail, columnFooter, pageFooter and summary.
At this moment the sample is ready to be ran.

Running the Sample

Running the sample requires the Apache Ant library. Make sure that ant is already installed on your system (version 1.5 or later).
In a command prompt/terminal window set the current folder to demo/hsqldb within the JasperReports source project and run the > ant runServer command. It will start the HSQLDB server shipped with the JasperReports distribution package. Let this terminal running the HSQLDB server.
Open a new command prompt/terminal window and set the current folder to demo/samples/jasper within the JasperReports source project and run the > ant test view command.
It will generate all supported document types containing the sample report in the demo/samples/jasper/build/reports directory.
Then the report will open in the JasperReports internal viewer. Shows how to export the report to CSV format using metadata associated with report elements at design time, to mark data columns. 4.0.0 Sanda Zaharia shertage@users.sourceforge.net Pixel-Perfect Requirement and Excel Output Format

Documents stored in a JasperPrint object are ready to be printed out in a pixel-perfect representation. This means that objects' own dimensions, absolute and relative positions within the document are completely preserved. The pixel-perfect representation is a must for the read-only or layout-oriented output formats, such as PDF or Graphics2D, but it could generate some inconvenients for data-oriented output formats like the Excel-based ones. In this case more important than the pixel-perfectness of the document is to allow the generated data in the report to be properly manipulated by the Excel engine, therefore to generate as much as possible Excel-like documents. When opening an Excel document, ideally is to see:

data with correct field type (numeric, currency, date, etc);
no extra columns/rows added by the grid generation constraints;
no page margins and other padding settings;
no page numbers;
no repetition of page headers;
data organized in columns/rows in order to allow formula calculations;
some report sections to be excluded/hidden;
outline data grouping;
etc.

The CSV Metadata Exporter

A possibility to extract relevant data from a pixel-perfect JasperPrint object in order to generate a data-oriented document, is to customize the export. Some properties are needed to tell the JR engine which elements should be exported and where should they be placed in the current sheet. The JRCsvMetadataExporter is designed to process such kind of metadata information and to generate consistent columns of data, with or without column headers on their top.
Before starting the export work, the CSV metadata exporter looks for the presence of the column names by calling the getColumnNames() exporter configuration setting. One can populate this setting either directly, using the APIs, or by collecting values from the net.sf.jasperreports.export.csv.column.names.{suffix} properties at report level. If present, they provide a comma-separated list of column names, each one referencing a column that should be exported. For accurate results it's recommended that the column names in the list to follow the same order as the original columns.
Below is an example of populating the column names via JasperReports APIs:

It ensures that only 2 columns will be printed out: the column with names and the column with Ids.
Now, that we have the column names, it's time to see which elements will be exported into these columns and how. Let's introduce the other metadata properties:

net.sf.jasperreports.export.csv.column.name - this is an important element-level property. If the net.sf.jasperreports.export.csv.column.names.{suffix} properties are not present in the report, this property specifies the name of an exported column and assumes that the current element will be placed in that column. If there are defined net.sf.jasperreports.export.csv.column.names.{suffix} properties in the report, then the column name specified by the net.sf.jasperreports.export.csv.column.name property must be one of the names declared in the net.sf.jasperreports.export.csv.column.names.{suffix} properties. The current element will be placed in that column.
net.sf.jasperreports.export.csv.write.header - a report-level flag property indicating whether the column names should be exported as column headers or not. The default value is false.
net.sf.jasperreports.export.csv.repeat.value - an element-level flag property indicating whether the value associated to that column should be repeated or not when it is missing.
net.sf.jasperreports.export.csv.data - element-level property containing the exported value for that element. By default is considered the text value of the report element itself.

In this sample only five columns are exported to CSV format: ShipCountry, Order, ShipCity, ShipRegion and OrderDate. Column headers are not exported and for the ShipCity column the exported data is customized using the net.sf.jasperreports.export.csv.data property. All these settings apply to the <detail/> section:

After running the >ant test view command the data-centric document exported with the CSV metadata exporter will be available in the demo/samples/jasper/build/reports directory as FirstJasper.metadata.csv. Shows how to export the report to XLS format using metadata associated with report elements at design time, to mark data columns. 4.0.0 Sanda Zaharia shertage@users.sourceforge.net The Excel 2003 Metadata Exporter

As shown in the section above, the CSV metadata exporter is a very useful tool when data-oriented outputs are preferred. The only problem is that any format setting is dropped when the CSV file is saved. CSVs do not store layout and style, they only keep data safe. Sometimes this is not enough for complex documents. Sometimes data needs to be presented in a meaningful way, column headers should be centered, totals should appear in a bold style, some cells might require a particular background, etc. There is a need to keep together relevant data with their style and formatting information. Since the CSV metadata exporter is limited to data only, another metadata-based exporter comes to solve the problem. This is the JRXlsMetadataExporter that provides a columnar Excel 2003 output. It relies on equivalent metadata properties and parameters having the same meanings, but dedicated to the XLS output format:

In this sample the same five columns are exported to XLS format: ShipCountry, Order, ShipCity, ShipRegion and OrderDate. Column headers are not exported and for the ShipCity column the exported data is customized using the net.sf.jasperreports.export.xls.data property. All these settings apply to the <detail/> section:

After running the >ant test view command the data-centric document exported with the Excel 2003 metadata exporter will be available in the demo/samples/jasper/build/reports directory as FirstJasper.xls.metadata.xls. Notice the differences between this one and the FirstJasper.metadata.csv CSV document. Shows how to define and use a conditional style in a report template. 1.2.0 Sanda Zaharia shertage@users.sourceforge.net Conditional Styles

In JasperReports styles are the bricks used to generate the report elements appearance. Styles mean anything about fonts, but also mean borders, horizontal and vertical alignment, element transparency or opacity, background and foreground colors, format patterns, text markup information, text rotation, and so on... Almost anything needed to set up a complex, elegant and meaningful element look and feel.
However, there are situations when the L&F depends on certain conditions determined only at runtime. The most common example is the necessity to use alternate row colors in a table with a large number of rows, in order to better distinguish between them. When the total number of rows is unknown at report design time, or if the row is used in the detail section, a tool for setting up different backgrounds for the same cell is definitely required.
And here come conditional styles to get some help.

Conditional styles consist in two elements: a Boolean condition expression and a style. When the condition evaluates to true, the corresponding style is applied. In the Jasper sample one can see a conditional style definition:

]]>

The OrderIdStyle defined above derives from the Sans_Normal parent style. Usually, elements with OrderIdStyle will have the default black forecolor and a normal font weight. But when the condition expression evaluates to true (this happens each time the OrderID field value is a multiple of 10) the element's style changes: the forecolor becomes red and the font is displayed in bold style.
Therefore, when applied, a conditional style will override the properties of its parent style.

A style definition may contain many conditional styles, any of them inheriting from the parent style. In this case, all conditions that evaluate to true will append their own style properties to the existing style, in the same order they were defined in the report (the second style will be appended to the first one, and so on). If more than one conditional style affect the same style property, the property value will be done by the first conditional style in the styles sequence which evaluates its condition to true.
Here is a more elaborate example:

]]>

One can see above that on each even row the element forecolor becomes blue. More than that, if the AMOUNT field value is greater than 10,000, the second conditional style evaluates to true, and the element displays in bold font (this doesn't affect the red color or blue color set by the first conditional style, because the forecolor and font weight properties do not interfere). Further, if the AMOUNT field value is greater than 20,000, the font style becomes italic, without affecting the font color. But because any value greater than 20,000 is also greater than 10,000, then the isBold="false" font weight is no more applied, because both conditions >10,000 and >20,000 evaluate to true and isBold="true" style was appended first.

Note:

By default, the style condition expressions are evaluated during the report filling at the moment they are actually used. The conditional expression evaluation is performed with the current values of referenced variables and fields in that moment, regardless of the evaluationTime attribute of the element itself.If the condition expression of the style needs a delayed evaluation, just like the value of the text field or the image element that uses the conditional style, the net.sf.jasperreports.style.evaluation.time.enabled configuration property should be set to true.
Conditional styles cannot be defined in style templates (see the Templates sample). This is because style templates store styles with properties available for a large group of reports, while conditional styles are styles depending on conditions, variables and parameters specific to each report apart. However, styles defined in style templates can be used as parent styles for conditional styles.
Other examples of conditional styles can be found in Scriptlet, List and Crosstabs samples.