JRGroup (JasperReports Library 6.17.0 API)

All Superinterfaces:

Cloneable, JRCloneable

All Known Implementing Classes:

JRBaseGroup, JRDesignGroup, JRFillGroup, TableReportGroup
```
public interface JRGroup
extends JRCloneable
```
Groups represent a flexible way to organize data on a report. A report group is represented by sequence of consecutive records in the data source that have something in common, like the value of a certain report field for example.
A report group has three components:
- Group expression
- Group header section
- Group footer section
The value of the associated group expression is what makes group records stick together. This value is the thing that they have in common. When the value of the group expression changes during the iteration through the data source at report-filling time, a group rupture occurs and the corresponding <groupFooter> and <groupHeader> sections are inserted in the resulting document.
You can have as many groups as you want on a report. The order of groups declared in a report template is important because groups contain each other. One group contains the following group, and so on. When a larger group encounters a rupture, all subsequent groups are reinitialized.
Note: Data grouping works as expected only when the records in the data source are already ordered according to the group expressions used in the report. For example, if you want to group some products by the country and city of the manufacturer, the engine expects to find the records in the data source already ordered by country and city.
Group Name
The name unequivocally identifies the group and can be used in other JRXML attributes when you want to refer a particular report group. The name of a group is mandatory and obeys the same naming convention that we mentioned for the report parameters, fields, and report variables.
Staring a New Page or a New Column When a Group Breaks
Sometimes it is useful to introduce a page or column break when a new group starts, usually because that particular group is more important and should start on a page or column of its own.
To instruct the engine to start a new page or column for a certain group instead of printing it on the remaining space at the bottom of the page or column, one must set either the isStartNewPage or isStartNewColumn attribute to true. These two attributes represent one of the most common ways to control page and column breaks in a report. The other one is by using the special break element. In all other situations, the reporting engine introduces page breaks automatically if content overflows onto a new page or column during the report-filling process.
In some report templates, you may want to introduce page breaks on purpose when a report section is larger than one page. Using the break element would not help, as the report template, having a band larger than the page size, would not get past the report validation process. To do this, you would need to introduce special dummy groups, as explained in the FAQs section of the freely available documentation published on the JasperReports web site (http://community.jaspersoft.com/wiki/jasperreports-library-faqs). However, if you don't want to consistently introduce page or column breaks for a particular group, but prefer to do that only if the remaining space at the bottom of the page or column is too small, use the minHeightToStartNewPage attribute. This attribute specifies the minimum remaining vertical space that prevents the group from starting a new page of its own. It is measured in pixels.
Resetting Page Number
If required, report groups have the power to reset the built-in report variable that contains the current page number (variable PAGE_NUMBER). To do this, set the isResetPageNumber attribute to true.
Group Header
This section marks the start of a new group in the resulting document. It is inserted in the document every time the value of the group expression changes during the iteration through the data source. The group header section is a multi-band section.
Group Footer
Every time a report group changes, the engine adds the corresponding group footer section before starting the new group or when the report ends. The group footer section is also a multi-band section.
The rendering position of the group footer on the page, as well as its behavior in relation to the report sections that follow it, is controlled by the footerPosition attribute, as follows:
- Normal - The group footer section is rendered immediately after the previous section.
- StackAtBottom - The group footer section appears at the bottom of the current page. Remaining space on the page appears above it. The group footer section of the outer groups is pushed to the bottom of the current page, as well, in case the current group is a nested inner group. So both the current group footer and the outer group footers stack at the bottom of the current page
- ForceAtBottom - The group footer section is forced to render at the very bottom of the page and is followed only by the page footer section. All sections following this type of group footer are forced to render on the next page
- CollateAtBottom - The collate setting is a weak setting. If all outer group footers are configured to render at the bottom of the page, the group footer section will also appear at the bottom and any remaining white space will appear above it. However, if at least one outer group footer has normal rendering position and its positioning is not overridden by another inner group, the current group footer renders at the normal position.
Without specifying a footer position for the group, the group footer is rendered in normal position.
Preventing Group Split
Sometimes it is useful to keep the content of a group together and prevent it from spanning pages or columns. In such cases, it is often advisable to start the group on a new page or column and leave some unused space on the current page/column rather than having the group split in the middle.
This behavior can be controlled with the keepTogether flag available at group level. When this flag is turned on, we prevent the group from splitting on its first break attempt. If a group is long, it will certainly need to break at some point. So, with a first break only, we avoid a split only when the group attempts to split for the first time, while subsequent breaks during the current group are allowed.
Note that this a purely visual feature of the engine, because it does not involve reverting any of the calculations made during the current group iteration . It is only about moving already-generated content to a new page, making it appear as if the group started there in the first place. Be advised that in cases where group-, page- or column-related information is displayed in the group, such as the current page number, their values might be wrong after they are moved.
Author:

Teodor Danciu ([email protected])

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`JRVariable`	`getCountVariable()`
`JRExpression`	`getExpression()` Gets the expression that defines what records in the group have in common.
`FooterPositionEnum`	`getFooterPositionValue()` Specifies how the group footer section behaves with regards to its position on the current page.
`JRSection`	`getGroupFooterSection()` Gets the footer section created for this group.
`JRSection`	`getGroupHeaderSection()` Gets the header section created for this group.
`int`	`getMinDetailsToStartFromTop()` Gets the minimum number of details to be rendered on the current column, to avoid starting the group on a new column.
`int`	`getMinHeightToStartNewPage()` Gets the minimum amount of vertical space needed at the bottom of the column in order to place the group header on the current column.
`String`	`getName()` Gets the group name
`boolean`	`isKeepTogether()` Gets the flag that signals if the group should be prevented from splitting on first break attempt.
`boolean`	`isPreventOrphanFooter()` Gets the flag that signals if the group footer should be prevented from appearing without a detail at the top of a new page/column.
`boolean`	`isReprintHeaderOnEachColumn()` Gets the flag that signals if the group header should be reprinted at the beginning of each column, in vertically filled reports only.
`boolean`	`isReprintHeaderOnEachPage()` Gets the flag that signals if the group header should be reprinted at the beginning of each page.
`boolean`	`isResetPageNumber()` Gets the flag that signals if the group header should be printed always on a new page, along with the re-initialization of the page number.
`boolean`	`isStartNewColumn()` Gets the flag that signals if the group header should be printed always on a new column.
`boolean`	`isStartNewPage()` Gets the flag that signals if the group header should be printed always on a new page.
`void`	`setFooterPosition(FooterPositionEnum footerPosition)` Specifies the group footer section behavior with regards to its position on the current page.
`void`	`setKeepTogether(boolean keepTogether)` Sets the flag that signals if the group should be prevented from splitting on first break attempt.
`void`	`setMinDetailsToStartFromTop(int minDetails)` Sets the minimum number of details to be rendered on the current column, to avoid starting the group on a new column.
`void`	`setMinHeightToStartNewPage(int minHeight)` Sets the minimum amount of vertical space needed at the bottom of the column in order to place the group header on the current column.
`void`	`setPreventOrphanFooter(boolean preventOrphanFooter)` Sets the flag that signals if the group should be prevented from appearing without a detail at the top of a new page/column.
`void`	`setReprintHeaderOnEachColumn(boolean isReprint)` Sets the flag that signals if the group header should be reprinted at the beginning of each column, in vertically filled reports only.
`void`	`setReprintHeaderOnEachPage(boolean isReprint)` Sets the flag that signals if the group header should be reprinted at the beginning of each page.
`void`	`setResetPageNumber(boolean isReset)` Sets the flag that signals if the group header should be printed always on a new page, along with the re-initialization of the page number.
`void`	`setStartNewColumn(boolean isStart)` Sets the flag that signals if the group header should be printed always on a new column.
`void`	`setStartNewPage(boolean isStart)` Sets the flag that signals if the group header should be printed always on a new page.

Methods inherited from interface net.sf.jasperreports.engine.JRCloneable
clone

- Method Detail
  - getName
```
String getName()
```
    Gets the group name
  - isStartNewColumn
```
boolean isStartNewColumn()
```
    Gets the flag that signals if the group header should be printed always on a new column.
  - setStartNewColumn
```
void setStartNewColumn(boolean isStart)
```
    Sets the flag that signals if the group header should be printed always on a new column.
  - isStartNewPage
```
boolean isStartNewPage()
```
    Gets the flag that signals if the group header should be printed always on a new page.
  - setStartNewPage
```
void setStartNewPage(boolean isStart)
```
    Sets the flag that signals if the group header should be printed always on a new page.
  - isResetPageNumber
```
boolean isResetPageNumber()
```
    Gets the flag that signals if the group header should be printed always on a new page, along with the re-initialization of the page number.
  - setResetPageNumber
```
void setResetPageNumber(boolean isReset)
```
    Sets the flag that signals if the group header should be printed always on a new page, along with the re-initialization of the page number.
  - isReprintHeaderOnEachPage
```
boolean isReprintHeaderOnEachPage()
```
    Gets the flag that signals if the group header should be reprinted at the beginning of each page.
  - isReprintHeaderOnEachColumn
```
boolean isReprintHeaderOnEachColumn()
```
    Gets the flag that signals if the group header should be reprinted at the beginning of each column, in vertically filled reports only.
  - setReprintHeaderOnEachPage
```
void setReprintHeaderOnEachPage(boolean isReprint)
```
    Sets the flag that signals if the group header should be reprinted at the beginning of each page.
  - setReprintHeaderOnEachColumn
```
void setReprintHeaderOnEachColumn(boolean isReprint)
```
    Sets the flag that signals if the group header should be reprinted at the beginning of each column, in vertically filled reports only.
  - getMinHeightToStartNewPage
```
int getMinHeightToStartNewPage()
```
    Gets the minimum amount of vertical space needed at the bottom of the column in order to place the group header on the current column.
  - setMinHeightToStartNewPage
```
void setMinHeightToStartNewPage(int minHeight)
```
    Sets the minimum amount of vertical space needed at the bottom of the column in order to place the group header on the current column.
  - getMinDetailsToStartFromTop
```
int getMinDetailsToStartFromTop()
```
    Gets the minimum number of details to be rendered on the current column, to avoid starting the group on a new column.
  - setMinDetailsToStartFromTop
```
void setMinDetailsToStartFromTop(int minDetails)
```
    Sets the minimum number of details to be rendered on the current column, to avoid starting the group on a new column.
  - getFooterPositionValue
```
FooterPositionEnum getFooterPositionValue()
```
    Specifies how the group footer section behaves with regards to its position on the current page.
  - setFooterPosition
```
void setFooterPosition(FooterPositionEnum footerPosition)
```
    Specifies the group footer section behavior with regards to its position on the current page.
  - isKeepTogether
```
boolean isKeepTogether()
```
    Gets the flag that signals if the group should be prevented from splitting on first break attempt.
  - setKeepTogether
```
void setKeepTogether(boolean keepTogether)
```
    Sets the flag that signals if the group should be prevented from splitting on first break attempt.
  - isPreventOrphanFooter
```
boolean isPreventOrphanFooter()
```
    Gets the flag that signals if the group footer should be prevented from appearing without a detail at the top of a new page/column.
  - setPreventOrphanFooter
```
void setPreventOrphanFooter(boolean preventOrphanFooter)
```
    Sets the flag that signals if the group should be prevented from appearing without a detail at the top of a new page/column.
  - getExpression
```
JRExpression getExpression()
```
    Gets the expression that defines what records in the group have in common.
  - getGroupHeaderSection
```
JRSection getGroupHeaderSection()
```
    Gets the header section created for this group.
  - getGroupFooterSection
```
JRSection getGroupFooterSection()
```
    Gets the footer section created for this group.
  - getCountVariable
```
JRVariable getCountVariable()
```

Interface JRGroup

Group Name

Staring a New Page or a New Column When a Group Breaks

Resetting Page Number

Group Header

Group Footer

Preventing Group Split

Method Summary

Methods inherited from interface net.sf.jasperreports.engine.JRCloneable

Method Detail

getName

isStartNewColumn

setStartNewColumn

isStartNewPage

setStartNewPage

isResetPageNumber

setResetPageNumber

isReprintHeaderOnEachPage

isReprintHeaderOnEachColumn

setReprintHeaderOnEachPage

setReprintHeaderOnEachColumn

getMinHeightToStartNewPage

setMinHeightToStartNewPage

getMinDetailsToStartFromTop

setMinDetailsToStartFromTop

getFooterPositionValue

setFooterPosition

isKeepTogether

setKeepTogether

isPreventOrphanFooter

setPreventOrphanFooter

getExpression

getGroupHeaderSection

getGroupFooterSection

getCountVariable