<?xml version="1.0" encoding="UTF-8"?>

<sample>

  <name>antcompile</name>
  <title>Ant Compile Sample</title>
  <description>Shows how multiple JRXML files can be compiled in batch mode using the ANT build tool.</description>

  <mainFeature ref="antcompile"/>
  <mainFeature ref="antdecompile"/>
  <secondaryFeature name="reportcompilers" sample="groovy" title="Report Compilers"/>
  
  <!-- antcompile -->
  
  <feature name="antcompile" title="Compiling Multiple Report Template Files Using the Ant Build Tool">
    <description>
How to compile all your JRXML report source files at application build time using the Ant build tool.
    </description>
    <since>0.4.6</since>
    <documentedBy>
      <author>
    	<name>Teodor Danciu</name>
    	<email>teodord@users.sourceforge.net</email>
      </author>
    </documentedBy>
  	<otherSample ref="groovy"/>
  	<otherSample ref="java1.5"/>
  	<otherSample ref="javascript"/>
    <content>
The JRXML files represent the source files for static report templates. These report templates need to be 
prepared for use at runtime by compiling them into <code>*.jasper</code> files, which are basically serialized 
<api href="net/sf/jasperreports/engine/JasperReport.html">JasperReport</api> objects, ready for filling with data.
<br/>
<br/>
Report template source files having the <code>*.jrxml</code> file extensions are compiled into serialized object files 
having the <code>*.jasper</code> file extension, just like Java source files having the <code>*.java</code> file extension 
are transformed into Java bytecode binary files with the <code>*.class</code> file extension.
<br/>
The transformation of <code>*.jrxml</code> files into <code>*.jasper</code> files should be part of the application 
build process, just as the compilation of <code>*.java</code> files into <code>*.class</code> files is.
In the majority of cases, when the report templates are static and do not change at runtime (only data feed into them changes), 
there is no point in deploying source JRXML files  with the application.
<br/>
After all, when deploying a Java application, you deploy <code>*.class</code> files, packaged up in JARs, not source <code>*.java</code> files. 
The same technique is applicable to JR report template files, where compiled <code>*.jasper</code> files should be created 
at application built time and then deployed as part of the application classpath as resources.
<br/>
<br/>
The JasperReports library provides a built-in Ant task for compiling source JRXML report template files into <code>*.jasper</code> files. 
This task is represented by the <api href="net/sf/jasperreports/ant/JRAntCompileTask.html">JRAntCompileTask</api> task and 
works very similar to the Ant built-in <a href="http://ant.apache.org/manual/Tasks/javac.html">Javac</a> task.
<br/>
<br/>
This task scans source folders and looks up for report template files (usually having the JRXML file extension) 
and compiles them into <code>*.jasper</code> files which are placed into a destination folder hierarchy.
<br/>
The destination folder tree is similar to the source folder tree, meaning that the relative location of source files from 
the root source folder is preserved for the resulting <code>*.jasper</code> files.
<br/>
<br/>
Similar to the <code>Javac</code> task, the source folders can be specified using either the <code>srcdir</code> attribute 
of the task (when there is only one root source folder) or using a nested <code>&lt;src&gt;</code> tag (when source files 
are scattered across multiple paths).
<!--
<br/>
<br/>
Note that before JR 3.7.1, using a nested <code>&lt;src&gt;</code> tag to specify the source folders caused the compiled report 
templates to be placed flattened into the destination folder, losing the source file folder hierarchy. This was fixed in JR 3.7.1.
-->
<br/>
<br/>
Open the <code>build.xml</code> file in the current sample and notice how the custom Ant task called <code>jrc</code> is defined:
<br/>
<br/>
<pre><![CDATA[
<taskdef name="jrc" classname="net.sf.jasperreports.ant.JRAntCompileTask"> 
  <classpath refid="classpath"/>
</taskdef>
]]>
</pre>
This task definition uses a <code>&lt;classpath&gt;</code> element which contains the JasperReports JAR and all its required dependencies.
<br/>
<br/>
Then, the custom <code>jrc</code> task is used to compile report templates having the <code>*.jrxml</code> file extension found under 
the sample's <code>reports</code> folder. This source folder is specified using the <code>srcdir</code> attribute of the <code>jrc</code> task 
in the <code>compile1</code> target of the <code>build.xml</code> file:
<br/>
<br/>
<pre><![CDATA[
<target name="compile1"> 
  <mkdir dir="./build/reports"/> 
  <jrc 
    srcdir="./reports"
    destdir="./build/reports"
    tempdir="./build/reports"
    keepjava="true"
    xmlvalidation="true">
   <classpath refid="runClasspath"/>
   <include name="**/*.jrxml"/>
  </jrc>
</target> 
]]>
</pre>
The <code>compile2</code> target in the same <code>build.xml</code> file performs the same report compilation process, 
but the source folder is specified using a nested <code>&lt;src&gt;</code> tag with filesets. The nested source tag allows compiling report 
templates that are scattered through many different locations and are not grouped under a single root report source folder.
<br/>
<br/>
<pre><![CDATA[
<target name="compile2">
  <mkdir dir="./build/reports"/> 
  <jrc 
    destdir="./build/reports"
    tempdir="./build/reports"
    keepjava="true"
    xmlvalidation="true">
   <src>
    <fileset dir="./reports">
     <include name="**/*.jrxml"/>
    </fileset>
   </src>
   <classpath refid="runClasspath"/>
  </jrc> 
</target> 
]]>
</pre>
Notice that both report compilation targets have a <code>&lt;classpath&gt;</code> nested element, used to specify the classpath used by the report 
compiler. This so called run-classpath contains classes that are referenced inside the report templates themselves, such as scriptlet classes, 
chart customizers and so forth.
<br/>
In this particular sample, both source JRXML files make use of such helper classes found in the <code>src</code> folder of the samples. 
These helper classes have to be compiled before the report templates are compiled, using the <code>javac</code> target of the <code>build.xml</code> file.
<br/>
<br/>
In addition to the <code>srcdir</code> and the <code>destdir</code> attributes, the <code>jrc</code> custom Ant task shipped with JasperReports 
supports the following attributes:
<br/>
<br/>
<ul>
<li><code>compiler</code> : Name of the class that implements the <api href="net/sf/jasperreports/engine/design/JRCompiler.html">JRCompiler</api> interface to be used for compiling the reports (optional).</li>
<li><code>xmlvalidation</code> : Flag to indicate whether the XML validation should be performed on the source report template files (<code>true</code> by default).</li>
<li><code>tempdir</code> : Location to store the temporarily generated files (the current working directory by default).</li>
<li><code>keepjava</code> : Flag to indicate if the temporary Java files generated on the fly should be kept and not deleted automatically (<code>false</code> by default).</li>
</ul>
<br/>
<br/>
In our sample, we use the default report compiler, which is the JDT-based compiler, because the JDT JAR is found in the classpath. 
This compiler works on the assumption that report expressions are Java expressions and thus it produces a Java class file dynamically containing 
all the report expressions and compiles it using the JDT Java compiler. Normally, this report compiler does all the Java class file generation 
and compilation in-memory and does not work with actual files on disk, which makes it very flexible and easy to deploy in all environments. 
However, if the <code>keepjava</code> flag is turned to <code>true</code>, it will save the report's temporary Java source file on disk, 
in the specified <code>tempdir</code>. This is useful for debugging report expressions in certain cases.
<br/>
<br/>
Depending on the report expression language they are mapped to, other report compiler implementations might produce script files instead of Java files, 
for report expression evaluation. The <code>keepjava</code> and the <code>tempdir</code> attributes will still work for them, except that the files 
that will be kept into the temporary location will not be Java source files but script files, also helpful for debugging.
    </content>
  </feature>

  <!-- antdecompile -->
  
  <feature name="antdecompile" title="Generating the JRXML Source Files for Multiple Compiled Report Template Files Using the Ant Build Tool (Decompiling)">
    <description>
