SeamFramework.orgCommunity Documentation

Chapter 47. Usage

47.1. Quick Start
47.2. Annotations
47.3. Troubleshooting

47.1. Quick Start

Using Seam Reports is a simple four step process. These steps are the same regardless of the reporting engine being used.

  1. Create a report using a favorite report editor

  2. Load the created report

  3. Fill the report with data

  4. Render the report

Of course some of these steps will have different ways of accomplishing the task, but at a high level they are all the same. For simplicity this quick start will use JasperReports and the first step will be assumed to have already taken place and the report is available in the deployed archive. The location of the report isn't important, the ability to pull it into an InputStream is all that really matters.

The following code demonstrates a basic way of fulfilling the last three steps in using Seam Reports using JasperReports as the reporting engine. The report has already been created and is bundled inside the deployable archive. There are no paramaters for the report. The report is a simple listing of people's names and contact information. 

@Model

public class PersonContactReport {

(1)  @Inject @Resource("WEB-INF/jasperreports/personContact.jrxml")

  private InputStream reportTemplate;


(2)  @Inject @Jasper

  private ReportCompiler reportCompiler;


(3)  @Inject @Jasper @PDF

  private ReportRenderer pdfRenderer;


  @Inject

  private EntityManager em;
       (4)

  public OutputStream render() {

    final Report filledReport = this.fillReport();

    final OutputStream os = new ByteArrayOutputStream();


    this.pdfRenderer.render(filledReport, os);

    return os;

  }
       (5)

  private Report fillReport() {

    final ReportDefinition rd = this.reportCompiler.compile(reportTemplate);

    return rd.fill(this.createDatasource(), Collections.EMPTY_MAP);

  }
       (6)

  private JRDataSource createDatasource() {

    final List<Person> personList = this.em.createQuery("select p from Person", Person.class).getResultList();

    return new JRBeanCollectionDataSource(personList);

  }

}

1

Solder allows easy resource injection for files available in the archive. This injects the report template which has been created previously (perhaps by someone else in the business) and added to the deployable archive.

2

A ReportCompiler is an interface from Seam Reports which abstracts compiling the report template into ReportDefinition. Seam Reports makes use of CDI's type safety features by using qualifiers to further narrow the intended type. This allows programs to remain implementation agnostic. The Jasper qualifier annotation instructs CDI to inject an implementation of the ReportCompiler which contains the same qualifer.

3

This is an instance of using both a qualifer (@Jasper) and also a metadata annotation, which happens to be a stereotype. The @PDF annotation is a CDI stereotype, which essentially means it's a group of other annotations. It carries metadata about the type it is decorating. More about this later.

4

The render method is the only entry point into the class, it also returns the final output of generating a report. It makes use of other methods in the class to finish the steps outlined above to generate a report using Seam Reports.

5

At this stage data to populate the report is retrieved and added to the compiled ReportDefinition. This particular report doesn't make use of any parameters, hence the empty map instance being passed.

6

This last stage of using Seam Reports is the only place that may require the application to use the report engine API. In this example a list of JPA entities is retrieved and added to a JasperReports datasource, which is then used by the calling method to populate the report template as mentioned above.

47.2. Annotations

There are four API level annotations to be aware of when using Seam Reports. All four of them declare metadata about objects that are being injected. They're also all CDI stereotypes which instruct the implementing renderer the mimetype that should be used.

These annotations are only used when injecting a ReportRenderer. Only one of them may be used per renderer. Multiple renderers must be injected if multiple renderering types are desired.

47.3. Troubleshooting