Package net.sf.jasperreports.engine

Interface JRBand

  • All Superinterfaces:
    java.lang.Cloneable, JRChild, JRCloneable, JRElementGroup, JRPropertiesHolder, JRVisitable
    All Known Implementing Classes:
    JRBaseBand, JRDesignBand, JRFillBand
    public interface JRBand
extends JRElementGroup, JRPropertiesHolder
    Implementations of this interface represent various bands in the report template.

    Report Sections

    JasperReports works with templates that are structured into multiple sections, like any traditional reporting tool. A report can contain the following sections: background, title, summary, page header, page footer, last page footer, column header and column footer.

    At report-filling time, the engine iterates through the virtual records of the supplied report data source and renders each report section when appropriate, depending on each section's defined behavior.

    For instance, the detail section is rendered for each record in the data source. When page breaks occur, the page header and page footer sections are rendered as needed.

    Sections are made of one or more bands. Bands are portions of the report template that have a specified height and width and can contain report elements like lines, rectangles, images, and text fields. These bands are filled repeatedly at report-generating time and make up the final document.

    When declaring the content and layout of a report section, in an JRXML report design, use the generic element <band>.

    Report sections, sometimes referred to as report bands, represent a feature and functionality common to almost all reporting tools.

    Band Height

    The height attribute in a report band declaration specifies the height in pixels for that particular band and is very important in the overall report design.

    The elements contained by a certain report band should always fit the band's dimensions; this will prevent potentially bad results when generating the reports. The engine issues a warning if it finds elements outside the band borders when compiling report designs.

    Preventing Band Split

    In some cases it is desirable to keep the whole contents of a given band in one piece to prevent page breaks when the band stretches beyond its initial specified height. To do this, use the splitType attribute, as follows:
    Stretch
    The band never splits within its declared height. The band will not start rendering on the current page if the remaining available space is not at least equal to the band's declared height. However, if the band stretches on the current page, the region that is added to the original height is allowed to split onto the next page.
    Prevent
    The band starts to render normally, but if the bottom of the page is reached without finishing the band, the whole contents of the band that are already being laid out are moved to the next page. If the band does not fit on the next page, the split occurs normally, as band split prevention is effective only on the first split attempt
    Immediate
    The band is allowed to split anywhere except above its topmost element
    If a split type is not specified, the default is given by the net.sf.jasperreports.band.split.type configuration property.

    Skipping Bands

    All the report sections allow users to define a report expression that will be evaluated at runtime to decide if that section should be generated or skipped when producing the document. This expression is introduced by the <printWhenExpression> tag, which is available in any <band> element of the JRXML report design and should always return a java.lang.Boolean object or null.
    Author:
    Teodor Danciu (teodord@users.sourceforge.net)
    See Also:
    JRSection

    • Field Detail

    • Method Detail

      • getHeight

        int getHeight()

      • getSplitTypeValue

        SplitTypeEnum getSplitTypeValue()
        Specifies the band split behavior.

      • getPrintWhenExpression

        JRExpression getPrintWhenExpression()
        Returns the boolean expression that specifies if the band will be displayed.

      • getReturnValues

        java.util.List<ExpressionReturnValue> getReturnValues()
        Returns the list of values to increment report variables with.
        Returns:
        the list of returned values.