COSWriter

COSWriterは、Apache PDFBoxにおいてCOS（Carousel Object Structure）オブジェクトをPDFファイルに書き込み、シリアル化するための低レベルクラスです。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ドキュメントの内部構造を表す基礎的なオブジェクトモデルです。COSWriterは、メモリ上のCOSオブジェクト（辞書、配列、ストリーム、プリミティブ型など）を、有効なPDFファイル出力に必要な適切にフォーマットされたバイト列に変換するメカニズムを提供します。

COSWriterは、Apache PDFBoxライブラリ内の特化されたシリアル化コンポーネントで、COSオブジェクトをPDFファイル形式の表現に変換します。COSモデル自体は、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 ) で概説されている基本型（真偽値、整数、文字列、名前）、コンテナ型（配列と辞書）、バイナリデータを含むストリームオブジェクトが含まれます。

ドキュメント操作のためのユーザーフレンドリーなAPIを提供するPDDocumentやPDPageなどの高レベルPDFBoxクラスとは異なり、COSWriterは生のオブジェクトレベルで動作します。相互参照テーブルの生成、オブジェクト番号付け、間接オブジェクト参照、ストリーム圧縮などの重要な低レベルタスクを管理します。COSWriterは、PDFオブジェクトを読み取るCOSParserとは異なり、出力方向のみを扱い、オブジェクトグラフをPDFファイル保存に必要な線形化されたフォーマットに変換します。

PDF開発者にとって、COSWriterの理解は、カスタムPDF生成、低レベルドキュメント変更の実行、またはPDF出力問題のデバッグを行う際に不可欠です。ほとんどのPDFBoxユーザーは高レベルの抽象化を使用しますが、カスタムPDF機能の実装、ファイルサイズの最適化、PDF/UA ( 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標準への準拠を確保する必要がある場合など、COSを直接操作する状況では、COSWriterがオブジェクトをどのようにシリアル化するかの知識が必要になります。

COSWriterの適切な機能は、有効で標準準拠のPDFファイルを生成するために重要です。このレベルでのエラーは、リーダーで開けない破損したPDF、 ( Citation: PDF Association, 2023 PDF Association(2023). Retrieved from https://pdfa.org/resource/tagged-pdf-best-practice-guide-syntax/ ) で説明されているアクセシビリティに必要なタグ付きコンテンツを含むドキュメント構造の損失、またはPDF仕様要件の違反を引き起こす可能性があります。アクセシビリティ準拠ドキュメントを作成する開発者は、COSWriterが構造ツリーとタグ付きコンテンツ要素を正しくシリアル化することを確認する必要があります。

COSWriterは、複数段階のシリアル化プロセスを通じて動作します。

1. オブジェクト収集: COSWriterは、ドキュメントカタログから開始してCOSオブジェクトグラフをトラバースし、書き込む必要があるすべてのオブジェクトを識別し、間接オブジェクトに一意のオブジェクト番号を割り当てます。

2. 相互参照の構築: オブジェクトが書き込まれると、COSWriterは出力ファイル内の各オブジェクトのバイトオフセットを記録する相互参照テーブルを維持し、PDFリーダーが任意のオブジェクトを迅速に見つけられるようにします。

3. ストリームエンコーディング: COSStreamオブジェクトの場合、COSWriterは指定されたフィルター（Flateなどの圧縮アルゴリズム）を適用し、 ( 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 ) で要求される形式でストリーム辞書とエンコードされたストリームデータの両方を書き込みます。

4. インクリメンタル書き込み: COSWriterはインクリメンタル更新をサポートし、ファイル全体を書き直すのではなく、新しいオブジェクトと更新された相互参照セクションを追加することで、既存のPDFへの変更を可能にします。

5. トレーラー生成: 最後に、COSWriterは、必須のドキュメントメタデータと相互参照テーブルへのバイトオフセットを含むPDFトレーラー辞書を生成し、PDFファイル終端マーカーで終了します。

このクラスは、文字列内の特殊文字の適切なエスケープ、数値の正しいフォーマット、およびPDF構文規則に従ったすべてのオブジェクトタイプの適切な区切りを処理します。

• COS（Carousel Object Structure）– PDFドキュメント構造の基礎となるオブジェクトモデルで、すべてのプリミティブおよび複合データ型を定義します
• COSDocument – シリアル化前のメモリ内のPDFドキュメント全体を表すルートCOSオブジェクト
• COSDictionary – キーと値のペアを持つPDF辞書構造を表すCOSオブジェクト
• COSStream – バイナリデータと関連する辞書を含むPDFストリームオブジェクトを表すCOSオブジェクト
• PDDocument – 内部的にCOSオブジェクトを使用する、ユーザーフレンドリーなドキュメント操作APIを提供する高レベルPDFBoxクラス