Report Resolution

Report Descriptor

ReportShell introduces ReportDescriptor interface representing a report stored in the system. ReportDescriptor contains a Report ID String that identifies the report in the storage.

Services resolve a ReportDescriptor from a ReportStore using a ReportKey, a logical key that uniquely identifies a report.

Report Key

ReportShell web controllers receive a report identifier called as the “report key” either as a URL path variable or as a property/parameter in the request body (JSON or form data). Most controllers support two request mapping variants:

1. /reports/{reportKey}/<action>
2. /<action>/{*reportKey}

The first variant supports single-segment keys (e.g., /reports/123/controls), where the key is a simple unique identifier like a database ID or UUID. The second variant supports multi-segment keys (e.g., /controls/sales/summary), where the key acts as a hierarchical path or slug.

Recent versions of the Spring Framework do not support multi-segment path variables in the middle of a URL pattern. Therefore, a single mapping strategy like /reports/sales/summary/<action> is not feasible out-of-the-box. While you can implement custom mapping strategies or revert to legacy Spring behaviors, those approaches are outside the scope of this documentation.

Upon receiving a request, the system transforms the raw key string into a typed key object for resolving the report with that typed key through a report store.

‘Executable’ Reports

An executable report is a report that is discoverable, executable and exportable by clients through the REST APIs. These are often all reports except the subreports.

ReportDescriptor interface has a isClientExecutable() flag that determines if a report is executable or not. It is the ReportStore that determines whether a ReportDescriptor it returns is executable or not.

The default report store described below determines that based on a report property named reportshell.report.isExecutable. This property takes a boolean value of true or false. If the property is missing, the report is assumed to be NOT executable. You can override this by registering your own ReportStore as a Spring bean.

This is mainly a REST exposure concern rather than a repository-loading concern. A common use case is to keep subreports, shared fragments, or other internal report artifacts resolvable by JasperReports while preventing clients from running them directly through the REST APIs.

The Default Report Store

The default implementation of ReportStore uses JasperReports Library’s RepositoryUtil to load a compiled JasperReport object. It treats the report key (e.g., sales/monthly_summary) as a relative URI and appends the .jasper extension to create the lookup URI.

For this example, final lookup URI becomes sales/monthly_summary.jasper.

RepositoryUtil attempts to find a RepositoryService that can resolve this URI to a JasperReport object. If you haven’t configured any RepositoryService, JasperReports Library’s DefaultRepositoryService is used.

Concurrent Updates

The default store reads serialized .jasper files directly from the disk. As with any system reading serialized objects, non-atomic updates can lead to corruption errors if a file is modified during a read operation. We recommend using atomic file updates (e.g., moving/renaming a new file over the old one) to ensure seamless updates without downtime.

Custom Stores

ReportShell allows you to implement custom ReportStore implementations to load reports from:

• A database
• A remote service
• A custom filesystem structure

If you are using the Spring Boot starter, simply register your custom store implementation as a Spring bean, and it will be detected automatically.

Tip

See custom report store sample application on Github that uses a JPA repository for loading report metadata from a database.