org.jfree.report
Class Band

java.lang.Object
  org.jfree.report.Element
      org.jfree.report.Band

All Implemented Interfaces:

java.lang.Cloneable, DataTarget, java.io.Serializable

Direct Known Subclasses:

GroupFooter, GroupHeader, ItemBand, PageFooter, PageHeader, ReportFooter, ReportHeader, Watermark

public class Band

extends Element

implements java.io.Serializable, java.lang.Cloneable

A report band is a collection which can contain other Report-Elements. A band contains a list of elements to be displayed, and represents one section of a report (the report header or footer, the page header or footer, the group header or footer, or the items within a group).

The elements in a report band can contain fixed values, field values from the dataset, or function values. The elements are not required to have unique names.

This implementation is not synchronized, to take care that you externally synchronize it when using multiple threads.

A band's contents should not be modified after the report processing starts, so don't add Elements to the band's contained in or aquired from an report-state.

Bands contain a master stylesheet for all element contained in that band. This StyleSheet is registered in the child when the element is added to the band.

Bands now extend the Element-class, so it is possible to stack bands into another band. 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 java.lang.String	ANONYMOUS_BAND_PREFIX The prefix for anonymous bands, bands without an userdefined name.
static java.lang.String	CONTENT_TYPE the defined content type for the band.

Fields inherited from class org.jfree.report.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.

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(java.util.Collection elements) Adds a collection of elements to the band.
java.lang.Object	clone() Clones this band and all elements contained in this band.
ElementStyleSheet	getBandDefaults() Returns the default style sheet for all children of this band.
java.lang.String	getContentType() Returns the content type of the element.
Element	getElement(int index) Returns the element stored add the given index.
Element	getElement(java.lang.String name) Returns the first element in the list that is registered 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.
java.util.List	getElements() Returns all child-elements of this band as immutable list.
BandLayoutManager	getLayout() Returns the layout manager for the band.
protected void	handleRegisterStyleSheetCollection() Handles the registration of the stylesheet collection.
protected void	handleUnregisterStyleSheetCollection() Handles the unregistration of the stylesheet collection.
void	invalidateLayout() Invalidates the layout.
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	setLayout(BandLayoutManager layoutManager) Sets the band layout manager.
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.
java.lang.String	toString() Returns a string representation of the band and all the elements it contains, useful mainly for debugging purposes.
void	updateStyleSheetCollection(StyleSheetCollection sc) Updates the stylesheet collection for this element and all substylesheets.

Methods inherited from class org.jfree.report.Element

getDataSource, getMaximumSize, getMinimumSize, getName, getParent, getPreferredSize, getStyle, getStyleSheetCollection, getTreeLock, getValue, isDynamicContent, isLayoutCacheable, isVisible, registerStyleSheetCollection, setDataSource, setDynamicContent, setLayoutCacheable, setMaximumSize, setMinimumSize, setName, setParent, setPreferredSize, setVisible, unregisterStyleSheetCollection

Methods inherited from class java.lang.Object

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

Field Detail

CONTENT_TYPE

public static final java.lang.String CONTENT_TYPE

the defined content type for the band. The content type is used when selecting the correct display-method for an element.

See Also:

Constant Field Values

ANONYMOUS_BAND_PREFIX

public static final java.lang.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(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

getLayout

public BandLayoutManager getLayout()

Returns the layout manager for the band.

Returns:

The layout manager.

setLayout

public void setLayout(BandLayoutManager layoutManager)

Sets the band layout manager.

Parameters:

layoutManager - the layout manager.

getBandDefaults

public ElementStyleSheet getBandDefaults()

Returns the default style sheet for all children of this band. This style sheet is used to define a set of base (or default) properties for all elements.

Returns:

the default style sheet.

addElement

public void addElement(Element element)

Adds a report element to the band.

Parameters:

element - the element (null not permitted).

Throws:

java.lang.NullPointerException - if the element is null or contains null values.

addElement

public void addElement(int position,
                       Element element)

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

Parameters:

position - the position where to insert the element

element - the element that should be added

Throws:

java.lang.NullPointerException - if the given element is null

java.lang.IllegalArgumentException - if the position is invalid, either negative or greater than the number of elements in this band.

addElements

public void addElements(java.util.Collection elements)

Adds a collection of elements to the band.

Parameters:

elements - the element collection.

Throws:

java.lang.NullPointerException - if the collection given is null or the collection contains null elements.

getElement

public Element getElement(java.lang.String name)

Returns the first element in the list that is registered by the given name.

Parameters:

name - the element name.

Returns:

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

Throws:

java.lang.NullPointerException - if the given name is null.

removeElement

public void removeElement(Element e)

Removes an element from the band.

You should not use this method on a band acquired from a ReportState or Function.

Parameters:

e - the element to be removed.

getElements

public java.util.List getElements()

Returns all child-elements of this band as immutable list.

Returns:

an immutable list of all registered elements for this band.

getElementCount

public int getElementCount()

Returns the number of elements in this band.

Returns:

the number of elements of this band.

getElementArray

public Element[] getElementArray()

Returns an array of the elements in the band. This method never returns null.

Returns:

the elements.

getElement

public Element getElement(int index)

Returns the element stored add the given index.

Parameters:

index - the element position within this band

Returns:

the element

Throws:

java.lang.IndexOutOfBoundsException - if the index is invalid.

toString

public java.lang.String toString()

Returns a string representation of the band and all the elements it contains, useful mainly for debugging purposes.

Returns:

a string representation of this band.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clones this band and all elements contained in this band.

Specified by:

clone in interface DataTarget

Overrides:

clone in class Element

Returns:

the clone of this band.

Throws:

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

getContentType

public java.lang.String getContentType()

Returns the content type of the element. For bands, the content type is by default "X-container".

Specified by:

getContentType in class Element

Returns:

the content type

invalidateLayout

public void invalidateLayout()

Invalidates the layout. This method is called whenever a new element has been added. You should also call this method if you modified one of the elements of the band (eg. redefined the max, min or preferred size).

handleUnregisterStyleSheetCollection

protected void handleUnregisterStyleSheetCollection()

Handles the unregistration of the stylesheet collection.

Overrides:

handleUnregisterStyleSheetCollection in class Element

handleRegisterStyleSheetCollection

protected void handleRegisterStyleSheetCollection()

Handles the registration of the stylesheet collection.

Overrides:

handleRegisterStyleSheetCollection in class Element

updateStyleSheetCollection

public void updateStyleSheetCollection(StyleSheetCollection sc)
                                throws InvalidStyleSheetCollectionException

Updates the stylesheet collection for this element and all substylesheets. This method must be called after the element was cloned, to make sure that all stylesheets are registered properly.

If you don't call this function after cloning prepare to be doomed. This method will replace all inherited stylesheets with clones from the stylesheet collection.

Overrides:

updateStyleSheetCollection in class Element

Parameters:

sc - the stylesheet collection that contains the updated information and that should be assigned with that element.

Throws:

java.lang.NullPointerException - if the given stylesheet collection is null.

InvalidStyleSheetCollectionException - if there is an other stylesheet collection already registered with that element.

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