Learn how to install Pull Reports™ Ad Hoc reporting and data service software into the Spring Boot web application framework.
Follow these instructions to install Pull Reports™ within an existing Spring Boot application. These instructions assume the reader is familiar with Spring Boot and has already created a Spring Boot application. Spring Boot has an excellent quick start tutorial to help those unfamiliar with Spring Boot.
Pull Reports™ has a
quick start example
repository publicly available on GitHub to aid understanding of the various installation components.
See the spring-boot
sub-project for information specific to Spring Boot Pull Reports™ installation.
The following instructions were created with Spring Boot 2.7.
After creating the Spring Boot application, place the purchased pullreports.license
file within the src/main/resources directory.
This file is read from the root of the JVM classpath at WAR initialization and
validates the license term and number of allowable <report>s.
Community Edition deployments do not require a license. See the Administrative Guide, About the License documentation for more information.
Spring Boot uses either Gradle or Maven dependency management to resolve application JAR dependencies. See the dependency management documentation for recommendations on managing Pull Reports™ JARs within a Spring Boot project.
See an example of how to use Gradle dependency management in the Pull Reports quick start repository's
build.gradle
Add the @ServletComponentScan(basePackages="com.pullreports")
annotation to the Spring Boot application class in order to automatically register the
com.pullreports.web.PullReportsContextListener and
com.pullreports.web.PullReportsServlet on application start up.
See an example in the Pull Reports quick start repository's
Application.java
Pull Reports™ retrieves javax.sql.DataSources from
JNDI. In a production deployment environment, the Servlet Container will typically provide the JNDI
DataSource to a running Spring Boot application.
When running Spring Boot with an embedded Servlet Container in development or in production via a runnable JAR,
create the JNDI DataSource by overriding the
ConfigurableServletWebServerFactory
bean and providing the necessary JNDI configuration.
The Pull Reports™ quick start repository has an example
JndiTomcatServletWebServerFactory
which establishes a JNDI javax.sql.DataSource backed by an H2 database connection.
Note that creating a JNDI javax.sql.DataSource requires
registering the database JDBC driver as a compile time dependency. For instance, if using Gradle and H2,
add the H2 JDBC driver as a dependency within build.gradle:
dependencies{
implementation 'com.h2database:h2:1.4.200'
}
Pull Reports™ uses the SLF4J logging framework.
Since the Spring Boot spring-boot-starter-web plugin transitively includes
SLF4J, see the
Spring Boot logging documentation
to configure Pull Reports™ loggers in a Spring Boot application.
For example, add the following property to application.properties
to log all Pull Reports™ SQL statements:
// Example: setting the Pull Reports SQL logger to DEBUG logging.level.com.pullreports.SQL=DEBUG
See the Administrative Guide, logging documentation for more information on SLF4J logging.
Spring Boot 2.4+ no longer registers the DefaultServlet required to
serve Pull Reports™ JS and CSS files. Register the DefaultServlet with
the following application.properties configuration.
server.servlet.register-default-servlet=true
See the Catalog Configuration Introduction documentation for information on how to create Pull Reports™ XML Catalog files or usage of the Catalog Configuration Java API.
When using Pull Reports™ XML Catalog files for catalog configuration, place the
XML Catalog files within the src/main/resources directory
and reference them in the next step via the pullreports.properties
catalogs property.
For example, for Pull Reports™ XML Catalog files installed here:
src/main/resources/financial-report-catalog.xml src/main/resources/client-report-catalog.xml
The catalogs property value should be:
catalogs=classpath:financial-report-catalog.xml \
classpath:client-report-catalog.xml
See an example Pull Reports™ XML Catalog file setup in the Pull Reports quick start repository's
petstore.xml
and pullreports.properties
Because Pull Reports™ caches XML Catalog file configuration in the JVM memory, changes to XML Catalog files
are not hot deployed to the running Spring Boot application during development. To enable hot reloading,
explicitly add the Pull Reports JAR to the
spring-boot-devtools
restart classloader via the following spring-devtools.properties property:
restart.include.pullreports=/pullreports-[\\w\.]+\.jar
Hot reloading will not work if your installation includes a value for the
system.userProvider
configuration property.
pullreports.properties
Create a text file named pullreports.properties
within the src/main/resources directory.
This file contains required configuration information related to database
connectivity and report definition.
Taking the XML Catalog file location from the previous step and a default JNDI javax.sql.DataSource
location of java:comp/env/jdbc/example-datasource, the pullreports.properties file would be:
catalogs=classpath:financial-report-catalog.xml classpath:client-report-catalog.xml jndiDataSource=java:comp/env/jdbc/example-datasource
See the pullreports.properties
reference documentation
for a description of all required and available properties.
See an example in the Pull Reports quick start repository's
pullreports.properties
See the Security documentation chapter for instructions on how to configure security for all or individual Pull Reports™.
Execute gradle bootRun to run the application.
The following instructions assume the application is available at the
URL http://localhost:8080/[context]
The PullReportsServlet exposes a REST API to catalog and report resources within the installed catalog configuration. Use the API to verify correct installation.
Open a browser and paste the following URL into the location bar:
http://localhost:8080/[context]/pullreports/catalog.json
This URL returns a simple JSON representation of all <catalog>s and their child
<report>s. The Pull Reports™ Report Creator uses this endpoint
to display report metadata within the Report Repository. Request it directly within a browser to verify the Pull Reports™ installation.
Open a browser and paste the following URL into the location bar:
http://localhost:8080/[context]/pullreports/catalog/[catalog_id]/report/[report_id]/export?limit=1
This URL invokes the Export Report REST API for the report identified by [catalog_id]
and [report_id]. Requesting this URL within a web browser is an easy way to verify
that the configured DataSource works and that the catalog configuration contains valid database
table and column names.
limit=1do?The limit=1 parameter restricts the returned
results to just 1 row. Without it, the default behavior of the export API is to return every row of the
report's base table up to the configured
export.report.maxResults.
By default, the Export Report REST API returns JSON output. Change this by appending
another format type (e.g. &format=html) to the query string.
Follow these directions to install the Report Creator into the Spring Boot application.
Note that these directions assume the use of Freemarker
templating via the spring-boot-starter-freemarker plugin:
Create a Freemarker template within the src/main/resources/templates
directory (e.g. ad-hoc-creator.ftlh)
Add a Spring controller mapping for the template:
@GetMapping("/adHocCreator")
public String adHocCreator() {
return "ad-hoc-creator";
}
Follow the Report Creator installation instructions
to install the basic HTML template into ad-hoc-creator.ftlh.
After installation, the Report Creator will be available at http://localhost:8080/[context]/adHocCreator.
See an example in the Pull Reports quick start repository's
ad-hoc-creator.ftlh