COSStream

COSStreamは、Apache PDFBoxにおける基本的なクラスで、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ストリームオブジェクトへの直接アクセスを提供します。ストリームオブジェクトは、ディクショナリとそれに続く「stream」と「endstream」キーワードで囲まれたバイナリまたはテキストデータで構成されます。COSStreamは、PDFドキュメント内のコンテンツストリーム、画像データ、埋め込みフォント、その他のバイナリリソースを処理するための基盤となります。

COSStreamは、Apache PDFBoxライブラリのJavaクラスで、最も低い抽象化レベルでPDFストリームオブジェクトを表現します。PDPageやPDImageXObjectなど、目的別の便利なAPIを提供する上位レベルのPDFBoxクラスとは異なり、COSStreamは ( 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オブジェクト構造を直接操作します。

COSStreamオブジェクトは、主に2つの要素で構成されます。ストリームに関するメタデータ（Length、Filter、DecodeParmsなどのエントリ）を含むCOSDictionaryと、実際のストリームデータです。これは、COSArrayやCOSDictionaryなど、関連するバイナリデータを持たないより単純なPDFオブジェクトタイプを表現する他のCOSオブジェクトとは異なります。ストリームデータは、さまざまなフィルタ（FlateDecode、DCTDecodeなど）を使用して圧縮でき、ページコンテンツ命令から埋め込みファイルデータまで、あらゆるものを含むことができます。

開発者は通常、ページの外観を定義するコンテンツストリームを扱う際、バイナリリソースを抽出または埋め込む際、または上位レベルのAPIが提供する範囲を超えたカスタムPDF処理を実装する際にCOSStreamを使用します。

COSStreamを理解することは、標準的なドキュメント操作を超えた高度なPDF操作タスクを実行する必要がある開発者にとって重要です。 ( Citation: PDF Association, 2023 PDF Association(2023). Retrieved from https://pdfa.org/resource/tagged-pdf-best-practice-guide-syntax/ ) に記載されているTagged PDF構造を扱う場合、開発者は適切な構造とアクセシビリティ機能を確保するために、コンテンツストリームに直接アクセスして変更する必要があることがあります。

COSStreamにより、開発者は次のことが可能になります。

• カスタムテキストまたはグラフィックス抽出のために、生のコンテンツストリームを抽出およびデコードする
• 特定の圧縮設定で画像、フォント、ファイル添付などのバイナリデータを埋め込む
• 特殊なPDF処理のためにカスタムフィルタまたは暗号化ハンドラを実装する
• 生のオブジェクト構造を調査して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 ) などの標準に準拠したアクセシブルなPDFドキュメントを作成する

PDF処理ツール、コンテンツ抽出ツール、またはアクセシビリティ検証ツールを構築する開発者にとって、COSStreamは、上位レベルのAPIが意図的に抽象化しているPDF内部への必要な低レベルアクセスを提供します。

COSStreamは、PDFストリームオブジェクトのラッパーとして機能し、ストリームディクショナリとストリームデータの両方を読み書きするメソッドを提供します。PDFが解析されると、PDFBoxは検出された各ストリームオブジェクトに対してCOSStreamインスタンスを作成し、ディクショナリメタデータとバイナリデータの関連付けを維持します。

ストリームディクショナリは、標準のCOSDictionaryメソッドを通じてアクセスされ、開発者は次のようなエントリを読み取りまたは変更できます。

• /Length – エンコードされたストリームのバイト数を指定
• /Filter – 適用される圧縮またはエンコード方式を識別
• /DecodeParms – デコードフィルタのパラメータを提供
• /Subtype – データのタイプ（Image、Formなど）を識別

ストリームデータ自体には、主に2つの方法でアクセスできます。PDFファイルに格納されているとおりのデータを返すエンコード済み（生の）InputStreamとして、または指定された解凍およびデコードフィルタを自動的に適用するデコード済み（フィルタ処理済み）InputStreamとしてです。この二重アクセスモデルにより、開発者は効率性のために圧縮データを扱うか、処理のために非圧縮データを扱うかを選択できます。

新しいCOSStreamを作成する場合、開発者はオブジェクトをインスタンス化し、必要なエントリをディクショナリに入力し、COSOutputStreamを使用するか、InputStreamをソースとして設定してデータを書き込みます。PDFが保存されるとき、PDFBoxはエンコーディングと長さの計算を自動的に処理しますが、開発者は特定の圧縮要件に対してカスタムフィルタとパラメータを指定することもできます。

このクラスは他のCOSクラスとシームレスに統合されます。PDFオブジェクトは間接オブジェクト参照（COSObject）を通じてストリームを頻繁に参照し、ストリーム自体もそのディクショナリ内で他のPDFオブジェクトへの参照を含むことがあります。

• COS（Carousel Object Structure） – Apache PDFBoxがPDFファイル構造を表現するために使用する低レベルオブジェクトモデル
• COSDictionary – キーと値のペアを格納し、ストリームオブジェクトのヘッダーとして機能するPDFディクショナリオブジェクトを表現するクラス
• PDStream – 一般的なユースケースに対してより便利なストリームアクセスを提供するために、COSStreamをラップする上位レベルのPDFBoxクラス
• Content Stream – ページの外観を定義するグラフィックスオペレータとオペランドを含む特定のタイプのストリーム
• Stream Filter – FlateDecodeやDCTDecodeなど、ストリームデータに適用される圧縮またはエンコード方式