JasperReports IO Report Execution Contexts

When a report is executed by the JasperReports IO reporting service, it is run within a "report execution context." This context is defined by custom Java code and JasperReports Library configuration properties that direct the behavior of the reporting engine.

The report execution context is defined using a context.xml file located in a folder named JR-INF, which has the same parent folder as the report's main template file.

For example, a report that stores its JRXML template file at /samples/reports/chartcustomizers/ChartCustomizersReport.jrxml within the JasperReports IO repository must use /samples/reports/chartcustomizers/JR_INF/context.xml for its report execution context file.

If multiple report templates are stored in the same folder, they will share the same its report execution context file found in the JR-INF subfolder. If you don't want a report template to share its report execution context with any other reports, it will need to be in its own subfolder along with the JR-INF folder containing the context.xml file.

Report Execution Context Configuration

The context.xml defines the classpath for any custom Java code, JasperReports Library properties, and inheritance rules needed to execute a report using JasperReports IO.

Parent Context

Report execution contexts inherit the classpaths and properties from other context files and you can control which files it inherits from.

• Folder Inheritance (Default)

By default, any report execution context stored in a JR-INF folder inherits from the contexts stored the JR-INF folders found in all parent folders up to the root folder of the repository.

• Direct Inheritance

You can specify a path to a parent context by using the <parentContext> tag in the context file as follows:

<context>
  <parentContext>
    <path>/parent</path>
  </parentContext>
  ...
</context>

The path needs to specify the absolute repository path to the parent folder containing the target JR-INF context that you want to use as parent context. Notice that the path specifies only the parent folder of the target report execution context and does not specify the JR-INF folder.

For example, if you want the report execution context located at /samples/reports/chartcustomizers/JR-INF/context.xml to inherit from the context located at /samples/reports/unicode/JR-INF/context.xml, you need to add the following to the context.xml file:

<context>
  <parentContext>
    <path>/samples/reports/unicode</path>
  </parentContext>
  ...
</context>

The report execution context will also inherit from the parents of the specified context, up to the root folder of the repository.

Classpath

As a Java reporting library, JasperReports has various extension points which allow the customization of its functionality using custom code in the form of compiled Java classes.

These classes are among the various types of resources that a report might need at execution time and they can also be stored in the repository, along with the subreports, style templates, images, fonts and other report resources.

The custom Java classes needed during a certain report execution need to be packaged as JAR files and placed in the repository, preferably under the JR-INF/lib subfolder of the report execution context that uses it.

The JAR then needs to be referenced from within the target context.xml file using a pair of <entry><path> tags within the <classpath> tag so that it will be loaded by the JasperReports IO reporting service when it runs the report.

For example, a report can use the custom Java code packaged in /samples/reports/chartcustomizers/JR_INF/lib/repo-sample.jar JAR file when it's referenced in the context.xml file as follows:

<context>
  <classpath>
    <entry><path>/samples/reports/chartcustomizers/JR-INF/lib/repo-sample.jar</path></entry>
  </classpath>
  ...
</context>

Properties

JasperReports IO can use JasperReports Library configuration settings to define specific behavior in reports.

Some of these configuration settings can be set at the report context execution level by using the <property> tags in the context.xml file.

The following is an example of setting the chart render type configuration property:

<context>
  ...
  <properties>
    <property>
      <name>net.sf.jasperreports.chart.render.type</name>
      <value>svg</value>
    </property>
    ...
  </properties>
</context>

Configuring a Report Execution Context

To create a Report Execution Context:

1. Start Jaspersoft Studio.
2. Select File > New > Other.

The wizard opens.

3. Select JasperReports IO Report Execution Context from the Jaspersoft Studio category and click Next.
4. Select the folder in your project to store the context file.
5. Click Finish.

Jaspersoft Studio creates a new subfolder called JR-INF and a context.xml file in the new subfolder. Jaspersoft Studio opens the file in the JasperReports IO Report Execution Context Editor.

6. Enter the parent context, classpaths, and properties for your report execution context. See Report Execution Context Configuration for more information.
7. Save the context file.

To edit a Report Execution Context Using the Report Execution Context Editor:

1. Right-click on the context file in the Project Explorer and select Open With > JasperReports IO Report Execution Context Editor.
OR
Double-click the context file.

Jaspersoft Studio opens the context file in the editor.

JasperReports IO Report Execution Context Editor
2. Edit the context file's parent context, classpaths, and properties.
3. Save the context file.

To edit a Report Execution Context Using the Text Editor:

1. Right-click on the context file in the Project Explorer and select Open With > Text Editor.

Jaspersoft Studio opens the context file.

2. Edit the context file's parent context, classpaths, and properties.
a. Add a parent context using the <parentContext><path> tags.
b. Add a classpath using the <entry><path> tags within the <classpath> tag
c. Add a property using <property> tags.
3. Save the context file.