Software and Dependencies


Software Description

Abstract

Read a description of the Pull Reports™ software media ZIP file and learn how to use IVY or Maven dependency management with Pull Reports™.

The Pull Reports™ software is available for download after purchase. The downloaded file is named pullreports-dist-x.y.z.zip where x, y, and z correspond to the product major, minor, and patch version numbers respectively. Unzip the file to access the following files and directories:

Table 1. pullreports-x.y.z.zip contents
File / DirectoryDescription
PullReportsEULA.pdfThe Pull Reports end user license agreement. Please read carefully.
dist/pullreports-x.y.z.jarThe Pull Reports software. See following table for a component description.
dist/pullreports-catalog-1.5.0.xsdThe XML schema definition for Pull Reports™ XML Catalog files. Use to validate Pull ReportsXML Catalog files.
dist/pom.xmlThe Maven POM file of required Pull Reports™ runtime dependencies. These dependencies are also found in the lib directory.
libThe transitive, runtime dependency JARs for Pull Reports™. These same dependencies are listed within dist/pom.xml and are included in the distribution as a convenience.

Table 2. pullreports-x.y.z.jar Principle Components
ComponentDescription
com.pullreports.web.PullReportsContextListenerServletContextListener which reads Pull Reportsconfiguration properties and initializes Pull Reports™.
com.pullreports.web.PullReportsServletHttpServlet which serves all Pull Reports™ resources. Mapped to URL pattern /pullreports/*.

Within the META-INF/resources/assets directory:

  • pullreports.min.js

  • pullreports.js

  • pullreports.min.css

  • pullreports.css

CSS and JavaScript assets to support the Pull Reports™ Ad Hoc Report Creator. Available at the following URL pattern relative to the context path of the WAR:

/[context]/assets/[filename]

For instance:

/[context]/assets/pullreports.min.js


Server Requirements

Java Virtual Machine

A Java 8 JVM.

Servlet Container

A Servlet Container which implements Servlet Specification 3.0 or higher (e.g. Tomcat 7).

Relational Database

A relational database which supports 2008 ANSI SQL.

Certified databases:

  • H2 1.4

  • MySQL 5.7

  • Oracle 12.1

  • PostgreSQL 9.4, 9.6

  • SQLServer 2016, 2017

Database compatibility

The most common database variability effecting Pull Reports™ is the implementation of limit and offset within SQL written by the Export Report REST API. By default, Pull Reports™ uses the ANSI standard offset [offset] rows fetch first [limit] rows only syntax but also implements pluggable SQL dialects for databases which do not support this syntax.

Dependency Management

Pull Reports™ recommends using dependency management software when installing Pull Reports™ into an existing JEE web application. Dependency management software such as Gradle, IVY, or Maven ensures that JARs and their transitive dependencies are automatically resolved, downloaded, and installed.

When using dependency management software with Pull Reports™, there are three general techniques for hosting JAR files: an enterprise repository, a local repository, and project-local JARs. The following examples use Gradle when discussing these three techniques in the context of Pull Reports™ installation but the technique is analogous for Maven and IVY.

Enterprise Repository

An enterprise repository is a common file or network location into which common code artifacts are installed. Nexus and Artifactory are popular open source repository management software, but a common network drive available to multiple team members may also suffice.

When publishing the Pull Reports™ JAR to an enterprise repository, include the Pull Reports™ POM descriptor in the publication so that dependency management software will resolve Pull Reports™ transitive, runtime dependencies. Most tools will automatically detect the POM file within the JAR's META-INF directory, but the POM is also available in the dist directory of the Pull Reports™ media. Nexus and Artifactory provide web interfaces and services for publishing artifacts; the Maven install:install-file plugin assists publication to a file based repository.

Once the Pull Reports™ JAR is published to an enterprise repository, include the Pull Reports™ JAR as a runtime dependency so as to download and install Pull Reports™ and all of its transitive, runtime dependencies. The following build.gradle example includes a URL based maven repository configuration and the Pull Reports™ dependency declaration.

Example 1. build.gradle fragment with enterprise maven repository configuration
repositories {
    maven {
        url "https://repo.myorganization.org/artifactory"
    }
}
dependencies {
    runtime 'com.pullreports:pullreports:1.3.1'
}

See the Gradle dependency management documentation for more repository configuration options.

Local repository

A local file repository is identical to an enterprise file repository except that it is scoped to one computer - usually within a user's home directory, (~). A local file repository can support local development but is not easily shared with other team members.

To manually publish the Pull Reports™ JAR to a local repository, place the pullreports-x.y.z.jar and pom.xml files from the Pull Reports™ media within ~/.m2/repository/com/pullreports/x.y.z/ where x.y.z is the version of the Pull Reports™ software. When copying pom.xml, rename it to pullreports-x.y.z.pom to comply with Maven repository guidelines.

For example, if publishing Pull Reports™ version 1.3.1, the local repository should be:

$ ls -1 ~/.m2/repository/com/pullreports/pullreports/1.3.1
pullreports-1.3.1.jar
pullreports-1.3.1.pom

Once the Pull Reports™ JAR is published to a local repository, include the Pull Reports™ JAR as a runtime dependency so as to download and install Pull Reports™ and all of its transitive, runtime dependencies. The following build.gradle demonstrates an example local repository configuration and the Pull Reports™ dependency declaration.

Example 2. build.gradle fragment with local maven repository configuration
repositories {
    mavenLocal()
}
dependencies {
    runtime 'com.pullreports:pullreports:1.3.1'
}

Project-local JARs

When an enterprise or local repository is not available, the Pull Reports™ JAR and all of its transitive, runtime dependencies may be installed within an application's project directly. When using project-local dependency management, know that the project must manage JAR version conflicts (e.g. two versions of the same JAR) and transitive, runtime dependencies itself. Additionally, since transitive, runtime JAR dependencies may change between Pull Reports™ versions, review each JAR within the Pull Reports™ media's lib directory with each Pull Reports™ upgrade.

To establish project-local dependency management, copy the Pull Reports™ JAR and all transitive, runtime dependency JARs into a project directory such as lib. The application build must then include these JARs within the application's classpath. The following build.gradle demonstrates a project-local Pull Reports™ dependency assuming the Pull Reports™ JAR and all transitive, runtime dependency JARs are within the project's lib directory.

Example 3. build.gradle fragment with project local Jar dependency configuration
dependencies {
    runtime fileTree(dir: 'lib', include: '*.jar')
}