org.pentaho.reporting.engine.classic.core
Class Band

java.lang.Object
  org.pentaho.reporting.engine.classic.core.Element
      org.pentaho.reporting.engine.classic.core.Section
          org.pentaho.reporting.engine.classic.core.Band

All Implemented Interfaces:

Serializable, Cloneable, DataTarget, ReportElement

Direct Known Subclasses:

AbstractRootLevelBand, CrosstabSummaryFooter, CrosstabSummaryHeader, CrosstabTitleFooter, CrosstabTitleHeader, DetailsFooter, DetailsHeader, PageFooter, PageHeader, Watermark

public class Band
extends Section

A report band is a collection of other elements and bands, similiar to an AWT-Container.

This implementation is not synchronized, to take care that you externally synchronize it when using multiple threads to modify instances of this class.

Trying to add a parent of an band as child to the band, will result in an exception.

Author:

David Gilbert, Thomas Morgner

See Also:

Serialized Form

Field Summary

static String	ANONYMOUS_BAND_PREFIX The prefix for anonymous bands, bands without an userdefined name.
static String	CONTENT_TYPE Deprecated. The content-type is no longer used.

Fields inherited from class org.pentaho.reporting.engine.classic.core.Element

ANONYMOUS_ELEMENT_PREFIX

Constructor Summary

Band()
Constructs a new band (initially empty).

Band(boolean pagebreakBefore, boolean pagebreakAfter)
Constructs a new band with the given pagebreak attributes.

Band(InstanceID id)

Method Summary

void	addElement(Element element) Adds a report element to the band.
void	addElement(int position, Element element) Adds a report element to the band.
void	addElements(Collection elements) Adds a collection of elements to the band.
void	clear()
Object	clone() Clones this band and all elements contained in this band.
Element	derive(boolean preserveElementInstanceIds) Creates a deep copy of this element and regenerates all instance-ids.
ReportElement	getElement(int index) Returns the element stored add the given index.
Element	getElement(String name) Returns the first element in the list that is known by the given name.
Element[]	getElementArray() Returns an array of the elements in the band.
int	getElementCount() Returns the number of elements in this band.
boolean	isPagebreakAfterPrint() Returns, whether the page layout manager should perform a pagebreak before this page is printed.
boolean	isPagebreakBeforePrint() Returns, whether the page layout manager should perform a pagebreak before this page is printed.
void	removeElement(Element e) Removes an element from the band.
void	setElementAt(int position, Element element)
void	setPagebreakAfterPrint(boolean pagebreakAfterPrint) Defines, whether the page layout manager should perform a pagebreak before this page is printed.
void	setPagebreakBeforePrint(boolean pagebreakBeforePrint) Defines, whether the page layout manager should perform a pagebreak before this page is printed.
String	toString() Returns a string representation of the band, useful mainly for debugging purposes.
Element[]	unsafeGetElementArray()

Methods inherited from class org.pentaho.reporting.engine.classic.core.Element

derive, getAttribute, getAttributeExpression, getAttributeExpressionNames, getAttributeExpressionNamespaces, getAttributeNames, getAttributeNamespaces, getAttributes, getChangeTracker, getContentBase, getDataSource, getDefinitionSource, getElementType, getElementTypeName, getHRefTarget, getId, getMetaData, getName, getObjectID, getParent, getParentSection, getReportDefinition, getStyle, getStyleExpression, getStyleExpressions, getTreeLock, getValue, isDynamicContent, isVisible, notifyNodeChildAdded, notifyNodeChildRemoved, notifyNodePropertiesChanged, notifyNodePropertiesChanged, notifyNodeStructureChanged, setAttribute, setAttribute, setAttributeExpression, setDataSource, setDynamicContent, setElementType, setHRefTarget, setId, setName, setStyleExpression, setVisible

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CONTENT_TYPE

public static final String CONTENT_TYPE

Deprecated. The content-type is no longer used.

The defined content type for the band.

See Also:

Constant Field Values

ANONYMOUS_BAND_PREFIX

public static final String ANONYMOUS_BAND_PREFIX

The prefix for anonymous bands, bands without an userdefined name.

See Also:

Constant Field Values

Constructor Detail

Band

public Band()

Constructs a new band (initially empty).

Band

public Band(InstanceID id)

Band

public Band(boolean pagebreakBefore,
            boolean pagebreakAfter)

Constructs a new band with the given pagebreak attributes. Pagebreak attributes have no effect on subbands.

Parameters:

pagebreakAfter - defines, whether a pagebreak should be done after that band was printed.

pagebreakBefore - defines, whether a pagebreak should be done before that band gets printed.

