Skip to main content
Version: 4.4

PDF Toolbox SDK for Java

The PDF Toolbox SDK for Java lets you create PDF files using Java.

info

The PDF Toolbox SDK for Java requires Java version 7 or higher.

note

For more information on the document model, graphics model, and thread safety, see About the PDF Toolbox SDK.

tip

For the full API reference for the PDF Toolbox SDK, see the Java API reference.

Compilation​

When using the Java interface, the Java archive jar\com.pdf_tools.fourheights.pdftoolbox.jar needs to be on the CLASSPATH. This can be done by either adding it to the environment variable CLASSPATH, or by specifying it using the -classpath or -cp switch:

javac -cp ".;C:\Program Files\PDF Tools AG\jar\com.pdf_tools.fourheights.pdftoolbox.jar" ^
sampleApplication.java

Execution​

Additionally, the library needs to be in one of the system’s library directories or added to the Java system property java.library.path.

In Windows, the library is defined by the environment variable PATH.

This can be achieved by either adding this system property dynamically at program startup before using the API, or by specifying it using the switch -Djava.library.path when starting the Java VM.

Choose the correct subdirectory (win-x64 or win-x86 on Windows) depending on the platform of the Java VM3. If the wrong data model is used, there is an error message similar to this: “Can't load IA 32-bit .dll on a AMD 64-bit platform”.

java -cp ".;C:\Program Files\PDF Tools AG\com.pdf_tools.fourheights.pdftoolbox.jar" ^
"-Djava.library.path=C:\Program Files\PDF Tools AG\lib\win-x64" sampleApplication

AutoCloseable objects​

Objects that must be closed explicitly implement the AutoCloseable interface. Instead of calling close() directly, it is recommended that you use the “try ­with ­resources” statement:

try (Document document = ...) {
 ...
} // document.close() is called implicitly here

See also Garbage collection and closing objects.

Properties​

Properties are modeled with setter and getter methods.

Error handling​

Errors are reported using exceptions. The following logic errors are mapped to the corresponding native runtime exception classes and are not checked:

  • IllegalArgument maps to java.lang.IllegalArgumentException
  • IllegalState maps to java.lang.IllegalStateException
  • UnsupportedOperation maps to java.lang.UnsupportedOperationException

Additionally, the following infrastructure error is mapped:

  • IO maps to java.io.IOException The remaining errors are modeled using exception classes that inherit from a base class PdfToolboxException.

Streams​

The native stream interfaces cannot be used, because they are lacking two important features:

  • The PDF file format is based on random access. Native Java streams have only limited support for this.
  • The ability to read from an output stream is crucial for processing large files.

Instead, a custom stream interface com.pdf_tools.fourheights.pdftoolbox.Stream is provided. A FileStream implementation for files is provided, backed by java.io.RandomAccessFile. For in-memory processing, a MemoryStream implementation is provided.

Lists​

Lists implement the native Java list interface java.util.List.

Enumerables​

Enumerables (lists that only allow iterating) implement the native Java iterator interface java.util.Iterable.

Maps​

Maps implement the native Java map interface java.util.Map.