Referencia de la API de Scala

PDF Oxide distribuye bindings idiomáticos de Scala 3 como una fachada fina, puramente JVM, sobre el maduro binding de Java fyi.oxide:pdf-oxide, que es el dueño del único puente nativo JNI (el crate pdf_oxide_jni). El módulo de Scala no añade ningún código nativo: usa directamente los tipos de Java (Pdf, PdfDocument, PdfPage, DocumentEditor, AutoExtractor, PdfSigner, PdfValidator, y los tipos de valor de geometría/texto/tablas/búsqueda) y añade encima métodos extension de Scala 3 que convierten java.util.Optional[T] en Option[T] y java.util.List[T] en Seq[T]. scala.util.Using funciona directamente con cualquier handle AutoCloseable.

// build.sbt — cross-versioned for Scala 3 (resolves pdf-oxide-scala_3)
libraryDependencies += "fyi.oxide" %% "pdf-oxide-scala" % "0.3.69"

La librería nativa JNI (libpdf_oxide_jni) no se incluye. Hazla cargable mediante System.loadLibrary("pdf_oxide_jni") en tu java.library.path, o indica al NativeLoader de Java su ubicación con -Dfyi.oxide.pdf.lib.path=<ruta>.

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 la API de Java, consulta la Referencia de la API de Java. Para la API de Rust, consulta la Referencia de la API de Rust. Para más detalles sobre los tipos, consulta Tipos y Enums.

---

Pdf

fyi.oxide.pdf.Pdf — crea PDF nuevos a partir de formatos de origen y divide PDF existentes. Implementa AutoCloseable.

Métodos de fábrica

def fromMarkdown(markdown: String): Pdf

Crea un PDF a partir de contenido Markdown.

def fromHtml(html: String): Pdf

Crea un PDF a partir de contenido HTML.

def fromImages(images: java.util.List[Array[Byte]]): Pdf

Crea un PDF multipágina, una página por imagen (bytes JPEG/PNG).

División

def planSplitByBookmarks(opts: SplitByBookmarksOptions): java.util.List[BookmarkSegment]

Planifica una división basada en marcadores sin generar bytes; devuelve los segmentos que se crearían.

def splitByBookmarks(opts: SplitByBookmarksOptions): java.util.List[Array[Byte]]

Divide el documento en los límites de los marcadores, devolviendo un array de bytes de PDF por segmento.

def planSplitByBookmarksCount(sourcePdf: Array[Byte], level: Int): Int

Ayudante estático: cuenta los segmentos que produciría una división por marcadores en el nivel de esquema indicado.

def splitByBookmarksFromBytes(sourcePdf: Array[Byte], level: Int): Array[Array[Byte]]

Ayudante estático: divide los bytes del PDF de origen en el nivel de esquema indicado en arrays de bytes por segmento.

Guardado y ciclo de vida

def save(): Array[Byte]
def saveTo(out: java.nio.file.Path): Unit
def isOpen(): Boolean
def close(): Unit

Serializa el PDF a bytes o a una ruta de archivo, comprueba si el handle nativo sigue activo, y libéralo.

---

PdfDocument

fyi.oxide.pdf.PdfDocument — abre, extrae, renderiza y consulta un PDF. Implementa AutoCloseable.

Apertura

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 un PDF desde una ruta de archivo, bytes en memoria o un input stream. Las sobrecargas con contraseña descifran documentos cifrados en un solo paso.

Extracción estática

def extractText(path: String): String
def extractText(path: java.nio.file.Path): String

Atajo de un solo paso: abre el archivo, extrae todo el texto y lo cierra.

Información del documento y autenticación

def pageCount(): Int
def authenticate(password: String): Boolean
def authenticate(password: Array[Byte]): Boolean
def isOpen(): Boolean
def close(): Unit

Número de páginas, autenticación posterior a la apertura para PDF cifrados (cadena o bytes en bruto), comprobación de actividad del handle y liberación de recursos.

Metadatos

def producer(): java.util.Optional[String]
def creator(): java.util.Optional[String]

Cadenas de productor / creador del documento. Usa la fachada producerOption / creatorOption para obtener un Option[String] idiomático.

Extracción de texto

def extractText(pageIndex: Int): String
def extractTextAuto(pageIndex: Int): String
def extractStructured(page: Int): String

Extrae texto plano de una página, texto con fallback automático a OCR para páginas escaneadas, o una representación estructurada en JSON. Las páginas están indexadas desde cero.

Conversión

def toMarkdown(): String
def toMarkdown(pageIndex: Int): String
def toHtml(): String
def toHtml(pageIndex: Int): String

Convierte el documento completo o una sola página a Markdown o HTML.

Renderizado

def render(pageIndex: Int): Array[Byte]
def render(pageIndex: Int, dpi: Int): Array[Byte]

Rasteriza una página a bytes PNG, opcionalmente a un DPI determinado.

Páginas y búsqueda

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]

Obtiene un handle de página individual, todas las páginas (como lista o stream), todos los campos de formulario AcroForm, y coincidencias de búsqueda en todo el documento. maxResults = 0 significa sin límite. Usa la fachada pagesSeq, formFieldsSeq y searchSeq para obtener resultados como Seq de Scala.

---

PdfPage

