net.sf.jasperreports.engine

Interface JRGenericElement

All Superinterfaces:

Cloneable, JRChild, JRCloneable, JRCommonElement, JRElement, JRIdentifiable, JRPropertiesHolder, JRStyleContainer, JRVisitable

All Known Implementing Classes:

JRBaseGenericElement, JRDesignGenericElement, JRFillGenericElement

public interface JRGenericElement
extends JRElement

A "generic" report element that will produce a generic print element in the generated report.

Generic Elements

Generic report elements are like special placeholders that are put in the report template at report design time, but are dealt with only at export time, when special content is generated for them by the exporter.

A good example of a generic element use case is someone wanting to embed Flash movies in reports exported to HTML format. JasperReports has built-in support for displaying text and images, but there is no built-in element for displaying Flash movies. This person would need to do the following to achieve it:

• A new HTML export handler is developed, bundled into a JAR and deployed in the application. The export handler would be registered with JasperReports for a specific generic element type.
• Optionally, a report custom component is implemented so that report designers would be able to use specialized syntax in JRXMLs. The component implementation would generate a JRGenericPrintElement at fill time.
• Report designers would include either generic report elements or report components (if implemented) in report templates.
• At fill time, generic print elements whose type would match the type for which the export handler was registered would be produced. Report expressions embedded in the design report element are evaluated and the result is included in the produced generic element as parameter values.
• When the report will get exported to HTML, the custom HTML export handler will output HTML snippets that embed Flash movies as part of the HTML output. Generic element parameter values would be used to parametrize the resulting Flash movie.

But generic elements can be placeholders for any kind of special content, not necessarily Flash content. The generic element handler implementation has the freedom to generate any kind of output that can be embedded in the exporter report.

Generic report elements cannot stretch at fill time, they will always produce a print element that has the same size as the design element.

They can be generated in filled reports either by a generic design element, or by custom report components. Generic design elements can be used in simple scenarios in which developing a specialized custom component would not benefit the report design process. A generic design element consists of a generic element type, and a list of element parameters.

Generic Type

The generic element type (see getGenericType()) is a key that identifies a class/type of generic elements which are to be handled uniformly. Such a type is composed of a namespace (usually an URI associated with an organization or a product) and a name.

The generic type is the key used to resolve an export handler for a generic element present in a generated report. Handlers are registered for a specific generic element types, and when a generic element is exported the extensions registry is queried for a generic element handler that has been registered for the element type.

Generic Element Parameters

A generic element can contain one or more arbitrary element parameters. The parameter values are provided by parameter expression when using generic design elements to generate a generic element.

At fill time, expressions associated with the parameters are evaluated and the result is preserved in the print element.

When the generic element is generated by a custom component element, its implementation is responsible for populating the generated element with parameter values.

The parameters are queried by the export element handlers and the values are used to produce the required output in the exported report.

Generic Element Export Handlers

Such a handler is an object responsible for handling generic print elements of a specific type at export time. They usually come in bundles, which are sets generic element export handlers that share the same type namespace.

Generic element handlers are specific to a report exporter. Currently only the HTML exporter features support for generic elements. A generic element handler that would be used for the HTML exporter would implement the GenericElementHtmlHandler interface (which extends the GenericElementHandler interface that is common to all export handlers). Handler bundles are deployed as JasperReports extensions, using GenericElementHandlerBundle as extension type. JasperReports includes DefaultElementHandlerBundle, a convenience handler bundle implementation that wraps a map of handlers per element type and exporter type.

Author:

Lucian Chirita (lucianc@users.sourceforge.net)

See Also:

JRGenericPrintElement, GenericElementHandler, GenericElementHandlerBundle

Method Summary

Methods

Modifier and Type	Method and Description
String	getEvaluationGroupName() Returns the name of the evaluation group for this element.
EvaluationTimeEnum	getEvaluationTimeValue() Returns the evaluation time of this element.
JRGenericElementType	getGenericType() Returns the generic type of this element.
JRGenericElementParameter[]	getParameters() Returns the list of parameters of this element.

Methods inherited from interface net.sf.jasperreports.engine.JRElement

clone, collectExpressions, getElementGroup, getKey, getPositionTypeValue, getPrintWhenExpression, getPrintWhenGroupChanges, getPropertyExpressions, getStretchTypeValue, getX, getY, isPrintInFirstWholeBand, isPrintRepeatedValues, isPrintWhenDetailOverflows, isRemoveLineWhenBlank, setPositionType, setPrintInFirstWholeBand, setPrintRepeatedValues, setPrintWhenDetailOverflows, setRemoveLineWhenBlank, setStretchType, setWidth, setX

Methods inherited from interface net.sf.jasperreports.engine.JRChild

clone

Methods inherited from interface net.sf.jasperreports.engine.JRVisitable

visit

Methods inherited from interface net.sf.jasperreports.engine.JRCloneable

clone

Methods inherited from interface net.sf.jasperreports.engine.JRCommonElement

getBackcolor, getForecolor, getHeight, getModeValue, getOwnBackcolor, getOwnForecolor, getOwnModeValue, getWidth, setBackcolor, setForecolor, setMode

Methods inherited from interface net.sf.jasperreports.engine.JRStyleContainer

getDefaultStyleProvider, getStyle, getStyleNameReference

Methods inherited from interface net.sf.jasperreports.engine.JRPropertiesHolder

getParentProperties, getPropertiesMap, hasProperties

Methods inherited from interface net.sf.jasperreports.engine.JRIdentifiable

getUUID

Method Detail

getGenericType

JRGenericElementType getGenericType()

Returns the generic type of this element. This type will be propagated to the generated print element, and used to resolve export handler for the print element.

Returns:

the generic type of this element

getParameters

JRGenericElementParameter[] getParameters()

Returns the list of parameters of this element.

Returns:

the list of parameters

getEvaluationTimeValue

EvaluationTimeEnum getEvaluationTimeValue()

Returns the evaluation time of this element.

The evaluation time determines the moment at which parameter expressions are evaluated for this element. All parameters will be evaluated at the same moment.

Returns:

the evaluation time of this element

getEvaluationGroupName

String getEvaluationGroupName()

Returns the name of the evaluation group for this element. The evaluation group is only present when the evaluation time is EvaluationTimeEnum.GROUP.

Returns:

the name of the evaluation group for this element