Scala API リファレンス

PDF Oxide は、唯一の JNI ネイティブブリッジ（pdf_oxide_jni クレート）を担う成熟した fyi.oxide:pdf-oxide Java バインディングの上にかぶせる、薄い純粋 JVM ファサードとしてイディオマティックな Scala 3 バインディングを提供します。Scala モジュールはネイティブコードを一切追加しません。Java の型（Pdf、PdfDocument、PdfPage、DocumentEditor、AutoExtractor、PdfSigner、PdfValidator、および図形・テキスト・テーブル・検索の値型）をそのまま使い、java.util.Optional[T] を Option[T] に、java.util.List[T] を Seq[T] に変換する Scala 3 の extension メソッドを重ねているだけです。すべての AutoCloseable ハンドルで scala.util.Using がそのまま使えます。

// 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）は同梱されていません。java.library.path 上で System.loadLibrary("pdf_oxide_jni") によって読み込めるようにするか、-Dfyi.oxide.pdf.lib.path=<path> で Java の NativeLoader にその場所を指定してください。

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 リファレンス、型の詳細については 型と列挙型 を参照してください。

---

Pdf

fyi.oxide.pdf.Pdf — ソース形式から新しい PDF を作成し、既存の PDF を分割します。AutoCloseable を実装しています。

ファクトリーメソッド

def fromMarkdown(markdown: String): Pdf

Markdown コンテンツから PDF を作成します。

def fromHtml(html: String): Pdf

HTML コンテンツから PDF を作成します。

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

画像 1 枚につき 1 ページの複数ページ PDF を作成します（JPEG/PNG バイト列）。

分割

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

バイト列を生成せずにブックマークベースの分割を計画します。作成されるであろうセグメントを返します。

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

ブックマークの境界でドキュメントを分割し、セグメントごとに 1 つの 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]

ドキュメントの producer / creator 文字列。イディオマティックな Option[String] にはファサードの producerOption / creatorOption を使ってください。

テキスト抽出

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

ページのプレーンテキストを抽出する、スキャンされたページに対して自動 OCR フォールバックを伴うテキストを抽出する、または構造化された JSON 表現を取得します。ページは 0 始まりです。

変換

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 は無制限を意味します。Scala の Seq 結果が欲しい場合はファサードの pagesSeq、formFieldsSeq、searchSeq を使ってください。

---

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

所有元のドキュメント、0 始まりのインデックス、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]

ページ全体または領域でクリップしたテキストに加え、構造化された単語・行・文字・画像・テーブル・注釈。Scala の Seq にはファサードの wordsSeq、linesSeq、charsSeq、imagesSeq、tablesSeq、annotationsSeq を使ってください。

---

DocumentEditor

fyi.oxide.pdf.DocumentEditor — フォームへの入力、墨消し、メタデータの除去、そして保存（差分または完全な再書き込み）を行います。AutoCloseable を実装しています。setter メソッドはフルーエントで 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

テキスト/選択フィールドの値を設定する、またはチェックボックス/ラジオフィールドを切り替えます。

墨消し

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 または差分追記された 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 キーストア（ファイルまたはバイト列）からサイナーを読み込み、指定した SignOptions で PDF に署名し、既存の署名を検証し、署名済み PDF の PAdES レベルを静的に分類します。

---

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

PDF/A、PDF/X、PDF/UA に対する真偽値クイックチェックと、（ルールごとの違反を含む）完全な ValidationResult レポート。

---

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

---

列挙型

列挙型	定数
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.util.Optional/java.util.List の代わりに Option/Seq を得られるよう、Java の型の上にこれらの extension メソッドを追加します。必要なものを 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	下層の I/O 障害
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"))

他の言語のバインディング

PDF Oxide はあらゆる主要なエコシステム向けにネイティブバインディングを提供しています： Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Clojure, Objective-C, Elixir。

次のステップ

• 型と列挙型 — すべての共有型と列挙型
• Page API リファレンス — バインディング間で一貫したページ単位の反復処理
• Scala 入門 — チュートリアル