• The table of content structure was configured in a subreport. See the reports/HeadingsReport.jrxml file for layout details. It is based on local anchor hyperlinks with different levels of indentation, depending on the heading type. Notice the presence of the invisible element labeled "HIDDEN TEXT TO MARK THE BEGINNING OF THE TABLE OF CONTENTS" in the title section. It will be used to identify the first page of the table of contents in the generated document.
  
  
• A HeadingBean class (see the src/HeadingBean.java file) was created in order to store the meaningful information of individual entries in the table of contents. A HeadingBean object exposes the following bean properties:
  • headingType - an integer that indicates the heading type of the entry.
  • headingText - the text to be written in the table of contents for this entry.
  • reference - the hyperlink reference associated with the entry.
  • pageIndex - the page index to be associated with this entry in the table of contents.
  During the report filling a JRBeanCollectionDataSource will be populated with HeadingBean object. The mechanism used to populate it is an inventive combination between report scriptlets and printWhenExpressions, as we'll see in a while. The bean collection will be passed as data source parameter to the HeadingsReport subreport placed in the summary section. At that moment the collection data source will be entirely complete and ready to be used.
  
  
• Every time the addHeading(String ) method in the HeadingsScriptlet class is called, a new member is added to the bean collection data source described above. So, we have to ensure that the method is called any time a heading element is met in the document. This is done using an interesting condition in printWhenExpressions in the master report (see the reports/TableOfContentsReport.jrxml file):

  <group name="FirstLetterGroup" minHeightToStartNewPage="60">
    ...
    <groupHeader>
    <band height="25">
      <line>
        <reportElement x="0" y="0" width="1" height="1">
          <printWhenExpression>
            <![CDATA[((HeadingsScriptlet)$P{REPORT_SCRIPTLET}).addHeading("FirstLetterGroup")]] ></printWhenExpression>
        </reportElement>
        <graphicElement/>
      </line>
      ...
      <textField>
        <reportElement mode="Opaque" x="190" y="10" width="325" height="15" backcolor="#c0c0c0" style="Sans_Bold"/>
        <textFieldExpression class="java.lang.String"><![CDATA[$V{FirstLetter}]] ></textFieldExpression>
        <anchorNameExpression><![CDATA["FirstLetterGroup_" + $V{FirstLetter}]] ></anchorNameExpression>
      </textField>
    </band>
    </groupHeader>
  </group>
  <group name="ShipCountryGroup" minHeightToStartNewPage="60">
    ...
    <groupHeader>
    <band height="20">
      <line>
        <reportElement x="0" y="0" width="1" height="1">
          <printWhenExpression>
            <![CDATA[((HeadingsScriptlet)$P{REPORT_SCRIPTLET}).addHeading("ShipCountryGroup")]] >
          </printWhenExpression>
        </reportElement>
        <graphicElement/>
      </line>
      ...
      <textField>
        <reportElement x="0" y="4" width="515" height="15" style="Sans_Bold"/>
        <textFieldExpression class="java.lang.String">
          <![CDATA["  " + String.valueOf($V{ShipCountryNumber}) + ". " + String.valueOf($F{ShipCountry})]] >
        </textFieldExpression>
        <anchorNameExpression><![CDATA["ShipCountryGroup_" + $V{ShipCountryNumber}]] ></anchorNameExpression>
      </textField>
    </band>
    </groupHeader>
    ...
  </group>

  One can see a similar construction present in both group headers of the report: a line with a printWhenExpression and a textfield with an anchorNameExpression. The addHeading(...) method called in the printWhenExpression populates the data source and always returns false. That means the line element never gets printed, being used only for calling the scriptlet method.
  But the related textfield will be printed and will be marked with the same anchor name as that one built in the reference field of the corresponding HeadingBean object. In the final document, clicking on any entry in the table of contents will send to the bookmarked element in the document.
  
  
• If the document would require a table of contents placed at the end, all the work would stop here. There would be nothing else to do. But in this sample is assumed that the table of contents is needed at the beginning of the document, hence an additional step is required. After filling the JasperPrint object, one can iterate through its pages and elements. We have to identify the pages containing the table of contents, to cut and move them at the beginning of the document. That's what the moveTableOfContents(JasperPrint) method in the src/TableOfContentsApp.java is doing. The method is called at fill time after the JasperPrint object was generated.

public void fill() throws JRException
{
  long start = System.currentTimeMillis();
  //Preparing parameters
  Map parameters = new HashMap();
  parameters.put("ReportTitle", "Orders Report");

  SimpleFileResolver fileResolver =
    new SimpleFileResolver(
      Arrays.asList(new File[]{new File("build/reports")})
      );
  fileResolver.setResolveAbsolutePath(true);
  
  parameters.put(JRParameter.REPORT_FILE_RESOLVER, fileResolver);
  
  JasperReport jasperReport = (JasperReport)JRLoader.loadObject("build/reports/TableOfContentsReport.jasper");

  JasperPrint jasperPrint = JasperFillManager.fillReport(jasperReport, parameters, getDemoHsqldbConnection());
  
  jasperPrint = moveTableOfContents(jasperPrint);

  JRSaver.saveObject(jasperPrint, "build/reports/TableOfContentsReport.jrprint");

  System.err.println("Filling time : " + (System.currentTimeMillis() - start));
}