Kernfunktionen von Aspose.PDF FOSS for Java

Einleitung

Aspose.PDF FOSS für Java ist eine MIT-lizenzierte Java-Bibliothek zum Erstellen und Bearbeiten von PDF-Dokumenten. Ihre Klassen sind im Paket org.aspose.pdf und dessen Unterpaketen (org.aspose.pdf.annotations, org.aspose.pdf.forms, org.aspose.pdf.facades und weitere) organisiert, und Document ist der Einstiegspunkt für die meisten Workflows. Die Bibliothek hat keine externen Laufzeitabhängigkeiten; die einzige Abhängigkeit im Maven-Build ist JUnit im Test-Scope.

Die Bibliotheksankündigung, der Facades-Beitrag und der Seiten-Bearbeitungs-Beitrag behandeln bereits die Dokumentenerstellung, Formularfelder, die Fassade-Klassen für Extraktion, Verschlüsselung und Stempeln sowie Seitenoperationen mit PdfFileEditor. Dieser Beitrag behandelt fünf weitere Bereiche desselben API, die in den genannten Beiträgen nicht gezeigt werden: Text-Markup-Annotationen, Freitext-Hinweise, dokumentweite Aktionen, ein Größen-Schutz beim Stream-Decoding und Diagnose-Logging.

Jeder Bereich ist ein kleines, eigenständiges API. Die untenstehenden Abschnitte zeigen die Aufrufe, die Standardwerte und die Randfälle, die durch die eigenen Tests der Bibliothek festgelegt werden.

Wichtige Funktionen

Text-Markup-Annotationen

HighlightAnnotation, UnderlineAnnotation, StrikeOutAnnotation und SquigglyAnnotation akzeptieren jeweils ein Page und ein Rectangle. Der Konstruktor leitet die Quad-Punkte der Annotation aus dem Rechteck ab, sodass getQuadPoints() acht Werte ohne manuelle Berechnung zurückgibt. Für das Rechteck (100, 200, 300, 250) ist das Ergebnis [100, 250, 300, 250, 100, 200, 300, 200]: oben-links, oben-rechts, unten-links, dann unten-rechts. setQuadPoints() ersetzt die abgeleiteten Werte durch Ihr eigenes Array mit acht Werten, und eine aus einem bestehenden Wörterbuch neu erstellte Annotation behält die dort bereits gespeicherten Quad-Punkte. getSubtype() gibt den PDF-Subtyp-Namen zurück: Highlight, Underline, StrikeOut oder Squiggly.

Das Erstellen einer Anmerkung fügt sie nicht der Seite hinzu. Fügen Sie sie mit page.getAnnotations().add(...) hinzu.

try (Document doc = new Document()) {
    Page page = doc.getPages().add();

    HighlightAnnotation highlight = new HighlightAnnotation(page, new Rectangle(100, 200, 300, 250));
    double[] quadPoints = highlight.getQuadPoints();

    UnderlineAnnotation underline = new UnderlineAnnotation(page, new Rectangle(50, 100, 200, 120));
    StrikeOutAnnotation strikeOut = new StrikeOutAnnotation(page, new Rectangle(50, 140, 200, 160));
    SquigglyAnnotation squiggly = new SquigglyAnnotation(page, new Rectangle(50, 180, 200, 200));

    page.getAnnotations().add(highlight);
    page.getAnnotations().add(underline);
    page.getAnnotations().add(strikeOut);
    page.getAnnotations().add(squiggly);
    doc.save("markup.pdf");
}

Freitext-Callouts

FreeTextAnnotation platziert Text direkt auf einer Seite. Sein Konstruktor mit drei Argumenten nimmt ein DefaultAppearance, das den Schriftartnamen, die Schriftgröße und die Textfarbe enthält. Drei Eigenschaften bestimmen den Callout:

setIntent() akzeptiert ein FreeTextIntent: FreeText, FreeTextCallout oder FreeTextTypeWriter. Eine neue Anmerkung meldet Undefined, und das Übergeben von null setzt sie in diesen Zustand zurück.
setCallout() nimmt die Callout-Linie als ein Array von zwei oder drei {x, y}-Punkten. Ein Array einer anderen Länge wird ignoriert und der bestehende Callout bleibt erhalten; null entfernt den Callout.
setEndingStyle() akzeptiert einen LineEnding-Wert wie OpenArrow oder Diamond. Eine neue Anmerkung meldet LineEnding.None.

