Skip to main content

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.

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. Contact 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.

Get 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​

Switch between the following tabs to display steps for the CLI (Maven or Gradle), Eclipse IDE, or IntelliJ IDEA. To compile and run the sample, follow these steps:

  1. Clone the toolbox-examples-java repository:

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

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

  3. Open toolbox-examples-java/ImageExtraction/lib/src/main/java/ToolboxImageExtraction/ToolboxImageExtraction.java, and replace the "insert-license-key-here" placeholder in the Sdk.initialize method call with your license key:

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

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

  1. Navigate to the ImageExtraction code example:

    cd toolbox-examples-java/ImageExtraction

  2. Create an output directory:

    mkdir output_images

  3. Build and run the sample to extract all images and image masks from the sample PDF file ImageCollection.pdf to the output directory output_images:

    mvn clean install
    mvn exec:java -Dexec.mainClass="ToolboxImageExtraction.ToolboxImageExtraction" -Dexec.args="ImageCollection.pdf output_images"

The code example 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 this snippet with a placeholder and compare it to the last step of the previous procedure:

mvn exec:java -Dexec.mainClass="ToolboxImageExtraction.ToolboxImageExtraction" -Dexec.args="INPUT_FILE OUTPUT_DIRECTORY"
note

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

Integrate the Toolbox add-on into your application​

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

Add the Toolbox add-on to your project​

To add the Toolbox add-on to your project, use one of the following methods:

The Toolbox add-on for Java is available on Maven Central. To add the Toolbox add-on for Java to your project, add the following to your pom.xml:

<dependency>
    <groupId>com.pdftools</groupId>
    <artifactId>toolbox</artifactId>
    <version>1.12.1</version>
</dependency>

The dependency includes native binaries for all supported platforms, which are loaded automatically at runtime.

Initialize the Toolbox add-on​

The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK). Without a valid license, every Toolbox add-on method call fails with LicenseError: No license key was set.

Getting a license key

Contact the Pdftools sales team through the Contact page to get a trial or full license.

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

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

  2. Call Sdk.initialize once at application startup, before any other Toolbox add-on method call:

    Sdk.initialize("YOUR_LICENSE_KEY", null);

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

To get a working reference with the Sdk.initialize method, follow these steps:

  1. Clone the toolbox-examples-java repository and navigate to a sample directory. For example, toolbox-examples-java/ImageExtraction.
  2. Open the main Java file and find the Sdk.initialize call. For example, the ImageExtraction Java sample includes it in lib/src/main/java/ToolboxImageExtraction/ToolboxImageExtraction.java.
  3. Replace the "insert-license-key-here" placeholder with your license key.

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.