com.jrefinery.report
Class Band

java.lang.Object
  |
  +--com.jrefinery.report.Element
        |
        +--com.jrefinery.report.Band
All Implemented Interfaces:
java.lang.Cloneable, DataTarget, java.io.Serializable
Direct Known Subclasses:
GroupFooter, GroupHeader, ItemBand, PageFooter, PageHeader, ReportFooter, ReportHeader

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 CONTENT_TYPE
          the defined content type for the band.
 
Fields inherited from class com.jrefinery.report.Element
BOTTOM, CENTER, LEFT, MIDDLE, RIGHT, TOP
 
Constructor Summary
Band()
          Constructs a new band (initially empty).
 
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.
 float getHeight()
          Deprecated. do not manipulate the element properties that way, use a stylesheet and an suitable layoutmanager using the correct stylesheet properties ...
 BandLayoutManager getLayout()
          Returns the layout manager for the band.
 void invalidateLayout()
          Invalidates the layout.
protected  void registerStyleSheetCollection()
           
 void removeElement(Element e)
          Removes an element from the band.
 void setHeight(float height)
          Deprecated. do not manipulate the element properties that way, use a stylesheet
 void setLayout(BandLayoutManager layoutManager)
          Sets the band layout manager.
 java.lang.String toString()
          Returns a string representation of the band and all the elements it contains, useful mainly for debugging purposes.
protected  void unregisterStyleSheetCollection()
           
 
Methods inherited from class com.jrefinery.report.Element
getDataSource, getName, getPaint, getParent, getStyle, getStyleSheetCollection, getValue, isVisible, setDataSource, setName, setPaint, setParent, setStyleSheetCollection, setVisible
 
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
Constructor Detail

Band

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

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.

Overrides:
toString in class java.lang.Object
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).


setHeight

public void setHeight(float height)
Deprecated. do not manipulate the element properties that way, use a stylesheet

Defines the minimum height of the band.

This property is deprecated, please don't use it anymore. The minimum height can be defined using the MINIMUMSIZE property in the ElementStyleSheet if needed.

Using this method will remove any previously set minimumsize of this band.

Parameters:
height - the new height. The minimum width is set to '0'.

getHeight

public float getHeight()
Deprecated. do not manipulate the element properties that way, use a stylesheet and an suitable layoutmanager using the correct stylesheet properties ...

Queries the minimum size of this band and returns the height portion.

Returns:
the minimum height of this band.

unregisterStyleSheetCollection

protected void unregisterStyleSheetCollection()
Overrides:
unregisterStyleSheetCollection in class Element

registerStyleSheetCollection

protected void registerStyleSheetCollection()
Overrides:
registerStyleSheetCollection in class Element