Package net.sf.jasperreports.engine

Interface JRReport

  • All Superinterfaces:
    JRDefaultStyleProvider, JRIdentifiable, JRPropertiesHolder
    All Known Implementing Classes:
    JasperDesign, JasperReport, JRBaseReport, TableJasperReport, TableReport
    public interface JRReport
extends JRDefaultStyleProvider, JRPropertiesHolder, JRIdentifiable
    An abstract representation of a Jasper report. This interface is inherited by all report implementations (designs, compiled reports, filled reports). It only contains constants and getters and setters for the most common report properties and elements. Below are listed these properties:

    Report Name

    Every report design needs a name. Its name is important because the library uses it when generating files, especially when the default behavior is preferred for compiling, filling, or exporting the report.

    The name of the report is specified using the name attribute, and its inclusion is mandatory. Spaces are not allowed in the report name - it must be a single word.

    Language

    Report expressions are usually written using the Java language. However, one can use other languages as long as a report compiler is available to help evaluate these expressions at report-filling time.

    The default value for the language property is java, meaning that the Java language is used for writing expressions, and that a report compiler capable of generating and compiling a Java class on the fly is used for producing the bytecode needed for expression evaluation at runtime.

    Report compilers reference this property to see whether they can compile the supplied report template or whether a different report compiler should be used, depending on the actual scripting language.

    Column Count

    JasperReports lets users create reports with more than one column on each page.

    Multicolumn report templates also have an associated column-filling order specified by the printOrder attribute.

    By default, the reporting engine creates reports with one column on each page.

    Print Order

    For reports having more that one column, it is important to specify the order in which the columns will be filled. One can do this using the printOrder attribute with 2 possible values:
    • Vertical - columns are filled from top to bottom and then left to right. This is the default print order.
    • Horizontal - columns are filled from left to right and then top to bottom

    Page Size

    There are two attributes at this level to specify the page size of the document that will be generated: pageWidth and pageHeight. Like all the other JasperReports attributes that represent element dimensions and position, these are specified in pixels. JasperReports uses the default Java resolution of 72 dots per inch (DPI). This means that pageWidth="595" will be about 8.26 inches, which is roughly the width of an A4 sheet of paper.

    The default page size corresponds to an A4 sheet of paper:

    pageWith="595" pageHeight="842"

    Page Orientation

    The orientation attribute determines whether the documents use the Portrait or the Landscape format.

    This orientation attribute is useful only at report-printing time to inform the printer about the page orientation, and in some special exporters. The default page orientation is Portrait.

    Page Margins

    Once the page size is decided, one can specify what margins the reporting engine should preserve when generating the reports. Four attributes control this: topMargin, leftMargin, bottomMargin, and rightMargin.

    The default margin for the top and bottom of the page is 20 pixels. The default margin for the right and left margins is 30 pixels.

    Column Size and Spacing

    Reports may have more that one column, as specified in the columnCount attribute. However, the reporting engine has to know how large a column can be and how much space should be allowed between columns. Two attributes control this: columnWidth and columnSpacing.

    Also, when a report is compiled JasperReports checks whether the width of the overall columns and the space between them exceed the specified page width and page margins.

    Since there is only one column by default, the default column spacing is 0 pixels and the default column width is 555 pixels (the default page width minus the default left and right margins).

    Empty Data Source Behavior

    The data source for a report might not contain any records. In this case, it is not clear what the output should be. Some people may expect to see a blank document and others may want some of the report sections to be displayed anyway.

    The whenNoDataType attribute lets users decide how the generated document should look when there is no data in the data source supplied to it. Possible values of this attribute are as follows:

    • NoPages - This is the default setting. The generated document will have no pages in it. Viewers might throw an error when trying to load such documents.
    • BlankPage - the generated document will contain a single blank page
    • AllSectionsNoDetail - All the report sections except the detail section will appear in the generated document.
    • NoData - the generated document will contain only the NoData section

    Title and Summary Section Placement

    To display the title or/and summary section on a separate page, set one or both of the following attributes to true:
    • isTitleNewPage
    • isSummaryNewPage
    Both of these Boolean attributes are set to false by default.

    When the summary section stretches to a new page, or starts on a new page altogether, it is not accompanied by the page header and page footer. In order to force the page header and page footer to reappear on summary trailing pages, set the isSummaryWithPageHeaderAndFooter to true; it is set to false by default.

    Column Footer Placement

    The isFloatColumnFooter Boolean property lets users customize the behavior of the column footer section. By default, this section is rendered at the bottom of the page, just above the page footer. In certain cases, it is useful to render it higher on the page, just below the last detail or group footer on that particular column. To do this, set the isFloatColumnFooter property to true.

    Scriptlet Class

    There can be multiple scriptlet instances associated with a report. The scriptletClass attribute is just a convenient way to specify the scriptlet class in case there is only one scriptlet associated with the report.

    This attribute is used by the engine only if no value is supplied for the built-in REPORT_SCRIPTLET parameter. If neither the attribute nor the parameter is used, and no other scriptlet is specified for the report using named scriptlet tags the reporting engine uses a single JRDefaultScriptlet instance as the report scriptlet.

    Resource Bundle

    To generate reports in different languages from the same report template, associate a resource bundle with the template and make sure that the locale-specific resources inside report expressions are retrieved based on the $R{} syntax.

    There are two ways to associate the java.util.ResourceBundle object with the report template.

    The first is a static association made by setting the resourceBundle property of the report template object to the base name of the target resource bundle.

    A dynamic association can be made by supplying a java.util.ResourceBundle object as the value for the REPORT_RESOURCE_BUNDLE parameter at report-filling time.

    Missing Resources Behavior

    The whenResourceMissingType property allows users to choose the desired behavior of the engine when it deals with missing locale-specific resources in the supplied resource bundle. There are four different values that can be used to deal with missing resources:
    • Null - The null value is used
    • Empty - An empty string is used
    • Key - The key is used
    • Error - An exception is raised in case a locale-specific resource is not found in the supplied resource bundle for the given key and locale

    Pagination

    When the isIgnorePagination property is set to true, the report-filling engine will completely ignore page break-related settings inside the report template and generate the document on a single, very long page. The value of this property can be overridden at runtime using the optional, built-in IS_IGNORE_PAGINATION parameter.

    Formatting Numbers, Dates and Times

    The formatFactoryClass attribute lets users specify the name of the factory class implementing the FormatFactory interface, which should be instantiated by the engine in order to produce java.text.DateFormat and java.text.NumberFormat objects to use for date and number formatting in the current report.

    This attribute specifying the factory class name is used only if no value is supplied for the built-in REPORT_FORMAT_FACTORY parameter.

    If neither of the attribute nor the parameter is used, the engine will eventually instantiate the DefaultFormatFactory implementation of the factory interface, which produces java.text.SimpleDateFormat and java.text.DecimalFormat objects for date and number formatting. This attribute or the built-in REPORT_FORMAT_FACTORY parameter should be used only if the report relies on custom date and number formatters.

    Custom Properties

    Sometimes it is useful to put some information into the report template itself. This information can be used by the parent application at runtime after loading the report template, or it can be used by the UI report-design tools to store designer-specific information, like whether to display the rules, the size of the snap grid, and so on.

    Some of the properties can be transferred onto the generated document and can be used by exporter to tailor their behavior.

    The report templates can store application or user-defined properties in the form of named values that can be archived by using any number or <property> tags inside the report template.

    It is recommended that property names rely on some namespace policy, just as Java application packages do, to ensure that no naming conflict arises when several applications store information in the same report template.

    Here is how a named value can be put inside the report template:

       <property name="com.mycompany.report.author" value="John Smith"/>
   <property name="com.mycompany.report.description" value="Displays sales data"/>
    At runtime, this application-defined data can be retrieved from the report template using the public method getPropertiesMap() inherited from the JRPropertiesHolder interface.

    Report Styles

    A report style is a collection of style settings declared at the report level. These settings can be reused throughout the entire report template when setting the style properties of report elements.

    The name attribute of a <style> element is mandatory. It must be unique because it references the corresponding report style throughout the report.

    One can use isDefault="true" for one of your report style declarations to mark the default for elements that do not or cannot have another style specified.

    Each report style definition can reference another style definition from which it will inherit some or all of its properties. The style attribute inside a <style> element specifies the name of the parent report style.

    All report elements can reference a report style to inherit all or part of the style properties. A report style declaration groups all the style-related properties supported throughout the library, but an individual element inherits only those style properties that apply to it. The others will be ignored.

    Sometimes users need to change a report element style at runtime based on certain conditions (for example, to alternate adjacent row colors in a report detail section). To achieve this goal, one can set some style properties to be enabled only if a specified condition is true. This is done using conditional styles.

    The default style of a report can be accessed using the getDefaultStyle() method inherited from the JRDefaultStyleProvider interface.

    Author:
    Teodor Danciu (teodord@users.sourceforge.net)
    See Also:
    JRParameter.IS_IGNORE_PAGINATION, JRParameter.REPORT_RESOURCE_BUNDLE, JRParameter.REPORT_SCRIPTLET, JRPropertiesMap, JRStyle, DefaultFormatFactory, FormatFactory

    • Field Detail

      • CONFIG_PROPERTY_WHEN_NO_DATA_TYPE

        static final String CONFIG_PROPERTY_WHEN_NO_DATA_TYPE
        Property that specifies a default value for the whenNoDataType attribute of report.
        See Also:
        Constant Field Values

      • LANGUAGE_JAVA

        static final String LANGUAGE_JAVA
        A constant used to specify that the language used by expressions is Java.
        See Also:
        Constant Field Values

      • LANGUAGE_GROOVY

        static final String LANGUAGE_GROOVY
        A constant used to specify that the language used by expressions is Groovy.
        See Also:
        Constant Field Values

    • Method Detail

      • getName

        String getName()
        Gets the report name.

      • getLanguage

        String getLanguage()
        Gets the report language. Should be Java or Groovy.

      • getColumnCount

        Integer getColumnCount()
        Gets the number of columns on each page

      • getPrintOrder

        PrintOrderEnum getPrintOrder()
        Specifies whether columns will be filled horizontally or vertically.
        Returns:
        a value representing one of the print order constants in PrintOrderEnum

      • getColumnDirection

        RunDirectionEnum getColumnDirection()
        Specifies whether columns will be filled from left to right or from right to left.
        Returns:
        a value representing one of the column direction constants in RunDirectionEnum

      • getPageWidth

        int getPageWidth()

      • getPageHeight

        int getPageHeight()

      • getOrientation

        OrientationEnum getOrientation()
        Specifies whether document pages will be rendered in a portrait or landscape layout.
        Returns:
        a value representing one of the orientation constants in OrientationEnum

      • getWhenNoDataType

        WhenNoDataTypeEnum getWhenNoDataType()
        Specifies the report behavior in case of empty datasources.

      • setWhenNoDataType

        void setWhenNoDataType​(WhenNoDataTypeEnum whenNoDataType)
        Sets the report behavior in case of empty datasources.

      • getSectionType

        SectionTypeEnum getSectionType()
        Specifies whether report sections are made of bands or of parts.
        Returns:
        a value representing one of the section type constants in SectionTypeEnum

      • getColumnWidth

        int getColumnWidth()

      • getColumnSpacing

        int getColumnSpacing()
        Specifies the space between columns on the same page.

      • getLeftMargin

        int getLeftMargin()

      • getRightMargin

        int getRightMargin()

      • getTopMargin

        int getTopMargin()

      • getBottomMargin

        int getBottomMargin()

      • isTitleNewPage

        boolean isTitleNewPage()
        Specifies if the title section will be printed on a separate initial page.

      • isSummaryNewPage

        boolean isSummaryNewPage()
        Specifies if the summary section will be printed on a separate last page.

      • isSummaryWithPageHeaderAndFooter

        boolean isSummaryWithPageHeaderAndFooter()
        Specifies if the summary section will be accompanied by the page header and footer.

      • isFloatColumnFooter

        boolean isFloatColumnFooter()
        Specifies if the column footer section will be printed at the bottom of the column or if it will immediately follow the last detail or group footer printed on the current column.

      • getScriptletClass

        String getScriptletClass()

      • getFormatFactoryClass

        String getFormatFactoryClass()
        Gets the name of the class implementing the FormatFactory interface to use with this report.

      • getResourceBundle

        String getResourceBundle()
        Gets the base name of the report associated resource bundle.

      • getPropertyNames

        String[] getPropertyNames()
        Gets an array of report properties names.

      • getProperty

        String getProperty​(String name)
        Gets a property value
        Parameters:
        name - the property name

      • setProperty

        void setProperty​(String name,
                 String value)

      • removeProperty

        void removeProperty​(String name)

      • getPropertyExpressions

        DatasetPropertyExpression[] getPropertyExpressions()
        Returns the list of dynamic/expression-based properties for this report.
        Returns:
        an array containing the expression-based properties of this report

      • getImports

        String[] getImports()
        Gets an array of imports (needed if report expression require additional classes in order to compile).

      • getStyles

        JRStyle[] getStyles()
        Gets an array of report styles.

      • getBackground

        JRBand getBackground()

      • getPageHeader

        JRBand getPageHeader()

      • getColumnHeader

        JRBand getColumnHeader()

      • getDetailSection

        JRSection getDetailSection()

      • getColumnFooter

        JRBand getColumnFooter()

      • getPageFooter

        JRBand getPageFooter()

      • getLastPageFooter

        JRBand getLastPageFooter()

      • getSummary

        JRBand getSummary()

      • getNoData

        JRBand getNoData()

      • setWhenResourceMissingType

        void setWhenResourceMissingType​(WhenResourceMissingTypeEnum whenResourceMissingType)
        Sets the resource missing handling type.
        Parameters:
        whenResourceMissingType - the resource missing handling type

      • getMainDataset

        JRDataset getMainDataset()
        Returns the main report dataset.

        The main report dataset consists of all parameters, fields, variables and groups of the report.

        Returns:
        the main report dataset

      • getDatasets

        JRDataset[] getDatasets()
        Returns the datasets of this report.
        Returns:
        the datasets of this report

      • isIgnorePagination

        boolean isIgnorePagination()
        Decides whether to use pagination when filling the report.

        If set to true the report will be generated on one long page.

        The design attribute can be overridden at fill time by the IS_IGNORE_PAGINATION parameter.

        Returns:
        whether to use pagination when filling the report

      • getTemplates

        JRReportTemplate[] getTemplates()
        Returns the list of report templates.

        A report template is an expression which resolves at runtime to a template. Templates include styles which can be used in the report.

        The order in which the templates are included in the report is important:

        • A style's parent must appear before the style itself.
        • A style overrides styles with the same name that are placed before it. Also, report styles override templates styles with the same name.
        Returns:
        the list of report templates, or null if none
        See Also:
        JRTemplate, JRParameter.REPORT_TEMPLATES