Skip to main content

Java technical notes

Learn about technical details of the Pdftools SDK for Java.

tip

For the full API reference for the Pdftools SDK, see the Java API reference.

AutoCloseable objects​

Objects that must be closed explicitly (for example, com.pdftools.pdf.Document, com.pdftools.image.Document, com.pdftools.crypto.providers.Provider, or subclasses) 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 SDK 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.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 Pdftools SDK uses the package com.pdftools.

note

We recommend using a custom, company-specific package for your code. Using the com.pdftools package like the SDK can lead to problems with ambiguous class names, especially when you use multiple Pdftools SDKs in the same project.