try (Document doc = new Document()) {
    Page page = doc.getPages().add();
    DefaultAppearance da = new DefaultAppearance("Helv", 10, Color.BLACK);
    FreeTextAnnotation note = new FreeTextAnnotation(page, new Rectangle(50, 50, 200, 100), da);

    note.setContents("Check this value");
    note.setIntent(FreeTextIntent.FreeTextCallout);
    note.setCallout(new double[][] {{10, 10}, {50, 50}, {100, 100}});
    note.setEndingStyle(LineEnding.OpenArrow);

    page.getAnnotations().add(note);
    doc.save("callout.pdf");
}

Das gespeicherte Anmerkungs-Dictionary speichert diese Werte als /IT, /CL und /LE.

Aktionen auf Dokumentebene

Document.getActions() gibt eine DocumentActions Ansicht des Dokumentenkatalogs zurück. setOpenAction() speichert eine Aktion im /OpenAction Eintrag des Katalogs. Fünf weitere Trigger, setBeforeClosing(), setBeforeSaving(), setAfterSaving(), setBeforePrinting() und setAfterPrinting(), werden unabhängig im /AA Zusatzaktionen-Wörterbuch des Katalogs gespeichert.

Jeder Getter gibt null zurück, bis sein Trigger gesetzt ist. Das Übergeben von null an einen Setter entfernt diesen Eintrag, und das Entfernen des letzten Triggers entfernt ebenfalls das /AA Wörterbuch. Aktionen sind PdfAction Instanzen; GoToURIAction ist ein Alias von UriAction, und ihr getType() gibt URI zurück. Das DocumentActions Objekt ist eine Live-Ansicht, sodass ein später Aufruf von getActions() Änderungen sieht, die durch einen früheren Aufruf vorgenommen wurden, und die Trigger werden beim erneuten Öffnen der gespeicherten Datei wieder ausgelesen.

try (Document doc = new Document()) {
    doc.getPages().add();
    DocumentActions actions = doc.getActions();

    actions.setOpenAction(new GoToURIAction("https://example.com"));
    actions.setBeforeSaving(new GoToURIAction("https://example.com/saving"));

    PdfAction open = doc.getActions().getOpenAction();
    if (open instanceof UriAction) {
        System.out.println(((UriAction) open).getUri());
    }

    actions.setBeforeSaving(null);   // removes /WS; /AA is removed once it is empty
    doc.save("actions.pdf");
}

Dekodiergrenzen für Stream-Filter

PDF-Streams werden in kodierter Form gespeichert, und ein beschädigter oder bösartiger Stream kann sich weit über seine gespeicherte Größe hinaus ausdehnen. DecodeLimits ist eine Schutzvorrichtung, die von den Filtern FlateDecode, LZWDecode und RunLengthDecode gemeinsam genutzt wird. Wenn die dekodierte Ausgabe eines Streams die Obergrenze überschreitet, wirft der Filter DecodeSizeLimitException, eine Unterklasse von IOException, anstatt weiter zu dekodieren, bis der Heap erschöpft ist.

Die Standardobergrenze beträgt 256MB pro dekodiertem Stream (DecodeLimits.DEFAULT_MAX_DECODED_BYTES). Um sie zu ändern, setzen Sie die System-Property, deren Name durch DecodeLimits.PROPERTY angegeben wird, und die aspose.pdf.maxDecodedStreamBytes ist, auf eine Größe in Bytes; ein Wert von 0 oder weniger deaktiviert den Schutz. Die Property wird bei jeder Dekodierung gelesen, sodass sie zur Laufzeit geändert werden kann.

static byte[] decodeFlate(byte[] encoded) {
    // Lower the cap to 16 MB (16777216 bytes) for this process
    System.setProperty(DecodeLimits.PROPERTY, "16777216");
    try {
        return new FlateFilter().decode(encoded, null);
    } catch (IOException e) {
        // "FlateDecode: decoded output exceeds 16777216 bytes - likely a corrupt stream
        //  or decompression bomb (override with -Daspose.pdf.maxDecodedStreamBytes)"
        return null;
    }
}

Streams, die unterhalb der Obergrenze liegen, werden wie üblich dekodiert. FlateFilter und RunLengthFilter führen beide einen Round-Trip von Daten über encode() und decode() durch, wenn die Ausgabe unter dem Limit bleibt.

Diagnostisches Logging

Die Bibliothek protokolliert über java.util.logging unter dem org.aspose.pdf Logger und ist standardmäßig stumm: Das Niveau ist OFF. AsposePdfLogging schaltet das Logging ein.

