COSArray

COSArrayは、Apache PDFBoxの中核となるクラスで、PDF文書構造内の配列オブジェクトを最低レベルで表現します。これは、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 ) で定義されているオブジェクト型に直接マッピングされるCOS（Carousel Object Structure）モデルの一部です。COSArrayは、PDF配列オブジェクトを操作するためのメソッドを提供し、開発者がプログラムによってPDFオブジェクトの順序付きコレクションを読み書きできるようにします。

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配列データ型を実装するJavaクラスです。PDF仕様において、配列は、数値、文字列、辞書、他の配列、間接参照など、あらゆるPDFオブジェクト型を含むことができる順序付きのオブジェクトコレクションです。COSArrayクラスは、PDFBox内のすべてのCOSオブジェクトの基礎となる抽象クラスCOSBaseを拡張しています。

PDFコンテンツを扱うための便利な抽象化を提供するPDModelオブジェクトなどの高レベルPDFBoxクラスとは異なり、COSArrayは生のPDFオブジェクトレベルで動作します。これは、PDFファイル内に見られる角括弧配列構文（例：[1 2 3]や[/Type /Page /Contents 5 0 R]）に直接対応することを意味します。COSArrayは、順序付きシーケンスではなくキー・バリューペアを表すCOSDictionaryのような類似のコレクションクラスや、PDFオブジェクト型とシリアル化を処理するために特別に設計されているJavaの標準コレクションクラスとは異なります。

PDF文書をプログラムで扱う開発者にとって、COSArrayはPDF構造の直接操作が必要な場合に不可欠です。PDFBoxの高レベルAPIは多くの一般的なタスクを処理しますが、ページコンテンツストリーム内の特定の配列エントリの変更、変換行列の操作、カスタムPDF構造の操作など、特定の操作にはCOSオブジェクトへの直接アクセスが必要です。COSArrayの理解は、Tagged PDF構造 ( Citation: PDF Association, 2023 PDF Association(2023). Retrieved from https://pdfa.org/resource/tagged-pdf-best-practice-guide-syntax/ ) を扱う場合や、アクセシビリティ機能 ( 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 ) を実装する場合に特に重要になります。これらの作業では、構造要素、属性、コンテンツ参照の配列を操作することが頻繁にあるためです。

配列はPDF文書全体に遍在しているため、このクラスは多くのPDF操作の基礎を提供します。配列は、ページツリー、コンテンツストリーム、色指定、バウンディングボックス、変換行列、その他多数のコンテキストに現れます。PDFを構造レベルで解析、検証、または変更する必要がある開発者は、COSArrayインスタンスに頻繁に遭遇し、それらを扱う必要があります。

COSArrayは内部的にCOSBaseオブジェクトのJava Listを保持し、インデックスによる要素の追加、削除、アクセスなどの標準的な操作を可能にします。このクラスは、add()、get()、set()、remove()、size()などのメソッドを提供し、馴染みのあるコレクション操作を反映しながら、PDFオブジェクトの型安全性を保証します。

COSArrayを扱う際、開発者は通常次のように操作します：

1. 既存の配列へのアクセス：ページ辞書やコンテンツストリームなどのPDFオブジェクトから、COSBaseオブジェクトを返すメソッドを使用してCOSArrayインスタンスを取得し、COSArrayにキャストします。

2. 新しい配列の作成：新しいCOSArrayオブジェクトをインスタンス化し、適切なCOSBase派生オブジェクト（COSInteger、COSFloat、COSName、COSDictionaryなど）で埋めます。

3. 内容の操作：インデックスベースのメソッドを使用して、配列要素を読み取り、変更、または削除します。このクラスは、JavaオブジェクトとPDFオブジェクト型間の変換を処理します。

4. 型安全な取得：型チェックと変換を自動的に処理するgetInt()、getName()、getObject()などの特殊化されたゲッターメソッドを使用します。

COSArrayクラスは、文書が保存される際にPDF構文へのシリアル化を処理し、メモリ内のJavaリスト構造を ( 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仕様への準拠を維持しながら、馴染みのあるJavaプログラミングパターンで作業できます。

• COSBase – 配列、辞書、プリミティブを含む、PDFBox内のすべてのCOSオブジェクトの抽象基底クラス
• COSDictionary – PDF辞書オブジェクトを表すCOSクラスで、COSArrayの順序付きシーケンスとは異なり、キー・バリューペアを格納します
• COSモデル – PDFBoxにおいてPDFオブジェクトプリミティブへの低レベルアクセスを提供するCarousel Object Structureモデル
• PDModel – COSクラスの上に構築された便利な抽象化を提供する、PDFBoxの高レベルAPIレイヤー
• 間接オブジェクト – 文書内の他のオブジェクトから参照できるPDFオブジェクトで、COSArray要素はCOSObject参照を使用してこれを指す場合があります