User Guide

Introduction

DiF Reports is plug-in for DiF2 that provides integration of a reporting API.
Document generation is a bundled feature in DiF Presentation, and the present module represents an extension to this feature providing JasperReports as another DiF Document generator.

For a full explanation of these concepts and their usage please refer to the generic documentation on the DiF User Guide, in the Documents Section.

Following we will show how to use this module with the above DiF features. We assume that you are familiar with them, and, if not, please read the above documentation section prior to the following sections, for a better understanding of it's instructions.

Usage

For our sample use case we will consider a pre-defined application report that we wish to call on sample web page.
We will have the following application parts to implement:

  • A Stage with the business logic to create the report
  • A View for the stage to render the report
  • A JasperReport report, in it's native jrxml file

Let's build them...

The JasperReports report

This is best accomplished with an UI Report Building tool. There are several. Check out the index page.
After we have a report.jrxml with our report, we add it to our project. Usually in the resources maven folder.

Like this:

|-- src
|   `-- main
|       |-- java
|       |   |-- (...)
|       |-- resources
|       |   |-- modules.properties
|       |   |-- messages
|       |   |   |-- (...)
|       |   `-- templates
|       |       |-- report.jrxml
|       |       |-- arrow.png
|       |       |-- header_logo.png
|       |       `-- header_right.png
|       `-- webapp
|           `-- (...)

Notice the sample image png files in the same dir as the template. These are any files that the report uses toe it's rendering.

With the UI tool you can build and test the report until it is ready. Info on this is beyond this documentation and you should refer to the JasperReports documentation.

The Stage class

This is the main part of our application. Where we call the template report, pass it parameters if we need to and generate it.
Actually the generation of the document is differed to when the user actually presses the link on the stage, bu we will soon get to it.

Let's start with the actual code: (we don't include the full stage source since it is a normal stage with this piece of code in it)

    @OnDocument("report")
    public IDocumentResponse getReport(IDIFContext context) throws HibernateException,
            ReportingException, BusinessException
    {
        DocumentResponseReportImpl response = new DocumentResponseReportImpl("reportFileName");

        Map<String, String> props = new HashMap<String, String>();
        props.put("param1", 1);
        props.put("param2", 2);

        response.getReport().setTemplatePath("templates/report.jrxml");
        response.getReport().setExportFormat(ReportExportFormat.PDF);
        response.getReport().setParameters(props);

        response.getReport().compileReport();
        response.getReport().fillReportFromConnection(getJDBCConnectionToDatabase());

        return response;
    }

The following are the important sections:

  • IDocumentResponse: The bundled interface that states to DiF a generic document response
  • new DocumentResponseReportImpl("reportFileName"): The implementation that uses JasperReports. In the initialization we declare the file name that the downloaded report output file will have.
  • A normal HashMap of parameters that will be passed by name to the report.
  • setTemplatePath("templates/report.jrxml"): The declaration of the template report file.
  • setExportFormat(ReportExportFormat.PDF): Declares the desired output format of the report.
  • compileReport(): Must always call this prior to the first report rendering.
  • fillReportFromConnection(getJDBCConnectionToDatabase()): The report generation, in this case, using a JDBC database connection as it's data source.

The above method creates the document. But when is it called?
We have declared it as an @OnDocument event. So it can be called from the view as we will see next.

Naturally we can also call this method any time we wish to, in our stage. We would then use it's methods to get the result file or output stream of data. But for Web Applications, it is much easier and automated.

The View

The end used layer. Where we will make available to our user the desired document download link.

Like before, let's start from the source code:

<%@ page language="java"%>
<%@ taglib uri="/difcore" prefix="dif"%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
<dif:document templateID="diftemplate">
    <dif:documentGenerator eventID="report" mimetype="pdf" message="Download Report"
        description="This is the monthly expense report for July 2009." />
</dif:document>

As you can see it is very simple. A UI component called documentGenerator has the functionality of creating a link for @OnDocument events.
This is completely integrated with DiF's document feature and automates the calling of the document event method and it's conversion in a specific servlet that returns the generated document byte stream contents.

The user get's a link that will call in a new request our stage and only on this request will the document be generated. This means that we will only generate the document on download request from the user and not on page renderin.

Conclusion

This quick guide is not meant to fully explain this module's features. For this you should analyze the reference Documentation.
Nevertheless you can see here a full explanations on using a standard report which will be the base usage of any report you will need.