Package net.sf.jasperreports.engine.export

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

  • All Implemented Interfaces:
    JRExporter<ExporterInput,​RC,​C,​OutputStreamExporterOutput>, 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 JRAbstractExporter<RC,​C,​OutputStreamExporterOutput,​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

    • Field Detail

      • XLS_EXPORTER_PROPERTIES_PREFIX

        public static final java.lang.String XLS_EXPORTER_PROPERTIES_PREFIX
        See Also:
        Constant Field Values

      • DEFAULT_SHEET_NAME_PREFIX

        public static final java.lang.String DEFAULT_SHEET_NAME_PREFIX
        See Also:
        Constant Field Values

      • DEFAULT_DEFINED_NAME_SCOPE

        public static final java.lang.String DEFAULT_DEFINED_NAME_SCOPE
        See Also:
        Constant Field Values

      • DEFAULT_DEFINED_NAME_SCOPE_SEPARATOR

        public static final java.lang.String DEFAULT_DEFINED_NAME_SCOPE_SEPARATOR
        See Also:
        Constant Field Values

      • EXCEPTION_MESSAGE_KEY_CANNOT_ADD_CELL

        public static final java.lang.String EXCEPTION_MESSAGE_KEY_CANNOT_ADD_CELL
        See Also:
        Constant Field Values

      • EXCEPTION_MESSAGE_KEY_CANNOT_MERGE_CELLS

        public static final java.lang.String EXCEPTION_MESSAGE_KEY_CANNOT_MERGE_CELLS
        See Also:
        Constant Field Values

      • EXCEPTION_MESSAGE_KEY_CELL_FORMAT_TEMPLATE_ERROR

        public static final java.lang.String EXCEPTION_MESSAGE_KEY_CELL_FORMAT_TEMPLATE_ERROR
        See Also:
        Constant Field Values

      • EXCEPTION_MESSAGE_KEY_COLUMN_INDEX_BEYOND_LIMIT

        public static final java.lang.String EXCEPTION_MESSAGE_KEY_COLUMN_INDEX_BEYOND_LIMIT
        See Also:
        Constant Field Values

      • EXCEPTION_MESSAGE_KEY_LOADED_FONTS_ERROR

        public static final java.lang.String EXCEPTION_MESSAGE_KEY_LOADED_FONTS_ERROR
        See Also:
        Constant Field Values

      • EXCEPTION_MESSAGE_KEY_NEGATIVE_COLUMN_INDEX

        public static final java.lang.String EXCEPTION_MESSAGE_KEY_NEGATIVE_COLUMN_INDEX
        See Also:
        Constant Field Values

      • EXCEPTION_MESSAGE_KEY_REPORT_GENERATION_ERROR

        public static final java.lang.String EXCEPTION_MESSAGE_KEY_REPORT_GENERATION_ERROR
        See Also:
        Constant Field Values

      • EXCEPTION_MESSAGE_KEY_TEMPLATE_NOT_FOUND

        public static final java.lang.String EXCEPTION_MESSAGE_KEY_TEMPLATE_NOT_FOUND
        See Also:
        Constant Field Values

      • PROPERTY_CELL_FORMULA

        public static final java.lang.String PROPERTY_CELL_FORMULA
        Property that stores the formula which has to be applied to a given cell in an excel sheet.
        See Also:
        Constant Field Values

      • PROPERTY_CELL_PATTERN

        public static final java.lang.String PROPERTY_CELL_PATTERN
        Property that stores the pattern which has to be applied to a given cell in an excel sheet.
        See Also:
        Constant Field Values

      • PROPERTY_SHEET_NAME

        public static final java.lang.String PROPERTY_SHEET_NAME
        Property used to set the name of the sheet containing a given element. Its value overrides the report-level settings for the sheet name. If several elements in the sheet contain this property, the engine will consider the value of the last exported element's property.
        See Also:
        JRPropertiesUtil, Constant Field Values

      • PROPERTY_FREEZE_ROW_EDGE

        public static final java.lang.String PROPERTY_FREEZE_ROW_EDGE
        This property indicates the horizontal edge of the freeze pane, relative to the current cell. If set, it overrides the PROPERTY_FREEZE_ROW value. Allowed values are:
        • Top - The current row is the first unlocked row in the sheet. All rows above are 'frozen'.
        • Bottom - The current row is the last 'frozen' row in the sheet. All rows below are unlocked.
        See Also:
        Constant Field Values

      • PROPERTY_FREEZE_COLUMN_EDGE

        public static final java.lang.String PROPERTY_FREEZE_COLUMN_EDGE
        This property indicates the vertical edge of the freeze pane, relative to the current cell. If set, it overrides the PROPERTY_FREEZE_COLUMN and PROPERTY_FREEZE_SHEET_COLUMNS values. Allowed values are:
        • Left - The current column is the first unlocked column in the sheet. All columns to the left are 'frozen'.
        • Right - The current column is the last 'frozen' column in the sheet. All columns to the right are unlocked.
        See Also:
        Constant Field Values

      • PROPERTY_AUTO_FIT_ROW

        public static final java.lang.String PROPERTY_AUTO_FIT_ROW
        Flag property that indicates whether Excel should autofit the current row height. Allowed values are:
        • true
        • false - this is the default value.
        Since:
        4.5.1
        See Also:
        JRPropertiesUtil, Constant Field Values

      • PROPERTY_AUTO_FIT_COLUMN

        public static final java.lang.String PROPERTY_AUTO_FIT_COLUMN
        Flag property that indicates whether Excel should autofit the current column width. Allowed values are:
        • true
        • false - this is the default value.
        Since:
        4.5.1
        See Also:
        JRPropertiesUtil, Constant Field Values

      • PROPERTY_AUTO_FILTER

        public static final java.lang.String PROPERTY_AUTO_FILTER
        This element-level property is used to indicate the boundaries of the autofilter data range in the current sheet. Allowed values are:
        • Start - The current cell will be marked as autofilter heading cell, and column data below/to the right of this cell can be considered as part of the autofilter data range. The starting point of the autofilter data range will be the next cell below the current cell (ie if the current cell reference is B4, the autofilter range will start with the "B5" cell reference: "B5:M20").
          If multiple autofilter Start values are found in the same sheet, only the last one will be considered. If the Start value is present but no End value is found in the sheet, then only the current column will be considered for the data range.
          If the autofilter Start value is set on the same row as the autofilter End value, the data range will include all data below this heading row, placed between the start column and the end column.
        • End - The current cell will be marked as autofilter ending cell, and column data in this cell and above/to the left can be considered as part of the autofilter data range. The ending cell in the data range is the current cell reference (ie if the current cell reference is M20, the autofilter range will end in "M20": "B5:M20"). The heading cell for the current column will be placed in the same column on the row containing the autofilter Start value.
          Caution: If no autofilter Start value is found in the sheet, the autofilter End value will be considered as Start value instead.
          If multiple autofilter End value are found in the same sheet, only the last one will be considered.
          If the autofilter Start value is set on the same row as the autofilter End value, the data range will include all data below this heading row, placed between the start column and the end column.
        See Also:
        JRPropertiesUtil, Constant Field Values

      • PROPERTY_COLUMN_WIDTH

        public static final java.lang.String PROPERTY_COLUMN_WIDTH
        Element-level property used to adjust the column width to values suitable for Excel output, taking into account that column widths are measured in Excel in Normal style default character width units. The pixel-to-character width translation depends on the default normal style character width, so it cannot be always accurately fitted. In this case, one can adjust the current column width by setting this property with an integer value measured in pixels. The JR engine will perform the pixel-to-character width mapping using this value instead of the element's width attribute.
        If defined, this property will override the PROPERTY_COLUMN_WIDTH_RATIO value for the current column
        See Also:
        XlsReportConfiguration.PROPERTY_COLUMN_WIDTH_RATIO, JRPropertiesUtil, Constant Field Values

      • PROPERTY_ROW_OUTLINE_LEVEL_PREFIX

        public static final java.lang.String PROPERTY_ROW_OUTLINE_LEVEL_PREFIX
        Property prefix used to indicate the current outline row level, and when necessary, the ending row of the current outline row group with the given level. The suffix of these properties is associated with the outline level, while the property value indicates if the current row group should continue or should end. The most recommended practice is to use the outline level itself as property suffix, although this is not mandatory. The suffix may take any other string value, but one has to keep in mind that suffixes are used as sorted row level descriptors. For instance, because "aaa" < "bbb", the outline level associated with the "aaa" suffix will be smaller than the level associated with the "bbb" suffix. The most intuitive representation of the row levels uses the row level as property suffix.
        In such a case, the net.sf.jasperreports.export.xls.outline.level.2 property means that its value is correlated with the outline level 2, so the current row belongs to a level 2 row group. Based on Office Open XML specs, allowed values for outline levels are positive integers from 1 to 7.
        The value of this property could be any expression (including null). When such a property occurrence is met, the suffix indicates the outline level for that row. If multiple properties with the same prefix are defined for the same row, the deepest outline level is considered for that row. To end an outline row group one has to set the related outline level property with the End value. This is a special property value instructing the JR engine that the current row group of that level ends on the current row.
        See Also:
        JRPropertiesUtil, Constant Field Values

      • PROPERTY_BREAK_BEFORE_ROW

        public static final java.lang.String PROPERTY_BREAK_BEFORE_ROW
        Element level property specifying if a sheet will break before the row displaying that element. It is very useful especially when displaying each report's group on a separate sheet is intended.
        See Also:
        Constant Field Values

      • PROPERTY_BREAK_AFTER_ROW

        public static final java.lang.String PROPERTY_BREAK_AFTER_ROW
        Element level property specifying if a sheet will break after the row displaying that element. It is very useful especially when displaying each report's group on a separate sheet is intended.
        See Also:
        Constant Field Values

      • loadedFonts

        protected java.util.List<java.lang.Object> loadedFonts

      • sheetNames

        protected java.lang.String[] sheetNames

      • reportIndex

        protected int reportIndex

      • pageIndex

        protected int pageIndex

      • onePagePerSheetMap

        protected java.util.Map<java.lang.Integer,​java.lang.Boolean> onePagePerSheetMap

      • sheetsBeforeCurrentReport

        protected int sheetsBeforeCurrentReport

      • sheetsBeforeCurrentReportMap

        protected java.util.Map<java.lang.Integer,​java.lang.Integer> sheetsBeforeCurrentReportMap

      • defaultFont

        protected JRFont defaultFont

      • sheetIndex

        protected int sheetIndex
        Used for counting the total number of sheets.

      • sheetNamesIndex

        protected int sheetNamesIndex
        Used for iterating through sheet names.

      • sheetNamesMap

        protected java.util.Map<java.lang.String,​java.lang.Integer> sheetNamesMap
        Used when indexing the identical sheet name. Contains sheet names as keys and the number of occurrences of each sheet name as values.

      • autoFilterStart

        protected java.lang.String autoFilterStart

      • autoFilterEnd

        protected java.lang.String autoFilterEnd

      • firstPageNotSet

        protected boolean firstPageNotSet

      • keepTemplateSheets

        protected java.lang.Boolean keepTemplateSheets

      • workbookTemplate

        protected java.lang.String workbookTemplate

      • invalidCharReplacement

        protected java.lang.String invalidCharReplacement

      • maxColumnIndex

        protected int maxColumnIndex