Report Viewer Controller

ReportShell automatically registers a Spring MVC controller that serves an interactive React Viewer page for a requested report, letting end users run it with parameters, preview the output, and export it to any supported format. The controller handles report loading, authorization, and parameter binding, and supplies the global settings and mount props the viewer needs.

Auto-Configuration

The ReportViewerController is automatically registered as a Spring bean when you include the ReportShell Spring Boot starter in your application. It’s configured through the ReportShellMvcControllersAutoConfiguration class.

Default Mapping

The controller is mapped to /view/{*reportKey} where reportKey is the path-style identifier for your report.

Example URLs:

• /view/customers - Renders the “customers” report
• /view/sales/monthly - Renders the report identified by the “sales/monthly” path to be handled by a supporting store.

View Template

The controller returns a Spring MVC view name that defaults to reportshell/viewer. This view name is resolved by your configured view resolver (e.g. Thymeleaf).

View Model

The controller populates the Spring MVC Model with two attributes:

• viewerEnv: An object containing properties for initializing the global viewer environment
• viewerProps: An object containing properties for mounting a report viewer instance

viewerEnv attribute is an instance of ViewerEnvironment type with the following properties:

Attribute	Type	Description
report	ReportDescriptor	The loaded report metadata
exportFormats	List<FormatMetadata>	Export format metadata list for all registered exporters each entry with the ID, extension and the display name of the export format
locale	Locale	Effective viewer locale, resolved from ReportShellSettings.locale or Locale.getDefault()
userLocale	Locale	Effective user locale, resolved from request.locale, ReportShellSettings.locale or Locale.getDefault()
localeDetails	Map<String, String>	locale split into a map of its language, country, script and variant parts
userLocaleDetails	Map<String, String>	userLocale split into a map of its language, country, script and variant parts
timeZone	String	Effective viewer time zone ID, resolved from ReportShellSettings.timeZone or TimeZone.getDefault().id

viewerProps attribute is documented on the React Viewer page. The controller is responsible for preparing that properties object and forwarding it to mountReportViewer(...).

The viewerEnv.exportFormats model attribute is separate from viewerProps.exportFormats:

• viewerEnv.exportFormats contains UI metadata objects for the global config
• viewerProps.exportFormats contains the enabled format ids for the mounted viewer instance

Locale Resolution

The controller resolves the effective viewer locale as follows:

1. ReportShellSettings.locale
2. If that is null, Locale.getDefault()

By default, ReportShellSettings.locale comes from the global JasperReports context property net.sf.jasperreports.engine.fill.JRFiller.PROPERTY_DEFAULT_LOCALE, as described in ReportShellSettings API documentation.

This locale is primarily a viewer-page default. The controller exposes it so your page can load the matching viewer locale bundle and localize the viewer UI and date pickers consistently.

It does not by itself force a report fill locale for every REST request. See REST API documentation for how to set fill locale by request parameters.

Property Format

JasperReports Library as of version 7.0.2 expects underscore (_) separators in locale names e.g. en_EN. Properties using hyphen(-) as the separator are not recognized properly by JRDataUtils.getLocale which ReportShell uses to be compatible with JR Library’s locale resolution logic.

While ReportShell includes safety checks to intercept hyphenated locales during initialization, you must use underscores in your configuration to ensure full compatibility with the underlying JasperReports engine and to prevent unexpected resolution fallbacks at runtime.

Time Zone Resolution

The controller resolves the effective viewer timezone as follows:

1. ReportShellSettings.timeZone
2. If that is null, TimeZone.getDefault()

By default, ReportShellSettings.timeZone comes from the global JasperReports context property net.sf.jasperreports.engine.fill.JRFiller.PROPERTY_DEFAULT_TIMEZONE.

This time zone represents the application level default business time zone and is used by the viewer to handle date/date-time conversions. It is also used for handling such conversions at the server side as well as for other purposes as explained in ReportShellSettings API documentation. React Viewer documentation further explains how the viewer uses this time zone.

It does not by itself force a report fill time zone for every REST request. See REST API documentation for how to set fill time zone by request parameters.

Customizing the Model

Typically, you set or override these attributes in your view page. In case you need to customize the model attributes before the view is rendered, you can register a ViewerCustomizer bean which is called just after ReportShell configures and sets these attributes to the Spring’s Model object.

Related Topics

• React Viewer - Learn about the viewer contract and integration options
• REST API Overview - Understand the underlying REST APIs
• Operation Contexts - Learn about the operation context lifecycle
• Report Resolution - Learn how ReportShell resolves reports from keys