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

java.lang.Object
  extended by 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.