Jump to content
JasperReports Library 7.0 is now available ×

  • djohnson53
    • Features: Ad Hoc, Data Sources, Domains, Filters, Input Controls Version: v8.2.0 Product: JasperReports® Server


    To get started with JasperReports Server and defining reports, it is important to understand the various components that are used to define a report. This tutorial explains the various components used in defining a report and their relationships, including:

    • Data Sources
    • Domains
    • Topics
    • Filters and Input Controls
    • Ad Hoc Reports versus Jasper Reports

    Product Version

    This tutorial refers to concepts associated with JasperReports Server Professional 3.0 and later.


    This guide will enable you to understand:



    Ad Hoc Reports versus Jasper Reports

    A report or report unit can be thought of as a complete set of components for controlling and generating report output.

    It includes the report query, input controls, necessary calculations, and layout instructions that when run against a particular data source or domain can produce results rendered and exported in a given layout and format for end-user consumption.

    Reports can be categorized into two major categories: Ad Hoc Reports and Jasper Reports

    • And Ad Hoc Report is defined using the Ad Hoc editor within JasperReports Server Professional and continues to be editable using this editor
      • The primary report definition is represented within JasperReports Server Professional as meta data rather than within JRXML
    • A Jasper Report is defined or modified outside of the Ad Hoc editor, typically with iReport.
    • The primary report description is represented as JRXML
    • An Ad Hoc report can be opened with iReport, which converts the ad hoc meta data into a JRXML representation, turning the Ad Hoc Report into a Jasper Report

    Data Source Component

    A Data Source defines the connection properties that JasperReports Server needs to access data.

    • JasperReports Server transmits queries to data sources and obtains datasets in return for use in filling reports and previewing Ad Hoc reports
    • JasperReports Server supports JDBC, JNDI, and Bean data sources
      • Custom data sources can be defined as well

    Domain Component

    A Domain is a virtual view of a data source that presents the data in business terms, allows for localization, and provides data-level security.

    • A Domain is not a view of the database in relational terms, but it implements the same functionality within JasperReports Server
    • The design of a Domain specifies tables in the database, derived tables, join clauses, calculated fields, display names, and default properties, all of which define items and sets of items for creating topics and reports

    Topic Component

    A Topic is a predefined set of fields, filters, and input controls defined by a particular query against a data source or domain, input controls, and a data source or domain that can be used to create Ad Hoc Reports.

    • Topics are created by business analysts to specify a data source and a list of fields with which business users can easily create reports in the Ad Hoc Editor without having to define the data relationships
    • The topic is a helper component where once the report has been created, it does not directly rely on the topic; meaning changes to Topics will not impact existing reports

    Filters and Input Controls

    A Filter limits the data returned by a report based on a comparison of fields and values.

    • Added as a portion of the “WHERE” clause within the report query, a filter directly limits the data processed within the report.

    An Input Control defines the prompt that an end-user receives at run time to provide a value or values to be used in a Filter.

    • In some cases, the filter is parameterized to accept different comparison values from the end user at run-time
    • The parameter is associated with an Input Control of the same name to allow the end-user to pass values to the report

    Report Component Relationships

    To help visualize the relationship between the various report components and the resulting report, consider the following image, which shows the components of a working report.



    • As shown, a report is made up at a basic level of the layout definition and the data query with filters and any input controls needed to allow for user input
    • The Report is connected to either a Domain, which is connected to a Data Source, or it is connected directly to a Data Source.
      • Without a data source, there is no way for the report to gather data on which to report.

    A Topic is made up of the same components and relationship to a Domain or Data Source as a report, except it is missing the layout definition.

    • Without the layout definition, there is no way to render the data for viewing. The purpose of the Topic is not for viewing
      • It serves as a reusable template for building reports that require the same data.
    • When a Topic is used to define a report, current Topic definition is copied as a starting point for the report.


    Note: All Ad Hoc reports are built starting from a Topic.

    • If a Domain is selected, the initial steps are the same as those followed when defining a Topic and the user is given an option to save a Topic in the process of defining the Ad Hoc Report.
    • Within the Ad Hoc editor, the first step is to select a Topic or a Domain.

    What's Next?

    With an understanding of the basic components used in the building of reports and their relationships, now is the time to try building these components and building your first report.

    User Feedback

    Recommended Comments

    There are no comments to display.

    Create an account or sign in to comment

    You need to be a member in order to leave a comment

    Create an account

    Sign up for a new account in our community. It's easy!

    Register a new account

    Sign in

    Already have an account? Sign in here.

    Sign In Now

  • Create New...