Skip to main content
Version: Version 1.14

Java technical notes

Learn about technical details of the Toolbox add-on for Java.

tip

For the full API reference for the Toolbox add-on, see the Java API reference.

AutoCloseable objects​

Objects that must be closed explicitly (for example, com.pdftools.toolbox.pdf.Document or com.pdftools.toolbox.pdf.content.ContentGenerator) implement the java.lang.AutoCloseable interface. Instead of calling close() directly, use the “try-with-resources” statement:

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

Properties​

Properties are modeled with setter and getter methods.

Error handling​

Errors are reported using exceptions. Where applicable, the Toolbox add-on maps errors to corresponding native runtime exceptions, such as java.lang.IllegalArgumentException, java.lang.IllegalStateException, java.lang.UnsupportedOperationException, or java.io.IOException. The remaining errors are modeled using exception classes that inherit from a base class PdfToolsException.

Streams​

The native stream interfaces can’t be used because they’re 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.pdftools.toolbox.sys.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 and iterables​

The API uses different concepts for returning collections of elements depending on the context:

  • Lists (java.util.List) are used when the elements are already in memory and random access is possible. Depending on the context, manipulation (add, remove, and so on) might also be possible.
  • Iterables (java.util.Iterable) are used when elements are retrieved on demand. They don’t allow random access, but only allow iterating through the elements.

Maps​

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

Package​

The Toolbox add-on uses the package com.pdftools.toolbox.

note

We recommend using a custom, company-specific package for your code. Using the com.pdftools.toolbox package like the Toolbox add-on can lead to problems with ambiguous class names.