Basic WAR Installation

Abstract

Learn how to install Pull Reports™ Ad Hoc reporting and data service software into a JEE web application.


Follow these instructions to install Pull Reports™ within a new or existing Java Web Application Archive (WAR) file. These instructions describe installation into a "classic" JEE directory structure without the use of additional web or build frameworks.

JEE 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 jee sub-project for information specific to JEE 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

Place the pullreports.license at the root of the WAR's classpath such as within the WEB-INF/classes 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

The pullreports-x.y.z.jar plus all transitive, runtime dependency JARs from the Pull Reports™ media must be available on the WAR's classpath. See the dependency management documentation for recommendations on managing Pull Reports™ JARs within an application build.

Note

The WAR's web.xml must not be attributed with:

<web-app metadata-complete="true">

This will disable scanning for classes annotated with Servlet Specification 3.0 web component annotations such as @WebServlet and thus disable Pull Reports™.

Configure Logging

Pull Reports™ uses the SLF4J logging framework. Since Pull Reports™ does not come with an implementation of the SLF4J API, provide a SLF4J implementation in order to activate logging.

See the Administrative Guide logging documentation for more information on SLF4J logging.

SLF4J-Log4j example

Log4j is a popular implementation of SLF4J. In order to use a Log4j as the SLF4J implementation, put the slf4j-log4j12 binding and log4j implementation Jars into the WAR's WEB-INF/lib directory.

WEB-INF/lib/slf4j-log4j12-1.7.22.jar
WEB-INF/lib/log4j-1.2.17.jar

Then put a text file named log4j.properties file in WEB-INF/classes

WEB-INF/classes/log4j.properties
Example 1. log4j.properties file

This example assumes the WAR s deployed within the Tomcat Servlet Container with the catalina.home java.lang.System property set.

log4j.com.pullreports=error, pullreports

log4j.appender.pullreports=org.apache.log4j.RollingFileAppender
log4j.appender.pullreports.File=${catalina.home}/logs/pullreports.log
log4j.appender.pullreports.MaxFileSize=100KB
log4j.appender.pullreports.MaxBackupIndex=1
log4j.appender.pullreports.layout=org.apache.log4j.PatternLayout
log4j.appender.pullreports.layout.ConversionPattern=%p %t %c - %m%n

# Configure a separate log file for logging SQL queries
log4j.com.pullreports.SQL=debug, pullreports-sql
log4j.appender.pullreports-sql=org.apache.log4j.RollingFileAppender
log4j.appender.pullreports-sql.File=${catalina.home}/logs/pullreports-query.log
log4j.appender.pullreports-sql.MaxFileSize=100KB
log4j.appender.pullreports-sql.MaxBackupIndex=1
log4j.appender.pullreports-sql.layout=org.apache.log4j.PatternLayout
log4j.appender.pullreports-sql.layout.ConversionPattern=%p %t %c - %m%n

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 WAR's classes directory and reference them via the pullreports.properties catalogs property.

For example, for XML Catalog files installed within this WAR path:

WEB-INF/classes/financial-report-catalog.xml
WEB-INF/classes/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

Create pullreports.properties

Create a text file named pullreports.properties at the root of the WAR's classpath such as within the WEB-INF/classes directory. This properties file must contain at least two required properties, catalogs and jndiDataSource. The former lists the catalog configuration values specified during the Catalog Configuration step below. The later provides the default JNDI location of a javax.sql.DataSource used for report export.

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

Creating a JNDI javax.sql.DataSource is the responsibility of the Servlet Container into which the Pull Reports™ WAR is deployed. See the documentation for your Servlet Container for help configuring JNDI. For example, if using Tomcat, see the JNDI DataSource How-To documentation.

Furthermore, the Pull Reports quick start repository's build.gradle and context.xml demonstrate JNDI DataSource configuration within a Gretty managed Tomcat.

Configure Security (Optional)

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

Run the Application

Install the WAR file containing the Pull Reports™ JARs, license file, properties file, and catalog configuration into the Servlet Container of choice. Exact installation instructions vary between Servlet Container implementations. Please consult the documentation of the chosen container for more information.

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

See the Ad Hoc Report Creator chapter for instructions on how to install the creator into a website.

To install the Ad Hoc Report Creator into a HTML page within the WAR into which you installed the Pull Reports™ JAR, create an HTML page within the WAR (e.g. ./creator.html) and follow the installation instructions.

Note

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