Package net.sf.jasperreports.ant

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 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 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 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 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 JRXmlLoader or JRLoader and the JRXmlWriter.
This operation can be automated for any number of files using the Ant report update task provided by the JasperReports library in the 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: