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 JRPropertiesMap 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 `public JRStyle getDefaultStyle()` method inherited from the `JRDefaultStyleProvider` interface.

  Version:
    $Id: JRReport.java 7045 2014-04-24 14:20:46Z shertage $
  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 Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `LANGUAGE_GROOVY` A constant used to specify that the language used by expressions is Groovy.
    `static java.lang.String` | `LANGUAGE_JAVA` A constant used to specify that the language used by expressions is Java.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `JRBand` | `getBackground()`
    `int` | `getBottomMargin()`
    `int` | `getColumnCount()` Gets the number of columns on each page
    `RunDirectionEnum` | `getColumnDirection()` Specifies whether columns will be filled from left to right or from right to left.
    `JRBand` | `getColumnFooter()`
    `JRBand` | `getColumnHeader()`
    `int` | `getColumnSpacing()` Specifies the space between columns on the same page.
    `int` | `getColumnWidth()`
    `JRDataset[]` | `getDatasets()` Returns the datasets of this report.
    `JRSection` | `getDetailSection()`
    `JRField[]` | `getFields()`
    `java.lang.String` | `getFormatFactoryClass()` Gets the name of the class implementing the `FormatFactory` interface to use with this report.
    `JRGroup[]` | `getGroups()`
    `java.lang.String[]` | `getImports()` Gets an array of imports (needed if report expression require additional classes in order to compile).
    `java.lang.String` | `getLanguage()` Gets the report language.
    `JRBand` | `getLastPageFooter()`
    `int` | `getLeftMargin()`
    `JRDataset` | `getMainDataset()` Returns the main report dataset.
    `java.lang.String` | `getName()` Gets the report name.
    `JRBand` | `getNoData()`
    `OrientationEnum` | `getOrientationValue()` Specifies whether document pages will be rendered in a portrait or landscape layout.
    `JRBand` | `getPageFooter()`
    `JRBand` | `getPageHeader()`
    `int` | `getPageHeight()`
    `int` | `getPageWidth()`
    `JRParameter[]` | `getParameters()`
    `PrintOrderEnum` | `getPrintOrderValue()` Specifies whether columns will be filled horizontally or vertically.
    `java.lang.String` | `getProperty(java.lang.String name)` Gets a property value
    `java.lang.String[]` | `getPropertyNames()` Gets an array of report properties names.
    `JRQuery` | `getQuery()`
    `java.lang.String` | `getResourceBundle()` Gets the base name of the report associated resource bundle.
    `int` | `getRightMargin()`
    `java.lang.String` | `getScriptletClass()`
    `JRScriptlet[]` | `getScriptlets()`
    `JRSortField[]` | `getSortFields()`
    `JRStyle[]` | `getStyles()` Gets an array of report styles.
    `JRBand` | `getSummary()`
    `JRReportTemplate[]` | `getTemplates()` Returns the list of report templates.
    `JRBand` | `getTitle()`
    `int` | `getTopMargin()`
    `JRVariable[]` | `getVariables()`
    `WhenNoDataTypeEnum` | `getWhenNoDataTypeValue()` Specifies the report behavior in case of empty datasources.
    `WhenResourceMissingTypeEnum` | `getWhenResourceMissingTypeValue()` Returns the resource missing handling type.
    `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.
    `boolean` | `isIgnorePagination()` Decides whether to use pagination when filling the report.
    `boolean` | `isSummaryNewPage()` Specifies if the summary section will be printed on a separate last page.
    `boolean` | `isSummaryWithPageHeaderAndFooter()` Specifies if the summary section will be accompanied by the page header and footer.
    `boolean` | `isTitleNewPage()` Specifies if the title section will be printed on a separate initial page.
    `void` | `removeProperty(java.lang.String name)`
    `void` | `setProperty(java.lang.String name, java.lang.String value)`
    `void` | `setWhenNoDataType(WhenNoDataTypeEnum whenNoDataType)` Sets the report behavior in case of empty datasources.
    `void` | `setWhenResourceMissingType(WhenResourceMissingTypeEnum whenResourceMissingType)` Sets the resource missing handling type.

    - ### Methods inherited from interface net.sf.jasperreports.engine.JRDefaultStyleProvider

      `getDefaultStyle`

    - ### Methods inherited from interface net.sf.jasperreports.engine.JRPropertiesHolder

      `getParentProperties, getPropertiesMap, hasProperties`

    - ### Methods inherited from interface net.sf.jasperreports.engine.JRIdentifiable

      `getUUID`

- - ### Field Detail

    - #### LANGUAGE_JAVA

          static final java.lang.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 java.lang.String LANGUAGE_GROOVY

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

  - ### Method Detail

    - #### getName

          java.lang.String getName()

      Gets the report name.

    - #### getLanguage

          java.lang.String getLanguage()

      Gets the report language. Should be Java or Groovy.

    - #### getColumnCount

          int getColumnCount()

      Gets the number of columns on each page

    - #### getPrintOrderValue

          PrintOrderEnum getPrintOrderValue()

      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()

    - #### getOrientationValue

          OrientationEnum getOrientationValue()

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

    - #### getWhenNoDataTypeValue

          WhenNoDataTypeEnum getWhenNoDataTypeValue()

      Specifies the report behavior in case of empty datasources.

    - #### setWhenNoDataType

          void setWhenNoDataType(WhenNoDataTypeEnum whenNoDataType)

      Sets the report behavior in case of empty datasources.

    - #### 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

          java.lang.String getScriptletClass()

    - #### getFormatFactoryClass

          java.lang.String getFormatFactoryClass()

      Gets the name of the class implementing the `FormatFactory` interface to use with this report.

    - #### getResourceBundle

          java.lang.String getResourceBundle()

      Gets the base name of the report associated resource bundle.

    - #### getPropertyNames

          java.lang.String[] getPropertyNames()

      Gets an array of report properties names.

    - #### getProperty

          java.lang.String getProperty(java.lang.String name)

      Gets a property value
      Parameters:
        `name` - the property name

    - #### setProperty

          void setProperty(java.lang.String name,
                         java.lang.String value)

    - #### removeProperty

          void removeProperty(java.lang.String name)

    - #### getImports

          java.lang.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()

    - #### getWhenResourceMissingTypeValue

          WhenResourceMissingTypeEnum getWhenResourceMissingTypeValue()

      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:
        `JRTemplate`, `JRParameter.REPORT_TEMPLATES`

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com