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.
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.
Place the purchased 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.
Community Edition deployments do not require a license file. See the Administrative Guide, About the License documentation for more information.
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.
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™.
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.
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
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
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
See an example Pull Reports™ XML Catalog file setup in the Pull Reports quick start repository's
petstore.xml
and pullreports.properties
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 latter 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.
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.
See the Security documentation chapter for instructions on how to configure security for all or individual Pull Reports™.
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]
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.
See the Report Creator chapter for instructions on how to install the creator into a website.
To install the 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.
See an example creator installation in the Pull Reports quick start repository's
ad-hoc-creator.jsp