Spring Boot Installation

Abstract

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.

Spring Boot Quick Start Example

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.

In order to run the example, contact the Pull Reports™ sales team to receive the Pull Reports™ software and an evaluation license.

The following instructions were created with Spring Boot 1.5.

Install License

After creating the Spring Boot application, place the 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.

See the Administrative Guide, License documentation for more information.

Install Library Dependencies

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.

Note

See an example of how to use Gradle dependency management in the Pull Reports quick start repository's build.gradle

Register Web Components

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.

Note

See an example in the Pull Reports quick start repository's Application.java

Register JNDI DataSource

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 EmbeddedServletContainerFactory bean and providing the necessary JNDI configuration.

The Pull Reports™ quick start repository has an example JndiTomcatEmbeddedServletContainerFactory 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{
    compile 'com.h2database:h2:1.4.195'
}

Configure Logging

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.

Catalog Configuration

Note

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

Note

See an example Pull Reports™ XML Catalog file setup in the Pull Reports quick start repository's petstore.xml and pullreports.properties

Hot Reloading in Development

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

Note

See an example configuration in the Pull Reports quick start repository's spring-devtools.properties

Create 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.

Note

See an example in the Pull Reports quick start repository's pullreports.properties

Configure Security (Optional)

See the Security documentation chapter for instructions on how to configure security for all or individual Pull Reports™.

Run the Application

Execute gradle bootRun to run the application.

The following instructions assume the application is available at the URL http://localhost:8080/[context]

Verify REST API

The PullReportsServlet exposes a REST API to catalog and report resources within the installed catalog configuration. Use the the API to verify correct installation.

Verify: List catalogs

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™ Ad Hoc Report Creator uses this URL to display the Switch report drop down menu. Request it directly within a browser to verify the Pull Reports™ installation.

Learn more about the catalog REST API.

Verify: Export report

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.

What does 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.

Embed the Ad Hoc Report Creator

Follow these directions to install the Ad Hoc Report Creator into the Spring Boot application. Note that these directions assume the use of Freemarker templating via the spring-boot-starter-freemarker plugin:

  1. Create a Freemarker template within the src/main/resources/templates directory (e.g. ad-hoc-creator.ftl)

  2. Add a Spring controller mapping for the template:

    @GetMapping("/adHocCreator")
    public String adHocCreator() {
        return "ad-hoc-creator";
    }
  3. Follow the Ad Hoc Report Creator installation instructions to install the basic HTML template into ad-hoc-creator.ftl.

  4. After installation, the Ad Hoc Report Creator will be available at http://localhost:8080/[context]/adHocCreator.

Note

See an example in the Pull Reports quick start repository's ad-hoc-creator.ftl