Skip to main content
Version: Version 1.0

Get started with Java

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

Prerequisites​

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

Getting started with a sample project​

Learn how to use the Toolbox add-on using a Java code example. The ImageExtraction example extracts all images and image masks from a PDF document. Use similar steps to run any other code example from the toolbox-examples-java repository.

Compile and run the sample​

  1. Clone the toolbox-examples-java repository:

    git clone https://github.com/pdf-tools/toolbox-examples-java.git

  2. In the ToolboxImageExtraction.java file, replace the string "YOUR_LICENSE_KEY" with your license key:

    Sdk.initialize("YOUR_LICENSE_KEY", null);

  3. Compile the Java source file:

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

  4. Run the sample:

    java -cp jar/com.pdftools.toolbox.jar:bin:. ToolboxImageExtraction <inputpath> <outputdir>

    For example, to extract all images and image masks from the sample PDF file ImageCollection.pdf to the output directory /tmp/images, run:

    java -cp jar/com.pdftools.toolbox.jar:bin:. ToolboxImageExtraction ImageCollection.pdf /tmp/images
note

You can apply a similar procedure as described in this tutorial for other code examples. 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 next 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.0.0</version>
</dependency>
<dependency>
    <groupId>com.pdftools</groupId>
    <artifactId>toolbox</artifactId>
    <version>1.0.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.0.0/toolbox-1.0.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.0.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 Toolbox add-on​

After loading the native binary files the final step before using the Toolbox add-on is to initialize it with your license key. Replace YOUR_LICENSE_KEY in the following method with the value of your license key:

Sdk.initialize("YOUR_LICENSE_KEY", null);
tip

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

Implement your use case​

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