Kernfuncties van Aspose.PDF FOSS for Java

Inleiding

Aspose.PDF FOSS voor Java is een MIT-gelicentieerde Java bibliotheek voor het maken en bewerken van PDF-documenten. De klassen zijn georganiseerd onder het org.aspose.pdf pakket en de subpakketten (org.aspose.pdf.annotations, org.aspose.pdf.forms, org.aspose.pdf.facades en andere), en Document is het toegangspunt voor de meeste werkstromen. De bibliotheek heeft geen runtime-afhankelijkheden van derden; de enige afhankelijkheid in de Maven-build is JUnit, op test-scope.

De bibliotheekaankondiging, het facades-bericht, en het pagina-bewerkingsbericht behandelen al documentcreatie, formuliervelden, de façade-klassen voor extractie, versleuteling en stempeling, en paginabewerkingen met PdfFileEditor. Dit bericht behandelt vijf andere gebieden van dezelfde API die die berichten niet laten zien: tekst-opmaakannotaties, vrije-tekst-callouts, document-niveau-acties, een grootte-bewaking bij stream-decodering, en diagnostische logging.

Elk gebied is een kleine, zelfstandige API. De onderstaande secties tonen de aanroepen, de standaardwaarden en de randgevallen die de eigen tests van de bibliotheek vastleggen.

Belangrijkste kenmerken

Tekst-opmaakannotaties

HighlightAnnotation, UnderlineAnnotation, StrikeOutAnnotation en SquigglyAnnotation nemen elk een Page en een Rectangle. De constructor bepaalt de quad-punten van de annotatie aan de hand van de rechthoek, dus getQuadPoints() retourneert acht waarden zonder handmatige berekening. Voor de rechthoek (100, 200, 300, 250) is het resultaat [100, 250, 300, 250, 100, 200, 300, 200]: links-boven, rechts-boven, links-onder, dan rechts-onder. setQuadPoints() vervangt de berekende waarden door uw eigen acht-waarde array, en een annotatie die is herbouwd vanuit een bestaande dictionary behoudt de al opgeslagen quad-punten. getSubtype() retourneert de PDF-subtype-naam: Highlight, Underline, StrikeOut of Squiggly.

Het construeren van een annotatie voegt deze niet toe aan de pagina. Voeg het toe met page.getAnnotations().add(...).

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");
}

Vrije-tekst-callouts

FreeTextAnnotation plaatst tekst direct op een pagina. De drie-argumenten-constructor neemt een DefaultAppearance, die de lettertype-naam, lettergrootte en tekstkleur bevat. Drie eigenschappen vormen de callout:

• setIntent() neemt een FreeTextIntent: FreeText, FreeTextCallout of FreeTextTypeWriter. Een nieuwe annotatie rapporteert Undefined, en het doorgeven van null brengt het terug naar die toestand.
• setCallout() neemt de callout-lijn als een array van twee of drie {x, y} punten. Een array van een andere lengte wordt genegeerd en de bestaande callout blijft op zijn plaats; null verwijdert de callout.
• setEndingStyle() neemt een LineEnding waarde zoals OpenArrow of Diamond. Een nieuwe annotatie rapporteert 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");
}

Het opgeslagen annotatiedictionary slaat deze waarden op als /IT, /CL en /LE.

Acties op documentniveau

Document.getActions() retourneert een DocumentActions weergave van de documentcatalogus. setOpenAction() slaat een actie op in de /OpenAction invoer van de catalogus. Vijf extra triggers, setBeforeClosing(), setBeforeSaving(), setAfterSaving(), setBeforePrinting() en setAfterPrinting(), worden onafhankelijk opgeslagen in het /AA extra-acties woordenboek van de catalogus.

Elke getter retourneert null totdat zijn trigger is ingesteld. Het doorgeven van null aan een setter verwijdert die invoer, en het verwijderen van de laatste trigger verwijdert ook het /AA woordenboek. Acties zijn PdfAction instanties; GoToURIAction is een alias van UriAction, en zijn getType() retourneert URI. Het DocumentActions object is een live weergave, dus een latere aanroep van getActions() ziet de wijzigingen die via een eerdere zijn aangebracht, en de triggers worden opnieuw gelezen wanneer het opgeslagen bestand opnieuw wordt geopend.

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");
}

Decodeerlimieten voor streamfilters

PDF-streams worden opgeslagen in gecodeerde vorm, en een corrupte of kwaadaardige stream kan uitgroeien tot veel meer dan de opgeslagen grootte. DecodeLimits is een bewaker die wordt gedeeld door de FlateDecode, LZWDecode, en RunLengthDecode filters. Wanneer de gedecodeerde output van een stream de limiet overschrijdt, gooit het filter DecodeSizeLimitException, een subklasse van IOException, in plaats van te blijven decoderen totdat de heap uitgeput is.

De standaardlimiet is 256MB per gedecodeerde stream (DecodeLimits.DEFAULT_MAX_DECODED_BYTES). Om deze te wijzigen, stel de systeem-property in die wordt genoemd door DecodeLimits.PROPERTY, welke aspose.pdf.maxDecodedStreamBytes is, in op een grootte in bytes; een waarde van 0 of minder schakelt de bewaker uit. De property wordt bij elke decode gelezen, zodat deze tijdens runtime kan worden aangepast.

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 onder de limiet decoderen zoals gewoonlijk. FlateFilter en RunLengthFilter voeren beide data round-trip uit via encode() en decode() wanneer de output onder de limiet blijft.

Diagnostische logging

De bibliotheek logt via java.util.logging onder de org.aspose.pdf logger en is standaard stil: het niveau is OFF. AsposePdfLogging zet logging aan.

• setLevel(Level) stelt het niveau in vanuit code; null zet de bibliotheek terug naar OFF. getLevel() leest het terug.
• De aspose.pdf.log systeemproperty (ook beschikbaar als AsposePdfLogging.LOG_PROPERTY) stelt het in vanaf de commandoregel. configureFromSystemProperty() past de property toe en wordt ook uitgevoerd wanneer de klasse wordt geladen. De waarden on en warning selecteren WARNING, verbose selecteert FINE, debug selecteert ALL, elke java.util.logging.Level naam zoals SEVERE wordt geaccepteerd, en een niet-herkende waarde valt terug op OFF.

WARNING laat de waarschuwingen van de engine door; FINE, de verbose instelling, laat ook de hersteldetails van de parser door. AsposePdfLogging wijzigt alleen de org.aspose.pdf logger-subboom. Het verandert het niveau van de root-logger niet, en de bibliotheeklogger stuurt geen records naar de handlers van de root-logger. Als logging is ingeschakeld en er geen handler is gekoppeld aan de bibliotheeklogger, wordt er een consolehandler geïnstalleerd.

// 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

Snelstart

Voeg de afhankelijkheid toe aan je build:

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

Het volgende voorbeeld maakt een pagina, voegt een markering en een vrije-tekst-opmerking toe, en slaat het document op:

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");
}

Ondersteunde formaten

Formaatsondersteuning zoals bevestigd door de laad- en slaopties van de bibliotheek en renderapparaten:

Open source & licenties

Aspose.PDF FOSS voor Java is uitgebracht onder de MIT-licentie, die commercieel gebruik, modificatie en herdistributie toestaat. De broncode en issue-tracker zijn te vinden op github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Java. De bibliotheek richt zich op Java 11 of hoger.

Aan de slag

• Aan de slag
• Ontwikkelaarsgids
• KB-artikelen
• API Reference

Gerelateerde bronnen

• Aspose.PDF — Enterprise Blog
• Aspose.PDF for Java — Enterprise Product