Bevezetés

Aspose.PDF FOSS for Java egy MIT licenc alatt álló Java könyvtár PDF dokumentumok létrehozásához és szerkesztéséhez. Osztályai a org.aspose.pdf csomag és alkönyvtárai (org.aspose.pdf.annotations, org.aspose.pdf.forms, org.aspose.pdf.facades és egyéb) alatt vannak elrendezve, és a Document a legtöbb munkafolyamat belépési pontja. A könyvtárnak nincsenek harmadik fél által biztosított futásidejű függőségei; az egyetlen függőség a Maven buildben a JUnit, teszt hatókörben.

A könyvtár bejelentése, a facade poszt, és a oldal-szerkesztés poszt már lefedik a dokumentum létrehozását, űrlapmezőket, a kinyeréshez, titkosításhoz és pecsételéshez használt facade osztályokat, valamint a PdfFileEditor segítségével végzett oldal műveleteket. Ez a poszt öt további területet tárgyal ugyanabból a API-ból, amelyeket a korábbi posztok nem mutatnak be: szöveg-jelölő annotációk, szabad szöveges felhívások, dokumentumszintű műveletek, méretkorlátozás a stream dekódolásnál, és diagnosztikai naplózás.

Minden terület egy kicsi, önálló API. Az alábbi szekciók bemutatják a hívásokat, az alapértelmezéseket és a szélsőséges eseteket, amelyeket a könyvtár saját tesztjei rögzítenek.

Főbb jellemzők

Szövegjelölő annotációk

HighlightAnnotation, UnderlineAnnotation, StrikeOutAnnotation és SquigglyAnnotation mindegyik egy Page-t és egy Rectangle-t fogad. A konstruktor a téglalapból származtatja az annotáció négyzet pontjait, így a getQuadPoints() nyolc értéket ad vissza manuális számítás nélkül. A (100, 200, 300, 250) téglalap esetén az eredmény [100, 250, 300, 250, 100, 200, 300, 200]: bal-fent, jobb-fent, bal-lent, majd jobb-lent. A setQuadPoints() felülírja a származtatott értékeket a saját nyolcértékű tömbjével, és egy meglévő szótárból újjáépített annotáció megtartja a már ott tárolt négyzet pontokat. A getSubtype() visszaadja a PDF al-típus nevét: Highlight, Underline, StrikeOut vagy Squiggly.

Az annotáció létrehozása nem csatolja azt az oldalhoz. Add hozzá a page.getAnnotations().add(...) segítségével.

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

Szabad szöveges felhívások

FreeTextAnnotation közvetlenül az oldalra helyezi a szöveget. Három argumentumos konstruktorja egy DefaultAppearance típust fogad, amely a betűtípus nevét, méretét és a szöveg színét tartalmazza. Három tulajdonság alakítja a felhívást:

  • setIntent() egy FreeTextIntent típust vár: FreeText, FreeTextCallout vagy FreeTextTypeWriter. Egy új annotáció Undefined értéket jelent, és a null átadása visszaállítja azt az állapotba.
  • setCallout() a felhívás vonalát két vagy három {x, y} pontból álló tömbként veszi. A más hosszúságú tömböt figyelmen kívül hagyja, és a meglévő felhívás helyben marad; a null eltávolítja a felhívást.
  • setEndingStyle() egy LineEnding értéket fogad, például OpenArrow vagy Diamond. Egy új annotáció LineEnding.None értéket jelent.
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");
}

A mentett annotációszótár ezeket az értékeket /IT, /CL és /LE kulcsok alatt tárolja.

Dokumentumszintű műveletek

Document.getActions() visszaad egy DocumentActions nézetet a dokumentumkatalógusról. setOpenAction() egy műveletet tárol a katalógus /OpenAction bejegyzésében. További öt trigger, setBeforeClosing(), setBeforeSaving(), setAfterSaving(), setBeforePrinting() és setAfterPrinting(), önállóan tárolódik a katalógus /AA additional-actions szótárában.

