Skip to main content
Version: Version 1.14

Get started with Java

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

tip

Try the Pdftools SDK without a license key.

Prerequisites​

The Pdftools SDK for Java requires Java version 8 or higher.

Getting started with a sample project​

Learn how to use the Pdftools SDK using a Java code example. The Pdf2ImgSimple example converts a PDF file to an image. Use similar steps to run any other code example from the sdk-examples-java repository.

Compile and run the sample​

Switch between the following tabs to display steps for the command line interface or for the Eclipse IDE. To compile and run the sample, follow these steps:

  1. Clone the sdk-examples-java repository:

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

  2. From the cloned repository, import the .project file into the Eclipse IDE. The source file PdfToolsPdf2ImgSimple.java is compiled automatically.

  3. Right-click the java file, and then select PdfToolsPdf2ImgSimple.java > Run As > Run configurations….

  4. Create a new configuration for a Java Application, and then add the required arguments, for example:

    PdfPrimerWhitepaper.pdf OutputPdfPrimerWhitePaper.tiff
note

You can apply a similar procedure 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 Pdftools SDK into your application by following the instructions in the following sections.

Add the SDK to your project​

The Pdftools SDK for Java is available on Maven. To add the Pdftools SDK 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>pdftools-sdk</artifactId>
    <version>1.14.0</version>
</dependency>
<dependency>
    <groupId>com.pdftools</groupId>
    <artifactId>pdftools-sdk</artifactId>
    <version>1.14.0</version>
    <classifier>linux-x64</classifier>
    <type>so</type>
</dependency>

Load the SDK​

The Pdftools SDK 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 Pdftools SDK 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/pdftools-sdk/1.14.0/pdftools-sdk-1.14.0-linux-x64.so");

  2. Alternatively, use the system library path:

    1. Add the Pdftools SDK 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("pdftools-sdk-1.14.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.

Optional: Initialize the SDK​

Learn how to remove watermarked output of the Pdftools SDK using a valid license key.

tip

Initialization removes watermarks from output files and readies the SDK for production. Without a license key, output files carry a watermark.

Getting a license key

Contact the Pdftools sales team through the Contact page to get a full license. For additional information, review Pdftools SDK license management.

To remove watermarks, 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 Pdftools SDK method call:

    Sdk.initialize("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. On the Code samples page, clone a sample repository. For example, clone sdk-examples-java and navigate to sdk-examples-java/Pdf2ImgSimple.
  2. Find the Sdk.initialize method in the main Java file of the sample. For example: Convert PDF to image sample includes Sdk.initialize method in the PdfToolsPdf2ImgSimple.java file.
  3. Uncomment the call and 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 Pdftools SDK for Java, consult the Java technical notes.
  • If you need to configure a proxy, review Configure proxy documentation section.