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.

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.

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:

  • Field Details

    • 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:

    • LANGUAGE_JAVA

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

    • LANGUAGE_GROOVY

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

  • Method Details

    • 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.

    • getScriptlets

      JRScriptlet[] getScriptlets()

    • getParameters

      JRParameter[] getParameters()

    • getQuery

      JRQuery getQuery()

    • getFields

      JRField[] getFields()

    • getSortFields

      JRSortField[] getSortFields()

    • getVariables

      JRVariable[] getVariables()

    • getGroups

      JRGroup[] getGroups()

    • getBackground

      JRBand getBackground()

    • getTitle

      JRBand getTitle()

    • getPageHeader

      JRBand getPageHeader()

    • getColumnHeader

      JRBand getColumnHeader()

    • getDetailSection

      JRSection getDetailSection()

    • getColumnFooter

      JRBand getColumnFooter()

    • getPageFooter

      JRBand getPageFooter()

    • getLastPageFooter

      JRBand getLastPageFooter()

    • getSummary

      JRBand getSummary()

    • getNoData

      JRBand getNoData()

    • getWhenResourceMissingType

      WhenResourceMissingTypeEnum getWhenResourceMissingType()
      Returns the resource missing handling type.

    • 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: