JSON Data Source Overview
JSON stands for JavaScript Object Notation and represents an open standard text format used
to transmit data across the network. The main purpose of the JSON format is to provide an alternate way to XML for
transporting data between a server and a client (web) application. Wherever possible, the use of a JSON data source
implementation (see the built-in JsonDataSource)
is recommended, because:
- JSON comes with less memory consumption
- data is retrieved faster from JSON than from an equivalent XML stream
- the JSON syntax rules are very simple, they represent a subset of JavaScript rules:
- data objects contain properties organized as name : value pairs, in a hierarchical structure
- each property inside an object has a specific value. Values of a JSON property can be:
- a number (integer or floating point)
- a boolean (true or false)
- a string
- an object (set of name : value pairs)
- an array
- null
- objects are enclosed in curly braces
- arrays are enclosed in square brackets; elements in an array are comma-separated
- distinct name : value pairs are comma-separated
- there are no reserved words
Let's see, for instance, the JSON objects inside the data/northwind.json source file:
There is a Northwind parent object enclosing 2 comma-separated objects: Customers and Orders.
The Customers object contains a list of similar structured objects, each representing a customer with the following properties:
"Phone""PostalCode""ContactName""Fax""Address""CustomerID""CompanyName""Country""City""ContactTitle"
The Orders object contains a list of order objects, each one exposing the following properties:
"ShipPostalCode""OrderDate""OrderID""Freight""ShipRegion""RequiredDate""ShipCity""ShipCountry""EmployeeID""ShipVia""CustomerID""ShipAddress""ShipName"
The JSON Query Executer
Properties within a JSON object can be accessed using the period notation. Therefore
we have the possibility to query a JSON data source, like below:
Northwind.Orders
or
Northwind.Orders[0].OrderID
This can be used as a JSON query expression language to navigate through objects hierarchy in a
source document and retrieve their information, based on a tree representation of objects. The query string is processed using the
Jackson library APIs.
For instance, one can specify the following expression to produce a list of JSON objects as the report query:
]]>
This query returns a list containing all customer elements in the Customers object. If we need
to retrieve only customers from USA, the query have to be refined as:
]]>
The JSON query language also supports parameters, in order to allow dynamic queries. Parameters are processed at runtime and replaced by their values.
For instance, if we define the Country parameter that holds the name of a given country, the parameterized query will look like:
...
]]>
The built-in JSON query executer (see the
JsonQueryExecuter class) is a tool that uses the query string to produce a
JsonDataSource instance,
based on specific built-in parameters (or equivalent report properties). This query executer is registered via
JsonQueryExecuterFactory factory class.
In order to prepare the data source, the JSON query executer looks for the
JSON_INPUT_STREAM parameter that contains the JSON
source objects in the form of an java.io.InputStream. If no
JSON_INPUT_STREAM parameter is provided, then
the query executer looks for the alternate net.sf.jasperreports.json.source
String parameter or report property that stores the path to the location of the JSON source file.
JsonQueryExecuter runs the query over the input source and stores
the result in an in-memory JsonDataSource object.
During the JsonDataSource instantiation, the query executer also looks for the following additional parameters or report properties, containing the required localization settings:
- net.sf.jasperreports.json.date.pattern
- net.sf.jasperreports.json.number.pattern
- JSON_LOCALE (parameter only) of type
java.util.Locale
- net.sf.jasperreports.json.locale.code of type
java.lang.String;
this can be used if no java.util.Locale parameter is available
- JSON_TIME_ZONE (parameter only) of type
java.util.TimeZone
- net.sf.jasperreports.json.timezone.id of type
java.lang.String;
this can be used if no java.util.TimeZone parameter is available
In the next section you can see how these additional parameters are provided in the /src/JsonDataSourceApp.java class.
The JSON Data Source Sample
In our example data are stored as a hierarchy of Northwind.Customers and Northwind.Orders objects in the data/northwind.json file.
The source file name is provided in the reports/JsonCustomersReport.jrxml via the report property:
]]>
In the JsonCustomersReport we run a JSON query in order to retrieve only the customers:
]]>
The only Customer properties (fields) we are interested in are CustomerID and CompanyName:
]]>
Additional parameters are passed to the report execution in the /src/JsonDataSourceApp.java class (see the fill() method):
params = new HashMap();
params.put(JsonQueryExecuterFactory.JSON_DATE_PATTERN, "yyyy-MM-dd");
params.put(JsonQueryExecuterFactory.JSON_NUMBER_PATTERN, "#,##0.##");
params.put(JsonQueryExecuterFactory.JSON_LOCALE, Locale.ENGLISH);
params.put(JRParameter.REPORT_LOCALE, Locale.US);
JasperFillManager.fillReportToFile("build/reports/JsonCustomersReport.jasper", params);
System.err.println("Filling time : " + (System.currentTimeMillis() - start));
}]]>
Each customer in the datasource requires an Orders subreport. Data source and parameters are transmitted from the master report:
]]>
The CustomerID parameter is required in order to filter data in the subreport.
Next, in the reports/JsonOrdersReport.jrxml file one can see a parametrized query. All orders related to a given CustomerID
are retrieved:
]]>
From each order we collect the following properties:
]]>
Running the Sample
Running the sample requires the Apache Ant library. Make sure that ant is already installed on your system (version 1.5 or later).
In a command prompt/terminal window set the current folder to demo/samples/jsondatasource within the JasperReports source project and run the > ant test view command.
It will generate all supported document types containing the sample report in the demo/samples/jsondatasource/build/reports directory.
Then the report will open in the JasperReports internal viewer.