antupdate Ant Update Sample Shows how multiple JRXML files can be updated in batch mode using the ANT build tool. How to update all your JRXML report source files using the Ant build tool, in order to perform the same modification on them or to bring them up-to-date with respect to the JasperReports Schema Reference. 3.7.1 Sanda Zaharia shertage@users.sourceforge.net The Ant Update Task

A problem that may occur in applications with several report templates stored in the same resource repository is the amount of time required to modify each report template individually when the same change has to be applied for all reports. Manual modification is not the best practice in this case, the entire process should be done automatically.
Based on the fact that JRXML templates can be read into JasperDesign objects that can be easily modified and then saved again as JRXML templates, we only need to know where the initial JRXML templates are located, and which changes are to be applied, in order to process a bulk update on all these templates.
A very good tool for operations such as scanning source folders for JRXML templates, triggering methods in java objects and performing batch modifications is the Apache Ant build tool. To accomplish our task described above, we can create an Ant task able to execute all the necessary steps. JasperReports provides the built-in task JRAntUpdateTask for batch-updating JRXML report designs, that:
  • Has to know the location of the source report templates. This location should be passed as a valid org.apache.tools.ant.types.Path object and is mandatory.

  • Has to know where to save the updated report templates. This output directory should be passed as a valid java.io.File object. If not set, the base directory set in the build.xml file will be considered instead.

  • Once the source location and destination folder are specified, the next step is to identify the individual report templates that need to be updated. The source folders are scanned for files with the appropriate .jrxml extension, ready to be updated. The update decision is based on timestamp: only JRXML files that either have no corresponding file in the destination directory, or their corresponding report design destination file is older than the source file, will be updated. They will be also updated if a given ReportUpdater is added to the task.

  • After report templates are identified and loaded into JasperDesign objects, the update operations are applied on each of them, then the modified report designs will be saved in the destination directory.

Report Updaters

Changes can be very easily applied on report designs using specific ReportUpdater implementations. Classes that inherit from the ReportUpdater interface should implement the
method to perform specific modifications on the jasperDesign object. The JRAntUpdateTask accepts any number of report updaters to be added to its updaters list. Update operations will be applied sequential in the same order as the report updaters were added to the list. A small example of report updater implementation can be found in the /src/com/update directory of our sample (see the StyleUpdater java file) sample. This report updater changes the font size, color and weight of the default report style.

The Ant Update Sample

First, let's take a look at how the demo/samples/antupdate sample is structured, to see if this structure is conserved after reports are updated.
The reports directory is the root for the following tree:
One can notice the presence of the ignoreme.txt file in the /reports/com folder. This is not a report template, hence it will be not considered for update.
Both BarReport.jrxml and FooReport.jrxml sources contain a title section with a printWhenExpression:
  • <printWhenExpression><![CDATA[com.bar.SomeBarClass.isToPrint()]]></printWhenExpression> - in BarReport.jrxml
  • <printWhenExpression><![CDATA[com.foo.SomeFooClass.isToPrint()]]></printWhenExpression> - in FooReport.jrxml
The com.bar.SomeBarClass and com.foo.SomeFooClass sources are located in the/src directory as follows:
and the related classes will be saved into the build/classes directory and added to the classpath.

Now let's update these report templates. There are some specific Ant targets declared in the build.xml file: 

  
  
    
  



  
  
  


 
  


 
   
  
    
    
    
  
 


   
  
    
      
        
      
    
    
   
 

 
  



   
  
      
      
  
 

 
   
  
    
  
  
    
    
  
 

 
   
  
    
  
  
    
    
  
 


  



  
  
  
  
  
  

]]>
When update1 target is called, the root directory for the JRXML sources, the destination folder and the source file type (*.jrxml) will be passed as parameters to the updater Ant task. The root source directory will be recursively scanned and any JRXML file in the path will be localized. Other file types (see the ignoreme.txt) will be neglected.
Also notice here the commented line 
com.update.StyleUpdater
-->]]>
that calls the StyleUpdater after source files are scanned. By default, the Ant updater task updates sources based on timestamp differences between source and destination files, or on schema changes. When the <updater> tag is present, the related report updater is also called to perform its specific update operations. In order to see how they act, just uncomment this line and run the sample again. If enabled, the StyleUpdater will modify the report Arial_Normal style attributes for font color (blue: #0000FF), font size (14px) and font weight (bold).

When update2 target is called, sources are passed to the Ant task as file set in the <src> tag. Once again we can see that only *.jrxml files are allowed. This target does not provide an <updater> tag, so only default updates will be performed.
After the batch update the destination folder tree will lokk like this:
Both BarReport.jrxml and FooReport.jrxml are present, but the ignoreme.txt is obviously missing.

If the updated reports have to be also compiled, the <compileUpdated> specific target can be executed to accomplish this need. It will compile all JRXML files found in the destination folder tree. Compiled reports also conserve the tree structure and will be saved in the build/classes directory.

Running the Sample

Running the sample requires the Apache Ant library. Make sure that ant is already installed on your system (version 1.5 or later).
In a command prompt/terminal window set the current folder to demo/samples/antupdate within the JasperReports source project and run the > ant test command.
It will generate updated reports in the demo/samples/antupdate/build/reports directory. Compare the updated JRXMLs with the original ones. Notice the replacement of the <DOCTYPE ...> line with schema informations added to the report. Also the title band comes with the splitType attribute and report elements provide the uuid atribute. The deprecated border attribute was replaced by the pen element. All these represent changes applied by default in order to get up-to-date report designs, in accordance with the current JasperReports schema.
Then uncomment the line 
com.update.StyleUpdater
-->]]>
in the update1 target and run again the > ant test command. The build directory will be cleaned up, then the update1 target will be executed. The updated JRXMLs will be saved in the destination folder. Then the update2 target will be executed, but because there are no newer default updates to be performed, this target will do nothing. It won't override changes performed by the update1 target. When opening the updated JRXMLs we'll see that style modifications introduced by the update1 task are still present after the consequent execution of update2.

To have updated AND compiled reports in the destination folder, just run the run the > ant test compileUpdated command. The compiled *.jasper reports will be available in the demo/samples/antupdate/build/classes directory.