Report Filling

Overview

JasperReports Library fills reports into a JasperPrint document. Filling is the process of executing a compiled report with parameters and data to produce this print document. The resulting print document can then be exported by an Exporter to formats such as HTML, PDF, XLSX, and others, or streamed back to the frontend viewer for paged navigation.

In the documentation, this transient operation is described as a run, fill, or on-demand render. The term persistent execution is reserved for the /executions API and the stored print document it manages.

JasperReports Filling Basics

At the JasperReports Library level, the fill APIs primarily work with the following inputs:

• JasperReport or JasperReportSource (required): The compiled report definition
• Parameter values map (required, but may be empty): A mutable map of report parameter values
• Report connection or data source (optional): Either a JDBC Connection or a JRDataSource instance

How ReportShell Executes Reports

ReportShell wraps the JasperReports fill APIs with the ReportExecutionService interface. From the caller’s perspective, only the first two inputs are provided:

• the compiled report (or a descriptor that can be resolved to it), and
• the parameter values map.

Report data sources are resolved automatically as described in Data Sources.

When filling a report, ReportExecutionService receives a ReportOperationContext and creates a ReportFillContext. This fill context contains the resolved JasperReport and the parameter value map (plus additional internal state used during the fill process).

In typical applications you do not call ReportExecutionService or JasperReports fill APIs directly. Instead, you interact with the HTTP/REST endpoints provided by ReportShell (see the persistent executions and render API documentation). Those controllers handle:

• binding and validating request parameters,
• resolving reports,
• running the fill step, and
• optionally persisting the resulting JasperPrint.

The low-level filling concepts on this page are mainly useful when you are extending ReportShell (for example, by adding custom interceptors, listeners or report stores).

Resource Resolution with JasperReportSource

A JR ReportFiller may be configured to use a JasperReportSource that provides a RepositoryResourceContext (optionally with fallback contexts). This context is used to resolve referenced resources such as subreports, images, and other external assets.

A ReportFillInterceptor can configure this JasperReportSource using the ReportDescriptor and JasperReport objects. This is the main extension point for customizing:

• how resources are located (e.g., alternate repositories, multi-tenant paths), and
• how the underlying JasperReports filler is configured.

The framework already configures a default JasperReportSource before calling the interceptors. This default report source is used to create the filler if no interceptor overwrites it.

Note that this report source’s location property might be null if the framework cannot determine the location from where the JasperReport was loaded.

Interceptors and Filler Customization

Before the actual fill happens, ReportShell invokes all registered ReportFillInterceptor beans in order, passing the ReportFillContext to each of them. Interceptors can:

• adjust parameter values or add additional parameters,
• configure the JasperReportSource and resource lookup strategy,
• register a ReportFillerCustomizer to customize the created ReportFiller (for example, attaching listeners or tweaking JasperReports fill settings).

After all interceptors have run, ReportShell creates a ReportFiller and executes the fill to produce a JasperPrint.