COSArrayList

COSArrayListは、Apache PDFBoxにおけるJavaクラスで、JavaのList標準インターフェースと、PDFオブジェクトを表現するために使用される低レベルの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文書構造の基盤となるオブジェクトシステムです。このクラスにより、開発者はPDFの配列構造を、使い慣れたJavaコレクション操作で扱いながら、基盤となるPDFオブジェクトモデルへの直接アクセスを維持することができます。

COSArrayListは、JavaのListインターフェースの特殊な実装で、COSArrayオブジェクトをラップします。COSArrayは、 ( 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表現です。メモリ内にJavaオブジェクトを格納する標準的なJavaコレクションとは異なり、COSArrayListはPDFのネイティブオブジェクト構造への直接的な接続を維持します。開発者がCOSArrayListに要素を追加、削除、または変更すると、これらの操作は直ちに基盤となるCOSArrayに反映され、その後PDFファイルのバイトストリームに直接シリアル化できます。

このクラスは、いくつかの重要な点で標準的なJava Listと異なります。第一に、PDFがサポートする内容に基づいた型制約を適用します。要素はCOSオブジェクト（文字列、数値、辞書、配列、その他のPDFプリミティブ）に変換可能でなければなりません。第二に、Java型とCOS型の間で自動変換を実行します。第三に、双方向同期を維持します。つまり、COSArrayListまたはその基盤となるCOSArrayのいずれかへの変更は、両方のインターフェースを通じて即座に可視化されます。

プログラムによってPDF文書を操作する開発者にとって、COSArrayListは低レベルのPDF操作を大幅に簡素化します。PDFBoxのCOSオブジェクトモデル全体を学習し、PDF配列構造を手動で管理する代わりに、開発者はadd()、get()、remove()などの使い慣れたJavaコレクションメソッドを使用でき、標準的なfor-eachループで反復処理できます。これは、注釈配列、ページコンテンツストリーム、または ( Citation: PDF Association, 2023 PDF Association(2023). Retrieved from https://pdfa.org/resource/tagged-pdf-best-practice-guide-syntax/ ) で定義されているTagged PDF内の構造化コンテンツ要素などの複雑なPDF構造を扱う際に特に有用です。

このクラスは、型変換を処理し、JavaとPDFオブジェクト表現の間の一貫性を維持することで、一般的なエラーも防止します。COSArrayListがなければ、開発者はすべてのJavaオブジェクトを対応するCOS型に手動で変換し、基盤となるPDF構造を明示的に更新する必要があり、冗長でエラーが発生しやすいコードになります。

COSArrayListはCOSArrayインスタンスをラップし、Listインターフェースとの互換性を提供しながら、すべての操作をそれに委譲します。Javaオブジェクトがリストに追加されると、COSArrayListは自動的に適切なCOS型に変換します。例えば、JavaのStringはCOSStringになり、IntegerはCOSIntegerになり、MapオブジェクトはCOSDictionaryオブジェクトに変換できます。変換プロセスは、 ( 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仕様により定義された型マッピング規則に従います。

このクラスは、データをコピーするのではなく、基盤となるCOSArrayへの参照を維持します。これは、複数のCOSArrayListインスタンスが同じCOSArrayをラップでき、任意のラッパーを通じて行われた変更がすべてに即座に可視化されることを意味します。PDF文書が保存されると、PDFBoxはCOSArrayを直接PDFファイル形式にシリアル化し、COSArrayListインターフェースを通じて行われたすべての変更を保持します。

内部的に、COSArrayListは標準のListメソッドを、同等のCOSArray操作に変換することで実装しています。例えば、list.get(index)はその位置のCOSオブジェクトを取得し、適切なJava型に変換して戻します。この双方向変換は透過的に行われ、開発者がPDFの内部構造に完全な忠実性を維持しながら、完全にJavaで作業できるようにします。

• COSArray – Carousel Object Structure内のPDF配列オブジェクトを表すPDFBoxの基盤クラス
• COSDictionary – PDF文書全体で使用されるキー・バリュー構造であるPDF辞書オブジェクトを表すPDFBoxクラス
• COSBase – PDFBoxのすべてのCOSオブジェクトのルート抽象クラス
• PDDocument – PDF文書全体を表すPDFBoxの高レベルクラス
• Carousel Object Structure（COS） – PDF仕様で定義されている、すべてのPDFコンテンツのための低レベルオブジェクトモデル