If you implement organizations, the absolute path is relative the user’s organization, as described in section Multiple Organizations in the Repository.
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.
There are several ways to define and reference all the resources in a JasperReport.
In environments that rely directly on JasperReports, shared resources are usually stored on a network file system 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. In order to share resources, reports must reference resources with a special syntax. To reference resources in the repository, use a URI with the repo: prefix in your JRXML. This is similar to the file: syntax for file-based resources and the http: syntax that is used for web-based resources, however it is recognized only inside of JasperReports Server.
When you use this syntax in your JRXML files, 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.
The following sections describe several ways of using the repo: syntax to create different kinds of references.
Absolute references are URIs in the JRXML of the report that specify a resource’s complete repository path. The following example references an image named myImage that is stored in the /images folder:
repo:/images/myImage
The path must start with a / to represent the root of the repository, and 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.
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:
repo:myImageLink
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 the server doesn’t allow you to delete resources that are being referenced. No one can delete the resource without first removing the external reference, either by editing the JasperReport to change the external reference or by deleting the JasperReport that contains it.
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.
Indirect references are also used implicitly when administrators define the following resources in the repository:
• For input controls, you must specify a datatype or list of values, either as a local resource or as an external reference to one in the repository.
• A query may optionally define a data source, either by creating a local data source resource, or by referencing an existing one in the repository.
• Domains may reference XML design files that are either created in the Domain Designer or uploaded from an external file resource. Domains also have XML security files and resource bundles, both of which can be either uploaded as local file resources or referenced from file resources in the repository.
• OLAP resources in Jaspersoft OLAP rely on other OLAP resources, for example views reference connections, and connections reference schemas. In each case, you can define local resources or external references. For more information, see the Jaspersoft OLAP User Guide.
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 use an external reference to its datatype. The server still manages the dependency between the local input control and the datatype resource in the repository.
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 section Enabling Data Snapshots.