Introduction

Aspose.PDF FOSS for Java is an MIT-licensed Java library for creating and manipulating PDF documents. It is available on GitHub under the MIT license and requires no API key or commercial agreement. The library exposes 527 classes covering the complete PDF specification from document structure to annotations, interactive forms, page rendering, and cryptographic operations.

The library is built around the Document class, which is the central entry point for all PDF operations. Creating a new document, accessing pages via PageCollection, reading metadata through DocumentInfo, or navigating the catalog via getCatalog() and getTrailer() — all begin with a Document instance.

Quick Start

Add the Maven dependency to your pom.xml:

<dependency>
  <groupId>org.aspose</groupId>
  <artifactId>aspose-pdf</artifactId>
  <version>0.1.0-alpha</version>
</dependency>

The library organises all public API classes under three packages. Add these package declarations to any Java source file that uses the API:

// Core API — Document, Page, Annotation, Form, etc.
org.aspose.pdf.*
// Annotation subclasses
org.aspose.pdf.annotations.*
// Facade classes — PdfFileEditor, PdfAnnotationEditor, etc.
org.aspose.pdf.facades.*

Aspose.PDF FOSS for Java requires Java 11 or later. The source code and issue tracker are available at https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Java.

Getting Started

Create and save a minimal document to verify the setup:

try (Document doc = new Document()) {
    PageCollection pages = doc.getPages();
    Page page = pages.add();
    doc.save("output.pdf");
    System.out.println("Pages: " + pages.getCount());
}

The Document class constructor accepts a file path or stream for accessing existing files, or can be called with no arguments to create a blank document. Pages are managed through PageCollection, accessible via Document.getPages(). Each Page exposes its geometry via getMediaBox(), getCropBox(), and getRotate(), and gives access to resources, content operators, and annotations.

try (Document doc = new Document()) {
    PageCollection pages = doc.getPages();
    Page page = pages.add();
    // page.getMediaBox() -> Rectangle with width/height
    // page.getAnnotations() -> AnnotationCollection
    doc.save("output.pdf");
}

The PdfFileEditor class provides concatenate() for merging multiple documents and resizeContents() with ContentsResizeParameters for adjusting content layout within existing page boundaries.

Annotations

Aspose.PDF FOSS for Java implements the full PDF annotation hierarchy rooted at the abstract Annotation class. Concrete annotation types include WidgetAnnotation for form controls, FreeTextAnnotation for text callouts, HighlightAnnotation and UnderlineAnnotation for markup, and CircleAnnotation and CaretAnnotation for graphical notes.

Each annotation is associated with a Page and a Rectangle defining its location. Visual properties are controlled through AppearanceCharacteristics, which exposes setBorder(), setBackground(), setRotate(), and setCaption() methods. Annotations are added to a page via page.getAnnotations().add(annotation).

try (Document doc = new Document()) {
    PageCollection pages = doc.getPages();
    Page page = pages.add();
    WidgetAnnotation w = new WidgetAnnotation(page, new Rectangle(0, 0, 100, 50));
    w.getCharacteristics().setBorder(Color.fromRgb(1, 0, 0));
    w.getCharacteristics().setCaption("Submit");
    page.getAnnotations().add(w);
    doc.save("annotated.pdf");
}

Interactive Form Fields

The Form class, accessible via Document.getForm(), manages all AcroForm fields. The library provides ButtonField, CheckboxField, RadioButtonField, TextBoxField, ComboBoxField, and ListBoxField for building fillable forms. FormEditor is a facade class for working with form fields in a bound document.

Radio button groups are created with RadioButtonField, which accepts a page and supports addOption() to add selectable choices, each associated with a Rectangle for its visual location. The setValue() method programmatically selects an option.

try (Document doc = new Document()) {
    PageCollection pages = doc.getPages();
    Page page = pages.add();
    RadioButtonField radio = new RadioButtonField(page);
    radio.setPartialName("answer");
    radio.addOption("Yes", new Rectangle(50, 50, 70, 70));
    radio.addOption("No", new Rectangle(50, 80, 70, 100));
    doc.getForm().add(radio, 1);
    radio.setValue("Yes");
    doc.save("form.pdf");
}

Security: AES Encryption

The AESCipher class implements AES encryption in CBC mode for encrypting and decrypting data byte arrays embedded in PDF documents. AESCipher.encrypt(key, data) returns the encrypted ciphertext, and AESCipher.decrypt(key, data) retrieves the original plaintext. For explicit IV control, encryptWithIV(key, iv, plaintext) and decryptWithIV(key, iv, cipherText) provide deterministic operation.

PDF/A Compliance Validation

The library includes ActionRules and ActionFixes for PDF/A compliance validation and correction. ActionRules.validate() checks for forbidden actions in catalog, page, and widget entries. ActionFixes provides methods such as removeCatalogAA(), removePageAA(), and removeWidgetAA() to fix non-compliant action dictionaries. Similarly, AnnotationRules and AnnotationFixes handle annotation compliance.

Artifacts: Headers, Footers, and Watermarks

The Artifact class models page decorations such as headers, footers, watermarks, and background images. ArtifactCollection, accessible via page resources, allows enumeration and removal of artifact objects. Iterating page.getArtifacts() and calling ArtifactCollection.delete(artifact) removes specific artifacts without modifying document content streams directly.

Page Rendering

The BmpDevice class renders PDF pages directly to BMP image files using process(page, outputPath). This is useful for thumbnail generation, document preview, or image-based processing pipelines.