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

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

All Implemented Interfaces:

Serializable, Cloneable, DataTarget, ReportElement

Direct Known Subclasses:

AnchorElement, DrawableElement, ImageElement, Section, ShapeElement, TextElement

public class Element
extends Object
implements DataTarget, ReportElement

Base class for all report elements (displays items that can appear within a report band).

Elements can either be Bands (which are container classes that group elements) or content-elements. Content elements produce printable values when the getValue(org.pentaho.reporting.engine.classic.core.function.ExpressionRuntime) method is called.

All elements have a non-null name and have a private style sheet defined. The style sheet is used to store and access all element properties that can be used to control the layout of the element or affect the elements appeareance in the generated content.

Elements can inherit all style information from its parent. A style value is inherited whenever the element's stylesheet does not define an own value for the corresponding key. Some style-keys cannot be inherited at all, in that case the default-style-sheets value is used as fall-back value. In addition to the bands stylesheet, elements may also inherit from stylesheets assigned to the current report definition's StyleSheetCollection. Foreign stylesheet will be lost after the local cloning is complete.

Use the following code to create and assign a global stylesheet to an element:

 JFreeReport report = .. // created elsewhere
 ElementStyleSheet globalStyle =
    report.getStyleSheetCollection().createStyleSheet ("a name for the global
 style");
 

 Element element = .. // created elsewhere
 element.getStyleSheet().addParent(globalStyle);
 report.getItemBand().addElement (element);
 

Global stylesheets will always be queried before the parent's stylesheet gets queried. The order of the add-operation does matter, StyleSheets which are added last will be preferred over previously added stylesheets.

Author:

David Gilbert, Thomas Morgner

See Also:

Serialized Form

Field Summary

static String

ANONYMOUS_ELEMENT_PREFIX The internal constant to mark anonymous element names.

Constructor Summary

Element()
Constructs an element.

Method Summary

Object	clone() Clones this Element, the datasource and the private stylesheet of this Element.
Element	derive()
Element	derive(boolean preserveElementInstanceIds) Creates a deep copy of this element and regenerates all instance-ids.
Object	getAttribute(String namespace, String name)
Expression	getAttributeExpression(String namespace, String name) Returns the attribute expression for the given attribute identified by its namespace and attribute name.
String[]	getAttributeExpressionNames(String name) Returns the names of all attributes for the given namespace that have attribute-expressions assigned.
String[]	getAttributeExpressionNamespaces() Returns the namespaces of all attributes that have attribute-expressions assigned.
String[]	getAttributeNames(String name)
String[]	getAttributeNamespaces()
ReportAttributeMap	getAttributes() Returns the attributes of the element as unmodifable collection.
long	getChangeTracker() Returns the element's change-tracker.
org.pentaho.reporting.libraries.resourceloader.ResourceKey	getContentBase()
DataSource	getDataSource() Deprecated. Whereever possible use ElementType implementations instead.
org.pentaho.reporting.libraries.resourceloader.ResourceKey	getDefinitionSource() Returns the resource-key of the file that defined this element.
ElementType	getElementType()
String	getElementTypeName()
String	getHRefTarget() Returns the currently set link target for this element.
String	getId() Returns the Xml-ID of this element.
ElementMetaData	getMetaData()
String	getName() Returns the name of the Element.
InstanceID	getObjectID() Returns a unique identifier for the given instance.
Band	getParent() Return the parent of the Element.
Section	getParentSection()
ReportDefinition	getReportDefinition() Returns the currently assigned report definition.
ElementStyleSheet	getStyle() Returns this elements private stylesheet.
Expression	getStyleExpression(StyleKey property) Returns the expressions for the report.
Map	getStyleExpressions() Returns a map of all style expressions attached to this element.
Object	getTreeLock() Returns the tree lock object for the self tree.
Object	getValue(ExpressionRuntime runtime) Deprecated. this method should not be used directly. Use getElementType().getValue(..) instead.
boolean	isDynamicContent() Checks whether the layout of this element is dynamic and adjusts to the element's printable content.
boolean	isVisible() Defines whether this Element should be painted.
void	notifyNodeChildAdded(Object o) Notifies the element and any parent element that a child node has been added.
void	notifyNodeChildRemoved(Object o) Notifies the element and any parent element that a child node has been removed.
void	notifyNodePropertiesChanged() Notifies the element and any parent element that a property of this element has changed.
void	notifyNodePropertiesChanged(Object parameter)
void	notifyNodeStructureChanged() Notifies the element and any parent element that the structure of this element has changed in some undisclosed way.
void	setAttribute(String namespace, String name, Object value) Defines a attribute's static value.
void	setAttribute(String namespace, String name, Object value, boolean notifyChange)
void	setAttributeExpression(String namespace, String name, Expression value) Assigns a new attribute expression for the given attribute.
void	setDataSource(DataSource ds) Deprecated. The data-source should not be used anymore. Use ElementType implementations instead.
void	setDynamicContent(boolean dynamicContent) Defines the stylesheet property for the dynamic attribute.
void	setElementType(ElementType elementType)
void	setHRefTarget(String target) Redefines the link target for this element.
void	setId(String id) Defines the Xml-ID of this element.
void	setName(String name) Defines the name for this Element.
void	setStyleExpression(StyleKey property, Expression function) Adds a function to the report's collection of expressions.
void	setVisible(boolean b) Defines, whether this Element should be visible in the output.
String	toString() Returns a string representation of the band, useful mainly for debugging purposes.

Methods inherited from class java.lang.Object

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

Field Detail

ANONYMOUS_ELEMENT_PREFIX

public static final String ANONYMOUS_ELEMENT_PREFIX

The internal constant to mark anonymous element names.

See Also:

Constant Field Values

Constructor Detail

Element

public Element()

Constructs an element.

The element inherits the element's defined default ElementStyleSheet to provide reasonable default values for common stylekeys. When the element is added to the band, the bands stylesheet is set as parent to the element's stylesheet.

A datasource is assigned with this element is set to a default source, which always returns null.

Method Detail

setAttributeExpression

public void setAttributeExpression(String namespace,
                                   String name,
                                   Expression value)

Description copied from interface: ReportElement

Assigns a new attribute expression for the given attribute. Attributes are identified by the namespace and name. Each attribute can have only one expression assigned. Setting the expression to null clears the expression and will preserve the attribute's static value.

Functions cannot be used as attribute-expressions as attribute- and style-expressions do not receive events and are not guaranteed to be executed unless the element is processed.

Specified by:

setAttributeExpression in interface ReportElement

Parameters:

namespace - the attribute's namespace.

name - the attribute's name.

value - the expression.

getAttributeExpression

public Expression getAttributeExpression(String namespace,
                                         String name)

Description copied from interface: ReportElement

Returns the attribute expression for the given attribute identified by its namespace and attribute name.

Specified by:

getAttributeExpression in interface ReportElement

Parameters:

namespace - the attribute's namespace.

name - the attribute's name.

Returns:

the assigned expression or null if the attribute has no expression assigned.

getAttributeExpressionNamespaces

public String[] getAttributeExpressionNamespaces()

Description copied from interface: ReportElement

Returns the namespaces of all attributes that have attribute-expressions assigned.

Specified by:

getAttributeExpressionNamespaces in interface ReportElement

Returns:

the attribute-namespaces as array.

getAttributeExpressionNames

public String[] getAttributeExpressionNames(String name)

Description copied from interface: ReportElement

Returns the names of all attributes for the given namespace that have attribute-expressions assigned.

Specified by:

getAttributeExpressionNames in interface ReportElement

Parameters:

name - the namespace for which the attribute-names should be returned, never null.

Returns:

the known attribute names as array.

setAttribute

public void setAttribute(String namespace,
                         String name,
                         Object value)

Description copied from interface: ReportElement

Defines a attribute's static value. Attributes are identified by the attribute's namespace and the attribute name. Setting a attribute value to null removes the attribute. Attribute values are not checked for type safety.

Specified by:

setAttribute in interface ReportElement

Parameters:

namespace - the attribute's namespace.

name - the attribute name.

value - the attribute value, or null to remove the attribute.

setAttribute

public void setAttribute(String namespace,
                         String name,
                         Object value,
                         boolean notifyChange)

getAttribute

public Object getAttribute(String namespace,
                           String name)

Specified by:

getAttribute in interface ReportElement

getAttributeNamespaces

public String[] getAttributeNamespaces()

Specified by:

getAttributeNamespaces in interface ReportElement

getAttributeNames

public String[] getAttributeNames(String name)

Specified by:

getAttributeNames in interface ReportElement

getAttributes

public ReportAttributeMap getAttributes()

Returns the attributes of the element as unmodifable collection. The collection can be safely stored as it is guaranteed to never change. (However, no assumptions are made about the contents inside the collection.)

Specified by:

getAttributes in interface ReportElement

Returns:

the unmodifiable attribute collection

setElementType

public void setElementType(ElementType elementType)

getElementType

public ElementType getElementType()

getElementTypeName

public String getElementTypeName()

getMetaData

public final ElementMetaData getMetaData()

Specified by:

getMetaData in interface ReportElement

getParent

public final Band getParent()

Return the parent of the Element. You can use this to explore the component tree.

Returns:

the parent of this element.

getParentSection

public final Section getParentSection()

Specified by:

getParentSection in interface ReportElement

setName

public void setName(String name)

Defines the name for this Element. The name must not be empty, or a NullPointerException is thrown.

Names can be used to lookup an element within a band. There is no requirement for element names to be unique.

Parameters:

name - the name of this element

getName

public String getName()

Returns the name of the Element. The name of the Element is never null.

Specified by:

getName in interface ReportElement

Returns:

the name.

getDataSource

public final DataSource getDataSource()

Deprecated. Whereever possible use ElementType implementations instead.

Returns the datasource for this Element. You cannot override this function as the Element needs always to be the last consumer in the chain of filters. This function must never return null.

Specified by:

getDataSource in interface DataTarget

Returns:

the assigned legacy datasource.

setDataSource

public void setDataSource(DataSource ds)

Deprecated. The data-source should not be used anymore. Use ElementType implementations instead.

Sets the data source for this Element. The data source is used to produce or query the element's display value.

Specified by:

setDataSource in interface DataTarget

Parameters:

ds - the datasource (null not permitted).

Throws:

NullPointerException - if the given data source is null.

getValue

public Object getValue(ExpressionRuntime runtime)

Deprecated. this method should not be used directly. Use getElementType().getValue(..) instead.

Queries this Element's datasource for a value.

Parameters:

runtime - the expression runtime for evaluating inline expression.

Returns:

the value of the datasource, which can be null.

isVisible

public boolean isVisible()

Defines whether this Element should be painted. The detailed implementation is up to the outputtarget.

Returns:

the current visiblity state.

setVisible

public void setVisible(boolean b)

Defines, whether this Element should be visible in the output. The interpretation of this flag is up to the content processor.

Parameters:

b - the new visibility state

clone

public Object clone()
             throws CloneNotSupportedException

Clones this Element, the datasource and the private stylesheet of this Element. The clone does no longer have a parent, as the old parent would not recognize that new object anymore.

Specified by:

clone in interface DataTarget

Overrides:

clone in class Object

Returns:

a clone of this Element.

Throws:

CloneNotSupportedException - should never happen.

derive

public final Element derive()
                     throws CloneNotSupportedException

Throws:

CloneNotSupportedException

derive

public Element derive(boolean preserveElementInstanceIds)
               throws CloneNotSupportedException

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

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

getStyle

public ElementStyleSheet getStyle()

Returns this elements private stylesheet. This sheet can be used to override the default values set in one of the parent-stylesheets.

Specified by:

getStyle in interface ReportElement

Returns:

the Element's stylesheet

getTreeLock

public final Object getTreeLock()

Returns the tree lock object for the self tree. If the element is part of a content hierarchy, the parent's tree lock is returned.

Specified by:

getTreeLock in interface ReportElement

Returns:

the treelock object.

getId

public String getId()

Returns the Xml-ID of this element. This ID is unique within the report-definition, but is not a internal object-instance ID but a user-defined string.

Specified by:

getId in interface ReportElement

Returns:

the element id.

setId

public void setId(String id)

Defines the Xml-ID of this element. This ID is unique within the report-definition, but is not a internal object-instance ID but a user-defined string.

getObjectID

public final InstanceID getObjectID()

Returns a unique identifier for the given instance. The identifier can be used to recognize cloned instance which have the same anchestor. The identifier is unique as long as the element remains in the JVM, it does not guarantee uniqueness or the ability to recognize clones, after the element has been serialized.

Specified by:

getObjectID in interface ReportElement

Returns:

the object identifier.

isDynamicContent

public boolean isDynamicContent()

Checks whether the layout of this element is dynamic and adjusts to the element's printable content. If set to false, the element's minimum-size will be also used as maximum size.

Returns:

true, if the Element's layout is dynamic, false otherwise.

setDynamicContent

public void setDynamicContent(boolean dynamicContent)

Defines the stylesheet property for the dynamic attribute. Calling this function with either parameter will override any previously defined value for the dynamic attribute. The value can no longer be inherited from parent stylesheets.

Parameters:

dynamicContent - the new state of the dynamic flag.

getReportDefinition

public ReportDefinition getReportDefinition()

Returns the currently assigned report definition.

Specified by:

getReportDefinition in interface ReportElement

Returns:

the report definition or null, if no report has been assigned.

setHRefTarget

public void setHRefTarget(String target)

Redefines the link target for this element.

Parameters:

target - the target

getHRefTarget

public String getHRefTarget()

Returns the currently set link target for this element.

Returns:

the link target.

setStyleExpression

public void setStyleExpression(StyleKey property,
                               Expression function)

Adds a function to the report's collection of expressions.

Specified by:

setStyleExpression in interface ReportElement

Parameters:

property - the stylekey that will be modified by this element.

function - the function.

getStyleExpression

public Expression getStyleExpression(StyleKey property)

Returns the expressions for the report.

Specified by:

getStyleExpression in interface ReportElement

Parameters:

property - the stylekey for which an style-expression is returned.

Returns:

the expressions.

getStyleExpressions

public Map getStyleExpressions()

Returns a map of all style expressions attached to this element. The map is keyed by an StyleKey and contains Expression instances.

Specified by:

getStyleExpressions in interface ReportElement

Returns:

the expression.

getDefinitionSource

public org.pentaho.reporting.libraries.resourceloader.ResourceKey getDefinitionSource()

Returns the resource-key of the file that defined this element. This method may return null if the whole report was created in memory.

Returns:

the the definition source.

getContentBase

public org.pentaho.reporting.libraries.resourceloader.ResourceKey getContentBase()

getChangeTracker

public long getChangeTracker()

Returns the element's change-tracker. The changetracker is a version indicator that tracks the number of changes that have been made to an element and makes it easier to implement caching on top of elements or bands. Any change will increase the change-tracker.

Returns:

the element's change tracking number.

See Also:

notifyNodePropertiesChanged(), notifyNodeStructureChanged()

notifyNodePropertiesChanged

public void notifyNodePropertiesChanged()

Notifies the element and any parent element that a property of this element has changed. This notification updates the change tracker.

notifyNodePropertiesChanged

public void notifyNodePropertiesChanged(Object parameter)

notifyNodeChildAdded

public void notifyNodeChildAdded(Object o)

Notifies the element and any parent element that a child node has been added. This notification updates the change tracker.

Parameters:

o - the node that has been added.

notifyNodeChildRemoved

public void notifyNodeChildRemoved(Object o)

Notifies the element and any parent element that a child node has been removed. This notification updates the change tracker.

Parameters:

o - the node that has been removed.

notifyNodeStructureChanged

public void notifyNodeStructureChanged()

Notifies the element and any parent element that the structure of this element has changed in some undisclosed way. This notification updates the change tracker.

toString

public String toString()

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

Overrides:

toString in class Object

Returns:

a string representation of this band.