COSDocument

COSDocumentは、Apache PDFBoxにおける基礎的なクラスであり、 ( 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 ) で定義されているCarousel Object Structure（COS）モデルを使用してPDFファイルの低レベル構造を表現します。このクラスは、辞書、配列、ストリーム、プリミティブ型を含むすべてのPDFオブジェクトを、未加工かつ未処理の形式でルートコンテナとして保持します。高レベルの解釈やセマンティック分析が行われる前の、内部PDF構造への直接アクセスを提供します。

COSDocumentは、 ( 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ファイルの基盤となるオブジェクトベースアーキテクチャであるCOS（Carousel Object Structure）レイヤーのApache PDFBoxにおけるJava実装です。PDDocument（PDFコンテンツのセマンティックでアプリケーション指向のビューを提供する）などの高レベルPDFBoxクラスとは異なり、COSDocumentは構文レベルで動作し、ファイル構造に現れる通りの生のPDFオブジェクトを扱います。

このクラスは、PDF文書内のすべてのCOSオブジェクトへの参照を保持します：

• COSDictionaryオブジェクト（キー・バリューペア）
• COSArrayオブジェクト（順序付きコレクション）
• COSStreamオブジェクト（関連する辞書を持つバイナリデータ）
• COSName、COSString、COSNumber、その他のプリミティブ型
• 文書のトレーラー辞書とクロスリファレンステーブル情報

COSDocumentがPDDocumentと異なるのは、PDFのセマンティクスや文書構造について一切の仮定を行わない点です。単にファイルに保存されている生のオブジェクトグラフを表現するだけであり、低レベルのPDF操作、修復、または分析タスクにおいて不可欠です。

COSDocumentの理解は、標準的な文書操作を超える高度なPDF操作を行う必要がある開発者にとって重要です。破損したPDFの処理、カスタムPDF機能の実装、またはPDFBoxの高レベルAPIでは公開されていない文書構造へのアクセスが必要な場合、COSDocumentとの直接的なやり取りが必要になります。

Tagged PDF構造 ( Citation: PDF Association, 2023 PDF Association(2023). Retrieved from https://pdfa.org/resource/tagged-pdf-best-practice-guide-syntax/ ) を必要とするアクセシビリティ実装では、開発者が生の構造ツリー要素とそれに関連する辞書を調査または修正するためにCOSDocumentにアクセスする必要がある場合があります。この低レベルアクセスは、アクセシビリティ機能のデバッグや、PDFBoxの便利メソッドで直接サポートされていないカスタムタグ付け戦略の実装において特に重要です。

パフォーマンスが重要なアプリケーションもCOSDocumentの知識から恩恵を受けます。大きなPDFファイルやバッチ操作を扱う際、高レベルの抽象化レイヤーをバイパスすることでメモリオーバーヘッドと処理時間を削減できます。

COSDocumentは、PDFファイルの完全なオブジェクトグラフのコンテナおよびマネージャーとして機能します。PDFBoxがPDFを解析する際、解析されたすべてのCOSオブジェクトへの参照を保存するCOSDocumentインスタンスを作成し、オブジェクト番号をその位置と内容にマッピングする文書のクロスリファレンステーブル（または最新のPDFではクロスリファレンスストリーム）を保持します。

典型的なワークフローは以下の通りです：

1. 解析：PDFBoxのパーサーがPDFファイル構造を読み取り、対応するCOSオブジェクトを作成し、すべてCOSDocumentインスタンスに登録します
2. オブジェクト管理：COSDocumentはすべてのCOSオブジェクトのコレクションを保持し、インクリメンタル保存のためにどのオブジェクトが変更されたかを追跡します
3. アクセス：開発者は（getTrailer()を介して）文書トレーラーを取得でき、これがオブジェクトグラフ全体をナビゲートするためのエントリーポイントとなります
4. シリアル化：保存時、COSDocumentはすべての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 ) で定義されているように、COSモデルはすべてのPDF要素を一意の識別子を持つオブジェクトとして扱います。COSDocumentは以下を提供するメソッドによってこの仕様を実装します：

• オブジェクト番号によるオブジェクトの取得
• 文書への新しいオブジェクトの追加
• オブジェクト間の間接参照の追跡
• 文書カタログとメタデータストリームの管理

開発者は通常、PDDocumentのgetDocument()メソッドを通じてCOSDocumentにアクセスし、トレーラー辞書から操作に必要な特定のオブジェクトへナビゲートします。

• PDDocument – COSDocumentの上に構築された、PDFドキュメントへのセマンティックアクセスを提供するApache PDFBoxの高レベルクラス
• COSDictionary – キー・バリューペアを含むPDF辞書オブジェクトの低レベル表現
• COSStream – 画像やコンテンツストリームなどのバイナリデータを含むPDFストリームを表すCOSオブジェクト
• Trailer Dictionary（トレーラー辞書） – 文書カタログとメタデータを参照するPDFファイルのルート辞書
• Cross-Reference Table（クロスリファレンステーブル） – オブジェクト番号をバイトオフセットにマッピングする内部PDF構造。COSDocumentによって管理される