net.sf.jasperreports.engine.design.JRCompiler Maven / Gradle / Ivy
/*
* JasperReports - Free Java Reporting Library.
* Copyright (C) 2001 - 2019 TIBCO Software 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
* Source report templates, created either by using the API or by parsing JRXML files, are
* subject to the report compilation process before they are filled with data.
* This is necessary to make various consistency validations and to incorporate into these
* report templates data used to evaluate all report expressions at runtime.
*
* The compilation process transforms
* {@link net.sf.jasperreports.engine.design.JasperDesign} objects into
* {@link net.sf.jasperreports.engine.JasperReport} objects. Both classes are
* implementations of the same basic {@link net.sf.jasperreports.engine.JRReport}
* interface. However, {@link net.sf.jasperreports.engine.JasperReport} objects
* cannot be modified once they are produced,
* while {@link net.sf.jasperreports.engine.design.JasperDesign} objects can.
* This is because some modifications made on the
* report template would probably require re-validation, or if a report expression is
* modified, the compiler-associated data stored inside the report template would have to be
* updated.
*
* {@link net.sf.jasperreports.engine.design.JasperDesign} objects are produced when parsing JRXML files using the
* {@link net.sf.jasperreports.engine.xml.JRXmlLoader} or created directly by the parent
* application if dynamic report templates are required. The GUI tools for editing
* JasperReports templates also work with this class to make in-memory modifications to
* the report templates before storing them on disk.
*
* A {@link net.sf.jasperreports.engine.design.JasperDesign} object must be
* subject to the report compilation process to produce a
* {@link net.sf.jasperreports.engine.JasperReport} object.
*
* Central to this process is this {@link net.sf.jasperreports.engine.design.JRCompiler}
* interface, which defines few methods, one being the following:
*
* public JasperReport compileReport(JasperDesign design) throws JRException;
*
* There are several implementations for this compiler interface depending on the language
* used for the report expressions or the mechanism used for their runtime evaluation.
*
* Expressions Scripting Language
* The default language for the report expressions is Java, but report expressions
* can be written in Groovy, JavaScript or any other scripting language as long as a report
* compiler implementation that can evaluate them at runtime is available.
*
* JasperReports currently ships report compiler implementations for the Groovy scripting
* language (http://groovy.codehaus.org) and
* JavaScript (http://www.mozilla.org/rhino).
* The related compiler implementation classes are:
*
* - {@link net.sf.jasperreports.compilers.JRGroovyCompiler}
* - {@link net.sf.jasperreports.compilers.JavaScriptCompiler}
*
*
* Since the most common scenario is to use the Java language for writing report
* expressions, default implementations of the report compiler interface are shipped with
* the library and are ready to use. They generate a Java class from the report expressions
* and store bytecode in the generated {@link net.sf.jasperreports.engine.JasperReport}
* object for use at report-filling time.
* Java Compilers
* The Java report compilers come in different flavors depending on the Java compiler used
* to compile the class that is generated on the fly:
*
* - {@link net.sf.jasperreports.engine.design.JRJdtCompiler}
* - {@link net.sf.jasperreports.engine.design.JRJdk13Compiler}
* - {@link net.sf.jasperreports.engine.design.JRJavacCompiler}
*
* @see net.sf.jasperreports.engine.JasperReport
* @see net.sf.jasperreports.engine.design.JasperDesign
* @see net.sf.jasperreports.engine.xml.JRXmlLoader
* @author Teodor Danciu ([email protected])
*/
public interface JRCompiler
{
/**
* The name of the class to be used for report compilation.
*
* No default value.
*
* @deprecated Replaced by {@link net.sf.jasperreports.engine.design.JRCompiler#COMPILER_PREFIX}.
*/
public static final String COMPILER_CLASS = JRPropertiesUtil.PROPERTY_PREFIX + "compiler.class";
/**
* Prefix for properties that map report compilers to expression languages.
*
* Properties having this prefix are used to indicate the JRCompiler implementation to be used when compiling
* report designs that rely on the expression language specified as property suffix.
*/
@Property(
name = "net.sf.jasperreports.compiler.{language}",
category = PropertyConstants.CATEGORY_COMPILE,
scopes = {PropertyScope.CONTEXT},
sinceVersion = PropertyConstants.VERSION_2_0_1
)
public static final String COMPILER_PREFIX = JRPropertiesUtil.PROPERTY_PREFIX + "compiler.";
/**
* Whether to keep the java file generated when the report is compiled.
*
* Defaults to false.
*/
@Property(
category = PropertyConstants.CATEGORY_COMPILE,
defaultValue = PropertyConstants.BOOLEAN_FALSE,
scopes = {PropertyScope.CONTEXT},
sinceVersion = PropertyConstants.VERSION_1_0_0,
valueType = Boolean.class
)
public static final String COMPILER_KEEP_JAVA_FILE = JRPropertiesUtil.PROPERTY_PREFIX + "compiler.keep.java.file";
/**
* The temporary directory used by the report compiler.
*
* Defaults to System.getProperty("user.dir").
*/
@Property(
category = PropertyConstants.CATEGORY_COMPILE,
defaultValue = "System.getProperty(\"user.dir\")",
scopes = {PropertyScope.CONTEXT},
sinceVersion = PropertyConstants.VERSION_1_0_0
)
public static final String COMPILER_TEMP_DIR = JRPropertiesUtil.PROPERTY_PREFIX + "compiler.temp.dir";
/**
* The classpath used by the report compiler.
*
* Defaults to System.getProperty("java.class.path").
*/
@Property(
category = PropertyConstants.CATEGORY_COMPILE,
scopes = {PropertyScope.CONTEXT},
defaultValue = "System.getProperty(\"java.class.path\")",
sinceVersion = PropertyConstants.VERSION_1_0_0
)
public static final String COMPILER_CLASSPATH = JRPropertiesUtil.PROPERTY_PREFIX + "compiler.classpath";
/**
* Compiles a report design.
*
* The compilation consists of verification of the design, generation of expression evaluators
* and construction of a serializable read-only version of the report.
*
* A report compiler should usually extend {@link JRAbstractCompiler JRAbstractCompiler}.
*
*
* @param jasperDesign the report design
* @return the compiled report
* @throws JRException
*/
public JasperReport compileReport(JasperDesign jasperDesign) throws JRException;
/**
* Loads the evaluator for a report's main dataset.
*
* @param jasperReport the report
* @return the evaluator for the report's main dataset
* @throws JRException
*/
public JREvaluator loadEvaluator(JasperReport jasperReport) throws JRException;
/**
* Loads a expression evaluator class for a dataset of a report.
*
* @param jasperReport the report
* @param dataset the dataset
* @return an instance of the dataset evaluator class
* @throws JRException
*/
public JREvaluator loadEvaluator(JasperReport jasperReport, JRDataset dataset) throws JRException;
/**
* Loads a expression evaluator class for a crosstab of a report.
*
* @param jasperReport the report
* @param crosstab the crosstab
* @return an instance of the dataset evaluator class
* @throws JRException
*/
public JREvaluator loadEvaluator(JasperReport jasperReport, JRCrosstab crosstab) throws JRException;
}