Installation and Setup

Requirements

PDFxStream requires Java 11 or higher, and otherwise has no other dependencies.

Classpath Configuration

An application's classpath must be changed in order for PDFxStream's classes to be available from the application's code. For example, if an application's runtime classpath is:

.:lib/:lib/yourapplication.jar:ext/resources/

and the PDFxStream jar is in the lib directory, then you should modify the application's classpath to be:

.:lib/:lib/yourapplication.jar:ext/resources/:lib/pdfxstream.jar

These classpath examples are suitable for a Unix/Linux/BSD system. The appropriate classpath for a Windows system would be the same as above, except using semicolons (;) instead of colons, and backslashes (\) instead of forward slashes.

Acquiring PDFxStream via Maven

We maintain a public Maven repository containing artifacts of all PDFxStream releases. If your project uses Maven, or another project-management tool that can consume artifacts from Maven repositories (e.g. Ant, Gradle, Leiningen, and so on), you can add the Snowtide repository and the PDFxStream dependency to your project configuration so as to avoid manually configuring classpaths.

Information about the Snowtide Maven repository and the PDFxStream dependency metadata is available on the PDFxStream downloads page.

Licensing

PDFxStream uses "license files" (plain-text files, usually named pdfxstream.license, containing key/value information about your subscription) to control access to its full capabilities.

Trial/free mode

When using PDFxStream without a license file, it will operate in a trial mode:

• It will allow only 50 documents to be opened within the first hour of your application's runtime
• It will allow only 10 documents to be opened within each successive hour of your application's runtime

These limitations are often sufficient to technically evaluate PDFxStream, and may well be sufficient even for "minor" production use of PDFxStream without a purchased subscription and its corresponding license file. However, special temporary evaluation license files are available for those who want or need to test PDFxStream more strenuously than its evaluation mode will allow; just submit your information via our evaluation license file request form to receive such a temporary license file for your evaluation purposes.

"Registering" your license file

Once you activate your PDFxStream subscription(s), you'll receive the corresponding license file(s).

Your license file should be named pdfxstream.license. Deploying this file alongside PDFxStream and registering it properly will remove its trial mode limitations.

Registering a license file with PDFxStream can be accomplished in many ways:

1. Place the pdfxstream.license file in your application's current directory, and PDFxStream will load it automatically.

2. Place the pdfxstream.license file at a Java classpath root.

   For example, if an application's classpath is .:lib/:lib/yourapplication.jar:ext/resources/, then the license file could be placed in lib or ext/resources/ or at the top-level of any JAR file on the classpath in order to be automatically recognized.

3. Specify the location of the license file at runtime, rather than at application startup or through configuration. This may be done by calling the com.snowtide.PDF.loadLicense(String) method. That method may be called at any time to load and verify a license file at the specified path.

4. Set the pdfxs_license_path environment variable to the full path where the pdfxstream.license file may be found. For example, if you copy the pdfxstream.license file to the C:\WINDOWS directory, this can be done from the command line by issuing this command:

   set pdfxs_license_path="C:\WINDOWS\pdfxstream.license"

   Your application server or other platform facilities may also offer ways to set environment variables.

5. Set the pdfxs_license_path system property to the full path where the pdfxstream.license file may be found. In Java, this can be done either by setting the system property before using PDFxStream by calling the java.lang.System.setProperty(String, String) method, or by specifying the full path of the license file's location using a –D argument to the JVM, such as –Dpdfxs_license_path=~/pdfxstream.license.

   Your application server or other platform facilities may also offer ways to set Java system properties.

Subscription license control

When a license file is successfully "registered", PDFxStream will occasionally "ping" a Snowtide service to check the status of its associated subscription. This happens extremely infrequently, and is designed to be inconsequential to your usage of PDFxStream and the performance and runtime of your application. Read more about PDFxStream's telemetry here.

Configuration

PDFxStream offers a number of configuration options, all of which are exposed via the com.snowtide.pdf.Configuration class. Read more about PDFxStream configuration here.