COSNumber

COSNumberは、Apache PDFBoxのCOS（Carousel Object Structure）レイヤーにおける基礎クラスであり、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 ) で定義されているプリミティブデータ型に直接マッピングされるJavaオブジェクトを提供します。COSNumberは、PDFファイル構造に現れる整数値と浮動小数点数値の両方を扱います。

COSNumberは、Apache PDFBoxにおけるPDF処理の最下層レベルで数値オブジェクトを表現する抽象基底クラスです。このクラスは、2つの具象実装クラスの親クラスとして機能します：COSInteger（整数用）とCOSFloat（小数用）です。PDFコンテンツを扱うための便利な抽象化を提供する上位レベルのPDFBoxクラスとは異なり、COSNumberは ( 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操作タスクに不可欠です。

COSNumberが属するCOSレイヤーは、初期のPDF実装で使用されていたCarousel Object Structureに由来します。このレイヤーは、JavaオブジェクトとPDFファイル構造の間に1対1のマッピングを提供します。つまり、COSNumberオブジェクトは、実際のPDFファイル構文に現れる数値を直接表現しています。

COSNumberの理解は、コンテンツの直接操作、カスタムPDF生成、PDF構造の問題のデバッグなど、低レベルのPDF操作を必要とする開発者にとって重要です。PDFBoxで作業する際、開発者は数値データを含む辞書の値、配列要素、ストリームパラメータにアクセスする時に、頻繁にCOSNumberオブジェクトに遭遇します。例えば、Tagged PDF構造 ( Citation: PDF Association, 2023 PDF Association(2023). Retrieved from https://pdfa.org/resource/tagged-pdf-best-practice-guide-syntax/ ) におけるページ寸法、変換行列、色値を操作する場合、通常はCOSNumberオブジェクトを使用して値を取得・設定します。

また、このクラスはパフォーマンスが重要なアプリケーションにとっても重要です。COSオブジェクトを直接操作することで、上位レベルの抽象化を回避し、PDFデータへのより効率的なアクセスが可能になります。これは、大きなPDFファイルを処理する場合や、オブジェクト生成のオーバーヘッドを最小化することが重要なバッチ操作を実行する場合に特に関連します。

COSNumberは、PDFBoxの3層アーキテクチャの一部として機能します：COSレイヤー（最下層）、PD（PDF Document）レイヤー（中間層）、コンテンツストリームレイヤー（最上層）です。PDFBoxがPDFファイルを解析する際、数値はCOSNumberインスタンスに変換され、ソースファイルからの正確な表現が維持されます。

コード内でCOSNumberを使用する場合、開発者は通常、COSBaseオブジェクト（すべてのCOS型の親クラス）を返すまたは受け入れるメソッドを通じて対話します。例えば、PDF辞書から数値を取得するとCOSNumberが返され、それをintValue()やfloatValue()などのメソッドを使用してJavaプリミティブ型に変換できます。数値を設定する場合、開発者は新しいCOSIntegerまたはCOSFloatインスタンスを作成し、COSDictionaryやCOSArrayなどのCOSコンテナに追加します。

このクラスは数値の不変性を維持しており、一度作成されるとCOSNumberの値は変更できません。この設計上の決定により、スレッドセーフティが保証され、PDF構造への意図しない変更が防止されます。PDF内の数値を変更する必要がある場合は、新しいCOSNumberインスタンスを作成し、親コンテナ内の既存の参照を置き換えます。

• COSBase – PDFBoxにおけるすべてのCOSオブジェクト（COSNumber、COSString、COSDictionary、COSArrayなど）の抽象親クラス
• COSDictionary – PDF辞書オブジェクトを表現するCOSクラスで、エントリとしてCOSNumber値を含むことが多い
• COSArray – PDF配列オブジェクトを表現するCOSクラスで、COSNumber値のシーケンスを含むことができる
• PDDocument – COSオブジェクト上に構築された、PDF文書全体を表現する上位レベルのPDFBoxクラス
• Content Stream – 描画演算子とオペランドを含むPDF構造で、COSNumber値が数値パラメータとして頻繁に現れる