How to re-create the JRXML source files for multiple compiled report templates using the Ant build tool. 
This is useful in cases where only the compiled <code>*.jasper</code> files of older reports are available, 
the initial <code>*.jrxml</code> source files being lost.
    </description>
    <since>3.7.1</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
    <content>
In the case the older reports JRXML templates are lost, but we still have acces to their <code>*.jasper</code> compiled state, there is a 
possibility to retrieve the related JRXML, based on a specific built-in Ant task.
This task provided by the JasperReports library is used for decompiling JasperReport objects serialized as <code>*.jasper</code> files. 
Its functionality is defined in the <api href="net/sf/jasperreports/ant/JRAntDecompileTask.html">JRAntDecompileTask</api> class and 
works as opposite to the Ant built-in <api href="net/sf/jasperreports/ant/JRAntCompileTask.html">JRAntCompileTask</api> task described 
<a href="#antcompile">above</a>.
<br/>
This task scans source folders and looks up for <code>*.jasper</code> files, load them into in-memory JasperReport objects,  
then write their report template source into corresponding <code>*.jrxml</code> files, placed into a destination folder hierarchy.
<br/>
The destination folder tree is similar to the source folder tree, meaning that the relative location of <code>*.jasper</code> files from 
the root folder is preserved for the resulting <code>*.jrxml</code> files.
<br/>
Similar to the <api href="net/sf/jasperreports/ant/JRAntCompileTask.html">JRAntCompileTask</api> task, the source folders can be specified 
using either the <code>srcdir</code> attribute of the task (when there is only one root source folder) or using a nested <code>&lt;src&gt;</code> 
tag (when source <code>*.jasper</code> files are scattered across multiple paths).
<br/>
Below is the <code>decompile</code> task definition in the build.xml file:
<pre><![CDATA[
<target name="decompile" description="Decompiles report designs specified using a &lt;fileset&gt; in the &lt;src&gt; tag.">
  <taskdef name="jrdc" classname="net.sf.jasperreports.ant.JRAntDecompileTask"> 
    <classpath refid="classpath"/>
  </taskdef>
  <jrdc destdir="./build/reports">
    <src>
      <fileset dir="./build/reports">
        <include name="**/*.jasper"/>
      </fileset>
    </src>
    <classpath refid="runClasspath"/>
  </jrdc> 
</target>]]></pre>
<b>The JRXML Writer Tool</b>
<br/>
<br/>
Once loaded from their serialized form, the JasperReport objects are passed one by one to the JRXML writer tool represented by the 
<api href="net/sf/jasperreports/engine/xml/JRXmlWriter.html">JRXmlWriter</api> class. Let's see how is it done in the 
<api href="net/sf/jasperreports/ant/JRAntDecompileTask.html">JRAntDecompileTask</api> <code>decompile()</code> method:
<pre><![CDATA[
protected void decompile() throws BuildException
{
  Collection<String> files = reportFilesMap.keySet();
  if (files != null && files.size() > 0)
  {
    boolean isError = false;
    System.out.println("Decompiling " + files.size() + " report design files.");
    for (Iterator<String> it = files.iterator(); it.hasNext();)
    {
      String srcFileName = it.next();
      String destFileName = reportFilesMap.get(srcFileName);
      File destFileParent = new File(destFileName).getParentFile();
      if(!destFileParent.exists())
      {
        destFileParent.mkdirs();
      }
      try
      {
        System.out.print("File : " + srcFileName + " ... ");
        JasperReport jasperReport = (JasperReport)JRLoader.loadObjectFromFile(srcFileName);
        new JRXmlWriter(jasperReportsContext).write(jasperReport, destFileName, "UTF-8");
        System.out.println("OK.");
      }
      catch(JRException e)
      {
        System.out.println("FAILED.");
        System.out.println("Error decompiling report design : " + srcFileName);
        e.printStackTrace(System.out);
        isError = true;
      }
    }
    if(isError)
    {
      throw new BuildException("Errors were encountered when decompiling report designs.");
    }
  }
}]]></pre>
The <api href="net/sf/jasperreports/engine/xml/JRXmlWriter.html">JRXmlWriter</api> reads the report template structure from the 
JasperReport object and write it down in a JRXML file:
<pre><![CDATA[
new JRXmlWriter(jasperReportsContext).write(jasperReport, destFileName, "UTF-8");]]></pre>
Below we can see how the method write(...) in the <api href="net/sf/jasperreports/engine/xml/JRXmlWriter.html">JRXmlWriter</api> looks like:
<pre><![CDATA[
public void write(
    JRReport report,
    String destFileName,
    String encoding
    ) throws JRException
{
  FileOutputStream fos = null;

  try
  {
    fos = new FileOutputStream(destFileName);
    Writer out = new OutputStreamWriter(fos, encoding);
    writeReport(report, encoding, out);
  }
  catch (IOException e)
  {
    throw new JRException("Error writing to file : " + destFileName, e);
  }
  finally
  {
    if (fos != null)
    {
      try
      {
        fos.close();
      }
      catch(IOException e)
      {
      }
    }
  }
}]]></pre>
The <api href="net/sf/jasperreports/engine/xml/JRXmlWriter.html">JRXmlWriter</api> tool provides dedicated methods for writing the report prologue,
report properties, styles, datasets, sections and elements.
<br/>
To see the effective result of the <code>decompile</code> task, just run the <code>'&gt;ant clean javac compile1 decompile'</code> 
command in the root directory of the sample. You will see in the <code>build/reports/com/bar</code> and <code>build/reports/com/foo</code> 
output directories both the compiled <code>*.jasper</code> and the decompiled <code>*.jrxml</code> files.
    </content>
  </feature>

</sample>
