Operation Contexts

The JasperReports Library uses JasperReportsContext objects to provide configuration and services when filling and exporting reports.

ReportShell uses two different runtime concepts:

• a shared global JasperReportsContext initialized once at startup, and
• a request-scoped OperationContext created for a single invocation (typically one web request).

Global JasperReportsContext

The global JasperReportsContext integrates with the Spring environment. This allows you to:

• register JasperReports extensions, such as repository services or font extensions, as Spring beans, and
• resolve JasperReports properties from the Spring Environment.

This context is initialized at startup and also inherits from the shared context created by DefaultJasperReportsContext.getInstance(), so JasperReports Library’s own configuration logic for properties and extensions is available as well.

Caution

The global context is a singleton and is not intended to be modified after initialization. This context must be the only bean that is registered for the JasperReportsContext type. It is strongly recommended that you don’t override this bean with a custom implementation.

Operation Contexts

ReportShell creates a request-scoped OperationContext early in the request lifecycle.

This context is created once and then carried through the reporting flow for that invocation (authorization, input controls, fill, export, pagination, etc.).

OperationContext is the main request-scoped context passed to ReportShell services. It carries invocation-specific data such as:

• the authenticated principal,
• the locale,
• extra request parameters, and
• application-defined attributes.

Caution

OperationContext instances are created and managed by the framework.

• Do not create your own OperationContext or pass one directly to core/domain services.
• Use the provided configuration hook described below to populate request-scoped values.
• Do not write request-specific values into the global JasperReportsContext.

How It Works

When a request arrives:

1. Controller obtains the current web request and passes it to the WebOperationContextFactory.
2. The factory creates a mutable OperationContext and applies framework defaults such as principal and locale.
3. Registered OperationContextInitializer beans run and may copy request-derived metadata into the mutable operation context.
4. Controller passes the resulting OperationContext to services for authorization, filling, and exports. When the controller passes the context to services, it converts the context to an immutable one. Service layer cannot update the context attributes afterward.

How to Set Request-Scoped Values

When creating an OperationContext, ReportShell invokes every registered OperationContextInitializer bean.

Implement the interface and register it as a Spring bean to copy request-derived values into the mutable operation context.

Example:

@Component
public class MyOperationContextInitializer implements OperationContextInitializer {
  // Do not use the prefix "reportshell." for your attribute keys
  private static final AttributeKey<String> REQUEST_ID = new AttributeKey<>("myapp.requestId");

  @Override
  public void initialize(WebRequest request, MutableOperationContext context) {
    var requestId = request.getHeader("X-Request-Id");
    if (requestId != null) {
      context.setAttribute(REQUEST_ID, requestId);
    }
  }
}

At that stage, you have direct access to Spring’s WebRequest. You can copy headers, parameters, correlation IDs, and similar simple metadata into the OperationContext.

ReportShell also automatically copies all rs.extra.* request parameters into the operation context’s extra-parameter map.

Important

Never store request-scoped objects such as WebRequest, HttpServletRequest, open streams, or database handles in the operation context.

Copy only stable values such as strings, numbers, IDs, or small immutable DTOs.

If you need to configure JasperReports properties, extensions, or services, do that once on the global JasperReportsContext during startup rather than during request handling.

The prefix reportshell. is reserved for ReportShell attributes.