Довідник Scala API
PDF Oxide постачає ідіоматичні біндинги Scala 3 як тонкий, чисто JVM-фасад поверх зрілого Java-біндингу fyi.oxide:pdf-oxide, якому належить єдиний нативний міст JNI (крейт pdf_oxide_jni). Модуль Scala не додає жодного нативного коду: він напряму використовує типи Java (Pdf, PdfDocument, PdfPage, DocumentEditor, AutoExtractor, PdfSigner, PdfValidator та типи значень для геометрії/тексту/таблиць/пошуку), а зверху накладає Scala 3 extension-методи, що перетворюють java.util.Optional[T] на Option[T], а java.util.List[T] — на Seq[T]. scala.util.Using працює без додаткових налаштувань з кожним дескриптором AutoCloseable.
// build.sbt — cross-versioned for Scala 3 (resolves pdf-oxide-scala_3)
libraryDependencies += "fyi.oxide" %% "pdf-oxide-scala" % "0.3.69"
Нативна бібліотека JNI (libpdf_oxide_jni) не постачається в комплекті. Зробіть її доступною для завантаження через System.loadLibrary("pdf_oxide_jni") на вашому java.library.path, або вкажіть Java NativeLoader шлях до неї через -Dfyi.oxide.pdf.lib.path=<path>.
import fyi.oxide.pdf.{Pdf, PdfDocument, producerOption, wordsSeq}
import scala.util.Using
Using.resource(Pdf.fromMarkdown("# Hello\n\nbody\n")): pdf =>
Using.resource(PdfDocument.open(pdf.save())): doc =>
println(doc.pageCount())
println(doc.extractText(0))
println(doc.toMarkdown())
println(doc.page(0).wordsSeq.map(_.text)) // List -> Seq
println(doc.producerOption.getOrElse("(none)")) // Optional -> Option
Про Java API див. Довідник Java API. Про Rust API див. Довідник Rust API. Подробиці про типи див. у розділі Типи та перелічення.
fyi.oxide.pdf.Pdf — створення нових PDF із вихідних форматів і розбиття наявних. Реалізує AutoCloseable.
Фабричні методи
def fromMarkdown(markdown: String): Pdf
Створити PDF із вмісту Markdown.
def fromHtml(html: String): Pdf
Створити PDF із вмісту HTML.
def fromImages(images: java.util.List[Array[Byte]]): Pdf
Створити багатосторінковий PDF, по одній сторінці на зображення (байти JPEG/PNG).
Розбиття
def planSplitByBookmarks(opts: SplitByBookmarksOptions): java.util.List[BookmarkSegment]
Спланувати розбиття за закладками без генерування байтів; повертає сегменти, які буде створено.
def splitByBookmarks(opts: SplitByBookmarksOptions): java.util.List[Array[Byte]]
Розбити документ за межами закладок, повертаючи по одному масиву байтів PDF на сегмент.
def planSplitByBookmarksCount(sourcePdf: Array[Byte], level: Int): Int
Статичний допоміжний метод: підрахувати кількість сегментів, які дасть розбиття за закладками на заданому рівні структури.
def splitByBookmarksFromBytes(sourcePdf: Array[Byte], level: Int): Array[Array[Byte]]
Статичний допоміжний метод: розбити байти вихідного PDF на заданому рівні структури на масиви байтів за сегментами.
Збереження та життєвий цикл
def save(): Array[Byte]
def saveTo(out: java.nio.file.Path): Unit
def isOpen(): Boolean
def close(): Unit
Серіалізувати PDF у байти або у файл за шляхом, перевірити, чи нативний дескриптор ще активний, і звільнити його.
PdfDocument
fyi.oxide.pdf.PdfDocument — відкриття, видобування, рендеринг і опитування PDF. Реалізує AutoCloseable.
Відкриття
def open(path: java.nio.file.Path): PdfDocument
def open(path: String): PdfDocument
def open(bytes: Array[Byte]): PdfDocument
def open(path: java.nio.file.Path, password: String): PdfDocument
def open(path: String, password: String): PdfDocument
def open(bytes: Array[Byte], password: String): PdfDocument
def open(stream: java.io.InputStream): PdfDocument
Відкрити PDF за шляхом до файлу, з байтів у пам’яті або з потоку вводу. Перевантаження з паролем дешифрують зашифровані документи за один крок.
Статичне видобування
def extractText(path: String): String
def extractText(path: java.nio.file.Path): String
Зручний одноразовий виклик: відкрити файл, видобути весь текст і закрити його.
Інформація про документ та автентифікація
def pageCount(): Int
def authenticate(password: String): Boolean
def authenticate(password: Array[Byte]): Boolean
def isOpen(): Boolean
def close(): Unit
Кількість сторінок, постфактумна автентифікація для зашифрованих PDF (рядком або сирими байтами), перевірка активності дескриптора та звільнення ресурсів.
Метадані
def producer(): java.util.Optional[String]
def creator(): java.util.Optional[String]
Рядки виробника / творця документа. Використовуйте фасадні producerOption / creatorOption для ідіоматичного Option[String].
Видобування тексту
def extractText(pageIndex: Int): String
def extractTextAuto(pageIndex: Int): String
def extractStructured(page: Int): String
Видобути звичайний текст сторінки, текст з автоматичним переходом на OCR для сканованих сторінок або структуроване представлення у JSON. Сторінки нумеруються від нуля.
Перетворення
def toMarkdown(): String
def toMarkdown(pageIndex: Int): String
def toHtml(): String
def toHtml(pageIndex: Int): String
Перетворити весь документ або окрему сторінку на Markdown чи HTML.
Рендеринг
def render(pageIndex: Int): Array[Byte]
def render(pageIndex: Int, dpi: Int): Array[Byte]
Растеризувати сторінку в байти PNG, за бажанням — із заданим DPI.
Сторінки та пошук
def page(index: Int): PdfPage
def pages(): java.util.List[PdfPage]
def pagesStream(): java.util.stream.Stream[PdfPage]
def formFields(): java.util.List[FormField]
def search(query: String): java.util.List[SearchMatch]
def search(query: String, caseInsensitive: Boolean, regex: Boolean, maxResults: Int): java.util.List[SearchMatch]
Отримати дескриптор окремої сторінки, всі сторінки (списком або потоком), усі поля AcroForm та збіги пошуку по всьому документу. maxResults = 0 означає необмежену кількість. Використовуйте фасадні pagesSeq, formFieldsSeq та searchSeq для результатів у вигляді Scala Seq.
PdfPage
fyi.oxide.pdf.PdfPage — дескриптор окремої сторінки, що повертається PdfDocument.page / pages.
Геометрія
def parent(): PdfDocument
def index(): Int
def mediaBox(): BBox
def cropBox(): BBox
def width(): Double
def height(): Double
def rotation(): Int
Документ-власник, індекс від нуля, прямокутники MediaBox / CropBox, розміри сторінки в пунктах та поворот у градусах.
Видобування вмісту
def text(): String
def text(region: BBox): String
def words(): java.util.List[TextWord]
def lines(): java.util.List[TextLine]
def chars(): java.util.List[TextChar]
def images(): java.util.List[ExtractedImage]
def tables(): java.util.List[Table]
def annotations(): java.util.List[Annotation]
Текст усієї сторінки або обрізаної області, а також структуровані слова, рядки, символи, зображення, таблиці та анотації. Використовуйте фасадні wordsSeq, linesSeq, charsSeq, imagesSeq, tablesSeq та annotationsSeq для Scala Seq.
DocumentEditor
fyi.oxide.pdf.DocumentEditor — заповнення форм, редагування, очищення метаданих і збереження (інкрементальне або повне). Реалізує AutoCloseable. Методи-сетери ланцюгові й повертають this.
Відкриття
def open(path: java.nio.file.Path): DocumentEditor
def open(path: String): DocumentEditor
def open(bytes: Array[Byte]): DocumentEditor
Форми
def setFormField(name: String, value: String): DocumentEditor
def setFormField(name: String, checked: Boolean): DocumentEditor
Встановити значення текстового/вибіркового поля або перемкнути прапорець/перемикач.
Редагування (Redaction)
def addRedaction(pageIndex: Int, region: BBox): DocumentEditor
def redactionCount(pageIndex: Int): Int
def redactionCount(): Int
def applyRedactionsDestructive(): RedactResult
Поставити в чергу прямокутник для редагування, підрахувати очікувані редагування на сторінці чи загалом і застосувати їх деструктивно (видаляючи базовий вміст), повертаючи RedactResult.
Метадані та збереження
def scrubMetadata(): DocumentEditor
def save(): Array[Byte]
def saveTo(out: java.nio.file.Path): Unit
def saveIncremental(): Array[Byte]
def saveIncrementalTo(out: java.nio.file.Path): Unit
def isOpen(): Boolean
def close(): Unit
Видалити ідентифікаційні метадані, потім зберегти PDF — повністю переписаний або з інкрементальним дописуванням — у байти чи на диск.
AutoExtractor
fyi.oxide.pdf.AutoExtractor — інтелектуальне видобування, що класифікує сторінки та за потреби переходить на OCR.
Створення
def of(doc: PdfDocument): AutoExtractor
def of(doc: PdfDocument, config: AutoExtractConfig): AutoExtractor
def fast(doc: PdfDocument): AutoExtractor
def balanced(doc: PdfDocument): AutoExtractor
def highFidelity(doc: PdfDocument): AutoExtractor
Створити екстрактор зі стандартною, користувацькою або готовою (fast / balanced / high-fidelity) конфігурацією.
Видобування
def extractText(): String
def extractTextForPage(pageIndex: Int): String
def extractDocument(): AutoResult
def extractPage(pageIndex: Int): AutoResult
def extractAutoDocument(): AutoResult
def extractAutoPage(pageIndex: Int): AutoResult
def extractDocumentJson(): String
def extractPageJson(pageIndex: Int): String
Видобути звичайний текст або розгорнуті записи AutoResult (текст, опціонально Markdown/HTML, рівень упевненості, чи використовувався OCR, регіони) для всього документа або окремої сторінки, а також варіанти в JSON.
Класифікація та доступ до даних
def classifyDocument(): ClassifyResult
def classifyPage(pageIndex: Int): ClassifyResult
def document(): PdfDocument
def config(): AutoExtractConfig
Класифікувати сторінки (текстовий шар / скановані / змішані, плюс списки сторінок з OCR/діаграмами/шифруванням) без видобування, а також отримати вихідний документ і конфігурацію.
MarkdownConverter
fyi.oxide.pdf.MarkdownConverter — статичні допоміжні методи для перетворення на Markdown/HTML.
def toMarkdown(doc: PdfDocument): String
def toMarkdown(doc: PdfDocument, pageIndex: Int): String
def toHtml(doc: PdfDocument): String
def toHtml(doc: PdfDocument, pageIndex: Int): String
Перетворити весь документ або окрему сторінку на Markdown чи HTML.
PdfSigner
fyi.oxide.pdf.PdfSigner — цифрове підписання та перевірка за стандартами PAdES / CMS.
def fromPkcs12(keystore: java.nio.file.Path, password: String): PdfSigner
def fromPkcs12(keystoreBytes: Array[Byte], password: String): PdfSigner
def sign(pdf: Array[Byte], opts: SignOptions): Array[Byte]
def verify(pdf: Array[Byte]): Boolean
def classifyLevel(pdf: Array[Byte]): SignatureLevel
Завантажити підписувача зі сховища ключів PKCS#12 (файл або байти), підписати PDF із заданими SignOptions, перевірити наявний підпис і статично класифікувати рівень PAdES підписаного PDF.
PdfValidator
fyi.oxide.pdf.PdfValidator — перевірки відповідності PDF/A, PDF/X та PDF/UA.
def isPdfA(doc: PdfDocument, level: PdfALevel): Boolean
def isPdfUa(doc: PdfDocument, level: PdfUaLevel): Boolean
def validatePdfA(doc: PdfDocument, level: PdfALevel): ValidationResult
def validatePdfX(doc: PdfDocument, level: PdfXLevel): ValidationResult
def validatePdfUa(doc: PdfDocument, level: PdfUaLevel): ValidationResult
Швидкі булеві перевірки, а також повні звіти ValidationResult (з порушеннями за кожним правилом) для PDF/A, PDF/X та PDF/UA.
PdfPolicy
fyi.oxide.pdf.PdfPolicy — глобальний режим криптографічної політики.
def current(): PolicyMode
def set(mode: PolicyMode): Unit
def compat(): PolicyMode
def strict(): PolicyMode
def fipsStrict(): PolicyMode
Зчитати або встановити загальнопроцесний режим політики, а також отримати доступ до пресетів COMPAT / STRICT / FIPS_STRICT.
Типи результатів і значень
AutoResult
def text(): String
def markdown(): java.util.Optional[String] // facade: markdownOption
def html(): java.util.Optional[String] // facade: htmlOption
def reason(): ExtractReason
def confidence(): Double
def ocrUsed(): Boolean
def regions(): java.util.List[RegionResult]
def pagesNeedingOcr(): java.util.List[Integer] // facade: pagesNeedingOcrSeq
RegionResult
def pageIndex(): Int
def bbox(): BBox
def text(): String
def reason(): ExtractReason
def confidence(): Double
def ocrUsed(): Boolean
def table(): java.util.Optional[Table]
ClassifyResult
def pages(): java.util.List[PageClass]
def pagesNeedingOcr(): java.util.List[Integer]
def pagesWithChart(): java.util.List[Integer]
def pagesEncrypted(): java.util.List[Integer]
AutoExtractConfig
Незмінна конфігурація, що будується через AutoExtractConfig.builder() (або .toBuilder()). Геттери повертають Optional:
def builder(): AutoExtractConfig.Builder
def toBuilder(): AutoExtractConfig.Builder
def mode(): java.util.Optional[ExtractMode]
def forceOcrPages(): java.util.Optional[java.util.List[Integer]]
def minOcrConfidence(): java.util.Optional[Double]
def ocrLanguages(): java.util.Optional[java.util.List[String]]
def passwords(): java.util.Optional[java.util.List[String]]
def topMarginFraction(): java.util.Optional[Double]
def bottomMarginFraction(): java.util.Optional[Double]
def allowSingleColumnTables(): java.util.Optional[Boolean]
def ocrInlineImages(): java.util.Optional[Boolean]
def cancelToken(): java.util.Optional[String]
AutoExtractConfig.Builder:
def withMode(m: ExtractMode): Builder
def withForceOcrPages(p: java.util.List[Integer]): Builder
def withMinOcrConfidence(c: Double): Builder
def withOcrLanguages(l: java.util.List[String]): Builder
def withOcrLanguages(l: String*): Builder
def withPasswords(p: java.util.List[String]): Builder
def withPasswords(p: String*): Builder
def withTopMarginFraction(f: Double): Builder
def withBottomMarginFraction(f: Double): Builder
def withAllowSingleColumnTables(b: Boolean): Builder
def withOcrInlineImages(b: Boolean): Builder
def withCancelToken(t: String): Builder
def build(): AutoExtractConfig
ValidationResult / ValidationViolation
// ValidationResult
def valid(): Boolean
def violations(): java.util.List[ValidationViolation]
// ValidationViolation
def ruleId(): String
def description(): String
def pageIndex(): java.util.Optional[Integer] // facade: pageIndexOption
RedactResult
def regionsApplied(): Int
def oracleVerified(): Boolean
SearchResult / SearchMatch / SearchOptions
// SearchResult
def query(): String
def matches(): java.util.List[SearchMatch]
def count(): Int
def isEmpty(): Boolean
// SearchMatch
def pageIndex(): Int
def bbox(): BBox
def text(): String
// SearchOptions (builder via SearchOptions.builder())
def caseSensitive(): Boolean
def wholeWord(): Boolean
def regex(): Boolean
def maxResults(): java.util.Optional[Integer]
SearchOptions.Builder: withCaseSensitive(b: Boolean), withWholeWord(b: Boolean), withRegex(b: Boolean), withMaxResults(m: Int), build().
FormField
def name(): String
def type(): FormFieldType
def value(): java.util.Optional[String] // facade: valueOption
def bbox(): java.util.Optional[BBox] // facade: bboxOption
def pageIndex(): Int
Annotation
def `type`(): AnnotationType
def pageIndex(): Int
def bbox(): BBox
def contents(): java.util.Optional[String] // facade: contentsOption
def uri(): java.util.Optional[String] // facade: uriOption
ExtractedImage
def bytes(): Array[Byte]
def format(): ImageFormat
def bbox(): BBox
def width(): Int
def height(): Int
Table / TableCell
// Table
def bbox(): BBox
def rows(): Int
def cols(): Int
def cells(): java.util.List[TableCell]
// TableCell
def text(): String
def bbox(): BBox
def row(): Int
def col(): Int
def rowSpan(): Int
def colSpan(): Int
Текстові типи
// TextWord
def text(): String
def bbox(): BBox
def confidence(): Float
// TextLine
def text(): String
def bbox(): BBox
def words(): java.util.List[TextWord]
// TextChar
def codepoint(): Int
def bbox(): BBox
def confidence(): Float
def asString(): String
// TextSpan
def text(): String
def bbox(): BBox
def style(): TextStyle
// TextStyle
def size(): Double
def color(): Color
def bold(): Boolean
def italic(): Boolean
Геометрія
// BBox(x0, y0, x1, y1)
def x0(): Double
def y0(): Double
def x1(): Double
def y1(): Double
def width(): Double
def height(): Double
// Color(r, g, b[, a])
def r(): Int
def g(): Int
def b(): Int
def a(): Int
// Point(x, y)
def x(): Double
def y(): Double
// Rect(x, y, width, height)
def x(): Double
def y(): Double
def width(): Double
def height(): Double
def toBBox(): BBox
Метадані
// DocumentInfo — all accessors return Optional[String]
def title(); def author(); def subject(); def keywords()
def creator(); def producer(); def creationDate(); def modificationDate()
// XmpMetadata(xml: String)
def xml(): String
def isEmpty(): Boolean
Параметри підписання та розбиття
// SignOptions (builder via SignOptions.builder())
def level(): SignatureLevel
def reason(): java.util.Optional[String]
def location(): java.util.Optional[String]
def contactInfo(): java.util.Optional[String]
def tsaUrl(): java.util.Optional[String]
// Builder: withLevel, withReason, withLocation, withContactInfo, withTsaUrl, build
// SplitByBookmarksOptions (builder via SplitByBookmarksOptions.builder())
def level(): Int
def filenamePrefix(): java.util.Optional[String]
// Builder: withLevel(l: Int), withFilenamePrefix(p: String), build
// BookmarkSegment
def title(): String
def firstPage(): Int
def lastPage(): Int
def filename(): String
SecurityPolicy
def mode(): PolicyMode
def additionalAllow(): java.util.List[String]
def additionalDeny(): java.util.List[String]
def builder(): SecurityPolicy.Builder
// Builder: withMode(m: PolicyMode), allow(algId: String), deny(algId: String), build
Перелічення (Enums)
| Перелічення | Константи |
|---|---|
AnnotationType |
HIGHLIGHT, TEXT, LINK, STAMP, UNDERLINE, STRIKEOUT, SQUIGGLY, FREE_TEXT, LINE, SQUARE, CIRCLE, FILE_ATTACHMENT |
FormFieldType |
TEXT, CHECKBOX, RADIO, CHOICE, SIGNATURE |
ImageFormat |
JPEG, PNG, JBIG2, JPEG2000, CCITT, RAW |
ExtractMode |
TEXT_ONLY, AUTO |
ExtractReason |
OK, SCANNED_NO_TEXT_LAYER, GLYPH_MAPPING_MISSING, ENCRYPTED_NO_EXTRACT_PERMISSION, IMAGE_TABLE_NO_STRUCTURE, CHART_NOT_TRANSCRIBED, OCR_REQUESTED_BUT_UNAVAILABLE, OCR_LOW_CONFIDENCE, EMPTY |
PageClass |
TEXT_LAYER, SCANNED, MIXED |
PdfALevel |
A_1B, A_1A, A_2B, A_2A, A_2U, A_3B, A_3A, A_3U, A_4, A_4E |
PdfUaLevel |
UA_1, UA_2 (кожен має code(): Int) |
PdfXLevel |
X_1A_2001, X_1A_2003, X_3_2002, X_3_2003, X_4, X_4P, X_5G, X_5N, X_5PG, X_6, X_6P |
PolicyMode |
COMPAT, STRICT, FIPS_STRICT |
PixelFormat |
RGBA_8888, RGB_888, GRAY_8 |
SignatureLevel |
B_B, B_T, B_LT |
Розширення-фасади Scala
Модуль Scala додає поверх типів Java такі extension-методи, щоб виклики отримували Option/Seq замість java.util.Optional/java.util.List. Імпортуйте ті, що вам потрібні, з fyi.oxide.pdf.
// Generic — any java.util.Optional[T]
extension [T](o: java.util.Optional[T]) def toOption: Option[T]
// PdfDocument
extension (doc: PdfDocument)
def producerOption: Option[String]
def creatorOption: Option[String]
def formFieldsSeq: Seq[FormField]
def pagesSeq: Seq[PdfPage]
def searchSeq(query: String): Seq[SearchMatch]
// PdfPage
extension (page: PdfPage)
def wordsSeq: Seq[TextWord]
def linesSeq: Seq[TextLine]
def charsSeq: Seq[TextChar]
def tablesSeq: Seq[Table]
def imagesSeq: Seq[ExtractedImage]
def annotationsSeq: Seq[Annotation]
// FormField
extension (f: FormField)
def valueOption: Option[String]
def bboxOption: Option[BBox]
// Annotation
extension (a: Annotation)
def contentsOption: Option[String]
def uriOption: Option[String]
// AutoResult
extension (r: AutoResult)
def markdownOption: Option[String]
def htmlOption: Option[String]
def pagesNeedingOcrSeq: Seq[Int]
// ValidationViolation
extension (v: ValidationViolation)
def pageIndexOption: Option[Int]
Винятки
Усі помилки походять від fyi.oxide.pdf.exception.PdfException:
| Виняток | Причина |
|---|---|
PdfException |
Базовий клас для всіх помилок PDF Oxide |
PdfParseException |
Пошкоджений або некоректний PDF |
PdfEncryptedException |
Зашифрований PDF відкрито без пароля |
PdfPermissionException |
Операцію заборонено прапорцями шифрування документа |
PdfInvalidStateException |
Операція над закритим або недійсним дескриптором |
PdfIoException |
Помилка введення-виведення нижчого рівня |
PdfUnsupportedException |
Непідтримувана функція або формат |
PdfOcrUnavailableException |
Запитано OCR, але функцію ocr не включено в збірку |
PdfSignatureException |
Помилка підписання чи перевірки підпису |
PdfErrorKind — перелічення, що класифікує конкретну категорію помилки, яку несе PdfException.
Повний приклад
import fyi.oxide.pdf.*
import fyi.oxide.pdf.auto.AutoExtractConfig
import scala.util.Using
// --- Creation ---
Using.resource(Pdf.fromMarkdown("# Report\n\nGenerated by PDF Oxide.")): pdf =>
pdf.saveTo(java.nio.file.Path.of("report.pdf"))
// --- Extraction ---
Using.resource(PdfDocument.open("report.pdf")): doc =>
println(s"Pages: ${doc.pageCount()}")
val page = doc.page(0)
println(s"${page.width()} x ${page.height()}")
page.wordsSeq.foreach(w => println(s"${w.text} @ ${w.bbox.x0}"))
// Search (facade -> Seq)
doc.searchSeq("Report").foreach(m => println(s"p${m.pageIndex}: ${m.text}"))
// Metadata (facade -> Option)
println(doc.producerOption.getOrElse("(none)"))
// Auto extraction with OCR fallback
val cfg = AutoExtractConfig.builder().withMinOcrConfidence(0.6).build()
val result = AutoExtractor.of(doc, cfg).extractDocument()
println(s"confidence=${result.confidence} ocr=${result.ocrUsed}")
result.markdownOption.foreach(println)
// --- Editing: fill a form, redact, scrub ---
Using.resource(DocumentEditor.open("form.pdf")): ed =>
ed.setFormField("name", "Jane Doe")
.setFormField("agree", true)
.addRedaction(0, BBox(72, 700, 272, 720))
val redacted = ed.applyRedactionsDestructive()
println(s"redacted ${redacted.regionsApplied} regions")
ed.scrubMetadata().saveTo(java.nio.file.Path.of("output.pdf"))
Other Language Bindings
PDF Oxide надає нативні прив’язки для всіх основних екосистем: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Clojure, Objective-C та Elixir.
Наступні кроки
- Типи та переліки — усі спільні типи та переліки
- Довідник API сторінки — узгоджена ітерація по сторінках для всіх прив’язок
- Початок роботи з Scala — посібник