Package net.sf.jasperreports.engine.export

Class JRXlsAbstractExporter<RC extends XlsReportConfiguration,​C extends XlsExporterConfiguration,​E extends JRExporterContext>

  • All Implemented Interfaces:
    Exporter<ExporterInput,​RC,​C,​OutputStreamExporterOutput>
    Direct Known Subclasses:
    JROdsExporter, JRXlsAbstractMetadataExporter, JRXlsExporter, JRXlsxExporter
    public abstract class JRXlsAbstractExporter<RC extends XlsReportConfiguration,​C extends XlsExporterConfiguration,​E extends JRExporterContext>
extends ExcelAbstractExporter<RC,​C,​E>
    Superclass for the Excel exporters.

    Excel Exporters

    For generating Excel files, there are currently two different exporter implementations available in JasperReports. The first to appear was the JRXlsExporter implementation, which uses the Apache POI library to export documents to the Microsoft Excel 2003 file format (XLS).

    Later on, with the introduction of the Microsoft Excel 2007 file format (XLSX), a new exporter was added to JasperReports to support it. This exporter implementation is the JRXlsxExporter; it does not rely on any third party library to produce XLSX files.

    Because in XLS and XLSX all document content is placed inside cells, the Excel exporters are considered typical grid exporters, and having their known limitations.

    Configuring Sheets

    An Excel file is structured in multiple sheets, and both exporters can be configured either to put all pages inside the source JasperPrint document on one sheet (one after the another), or to put each page on a separate sheet in the resulting Excel file. The choice is made by setting the isOnePagePerSheet() exporter configuration setting, which is set to Boolean.FALSE by default.

    When isOnePagePerSheet() is set to true, or when you have to execute a batch export to XLS, multiple sheets are created in the worksheet. You can also combine two exporter settings to customize the maximum number of rows per page, and display each page of the report in a separate sheet. To do this, set the number of rows per sheet for net.sf.jasperreports.export.xls.max.rows.per.sheet property and set true for net.sf.jasperreports.export.xls.one.page.per.sheet property.

    The JasperReports Excel exporters provide a simple but efficient sheet-naming mechanism. They use the getSheetNames() exporter configuration setting to read custom sheet names from the String array passed as value. This exporter setting can hold an array of strings, which are passed as sheet names in order. If no value is supplied for this setting or if the value contains fewer sheet names than actually needed by the final document, then the sheets are named by default Page i (where i represents the one-based sheet index).

    Taking into account the sheet name's length limitation in Excel (31 characters), if a sheet name contains more than 31 characters it will be truncated as follows: the name of the sheet will be given by the first 31 characters minus the sheet index length characters of the document's name, followed by the sheet index, so that the entire name has exactly 31 characters.

    For example, if the second sheet name is TheQuickBrownFoxJumpsOverTheLazyDog (35 chars), it will become TheQuickBrownFoxJumpsOverTheLa2 (the final zyDog gets truncated, and the second sheet index 2 will end the name). The name of the 12345-th sheet will become TheQuickBrownFoxJumpsOverT12345 (the final heLazyDog gets truncated, in order to make the exact room for 12345).

    Multiple sheet names can be specified in the JRXML file as well, using the net.sf.jasperreports.export.xls.sheet.names.<arbitrary_name> property at report level. Add the following to the JRXML file: 

     <property name="net.sf.jasperreports.export.xls.sheet.names.all" value="Sheet A/Sheet B/Sheet C" />
    Keep in mind the naming order is important, sheets will be named in the same order the names are provided in this property.

    Sheets can be also named at element level, using the net.sf.jasperreports.export.xls.sheet.name element property. This name will be provided for the sheet the element belongs to.

    Flow-Oriented Output

    The JasperPrint documents are page-oriented. When they are exported to a single sheet Excel document, all the pages are rendered consecutively. Because all exporters try to adhere as closely as possible to the quality and layout of the source document's Graphics2D or PDF format, the page breaks are visible in Excel format. Sometimes this is not desirable. One way to make page breaks less obvious and the layout more flow-based is to suppress all the remaining blank space between cells on the vertical axis.

    When set to Boolean.TRUE, the isRemoveEmptySpaceBetweenRows() exporter configuration flag ensures that all empty rows on the resulting sheet are collapsed. By default, the exporter preserves all the white space for a precise page layout. The provided /demo/samples/nopagebreak sample shows you how to use this setting when exporting to XLS to produce a more flow-based document layout.

    To completely ignore pagination, use the built-in fill-time parameter IS_IGNORE_PAGINATION. You can modify the API to remove the empty space between rows and columns as well. You need to set net.sf.jasperreports.export.xls.remove.empty.space.between.rows property and/or net.sf.jasperreports.export.xls.remove.empty.space.between.columns property to true.

    Keep in mind these settings are limited by your report layout. If it is too far away from a grid layout, these options cannot work. On a good grid layout, once you set net.sf.jasperreports.export.xls.remove.empty.space.between.rows property and/or net.sf.jasperreports.export.xls.remove.empty.space.between.columns property to true, the empty spaces are removed.

    Cell Types

    Inside the proprietary document format that JasperReports uses (represented by the JasperPrint object), all text elements are considered alphanumeric values. This means that if a numeric text field of type java.lang.Double is placed in the report template at design time, all the text elements inside the JasperPrint object resulting from it will hold java.lang.String values, even though they are actually numbers. Therefore, in a sense, data type information is lost during report filling. This is because the main goal of JasperReports is to create documents for viewing and printing, not necessarily for further data manipulation inside tools like Excel, where formulas could be added to numeric cells.

    However, these resulting text elements found in the generated documents nowadays hold enough data type information (in addition to the alphanumeric content) for the original value of the text element to be re-created, if needed.

    Both Excel exporters support the isDetectCellType() configuration flag, which forces the recreation of the original cell value in accordance with its declared data type, as specified in the report template.

    Cell type detection is turned off by default. You can have JasperReports automatically detect the cell type by modifying the API. Set the net.sf.jasperreports.export.xls.detect.cell.type property to true. When you do this, instead of being prompted by Excel to convert the value manually, the value is automatically converted.

    Format Pattern Conversions

    It is important to keep in mind that standard Java format patterns are not completely supported by Microsoft Excel. There are rather few data patterns that make a perfect match between Java and Excel.

    In the case that the Java pattern stored in the generated report does not match any of the supported Excel cell patterns, there is still a way to choose an appropriate Excel format pattern. The solution is to use the getFormatPatternsMap() export configuration setting and supply a java.util.Map as value. This map should contain Java format patterns as keys and corresponding Excel format patterns as values.

    Another way to adjust the format pattern to Excel-compatible values is to set the net.sf.jasperreports.export.xls.pattern property at element level.

    Font Size Correction

    Currently, there is no way to control the line spacing in a spreadsheet cell, which results in the cell text not fitting exactly within the cell boundaries. As a workaround, in order to force the cell text to fit, one can use the isFontSizeFixEnabled() exporter configuration flag to decrease the font size by one point when generating the cell format. Alternatively, one can use the net.sf.jasperreports.export.xls.font.size.fix.enabled property at report level.

    Background Color

    Empty space found on each page in the source JasperPrint document normally results in empty cells on the corresponding sheet inside the Excel file. The background color of these empty cells is specified by the configuration of the Excel viewer itself. This makes the cells appear transparent. To force the document's background to be white, set the isWhitePageBackground() exporter configuration flag to Boolean.TRUE.

    Excel Color Palette

    In JasperReports, any color can be used for the background or the foreground of a report element. However, when exporting to Excel format, only a limited set of colors is supported, through what is called a color palette.

    If the colors used in a report template do not match the colors in the color palette, then the Excel exporter will use a special algorithm to determine the closest matches by comparing the RGB levels. However, the results might not always be as expected. A possibility to optimize the use of supported colors is to create a custom color palette. This can be achieved by setting to true the isCreateCustomPalette() export configuration flag. If the flag is set, the nearest not yet modified color from the palette is chosen and modified to exactly match the report color. If all the colors from the palette are modified (the palette has a fixed size), the nearest color from the palette is chosen for further report colors.

    To see other various exporter configuration settings, please consult the XlsReportConfiguration and XlsExporterConfiguration classes.

    Author:
    Teodor Danciu (teodord@users.sourceforge.net)
    See Also:
    XlsExporterConfiguration, XlsReportConfiguration