net.sf.jasperreports.ant.package-info Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of jasperreports Show documentation
Free Java Reporting Library
There is a newer version: 6.21.3
/*
 * JasperReports - Free Java Reporting Library.
 * Copyright (C) 2001 - 2022 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 .
 */

/**
* Provides Ant task classes for batch-processing report files.
* 

* Ant Tasks
* When the number of different report files that one has to deal with in a project is 
* significant, there is a need for automating repeating or re-occurring tasks that are to be 
* performed on those files. 
* 

* From a design point of view, the most notable operation that needs to be performed on 
* report source files after they are finished and ready to be deployed is the report 
* compilation. Sometimes reports need to be decompiled in order to reproduce their 
* corresponding source files and perform additional design work on them, or when the 
* same modification needs to be performed identically on all reports. 
* 

* For these re-occurring tasks, JasperReports provides built-in ready-to-use Ant task 
* definitions, based on the {@link net.sf.jasperreports.ant.JRBaseAntTask JRBaseAntTask} class.
* 

* Ant Task for Compiling Reports
* Since report template compilation is more like a design-time job than a runtime one, a 
* custom Ant task has been provided with the library to simplify application development. 
* 

* This Ant task is implemented by the {@link net.sf.jasperreports.ant.JRAntCompileTask JRAntCompileTask} class. Its syntax and behavior are 
* very similar to the built-in <javac> Ant task. 
* 

* The report template compilation task can be declared like this, in a project's build.xml 
* file: 
* * <taskdef name="jrc" 
* classname="net.sf.jasperreports.ant.JRAntCompileTask"> 
*   <classpath> 
*     <fileset dir="./lib"> 
*       <include name="** /*.jar"/> 
*     </fileset> 
*   </classpath> 
* </taskdef> 
* 
* In the preceding example, the lib folder should contain the jasperreports-x.x.x.jar file 
* along with its other required libraries. 
* 

* You can then use this user-defined Ant task to compile multiple JRXML report template 
* files in a single operation by specifying the root directory that contains those files or by 
* selecting them using file patterns. 
* 

* Attributes of the Report Compilation Task
* Following is the list of attributes that can be used inside the Ant report compilation task 
* to specify the source files, the destination directory, and other configuration properties:
* 
* srcdir: Location of the JRXML report template files to be compiled. Required unless nested <src> elements are present.
* destdir: Location to store the compiled report template files (the same as the source directory by default).
* compiler: Name of the class that implements the {@link net.sf.jasperreports.engine.design.JRCompiler JRCompiler} interface to be used for compiling the reports (optional).
* xmlvalidation: Flag to indicate whether the XML validation should be performed on the source report template files (true by default).
* tempdir: Location to store the temporarily generated files (the current working directory by default).
* keepjava: Flag to indicate if the temporary Java files generated on the fly should be kept and not deleted automatically (false by default).
* 
* The report template compilation task supports nested <src> and <classpath> 
* elements, just like the Ant <javac> built-in task.
* 

* Ant Task for Decompiling Reports
* Sometimes it happens that report templates are to be found only in their compiled form. 
* 

* The source report template files might have been lost and we might have only the 
* compiled report template on which we need to make some modifications. 
* 

* In such cases, the Ant task for decompiling report template files that JasperReports 
* provides becomes very handy. It is implemented by the {@link net.sf.jasperreports.ant.JRAntDecompileTask JRAntDecompileTask} class and its declaration inside a 
* build.xml file should be as follows:
*  
* <taskdef name="jrdc" 
* classname="net.sf.jasperreports.ant.JRAntDecompileTask"> 
*   <classpath refid="classpath"/> 
* </taskdef>
* 
* In the above example, the classpath should contain the jasperreports-x.x.x.jar file along with its other required 
* libraries. 
* 

* This task works similarly to the report compilation task, but it does the reverse operation. 
* The files to be decompiled can be specified using the srcdir attribute for their root 
* folder or, for more sophisticated file match patterns, a nested <src> tag. The output 
* folder for the generated files is specified using the destdir attribute. 
* 

* Ant Task for Updating Reports
* Although JasperReports always guarantees backward compatibility of report templates 
* when upgrading to a newer version, sometimes tags or attributes in JRXML are 
* deprecated and replaced with newer ones that offer enhanced capabilities. So while the 
* deprecated attributes and tags still work, it is always advisable to use the latest syntax 
* and thus get rid of the deprecation warnings. 
* 

* Upgrading a report template to the latest JasperReports syntax is very easy; all that needs 
* to be done is to load the report and save it again using the API's utility classes, such as 
* the {@link net.sf.jasperreports.engine.xml.JRXmlLoader JRXmlLoader} or {@link net.sf.jasperreports.engine.util.JRLoader JRLoader} 
* and the {@link net.sf.jasperreports.engine.xml.JRXmlWriter JRXmlWriter}. 
* 

* This operation can be automated for any number of files using the Ant report update task 
* provided by the JasperReports library in the 
* {@link net.sf.jasperreports.ant.JRAntUpdateTask JRAntUpdateTask} class, which should have the 
* following definition in a build.xml file: 
* * <taskdef name="jru" 
* classname="net.sf.jasperreports.ant.JRAntUpdateTask"> 
*   <classpath refid="classpath"/> 
* </taskdef>
*  
* This task is useful also in situations where the same modification needs to be applied on 
* a number of different report files. The required modifications can be performed using the 
* JasperReport API after the report design object has been loaded but before it is saved 
* again. 
* 

* Related documentation:
* 
* Apache Ant Manual
* 
* 
*/
package net.sf.jasperreports.ant;