Referência da API Scala
A PDF Oxide oferece bindings idiomáticos para Scala 3 como uma fachada fina, puramente JVM, sobre o maduro binding de Java fyi.oxide:pdf-oxide, que é o dono da única ponte nativa via JNI (a crate pdf_oxide_jni). O módulo Scala adiciona zero código nativo: ele usa os tipos de Java (Pdf, PdfDocument, PdfPage, DocumentEditor, AutoExtractor, PdfSigner, PdfValidator, e os tipos de valor de geometria/texto/tabela/busca) diretamente, e acrescenta métodos extension de Scala 3 que transformam java.util.Optional[T] em Option[T] e java.util.List[T] em Seq[T]. scala.util.Using funciona diretamente sobre qualquer handle AutoCloseable.
// build.sbt — cross-versioned for Scala 3 (resolves pdf-oxide-scala_3)
libraryDependencies += "fyi.oxide" %% "pdf-oxide-scala" % "0.3.69"
A biblioteca nativa JNI (libpdf_oxide_jni) não vem incluída. Torne-a carregável via System.loadLibrary("pdf_oxide_jni") no seu java.library.path, ou aponte o NativeLoader de Java para ela com -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
Para a API de Java, veja a Referência da API Java. Para a API de Rust, veja a Referência da API Rust. Para detalhes dos tipos, veja Tipos e Enums.
fyi.oxide.pdf.Pdf — cria novos PDFs a partir de formatos de origem e divide PDFs existentes. Implementa AutoCloseable.
Métodos de Fábrica
def fromMarkdown(markdown: String): Pdf
Cria um PDF a partir de conteúdo Markdown.
def fromHtml(html: String): Pdf
Cria um PDF a partir de conteúdo HTML.
def fromImages(images: java.util.List[Array[Byte]]): Pdf
Cria um PDF de múltiplas páginas, uma página por imagem (bytes JPEG/PNG).
Divisão
def planSplitByBookmarks(opts: SplitByBookmarksOptions): java.util.List[BookmarkSegment]
Planeja uma divisão baseada em marcadores sem produzir bytes; retorna os segmentos que seriam criados.
def splitByBookmarks(opts: SplitByBookmarksOptions): java.util.List[Array[Byte]]
Divide o documento nos limites dos marcadores, retornando um array de bytes de PDF por segmento.
def planSplitByBookmarksCount(sourcePdf: Array[Byte], level: Int): Int
Auxiliar estático: conta quantos segmentos uma divisão por marcadores no nível de contorno informado produziria.
def splitByBookmarksFromBytes(sourcePdf: Array[Byte], level: Int): Array[Array[Byte]]
Auxiliar estático: divide os bytes do PDF de origem no nível de contorno informado em arrays de bytes por segmento.
Salvamento & Ciclo de Vida
def save(): Array[Byte]
def saveTo(out: java.nio.file.Path): Unit
def isOpen(): Boolean
def close(): Unit
Serializa o PDF em bytes ou em um caminho de arquivo, verifica se o handle nativo está ativo, e o libera.
PdfDocument
fyi.oxide.pdf.PdfDocument — abre, extrai, renderiza e consulta um PDF. Implementa AutoCloseable.
Abertura
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
Abre um PDF a partir de um caminho de arquivo, bytes em memória ou um input stream. As sobrecargas com senha decriptam documentos criptografados em uma única etapa.
Extração Estática
def extractText(path: String): String
def extractText(path: java.nio.file.Path): String
Atalho conveniente: abre o arquivo, extrai todo o texto e o fecha.
Informações do Documento & Autenticação
def pageCount(): Int
def authenticate(password: String): Boolean
def authenticate(password: Array[Byte]): Boolean
def isOpen(): Boolean
def close(): Unit
Contagem de páginas, autenticação pós-abertura para PDFs criptografados (string ou bytes brutos), verificação de atividade do handle e descarte.
Metadados
def producer(): java.util.Optional[String]
def creator(): java.util.Optional[String]
Strings de produtor / criador do documento. Use a fachada producerOption / creatorOption para obter Option[String] de forma idiomática.
Extração de Texto
def extractText(pageIndex: Int): String
def extractTextAuto(pageIndex: Int): String
def extractStructured(page: Int): String
Extrai o texto simples de uma página, texto com fallback automático de OCR para páginas escaneadas, ou uma representação estruturada em JSON. As páginas são indexadas a partir de zero.
Conversão
def toMarkdown(): String
def toMarkdown(pageIndex: Int): String
def toHtml(): String
def toHtml(pageIndex: Int): String
Converte o documento inteiro ou uma única página para Markdown ou HTML.
Renderização
def render(pageIndex: Int): Array[Byte]
def render(pageIndex: Int, dpi: Int): Array[Byte]
Rasteriza uma página em bytes PNG, opcionalmente em um DPI escolhido.
Páginas & Busca
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]
Obtém um handle de página única, todas as páginas (como lista ou stream), todos os campos de formulário AcroForm e as correspondências de busca em todo o documento. maxResults = 0 significa ilimitado. Use a fachada pagesSeq, formFieldsSeq e searchSeq para obter resultados em Seq do Scala.
PdfPage
fyi.oxide.pdf.PdfPage — um handle de página única retornado por PdfDocument.page / pages.
Geometria
def parent(): PdfDocument
def index(): Int
def mediaBox(): BBox
def cropBox(): BBox
def width(): Double
def height(): Double
def rotation(): Int
Documento proprietário, índice baseado em zero, retângulos MediaBox / CropBox, dimensões da página em pontos e rotação em graus.
Extração de Conteúdo
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]
Texto da página inteira ou recortado por região, além de palavras, linhas, caracteres, imagens, tabelas e anotações estruturados. Use a fachada wordsSeq, linesSeq, charsSeq, imagesSeq, tablesSeq e annotationsSeq para obter Seq do Scala.
DocumentEditor
fyi.oxide.pdf.DocumentEditor — preenche formulários, redige, limpa metadados e salva (de forma incremental ou completa). Implementa AutoCloseable. Os métodos setter são fluentes e retornam this.
Abertura
def open(path: java.nio.file.Path): DocumentEditor
def open(path: String): DocumentEditor
def open(bytes: Array[Byte]): DocumentEditor
Formulários
def setFormField(name: String, value: String): DocumentEditor
def setFormField(name: String, checked: Boolean): DocumentEditor
Define o valor de um campo de texto/escolha ou alterna um campo de caixa de seleção/botão de opção.
Redação
def addRedaction(pageIndex: Int, region: BBox): DocumentEditor
def redactionCount(pageIndex: Int): Int
def redactionCount(): Int
def applyRedactionsDestructive(): RedactResult
Enfileira um retângulo de redação, conta as redações pendentes por página ou no total, e as aplica de forma destrutiva (removendo o conteúdo subjacente), retornando um RedactResult.
Metadados & Salvamento
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
Remove os metadados de identificação e, em seguida, salva um PDF totalmente reescrito ou anexado de forma incremental em bytes ou em disco.
AutoExtractor
fyi.oxide.pdf.AutoExtractor — extração inteligente que classifica páginas e recorre a OCR quando necessário.
Construção
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
Constrói um extrator com configuração padrão, customizada, ou predefinida (fast / balanced / high-fidelity).
Extração
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
Extrai texto simples ou registros AutoResult enriquecidos (texto, Markdown/HTML opcional, confiança, uso de OCR, regiões) para o documento inteiro ou uma única página, além das variantes em JSON.
Classificação & Acessores
def classifyDocument(): ClassifyResult
def classifyPage(pageIndex: Int): ClassifyResult
def document(): PdfDocument
def config(): AutoExtractConfig
Classifica as páginas (camada de texto / escaneada / mista, além das listas de páginas com OCR/gráfico/criptografia) sem extrair, e recupera o documento de origem e a configuração.
MarkdownConverter
fyi.oxide.pdf.MarkdownConverter — auxiliares estáticos de conversão para 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
Converte um documento inteiro ou uma única página para Markdown ou HTML.
PdfSigner
fyi.oxide.pdf.PdfSigner — assinatura digital e verificação 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
Carrega um assinante a partir de um keystore PKCS#12 (arquivo ou bytes), assina um PDF com o SignOptions informado, verifica uma assinatura existente e classifica estaticamente o nível PAdES de um PDF assinado.
PdfValidator
fyi.oxide.pdf.PdfValidator — verificações de conformidade PDF/A, PDF/X e 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
Verificações booleanas rápidas, além de relatórios completos ValidationResult (com violações por regra) para PDF/A, PDF/X e PDF/UA.
PdfPolicy
fyi.oxide.pdf.PdfPolicy — modo de política criptográfica global.
def current(): PolicyMode
def set(mode: PolicyMode): Unit
def compat(): PolicyMode
def strict(): PolicyMode
def fipsStrict(): PolicyMode
Lê ou define o modo de política em todo o processo, e acessa as predefinições COMPAT / STRICT / FIPS_STRICT.
Tipos de Resultado & Valor
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
Configuração imutável construída via AutoExtractConfig.builder() (ou .toBuilder()). Os acessores retornam 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
Tipos de Texto
// 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
Geometria
// 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
Metadados
// 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
Opções de Assinatura & Divisão
// 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
| Enum | Constantes |
|---|---|
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 (cada um expõe 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 |
Extensões de Fachada Scala
O módulo Scala acrescenta estes métodos extension sobre os tipos de Java para que as chamadas obtenham Option/Seq em vez de java.util.Optional/java.util.List. Importe os que você precisar de 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]
Exceções
Todos os erros derivam de fyi.oxide.pdf.exception.PdfException:
| Exceção | Causa |
|---|---|
PdfException |
Classe base para todos os erros da PDF Oxide |
PdfParseException |
PDF malformado ou corrompido |
PdfEncryptedException |
PDF criptografado aberto sem senha |
PdfPermissionException |
Operação não permitida pelos flags de criptografia do documento |
PdfInvalidStateException |
Operação em um handle fechado ou inválido |
PdfIoException |
Falha subjacente de I/O |
PdfUnsupportedException |
Recurso ou formato não suportado |
PdfOcrUnavailableException |
OCR solicitado, mas o recurso ocr não foi incluído na build |
PdfSignatureException |
Falha na assinatura ou na verificação de assinatura |
PdfErrorKind é um enum que classifica a categoria específica de erro carregada por uma PdfException.
Exemplo Completo
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
O PDF Oxide oferece bindings nativos para todos os principais ecossistemas: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Clojure, Objective-C e Elixir.
Próximos Passos
- Tipos e Enums — todos os tipos e enums compartilhados
- Referência da API Page — iteração consistente por página entre os bindings
- Primeiros Passos com Scala — tutorial