The resource in the repository that aggregates all information needed to run a report is called a JasperReport. A JasperReport is based on a JRXML file that conforms to the JasperReports open source library that the server uses to render reports.
A JasperReport is a complex resource that is composed of other resources:
| • | A JRXML file that defines the report, called the main JRXML. |
| • | A data source that supplies data for the report. |
| • | A query if none is specified in the main JRXML. |
| • | The query may specify its own data source, which overrides the data source defined in the report. |
| • | Input controls for any parameters that users may enter before running the report. Input controls are composed of either: |
| • | A datatype definition. |
| • | A list of values. |
| • | Any additional file resources, such as images, fonts, and resource bundles referenced by the report template. |
| • | If the report includes sub-reports, the JRXML files for the subreports. |
The collection of all the resources that are referenced in a JasperReport is sometimes called a report unit. End users usually see and interact with a JasperReport as a single resource in the repository, but report creators must define all of the component resources.
Referencing Resources in the Repository
There are several ways to define and reference all the resources in a JasperReport.
In environments without JasperReports Server, reports are stored in the file system, and shared resources are usually stored on a network drive accessible to all developers and users. This solution is sometimes impractical, as you cannot always add such resources to the classpath, and the use of absolute paths has its own limitations. In addition, storing the resources in the file system discourages their reuse: your developers may invest time in creating new versions of resources that already exist because they don’t know about them.
By storing resources in the repository, JasperReports Server makes it easy and reliable to share resources such as images, style templates, and subreports between reports. The repository mimics a folder and file structure, so that references to external files can be handled as references to external resources in the repository.
In versions of JasperReports Server prior to 5.5, the JasperReports used the repo:syntax. As of 5.5, this is no longer necessary, and regular file paths are recognized and managed within the repository.
When you upload your JRXML to the repository, your file references become valid repository references, and you can store all your resources in well-known locations in the repository. This simplifies the process of uploading your reports, because you don’t have to upload the resources each time. Also, you can manage these resources either through iReport, through the JasperReports Server user interface, or through the server’s APIs. For example, when you update a logo image resource, all reports that reference the resource also display the new logo.
Absolute References
Absolute references are URIs in the JRXML of the report that specify a resource’s repository path. The path may refer to the file system where the JRXML was created, but when uploaded to the server, it refers to folders in the repository.
The path must start with one of the following:
/ to represent the root of the repository in the community edition, or the current user's organization in commercial editions. For example, /images/logo is a resource in the /images folder.
../ to represent the folder where the JasperReport is uploaded. For example, ../myLogo is a resource in the same folder as the JasperReport.
As with a file system path, the repository path is composed of the resource ID of every parent folder, ending with the ID of the resource. iReport with the JasperReports Server plug-in supports absolute references by allowing you to drag resources from the repository tree view into the design area.
| | If you implement organizations, the absolute path is relative the user’s organization, as described in section Multiple Organizations in the Repository. |
When uploading the JRXML with absolute resource references as part of a JasperReport in the server, you only need to ensure that the resource with the given path exists in the repository before running the report. When the report runs, the server locates the resource in the repository and uses it to render the report.
Because file resources such as images, fonts, and JARs are the only resources for which you can create references directly in JRXML, they are the only resources for which you can create absolute references.
One disadvantage of absolute references is that JasperReports Server does not maintain the dependency between the JRXML and the absolute reference. When uploading the JRXML, there is no warning if the resource does not exist, and the server allows you to delete the resource from the repository even if it is still being referenced. If the resource is not available, running the report fails with an error.
Local Resources and External References
JasperReports Server provides more flexibility and power when you use indirect references instead of absolute references. Indirect references are placeholder names that must be manually linked to the resource when uploading the JasperReport. The syntax for an indirect reference contains only a placeholder name for the resource, for example:
logoImage
When you upload a JRXML with this reference, the server prompts you to provide the resource. You have two choices:
| • | Creating a new resource, in this case by uploading an image, that becomes part of the JasperReport. This is called a local resource. You cannot access this resource from elsewhere in the repository, it exists only within the JasperReport. |
| • | Selecting a resource from the repository, called an external reference because it is external to the JasperReport. This allows any number of reports to link to the same resource, yet allow that resource to be managed independently of them. |
While indirect references require slightly more work than absolute references in the JRXML, the server manages the dependency. Local resources exist as part of JasperReport, and external references cannot be deleted until they are no longer referenced.
In cases when you don’t want to reference existing resources, local resources allow reports to be highly customized and self-contained. A local resource that is defined inside the JasperReport has all the same properties as a repository resource, but it is not accessible in the repository. Users must edit the JasperReport to access any resources it defines locally.
| | Users who are not administrators may create JasperReports but not other resources in the repository. Therefore, if an administrator does not provide them resources for external references, their only option is to create local resources for all dependencies within the JasperReport. |
Indirect references are used implicitly in several other cases when you define a JasperReport:
| • | The main JRXML itself is either a local resource created by uploading a file or an external reference to an existing JRXML file resource in the repository. |
| • | Every report must have a data source, and JasperReports Server gives you the option of creating a new local resource or of using an external reference to an existing data source. |
| • | Every report must also have a query that matches its data source. You may choose to create a query local resource or use an external reference to an existing query. |
| • | Parameters in a report are implicitly handled as an indirect reference to an input control. For every parameter named in your main JRXML, you must define an input control either as a local resource or external reference. |
Every level of indirect referencing is independent of the other. For example, when creating a JasperReport, you may choose to create an input control as a local resource, but that input control may have an external reference to its datatype. The server still manages the dependency between the local input control and the datatype resource in the repository.
Local resources and external references are use throughout the repository, for example when creating input controls, query resources, Domains, and OLAP resources.
References in Subreports
A subreport is a subordinate JRXML file that is included in a JasperReport. As with all other resources referenced by the main JRXML, the subreport JRXML file may be specified by an absolute reference, a local resource or an external reference.
As a JRXML file, a subreport can reference other resources of its own. However, the subreport is run as part of the main JRXML, and any references in the subreport are interpreted relative to the JasperReport resource (represented by the main JRXML) and the context in which the JasperReport is being run.
Data Snapshots
As of JasperReports Server 4.7, report resources may also store a snapshot of the report data. A snapshot is a copy of the data that the query returns when the data is refreshed. This data snapshot is an internal structure that is not visible nor accessible from the repository. However, when data snapshots are enabled, a data snapshot is stored in the repository with each report. When users open a report, the report viewer retrieves and displays from the snapshot. Users then have the option of refreshing the data in the report viewer, and if they have permissions, saving the data snapshot back into the report resource.
For more information about interacting with data snapshots, see the JasperReports Server User Guide. To enable snapshots, see Enabling Data Snapshots.
Recommended Comments
There are no comments to display.