setLevel(Level) setzt das Level aus dem Code; null setzt die Bibliothek zurück auf OFF. getLevel() liest es wieder ein.
Die System-Property aspose.pdf.log (auch verfügbar als AsposePdfLogging.LOG_PROPERTY) setzt sie über die Befehlszeile. configureFromSystemProperty() wendet die Property an und wird außerdem ausgeführt, wenn die Klasse geladen wird. Die Werte on und warning wählen WARNING aus, verbose wählt FINE aus, debug wählt ALL aus, jeder java.util.logging.Level-Name wie SEVERE wird akzeptiert, und ein nicht erkannter Wert fällt zurück auf OFF.

WARNING lässt die Warnungen der Engine durch; FINE, die Einstellung verbose, lässt ebenfalls die Wiederherstellungsdetails des Parsers durch. AsposePdfLogging ändert nur den org.aspose.pdf-Logger-Teilbaum. Es ändert nicht das Level des Root-Loggers, und der Bibliotheks-Logger leitet keine Einträge an die Handler des Root-Loggers weiter. Wenn das Logging aktiviert ist und kein Handler an den Bibliotheks-Logger angehängt ist, wird ein Konsolen-Handler installiert.

// Equivalent to starting the JVM with -Daspose.pdf.log=warning
AsposePdfLogging.setLevel(Level.WARNING);

System.setProperty(AsposePdfLogging.LOG_PROPERTY, "verbose");
AsposePdfLogging.configureFromSystemProperty();
System.out.println(AsposePdfLogging.getLevel());   // FINE

Schnellstart

Fügen Sie die Abhängigkeit zu Ihrem Build hinzu:

<dependency>
  <groupId>org.aspose</groupId>
  <artifactId>aspose-pdf-foss</artifactId>
  <version>26.8.0</version>
</dependency>

Das folgende Beispiel erstellt eine Seite, fügt eine Hervorhebung und einen Freitext-Hinweis hinzu und speichert das Dokument:

import org.aspose.pdf.*;
import org.aspose.pdf.annotations.*;

try (Document doc = new Document()) {
    Page page = doc.getPages().add();

    page.getAnnotations().add(new HighlightAnnotation(page, new Rectangle(100, 200, 300, 250)));

    FreeTextAnnotation note = new FreeTextAnnotation(page, new Rectangle(50, 50, 200, 100),
            new DefaultAppearance("Helv", 10, Color.BLACK));
    note.setContents("Check this value");
    note.setIntent(FreeTextIntent.FreeTextCallout);
    note.setCallout(new double[][] {{10, 10}, {50, 50}, {100, 100}});
    page.getAnnotations().add(note);

    doc.save("core-features.pdf");
}

Unterstützte Formate

Formatunterstützung, wie durch die Lade- und Speicheroptionen sowie Rendering-Geräte der Bibliothek bestätigt:

Format	Erweiterung	Lesen	Schreiben
PDF	pdf	✓	✓
HTML	html	✓	✓
DOCX	docx	✓	✓
DOC	doc	✓	✓
XFDF	xfdf	✓	✓
BMP	bmp	—	✓
GIF	gif	—	✓
JPEG	jpeg	—	✓
TIFF	tiff	—	✓
Text	txt	—	✓

Open Source & Lizenzierung

Aspose.PDF FOSS für Java wird unter der MIT-Lizenz veröffentlicht, die kommerzielle Nutzung, Modifikation und Weiterverteilung erlaubt. Der Quellcode und das Issue-Tracking befinden sich unter github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Java. Die Bibliothek richtet sich an Java 11 oder neuer.

Einleitung

Wichtige Funktionen

Text-Markup-Annotationen

Freitext-Callouts

Aktionen auf Dokumentebene

Dekodiergrenzen für Stream-Filter

Diagnostisches Logging

Schnellstart

Unterstützte Formate

Open Source & Lizenzierung

Erste Schritte

Verwandte Ressourcen

Einleitung#

Wichtige Funktionen#

Text-Markup-Annotationen#

Freitext-Callouts#

Aktionen auf Dokumentebene#

Dekodiergrenzen für Stream-Filter#

Diagnostisches Logging#

Schnellstart#

Unterstützte Formate#

Open Source & Lizenzierung#

Erste Schritte#

Verwandte Ressourcen#

Einleitung

Wichtige Funktionen

Text-Markup-Annotationen

Freitext-Callouts

Aktionen auf Dokumentebene

Dekodiergrenzen für Stream-Filter

Diagnostisches Logging

Schnellstart

Unterstützte Formate

Open Source & Lizenzierung

Erste Schritte

Verwandte Ressourcen