COSDictionary

COSDictionaryは、Apache PDFBoxにおける中核的なJavaクラスで、Carousel Object Structure（COS）モデル内の辞書オブジェクトを表現します。COSモデルは、 ( Citation: N.A., 2020 (N.A.). (2020). Document management — Portable document format — Part 2: PDF 2.0 .  International Organization for Standardization Retrieved from https://www.iso.org/standard/75839.html ) で定義されている低レベルのPDFファイル構造をPDFBoxで実装したものです。このクラスは、ページオブジェクト、フォント記述子、メタデータ構造など、PDFドキュメントの構成要素となる基本的なキーと値のペアに直接アクセスする機能を提供します。高レベルAPIが提供する範囲を超えて、PDFファイルを詳細なレベルで操作する必要がある開発者にとって、COSDictionaryの理解は不可欠です。

COSDictionaryは、Apache PDFBoxライブラリにおけるJavaクラスで、PDFの辞書オブジェクト、つまりキーがPDF名であり値が任意のPDFオブジェクト型となるキーと値のペアのコレクションを表現します。COS（Carousel Object Structure）レイヤーの一部として、COSDictionaryはPDF抽象化の最下層で動作し、 ( Citation: N.A., 2020 (N.A.). (2020). Document management — Portable document format — Part 2: PDF 2.0 .  International Organization for Standardization Retrieved from https://www.iso.org/standard/75839.html ) で記述されているオブジェクト構造を直接反映します。PDPageやPDFontなど、便利でドメイン固有のメソッドを提供するPDFBoxの高レベルPDModelクラスとは異なり、COSDictionaryは意味的な解釈を行わず、基礎となるPDFデータ構造への生のアクセスを提供します。

このクラスは、類似する概念とは重要な点で異なります。標準的なJavaのHashMapが任意のオブジェクトを格納するのに対し、COSDictionaryはPDF名キー（COSNameオブジェクトとして表現）とPDF互換の値（COSBaseサブクラス）を明示的に強制します。また、間接オブジェクト参照などのPDF固有の動作を維持し、PDF構文へのシリアライゼーションを処理します。COSDictionaryは、より高レベルのPDF構造が構築される基盤として機能するため、型付きデータモデルではなく生のJSONオブジェクトを扱うことに類似しています。

PDFドキュメントを扱う開発者にとって、COSDictionaryは高レベルAPIではサポートされていない方法でPDFファイルを操作する柔軟性を提供します。 ( Citation: N.A., 2014 (N.A.). (2014). Document management applications — Electronic document file format enhancement for accessibility — Part 1: Use of ISO 32000-1 (PDF/UA-1) .  International Organization for Standardization Retrieved from https://www.iso.org/standard/64599.html ) などの規格で要求されるアクセシビリティ機能を実装する際、開発者は便利メソッドでは完全に公開されていない構造要素内の特定の辞書エントリにアクセスまたは変更する必要がある場合があります。この低レベルアクセスは、 ( Citation: PDF Association, 2023 PDF Association(2023). Retrieved from https://pdfa.org/resource/tagged-pdf-best-practice-guide-syntax/ ) で説明されているTagged PDF構造を扱う場合に特に重要になります。構造ツリー要素とその属性に対する正確な制御が必要となるためです。

COSDictionaryは、カスタムPDF機能の実装、PDF問題のデバッグ、標準APIでカバーされていないメタデータの抽出、特定のPDF規格への準拠の確保など、高度なユースケースで特に価値があります。開発者はPDFファイル内の任意の辞書エントリを読み書きできるため、PDFドキュメント構造に対する完全な制御を必要とするツールには不可欠です。

COSDictionaryは、COSNameオブジェクトをキーとして、COSBase オブジェクト（すべてのCOSオブジェクトの基底クラス）を値として使用してキーと値のペアを格納する特殊なマップとして機能します。開発者は、エントリの追加や更新にはsetItem(COSName key, COSBase value)、値の取得にはgetItem(COSName key)、エントリの削除にはremoveItem(COSName key)といったメソッドを通じてCOSDictionaryとやり取りします。このクラスは、<<と>>デリミタを使った辞書構文の適切なフォーマットを含む、PDFオブジェクトのシリアライゼーションの複雑さを処理します。

COSDictionaryを扱う際、開発者は通常、PDModelラッパークラスを通じてgetCOSObject()を呼び出すことでアクセスし、これが基礎となるCOS表現を返します。例えば、PDPageオブジェクトは、/Type /Page、/MediaBox、/Contentsなどのエントリを含むCOSDictionaryをラップしています。COSDictionaryに直接アクセスすることで、開発者は非標準の辞書エントリを読み取ったり、PDModelレイヤーに専用のセッターメソッドがない値を変更したりできます。

このクラスは間接オブジェクト参照も自動的に管理し、直接オブジェクト（辞書内に埋め込まれたもの）と間接オブジェクト（オブジェクト番号で参照されるもの）を区別します。この区別は、ファイルサイズ、オブジェクトの再利用、インクリメンタル更新に影響するため、PDFファイル構造にとって重要です。COSDictionaryは、変更されたPDFファイルを保存する際に適切なシリアライゼーションを保証するため、PDFBoxのドキュメント書き込みシステムと統合されています。

• COSBase – COSDictionary、COSArray、COSString、プリミティブ型を含む、Apache PDFBoxのすべてのCOSオブジェクトの抽象基底クラス
• COSName – PDF名オブジェクトを表すクラスで、COSDictionaryのキーとして、またPDFオペレータやリソースの識別に使用される
• PDModel – PDFBoxの高レベルレイヤーで、COSオブジェクトをドメイン固有のクラスでラップし、一般的なPDF操作のための便利なメソッドを提供する
• Structure Tree（構造ツリー） – PDFドキュメント内のタグ付きコンテンツ要素の階層的な構成で、各要素はCOSDictionaryで表現される
• Indirect Object（間接オブジェクト） – オブジェクト番号と世代番号で識別されるPDFオブジェクトで、PDFドキュメント全体で複数回参照できる