Skip to main content

Get started with Java

This guide walks you through the steps to use a sample project, and then explains how to integrate the Toolbox add-on into your application with the Java programming language.

Request trial or full license​

The Toolbox add-on requires a license key for both evaluation and full use. To request a license key, follow these steps:

  1. Reach out to the sales team through the Contact page and mark the Toolbox add-on as the product of your interest for a trial license.

If you already have a license key and you need to copy it, review Find the license key.

Prerequisites​

The Toolbox add-on for Java requires Java version 8 or higher.

Getting started with a sample project​

Learn how to use Toolbox add-on using a Java sample project and extract all images and image masks from a PDF document.

Compile and run the sample​

To compile and run the sample, follow these steps:

  1. Download a sample project, and then unzip the file.

  2. Locate your license key. For more information, review Find the license key.

  3. In the ToolboxImageExtraction.java file, replace the string "insert-license-key-here" with your license key:

    Sdk.initialize("insert-license-key-here", null);

    Use the license key in the same format as you copied it. Include the less-than (<) and greater-than (>) signs.

  4. In the command line, navigate to the root directory of the unzipped sample project.

  5. Create an output directory:

    mkdir output_images

  6. Compile the Java source file:

    javac -cp jar/com.pdftools.toolbox.jar:. ToolboxImageExtraction.java

  7. To extract all images and image masks from the sample PDF file ImageCollection.pdf to the output directory /output_images, run the following command:

    java -cp jar/com.pdftools.toolbox.jar:bin:. ToolboxImageExtraction ImageCollection.pdf /output_images

The code sample takes:

  • The input and output files represented as a file name, a file path with the file name, or the output directory.
  • Both file paths (input and output) can be relative or absolute.

Review the following snippet with a placeholder and compare it to the last step of the previous procedure:

java -cp jar/com.pdftools.toolbox.jar:bin:. ToolboxImageExtraction INPUT_FILE OUTPUT_DIRECTORY
note

You can apply a similar procedure described in this tutorial for other code samples. For more information, see Code samples page.

Integrate the SDK into your application​

Integrate and initialize the Toolbox add-on into your application by following the instructions in the following sections.

Add the SDK to your project​

The Toolbox add-on for Java is available on Maven. To add the Toolbox add-on for Java to your project, select your operating system and system architecture and add the following to your pom.xml:

<dependency>
    <groupId>com.pdftools</groupId>
    <artifactId>toolbox</artifactId>
    <version>1.11.0</version>
</dependency>
<dependency>
    <groupId>com.pdftools</groupId>
    <artifactId>toolbox</artifactId>
    <version>1.11.0</version>
    <classifier>linux-x64</classifier>
    <type>so</type>
</dependency>

Load the Toolbox add-on​

The Toolbox add-on for Java requires you to load the underlying native binary files suitable for your operating system and system architecture at runtime.

There are two ways how to load the Toolbox add-on for Java with Maven:

  1. If you are consuming Java libraries directly from the local Maven repository, load the native binary files using the following code:

    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.11.0/toolbox-1.11.0-linux-x64.so");

  2. Alternatively, use the system library path:

    1. Add the Toolbox add-on lib directory to the system library path.

      • Windows: Environment variable PATH
      • Linux and macOS: Defined by LD_LIBRARY_PATH
      • Or specify the path using the VM arg -Djava.library.path=.

    2. Load the library using:

      System.loadLibrary("toolbox-1.11.0-linux-x64");
note

Note the difference between:

  • System.load(..): Loads the library from an absolute file path.
  • System.loadLibrary(..): Load the library from the system’s library path.
info

If you are shipping your application, ensure to ship it with the native binary files. Note that you must load the native binary files from the file system and cannot load them from within a jar file or other bundle.

Initialize the SDK​

The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK).

Getting a license key

Without a valid license key the Toolbox add-on returns an error. Get in touch with the Pdftools sales team through the Contact page to get a full license.

To initialize the Toolbox add-on with your license key, follow these steps:

  1. Locate your license key. For more information, review Find the license key.

  2. Before you call any function of the Toolbox add-on, first call the Sdk.initialize method.

    Sdk.initialize("insert-license-key-here", null);

    Replace insert-license-key-here with the value of your license key. Use the license key in the same format as you copied it. Include the less-than (<) and greater-than (>) signs.

To get a code sample with the Sdk.initialize method that you can use as a reference for your code, follow these steps:

  1. On the Code samples page, download and unzip a Java code sample. For example: Download Extract all images and image masks from a PDF sample.
  2. Unzip the file, and then find the Sdk.initialize method in the main Java file of the sample. For example: Extract all images and image masks from a PDF sample includes SDK.initialize method in the ToolboxImageExtraction.java file.
  3. Replace insert-license-key-here with your license key.

Implement your use case​

  • Find more use cases and sample projects on the Code samples page.
  • For more technical information about the Toolbox add-on for Java, consult the Java technical notes.