Method Detail

addElement

public void addElement(Element element)

Adds a report element to the band.

Parameters:

element - the element that should be added

Throws:

NullPointerException - if the given element is null

IllegalArgumentException - if the position is invalid, either negative or greater than the number of elements in this band or if the given element is a parent of this element.

addElement

public void addElement(int position,
                       Element element)

Adds a report element to the band. The element will be inserted at the specified position.

Parameters:

position - the position where to insert the element

element - the element that should be added

Throws:

NullPointerException - if the given element is null

IllegalArgumentException - if the position is invalid, either negative or greater than the number of elements in this band or if the given element is a parent of this element.

addElements

public void addElements(Collection elements)

Adds a collection of elements to the band.

Parameters:

elements - the element collection.

Throws:

NullPointerException - if one of the given elements is null

IllegalArgumentException - if one of the given element is a parent of this element.

getElement

public Element getElement(String name)

Returns the first element in the list that is known by the given name. Functions should use FunctionUtilities.findAllElements(Band, String) or FunctionUtilities.findElement(Band, String) instead.

Parameters:

name - the element name.

Returns:

the first element with the specified name, or null if there is no such element.

Throws:

NullPointerException - if the given name is null.

removeElement

public void removeElement(Element e)

Removes an element from the band.

Parameters:

e - the element to be removed.

Throws:

NullPointerException - if the given element is null.

setElementAt

public void setElementAt(int position,
                         Element element)

Specified by:

setElementAt in class Section

clear

public void clear()

getElementCount

public int getElementCount()

Returns the number of elements in this band.

Specified by:

getElementCount in class Section

Returns:

the number of elements of this band.

getElementArray

public Element[] getElementArray()

Returns an array of the elements in the band. If the band is empty, an empty array is returned.

Implementation note: The array returned is a copy of the internal backend. Any modification of the array will no longer result in modifications of the internal object state. To avoid unneccessary object creations, you can use the unsafeGetElementArray() method now.

Returns:

the elements.

unsafeGetElementArray

public final Element[] unsafeGetElementArray()

getElement

public ReportElement getElement(int index)

Returns the element stored add the given index.

Specified by:

getElement in class Section

Parameters:

index - the element position within this band

Returns:

the element

Throws:

IndexOutOfBoundsException - if the index is invalid.

toString

public String toString()

Returns a string representation of the band, useful mainly for debugging purposes.

Overrides:

toString in class Element

Returns:

a string representation of this band.

clone

public Object clone()
             throws CloneNotSupportedException

Clones this band and all elements contained in this band. After the cloning the band is no longer connected to a report definition.

Specified by:

clone in interface DataTarget

Overrides:

clone in class Element

Returns:

the clone of this band.

Throws:

CloneNotSupportedException - if this band or an element contained in this band does not support cloning.

derive

public Element derive(boolean preserveElementInstanceIds)
               throws CloneNotSupportedException

Creates a deep copy of this element and regenerates all instance-ids.

Overrides:

derive in class Element

Parameters:

preserveElementInstanceIds - defines whether this call generates new instance-ids for the derived elements. Instance-IDs are used by the report processor to recognize reoccurring elements and must not changed within the report run. Outside of the report processors new instance ids should be generated at all times to separate instances and to make them uniquely identifiable.

Returns:

the copy of the element.

Throws:

CloneNotSupportedException - if there was an error while cloning this or any child object.

isPagebreakBeforePrint

public boolean isPagebreakBeforePrint()

Returns, whether the page layout manager should perform a pagebreak before this page is printed. This will have no effect on empty pages or if the band is no root-level band.

Returns:

true, if to force a pagebreak before this band is printed, false otherwise

setPagebreakBeforePrint

public void setPagebreakBeforePrint(boolean pagebreakBeforePrint)

Defines, whether the page layout manager should perform a pagebreak before this page is printed. This will have no effect on empty pages or if the band is no root-level band.

Parameters:

pagebreakBeforePrint - set to true, if to force a pagebreak before this band is printed, false otherwise

isPagebreakAfterPrint

public boolean isPagebreakAfterPrint()

Returns, whether the page layout manager should perform a pagebreak before this page is printed. This will have no effect on empty pages or if the band is no root-level band.

Returns:

true, if to force a pagebreak before this band is printed, false otherwise

setPagebreakAfterPrint

public void setPagebreakAfterPrint(boolean pagebreakAfterPrint)

Defines, whether the page layout manager should perform a pagebreak before this page is printed. This will have no effect on empty pages or if the band is no root-level band.

Parameters:

pagebreakAfterPrint - set to true, if to force a pagebreak before this band is printed, false otherwise