net.sf.jasperreports.engine.JRGenericElement Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jasperreports Show documentation
JasperReports Library
There is a newer version: 7.0.1
/*
 * JasperReports - Free Java Reporting Library.
 * Copyright (C) 2001 - 2023 Cloud Software Group, Inc. All rights reserved.
 * http://www.jaspersoft.com
 *
 * Unless you have purchased a commercial license agreement from Jaspersoft,
 * the following license terms apply:
 *
 * This program is part of JasperReports.
 *
 * JasperReports is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * JasperReports is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with JasperReports. If not, see .
 */
package net.sf.jasperreports.engine;

import net.sf.jasperreports.engine.type.EvaluationTimeEnum;

/**
 * A "generic" report element that will produce a 
 * {@link JRGenericPrintElement 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 {@link net.sf.jasperreports.engine.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 {@link #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
 * {@link net.sf.jasperreports.engine.export.GenericElementHtmlHandler} interface
 * (which extends the
 * {@link net.sf.jasperreports.engine.export.GenericElementHandler} interface that is
 * common to all export handlers).
 * Handler bundles are deployed as JasperReports extensions, using
 * {@link net.sf.jasperreports.engine.export.GenericElementHandlerBundle} as
 * extension type. JasperReports includes
 * {@link net.sf.jasperreports.engine.export.DefaultElementHandlerBundle}, a
 * convenience handler bundle implementation that wraps a map of handlers per element
 * type and exporter type.
 * 
 * @see net.sf.jasperreports.engine.JRGenericPrintElement
 * @see net.sf.jasperreports.engine.export.GenericElementHandler
 * @see net.sf.jasperreports.engine.export.GenericElementHandlerBundle
 * @author Lucian Chirita ([email protected])
 */
public interface JRGenericElement extends JRElement
{

	/**
	 * 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. 
	 * 
	 * @return the generic type of this element
	 */
	JRGenericElementType getGenericType();
	
	/**
	 * Returns the list of parameters of this element.
	 * 
	 * @return the list of parameters 
	 */
	JRGenericElementParameter[] getParameters();
	
	/**
	 * 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.
	 * 
	 * @return the evaluation time of this element
	 */
	EvaluationTimeEnum getEvaluationTimeValue();
	
	/**
	 * Returns the name of the evaluation group for this element.
	 * The evaluation group is only present when
	 * {@link #getEvaluationTimeValue() the evaluation time} is
	 * {@link EvaluationTimeEnum#GROUP}.
	 * 
	 * @return the name of the evaluation group for this element
	 */
	String getEvaluationGroupName();
	
}