Grails 3 Installation

Abstract

Learn how to install Pull Reports™ Ad Hoc reporting and data service software into the Grails 3 web application framework.


Follow these instructions to install Pull Reports™ within a new or existing Grails 3 application. These instructions were created with Grails 3.3.

Grails 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 grails sub-project for information specific to Grails 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.

Install License

After creating the Grails application, place the pullreports.license file within the src/main/resources directory. This file is read 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

Grails 3 uses Gradle to resolve JAR dependencies. See the dependency management documentation for recommendations on managing Pull Reports™ JARs within a Grails project.

Read about additional dependency management resolution strategies within the Gradle user guide.

Note

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

Register JEE Beans

Register the PullReportsContextListener and PullReportsServlet as Spring beans within the grails-app/conf/spring/resources.groovy file.

Example 1. JEE listener and servlet components within resources.groovy
import org.springframework.boot.web.servlet.ServletRegistrationBean
import org.springframework.boot.web.servlet.ServletListenerRegistrationBean
import com.pullreports.web.PullReportsServlet
import com.pullreports.web.PullReportsContextListener

beans = {

    pullreportsListener(ServletListenerRegistrationBean) { bean ->
         listener = new PullReportsContextListener()
    }

    pullreportsServlet(ServletRegistrationBean) { bean ->
         servlet = new PullReportsServlet()
         urlMappings = ['/pullreports/*']
    }
}

Note

See an example in the Pull Reports quick start repository's resources.groovy

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. In Grails development, the application runs within an embedded Tomcat container, so the JNDI javax.sql.DataSource must be created by extending TomcatEmbeddedServletContainerFactory and adding the DataSource factory to the Catalina context.

The Pull Reports™ quick start repository has an example JndiTomcatEmbeddedServletContainerFactory bean which establishes a JNDI javax.sql.DataSource backed by an H2 database connection.

The JndiTomcatEmbeddedServletContainerFactory must be registered as the authoritative ContainerFactory tomcatEmbeddedServletContainerFactory bean within resources.groovy. In the example resources.groovy file from the quick start repository, the JndiTomcatEmbeddedServletContainerFactory implementation is only used during development. When the application is deployed in a non-development environment, the Servlet Container must provide the JNDI javax.sql.DataSource.

Note that creating a JNDI javax.sql.DataSource requires registering the database JDBC driver as a compile time dependency. For instance, if using H2, add the H2 JDBC driver as a dependency within build.gradle:

compile 'com.h2database:h2:1.4.195'

Configure Logging

Pull Reports™ uses the SLF4J logging framework. Since Grails 3 natively supports SLF4J logging, activate Pull Reports™ logging by adding appropriate loggers to grails-app/conf/logback.groovy.

// Example: setting all Pull Report loggers to log at the ERROR level.
logger("com.pullreports", ERROR)
// Example: setting the Pull Reports SQL logger to DEBUG
logger("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 XML Catalog files within the src/main/resources directory. 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 in the Pull Reports quick start repository's petstore.xml and pullreports.properties

Hot Reloading in Development

Grails uses spring-loaded to hot deploy changes to class files during development when run via the run-app command. Because Pull Reports™ deployed within a Servlet Container caches Pull Reports™ XML Catalog file configuration in the JVM memory, changes to Pull Reports™ XML Catalog files are not refreshed by spring-loaded.

In order to hot reload changes to Pull Reports™ XML Catalog files during Grails development, switch Grails to use spring-boot-devtools for hot reloading and include the pullreports-x.y.z.jar in the refresh classloader.

To do this, first declare a dependency on spring-boot-devtools within build.gradle:

dependencies {
    ...
    runtime 'org.springframework.boot:spring-boot-devtools'
    ...
}

Second, turn off spring-loaded in grails-app/conf/application-development.yml

grails:
    agent:
        enabled: false

Finally, include the pullreports JAR within the restart classloader via the following configuration in src/main/resources/META-INF/spring-devtools.properties:

restart.include.pullreports=/pullreports-[\\w\.]+\.jar

Create pullreports.properties

Create a text file called pullreports.properties within the src/main/resources directory. This file contains required configuration information related to database connectivity and report definition.

Requirement:  Grails 3 installations must set the static.resource.prefix property value to /static.

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
static.resource.prefix=/static

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

Run the Application

Execute grails run-app to run the application.

The following instructions assume the WAR 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

To install the Ad Hoc Report Creator into the Grails application, follow these steps:

  1. Create a GSP page within the grails-app/views directory (e.g. ./grails-app/views/ad-hoc-creator.gsp)

  2. Add a mapping for the new view to UrlMappings

    "/ad-hoc-creator"(view:"/ad-hoc-creator")

  3. Follow the Ad Hoc Report Creator installation instructions to install the basic HTML template into ad-hoc-creator.gsp.

    Important note for Grails 3

    Grails 3 prefixes all static content from JAR META-INF/resources directories with the /static URL path. For this reason, prefix all paths to Pull Reports.css and .js files with /static.

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

Note

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