fyi.oxide.pdf.PdfPage — un handle de página individual devuelto por PdfDocument.page / pages.

Geometría

def parent(): PdfDocument
def index(): Int
def mediaBox(): BBox
def cropBox(): BBox
def width(): Double
def height(): Double
def rotation(): Int

Documento propietario, índice de base cero, rectángulos MediaBox / CropBox, dimensiones de la página en puntos y rotación en grados.

Extracción de contenido

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 de página completa o recortado a una región, además de palabras, líneas, caracteres, imágenes, tablas y anotaciones estructuradas. Usa la fachada wordsSeq, linesSeq, charsSeq, imagesSeq, tablesSeq y annotationsSeq para obtener Seq de Scala.

---

DocumentEditor

fyi.oxide.pdf.DocumentEditor — rellena formularios, redacta, depura metadatos y guarda (de forma incremental o completa). Implementa AutoCloseable. Los métodos de asignación son fluidos y devuelven this.

Apertura

def open(path: java.nio.file.Path): DocumentEditor
def open(path: String): DocumentEditor
def open(bytes: Array[Byte]): DocumentEditor

Formularios

def setFormField(name: String, value: String): DocumentEditor
def setFormField(name: String, checked: Boolean): DocumentEditor

Asigna el valor de un campo de texto/selección o activa/desactiva una casilla de verificación o botón de radio.

Redacción

def addRedaction(pageIndex: Int, region: BBox): DocumentEditor
def redactionCount(pageIndex: Int): Int
def redactionCount(): Int
def applyRedactionsDestructive(): RedactResult

Encola un rectángulo de redacción, cuenta las redacciones pendientes por página o en total, y aplícalas de forma destructiva (eliminando el contenido subyacente), devolviendo un RedactResult.

Metadatos y guardado

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

Elimina metadatos identificativos y luego guarda un PDF reescrito por completo o añadido de forma incremental, ya sea en bytes o en disco.

---

AutoExtractor

fyi.oxide.pdf.AutoExtractor — extracción inteligente que clasifica las páginas y recurre a OCR cuando es necesario.

Construcción

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

Construye un extractor con configuración predeterminada, personalizada o un preset (fast / balanced / high-fidelity).

Extracción

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

Extrae texto plano o registros AutoResult enriquecidos (texto, Markdown/HTML opcional, confianza, uso de OCR, regiones) para todo el documento o una sola página, además de las variantes en JSON.

Clasificación y accesores

def classifyDocument(): ClassifyResult
def classifyPage(pageIndex: Int): ClassifyResult
def document(): PdfDocument
def config(): AutoExtractConfig

Clasifica páginas (capa de texto / escaneada / mixta, además de listas de páginas con OCR/gráfico/cifrado) sin extraer contenido, y consulta el documento de origen y la configuración.

---

MarkdownConverter

fyi.oxide.pdf.MarkdownConverter — ayudantes estáticos de conversión a 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

Convierte un documento completo o una sola página a Markdown o HTML.

---

PdfSigner

fyi.oxide.pdf.PdfSigner — firma y verificación digital 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

Carga un firmante a partir de un almacén de claves PKCS#12 (archivo o bytes), firma un PDF con las SignOptions indicadas, verifica una firma existente, y clasifica de forma estática el nivel PAdES de un PDF firmado.

---

PdfValidator

fyi.oxide.pdf.PdfValidator — comprobaciones de cumplimiento de PDF/A, PDF/X y 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

Comprobaciones rápidas booleanas, además de informes ValidationResult completos (con incumplimientos por regla) para PDF/A, PDF/X y 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

Lee o establece el modo de política a nivel de proceso, y accede a los presets COMPAT / STRICT / FIPS_STRICT.

---

Tipos de resultado y de 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

Configuración inmutable construida mediante AutoExtractConfig.builder() (o .toBuilder()). Los accesores devuelven 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

Geometría

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

Metadatos

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

Opciones de firma y división

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

---

Extensiones de fachada en Scala

El módulo de Scala añade estos métodos extension sobre los tipos de Java para que el código que los usa reciba Option/Seq en lugar de java.util.Optional/java.util.List. Importa los que necesites desde 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]

---

Excepciones

Todos los errores derivan de fyi.oxide.pdf.exception.PdfException:

Excepción	Causa
PdfException	Clase base de todos los errores de PDF Oxide
PdfParseException	PDF malformado o corrupto
PdfEncryptedException	PDF cifrado abierto sin contraseña
PdfPermissionException	Operación no permitida por los flags de cifrado del documento
PdfInvalidStateException	Operación sobre un handle cerrado o inválido
PdfIoException	Fallo de E/S subyacente
PdfUnsupportedException	Funcionalidad o formato no soportado
PdfOcrUnavailableException	Se solicitó OCR pero la feature ocr no está integrada
PdfSignatureException	Fallo al firmar o al verificar la firma

PdfErrorKind es un enum que clasifica la categoría específica de error que transporta una PdfException.

---

Ejemplo 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

PDF Oxide ofrece bindings nativos para todos los ecosistemas principales: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Clojure, Objective-C y Elixir.

Próximos pasos

• Tipos y enums — todos los tipos y enums compartidos
• Referencia de la API Page — iteración de página consistente entre bindings
• Primeros pasos con Scala — tutorial