Package net.sf.jasperreports.engine

Interface JRGenericElement

  • All Superinterfaces:
    java.lang.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 Javascript visualizations 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 Javascript visualizations. 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 Javascript as part of the HTML output. Generic element parameter values would be used to parametrize the resulting Javascript code.
    But generic elements can be placeholders for any kind of special content, not necessarily Javascript visualizations. 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 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

        java.lang.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