Minden getter null értéket ad vissza, amíg a trigger be nincs állítva. null átadása egy setternek eltávolítja azt a bejegyzést, és az utolsó trigger eltávolítása szintén törli a /AA szótárat. A műveletek PdfAction példányok; GoToURIAction egy alias a UriAction számára, és a getType() visszaadja a URI értéket. A DocumentActions objektum egy élő nézet, így egy későbbi hívás a getActions() esetén látja az előző hívás által végrehajtott változtatásokat, és a triggerek visszaolvasásra kerülnek, amikor a mentett fájlt újra megnyitják.

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

Stream szűrők dekódolási korlátai

A PDF stream-ek kódolt formában vannak tárolva, és egy sérült vagy rosszindulatú stream jóval nagyobbra nőhet, mint a tárolt mérete. DecodeLimits egy védelmi mechanizmus, amelyet a FlateDecode, az LZWDecode és a RunLengthDecode szűrők osztanak meg. Amikor egy stream dekódolt kimenete meghaladja a korlátot, a szűrő DecodeSizeLimitException kivételt dob, amely a IOException alosztálya, ahelyett, hogy a heap kimerüléséig dekódolna.

Az alapértelmezett korlát 256MB dekódolt stream-enként (DecodeLimits.DEFAULT_MAX_DECODED_BYTES). A módosításhoz állítsa be a DecodeLimits.PROPERTY által megnevezett rendszer tulajdonságot, amely aspose.pdf.maxDecodedStreamBytes, a kívánt méretet bájtokban; a 0 vagy kisebb érték letiltja a védelmet. A tulajdonság minden egyes dekódoláskor beolvasásra kerül, így futásidőben is módosítható.

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

A korlát alatti stream-ek a szokásos módon dekódolódnak. FlateFilter és RunLengthFilter egyaránt round-trip adatot a encode() és a decode() segítségével, ha a kimenet a határ alatt marad.

Diagnosztikai naplózás

A könyvtár a java.util.logging használatával naplóz a org.aspose.pdf naplózó alatt, és alapértelmezés szerint némán működik: a szint OFF. AsposePdfLogging bekapcsolja a naplózást.

  • setLevel(Level) beállítja a szintet kódból; null visszaállítja a könyvtárat OFF-ra. getLevel() visszaolvassa.
  • A(z) aspose.pdf.log rendszer tulajdonság (amely AsposePdfLogging.LOG_PROPERTY néven is elérhető) a parancssorból állítja be. configureFromSystemProperty() alkalmazza a tulajdonságot, és a osztály betöltésekor is fut. A on és warning értékek a(z) WARNING-t választják, a(z) verbose a(z) FINE-t, a(z) debug a(z) ALL-t, bármely java.util.logging.Level név, például SEVERE, elfogadható, és egy ismeretlen érték visszatér a(z) OFF alapértelmezett értékhez.

WARNING engedi, hogy a motor figyelmeztetései átjussanak; FINE, a verbose beállítás, szintén engedi, hogy a parser helyreállítási részletei átjussanak. AsposePdfLogging csak a org.aspose.pdf naplózó al-fáját módosítja. Nem változtatja meg a gyökér naplózó szintjét, és a könyvtár naplózó nem továbbítja a rekordokat a gyökér naplózó kezelői felé. Ha a naplózás engedélyezett, és nincs kezelő csatolva a könyvtár naplózóhoz, egy konzol kezelő kerül telepítésre.

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

Gyors kezdés

Add hozzá a függőséget a buildhez:

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

A következő példa egy oldalt hoz létre, hozzáad egy kiemelést és egy szabad szöveges felhívást, majd elmenti a dokumentumot:

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

Támogatott formátumok

Formátumtámogatás, ahogy a könyvtár betöltési és mentési opciói, valamint a renderelő eszközök megerősítik:

FormátumKiterjesztésOlvasásÍrás
PDFpdf✓✓
HTMLhtml✓✓
DOCXdocx✓✓
DOCdoc✓✓
XFDFxfdf✓✓
BMPbmp—✓
GIFgif—✓
JPEGjpeg—✓
TIFFtiff—✓
Texttxt—✓

Nyílt forráskód és licencelés

Aspose.PDF FOSS for Java MIT licenc alatt került kiadásra, amely megengedi a kereskedelmi felhasználást, módosítást és újraelosztást. A forráskód és a hibajegy-nyilvántartó itt érhető el: github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Java. A könyvtár a Java 11 vagy újabb verzióra céloz.

Első lépések

Kapcsolódó erőforrások