モジュール java.desktop
パッケージ javax.print

クラスDocFlavor

  • すべての実装されたインタフェース:
    Serializable, Cloneable
    直系の既知のサブクラス:
    DocFlavor.BYTE_ARRAY, DocFlavor.CHAR_ARRAY, DocFlavor.INPUT_STREAM, DocFlavor.READER, DocFlavor.SERVICE_FORMATTED, DocFlavor.STRING, DocFlavor.URL

    public class DocFlavor
extends Object
implements Serializable, Cloneable
    DocFlavorクラスは、印刷データのDocPrintJobへの提供形式を指定するオブジェクトをカプセル化します。 「Doc」は、印刷データの一部を意味する、短く発音しやすい用語です。 印刷データ形式である「docフレーバ」は、次の2つで構成されます。
    • MIMEタイプ。 これは、印刷データを解釈する方法を指定するMultipurpose Internet Mail Extensions (MIME)メディア・タイプ(RFC 2045およびRFC 2046で定義)です。 テキスト・データの文字セットは、IANA MIME優先名または正規名(優先名が指定されていない場合)にする必要があります。 さらに、以前のバージョンのJavaプラットフォームでサポートされていたいくつかの名前も認識可能です。 Javaプラットフォームでサポートされる文字セットの詳細は、「文字セット」を参照してください。
    • 表現クラス名。 実印刷データの出力元オブジェクトのクラスの完全修飾名を指定します。これは、Class.getName()メソッドにより返されます。 このため、byte[]のクラス名は"[B"、char[]のクラス名は"[C"になります。

    DocPrintJobは、Docインタフェースを使用して印刷データを取得します。 DocPrintJobは、Docオブジェクトを使用して、クライアントが提供可能なdocフレーバを判別できます。 また、DocPrintJobは、Docオブジェクトを使用して、docフレーバの表現クラスのインスタンスを取得することもできます。DocPrintJobは、このインスタンスから実印刷データを取得します。

    クライアント形式の印刷データ

    印刷データは、クライアント形式の印刷データとサービス形式の印刷データの2つのカテゴリに大きく分けることができます。

    クライアント形式の印刷データの場合、クライアントは印刷データ形式を認識または判別します。 たとえば、クライアントは、JPEGで符号化されたイメージ、HTMLコードのURL、またはどれかのエンコーディングのプレーン・テキスト・ファイルを含むディスク・ファイルを(外部ソースから取得するなどして)保持することができ、印刷サービスにデータ形式を記述する手段を必要とします。

    docフレーバの表現クラスは、JPS DocPrintJobのコンジットです。この表現クラスを使用して、クライアントから文字またはバイトのシーケンスを取得できます。 docフレーバのMIMEタイプは、文字またはバイトのシーケンスの解釈方法を指定する、標準メディア・タイプのうちのいずれかです。 標準メディア・タイプのリストについては、Internet Assigned Numbers Authority (IANA)の「Media Types Directory」を参照してください。 インタフェースDocは、Docオブジェクトのクライアントがクライアント形式の印刷データを抽出する際に利用可能な2つのユーティリティ操作、getReaderForTextおよびgetStreamForBytes()を提供します。

    通常、クライアント形式の印刷データは、次のどれかの印刷データ表現クラスになります(ほかの表現クラスも使用可能)。

    • 文字配列(char[]) -- 印刷データは、配列内のUnicode文字で構成される。
    • String -- 印刷データは、文字列内のUnicode文字から構成される。
    • 文字ストリーム(java.io.Reader) -- 印刷データは、ストリームを最初から最後まで読み込んだUnicode文字で構成される。
    • バイト配列(byte[]) -- 印刷データは、配列内のバイトで構成される。 バイトは、docフレーバのMIMEタイプで指定された文字セットに符号化される。 MIMEタイプで文字セットが指定されない場合、デフォルトの文字セットであるUS-ASCIIが使用される。
    • バイト・ストリーム(java.io.InputStream) -- 印刷データは、ストリームを最初から最後まで読み込んだバイトで構成される。 バイトは、docフレーバのMIMEタイプで指定された文字セットに符号化される。 MIMEタイプで文字セットが指定されない場合、デフォルトの文字セットであるUS-ASCIIが使用される。
    • Uniform Resource Locator (URL) -- 印刷データは、URL位置から読み込まれたバイトで構成される。 バイトは、docフレーバのMIMEタイプで指定された文字セットに符号化される。 MIMEタイプで文字セットが指定されない場合、デフォルトの文字セットであるUS-ASCIIが使用される。

      表現クラスがURLの場合、クライアントを介さずに、印刷サービス自体が、URLアドレスのドキュメントへのアクセスおよびダウンロードを直接実行します。 サービスの形態は、異なる環境で実行されるネットワーク印刷サービスの場合もあります。 このため、クライアントからは可視であるがプリンタからは可視ではない制限されたURLのドキュメントは、URL印刷データ・フレーバを使用して印刷しないでください。 また、クライアントとは別個にアクセス可能なURLでは使用不可能なローカル・ファイルに格納されたドキュメントも、URL印刷データ・フレーバを使用して印刷しないでください。 HTTPサーバーまたはFTPサーバーが提供していないファイルがその例です。 このようなファイルを印刷するには、クライアントを使用して、URLまたはファイルの入力ストリームを開き、入力ストリームをデータ・フレーバとして使用します。

    デフォルトおよびプラットフォームのエンコーディング

    docフレーバのMIMEタイプにcharsetパラメータが含まれないバイト印刷データの場合、Java Print Serviceインスタンスは、US-ASCII文字セットがデフォルトで設定されているものと判断します。 これは、デフォルト文字セットをUS-ASCIIとするという、RFC 2046に基づく動作です。 US-ASCIIはUTF-8のサブセットであるため、将来RFCによりUTF-8がデフォルトとして承認された場合、US-ASCIIが互換性を維持しつつ拡張される可能性があります。

    また、これは、バイト・ストリームをテキスト・データとして解釈する場合のJava実行時の動作とは異なる場合があります。 この場合には、ユーザーのロケールのデフォルト・エンコーディングと判断されるためです。 このため、ローカル・エンコーディングのファイルをJava Print Serviceにスプールする場合には、エンコーディングを正確に指定することが重要です。 特に、英語ロケールで作業を行う開発者は、自らのプラットフォーム・エンコーディングがデフォルトMIME文字セットに対応しているので、この点を意識する必要があります。 場合によっては、プラットフォーム・データのエンコーディングを指定しなくても動作することがあるためです。

    Java仮想マシンの各インスタンスには、仮想マシンの起動時に決定されるデフォルト文字エンコーディングがあり、通常、基本オペレーティング・システムが使用するロケールおよび文字セットに依存します。 分散環境では、2つのVMが同じデフォルト・エンコーディングを共有することは保証されません。 このため、プラットフォームでエンコードされたテキスト・データを、ホスト・プラットフォームからJava Print Serviceインスタンスにストリーム処理するクライアントは、文字セットを明示的に宣言して、デフォルトに依存しないようにする必要があります。

    優先される形式は、エンコーディングの正式なIANAプライマリ名です。 テキスト・データをストリーム処理するアプリケーションは、文字セットを常にMIMEタイプで指定する必要があります。このため、ホスト・プラットフォームのエンコーディングで保存されたデータ(ファイルなど)に関する、プラットフォームのエンコーディングを取得する必要があります。 これに対応し、DocFlavorのMIMEタイプでの使用に適したCharSetは、DocFlavor.hostEncodingから取得できます。これは、常にプライマリIANA名というわけではありませんが、確実にこの仮想マシンで認識されます。 一般的なフレーバの場合、事前定義済の*HOST DocFlavorsを使用できます。

    Javaプラットフォームでサポートされる文字セットの詳細は、「文字セット」を参照してください。

    推奨されるDocFlavor

    Java Print Service APIは、必須でサポートされるDocFlavorを定義しません。 ただし、Java Print Serviceインスタンスが、クライアント形式の印刷データでサポートするMIMEタイプの例をいくつか示します。 DocFlavorクラス内部でネストされたクラスは、これらのサンプルdocフレーバに対して事前定義済static定数DocFlavorオブジェクトを宣言します。DocFlavorクラスのコンストラクタを使用して、任意のdocフレーバを作成できます。

    • 書式設定済みのテキスト
      MIMEタイプと説明
      MIMEタイプ説明
      "text/plain" デフォルト文字セット(US-ASCII)のプレーン・テキスト
      "text/plain; charset=xxx" 文字セットxxxのプレーン・テキスト
      "text/html" デフォルト文字セット(US-ASCII)のハイパーテキスト・マークアップ言語
      "text/html; charset=xxx" 文字セットxxxのハイパーテキスト・マークアップ言語

      一般に、書式設定済みのテキスト印刷データは、文字指向の表現クラス(文字配列、String、Reader)、またはバイト指向の表現クラス(バイト配列、InputStream、URL)で提供されます。

    • 書式設定済みのページ記述言語(PDL)ドキュメント
      MIMEタイプと説明
      MIMEタイプ説明
      "application/pdf" Portable Document Formatドキュメント
      "application/postscript" PostScriptドキュメント
      "application/vnd.hp-PCL" Printer Control Languageドキュメント

      一般に、書式設定済みのPDL印刷データは、バイト指向の表現クラス(バイト配列、InputStream、URL)で提供されます。

    • 書式設定済みのイメージ
      MIMEタイプと説明
      MIMEタイプ説明
      "image/gif" Graphics Interchange Formatイメージ
      "image/jpeg" Joint Photographic Experts Groupイメージ
      "image/png" Portable Network Graphicsイメージ

      一般に、書式設定済みのイメージ印刷データは、バイト指向の表現クラス(バイト配列、InputStream、URL)で提供されます。

    • 書式設定のautosense印刷データ
      MIMEタイプと説明
      MIMEタイプ説明
      "application/octet-stream" 印刷データ形式は指定されない(octetストリームのみ)

      プリンタが、印刷データの解釈方法を判別します。この「自動認識」の動作は、実装によって異なります。 一般に、事前フォーマット済のautosense印刷データは、バイト指向の表現クラス(バイト配列、InputStream、URL)で提供されます。

    サービス形式の印刷データ

    サービス形式の印刷データの場合、Java Print Serviceインスタンスが印刷データ形式を判別します。 docフレーバの表現クラスが示すインタフェースのメソッドが、DocPrintJobにより呼び出され、印刷する内容(描画可能なイメージ・インタフェースやJavaの印刷可能インタフェースなど)が決定されます。 docフレーバのMIMEタイプは、特殊な値"application/x-java-jvm-local-objectref"になります。この値は、クライアントが、表現クラスとして命名されたインタフェースを実装するJavaオブジェクトへの参照を提供することを表します。 このMIMEタイプは単なるプレースホルダーであり、重要なのは印刷データ表現クラスです。

    サービス形式の印刷データの場合、印刷データ表現クラスは(他の表現クラスを利用可能な場合でも)通常次のいずれかになります。 DocFlavorクラス内部でネストされたクラスは、これらのサンプルdocフレーバに対して事前定義済static定数DocFlavorオブジェクトを宣言します。DocFlavorクラスのコンストラクタを使用して、任意のdocフレーバを作成できます。

    • 描画可能なイメージ・オブジェクト -- クライアントは、RenderableImageインタフェースを実装するオブジェクトを提供します。 プリンタはこのインタフェース内のメソッドを呼び出して、印刷するイメージを取得します。
    • 印刷可能なオブジェクト -- クライアントは、Printableインタフェースを実装するオブジェクトを提供します。 プリンタはこのインタフェース内のメソッドを呼び出して、印刷するページをページごとに取得します。 プリンタはページごとにグラフィックス・コンテキストを提供し、クライアントによりグラフィックス・コンテキストに描画された内容がすべて印刷されます。
    • ページング可能なオブジェクト -- クライアントは、Pageableインタフェースを実装するオブジェクトを提供します。 プリンタはこのインタフェース内のメソッドを呼び出して、印刷するページをページごとに取得します。 プリンタはページごとにグラフィックス・コンテキストを提供し、クライアントによりグラフィックス・コンテキストに描画された内容がすべて印刷されます。

    定義済みのdocフレーバ

    Java Print Serviceインスタンスには、次の印刷データ形式および印刷データ表現クラスをサポートすることは要求されていません。 実際、このクラスを使用する開発者は、これらの定義済みdocフレーバに対応するドキュメント型を特定の印刷サービスがサポートしているとは絶対に想定しないでください。 常に印刷サービスに照会を行なって、サポートするdocフレーバを判別してください。 ただし、これらのdocフレーバをサポートする印刷サービスを保持する開発者は、ここで作成された定義済みの単独インスタンスを参照することをお勧めします。
    • バイト・ストリームを介して提供されるプレーン・テキスト印刷データ。 特に、次のdocフレーバのサポートが推奨されている
      ・   ("text/plain", "java.io.InputStream")
      ・   ("text/plain; charset=us-ascii", "java.io.InputStream")
      ・   ("text/plain; charset=utf-8", "java.io.InputStream")
    • 描画可能なイメージ・オブジェクト。 特に、次のdocフレーバのサポートが推奨されている
      ・   ("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")

    Java Print Serviceインスタンスは、上記の必須docフレーバに加え、任意のdocフレーバをサポート可能です(必須のdocフレーバだけに限定することも可)。

    印刷を行うクライアントが、プリンタがサポートするdocフレーバに関係なく、任意のJPSプリンタで印刷可能であると判断できるようにするために、前述のdocフレーバのサポートが推奨されています。 プリンタがクライアントの優先docフレーバをサポートしない場合、クライアントは少なくともプレーン・テキストを印刷できます。また、データを描画可能イメージに変換してからイメージを印刷することも可能です。

    各Java Print Serviceインスタンスは、次に示すプレーン・テキスト印刷データの処理要件も満たす必要があります。

    • 復帰文字と改行文字のペア(CR-LF)は、「次の行の第1列に移動する」ことを意味する
    • 復帰(CR)文字は、それ自体で「次の行の第1列に移動する」ことを意味する
    • 改行(LF)文字は、それ自体で「次の行の第1列に移動する」ことを意味する

    クライアントは、上記の要件に含まれない、すべてのプレーン・テキスト印刷データの書式設定を実行する必要があります。

    設計の根拠

    javax.print.dataパッケージ内のDocFlavorクラスは、DataFlavorクラスに類似しています。 Java Print Service (JPS) APIでは、DataFlavorクラスは次の3つの理由で使用されません。これらの理由はどれも、JPS APIを共有可能な他の印刷サービスAPIが、Java Platform, Standard Editionのすべてを含まないJavaプロファイル上で実行される場合があることに由来しています。

    1. JPS APIは、AWTをサポートしないJavaプロファイルで使用するよう設計されている。
    2. java.awt.datatransfer.DataFlavorクラスの実装は、等価なデータ・フレーバが同じ直列化表現を保持することを保証しない。 DocFlavorをサービスで使用することで、等価なデータ・フレーバが同じ直列化表現を保持することが保証される。
    3. java.awt.datatransfer.DataFlavorクラスの実装には、判読可能な名前が直列化表現の一部に含まれる。 これは、サービス一致制約の一部としては不適切である。

    DocFlavorクラスの直列化表現は、次に示す正規の形式のMIMEタイプ文字列を使用します。 このため、同一ではなく等価(正規形式が同じ)のMIMEタイプを保持する2つのdocフレーバは、等しいと見なすことができます。

    • メディア・タイプ、メディア・サブタイプ、およびパラメータは保持されるが、コメントおよび空白文字はすべて破棄される
    • メディア・タイプ、メディア・サブタイプ、およびパラメータ名は、小文字に変換される
    • パラメータ値は元の大文字/小文字を保持する。ただし、テキスト・メディア・タイプの文字セット・パラメータ値は、小文字に変換される
    • パラメータ値を囲む引用符文字は、削除される
    • パラメータ値内部の引用バックスラッシュ文字は、削除される
    • パラメータは、パラメータ名をキーにして昇順に配置される

    DocFlavorクラスの直列化表現には、表現クラスそのもの(Classオブジェクト)ではなく、表現クラスの完全修飾クラス名 (Stringオブジェクト)も含まれます。 クライアントは、このクラス名を利用することで、表現クラスをロードしなくても、Java Print Serviceインスタンスがサポートするdocフレーバを検証できます。クライアントの使用可能なリソースが限られている場合、表現クラスのロードで問題が発生することがあるため、これは有用な方法です。

    関連項目:
    直列化された形式

    • ネストされたクラスのサマリー

      ネストされたクラス 
      修飾子と型 クラス 説明
      static class  DocFlavor.BYTE_ARRAY
      DocFlavor.BYTE_ARRAYクラスは、事前定義されたstatic定数DocFlavorオブジェクトを提供します。バイト配列(byte[])を印刷データ表現クラスとして使用するdocフレーバはその例です。
      static class  DocFlavor.CHAR_ARRAY
      DocFlavor.CHAR_ARRAYクラスは、事前定義されたstatic定数DocFlavorオブジェクトを提供します。文字配列(char[])を印刷データ表現クラスとして使用するdocフレーバはその例です。
      static class  DocFlavor.INPUT_STREAM
      DocFlavor.INPUT_STREAMクラスは、事前定義されたstatic定数DocFlavorオブジェクトを提供します。バイト・ストリーム(java.io.InputStream)を印刷データ表現クラスとして使用するdocフレーバはその例です。
      static class  DocFlavor.READER
      DocFlavor.READERクラスは、事前定義されたstatic定数DocFlavorオブジェクトを提供します。文字ストリーム(java.io.Reader)を印刷データ表現クラスとして使用するdocフレーバはその例です。
      static class  DocFlavor.SERVICE_FORMATTED
      DocFlavor.SERVICE_FORMATTEDクラスは、定義済みのstatic定数DocFlavorオブジェクト(例、サービス形式の印刷データ用docフレーバ)を提供します。
      static class  DocFlavor.STRING
      DocFlavor.STRINGクラスは、事前定義されたstatic定数DocFlavorオブジェクトを提供します。文字列(java.lang.String)を印刷データ表現クラスとして使用するdocフレーバはその例です。
      static class  DocFlavor.URL
      DocFlavor.URLクラスは、事前定義されたstatic定数DocFlavorオブジェクトを提供します。

    • フィールドのサマリー

      フィールド 
      修飾子と型 フィールド 説明
      static String hostEncoding
      ホスト・オペレーティング・システムのエンコーディングを表す文字列です。

    • コンストラクタのサマリー

      コンストラクタ 
      コンストラクタ 説明
      DocFlavor​(String mimeType, String className)
      指定されたMIMEタイプおよび表現クラス名から新規docフレーバ・オブジェクトを構築します。

    • フィールドの詳細

      • hostEncoding

        public static final String hostEncoding
        ホスト・オペレーティング・システムのエンコーディングを表す文字列です。 これは「 RFC 2278: IANA Charset Registration Procedures」に記載されている規則に従います。ただし、Javaプラットフォームの以前のバージョンとの互換性を維持するため、履歴名が返される点が異なります。 メソッドから返される値は、値を返す仮想マシンで、DocFlavorで使用する場合のみ有効です。 これは、実行するVM内の、「HOST」が事前定義済のすべてのDocFlavorに対応する文字セットです。

    • コンストラクタの詳細

      • DocFlavor

        public DocFlavor​(String mimeType,
                 String className)
        指定されたMIMEタイプおよび表現クラス名から新規docフレーバ・オブジェクトを構築します。 指定されたMIMEタイプは、正規の形式に変換され、内部に格納されます。
        パラメータ:
        mimeType - MIMEメディア・タイプ文字列。
        className - 完全指定の表現クラス名。
        例外:
        NullPointerException - 非チェック例外。mimeTypeがnullの場合、またはclassNameがnullの場合にスローされる。
        IllegalArgumentException - 非チェック例外。mimeTypeがMIMEメディア・タイプ文字列の構文に従わない場合にスローされる。

    • メソッドの詳細

      • getMimeType

        public String getMimeType​()
        このdocフレーバ・オブジェクトのMIMEタイプ文字列を、正規の形式で返します。 各パラメータ値は、引用符で囲まれる。
        戻り値:
        MIMEタイプ

      • getMediaType

        public String getMediaType​()
        このdocフレーバ・オブジェクトのメディア・タイプを(MIMEタイプから)返します。
        戻り値:
        メディア・タイプ

      • getMediaSubtype

        public String getMediaSubtype​()
        このdocフレーバ・オブジェクトのメディア・サブタイプを(MIMEタイプから)返します。
        戻り値:
        メディア・サブタイプ

      • getParameter

        public String getParameter​(String paramName)
        MIMEパラメータを表すStringを返します。 MIMEタイプには、通常オプションのパラメータを含めることができます。 テキスト・タイプの文字セットは、サンプルとしてよく使用されます。 このメソッドは、指定されたパラメータの値がこのフレーバのMIMEタイプ内に指定されている場合に、その値を返します。
        パラメータ:
        paramName - パラメータの名前。 マッチングの実行前に、この名前は内部で正規の小文字形式に変換される。
        戻り値:
        MIMEパラメータを表す文字列。または、パラメータがMIMEタイプ文字列に存在しない場合はnull。
        例外:
        NullPointerException - paramNameがnullの場合。

      • getRepresentationClassName

        public String getRepresentationClassName​()
        このdocフレーバ・オブジェクトの表現クラスの名前が返されます。
        戻り値:
        表現クラスの名前

      • toString

        public String toString​()
        このDocFlavorを文字列に変換します。
        オーバーライド:
        toString、クラス: Object
        戻り値:
        正規の形式に基づくMIMEタイプ文字列。 各パラメータ値は、引用符で囲まれる。 表現クラス名を示すために、「class=」パラメータがMIMEタイプ文字列に追加される。

      • equals

        public boolean equals​(Object obj)
        このdocフレーバ・オブジェクトが指定されたオブジェクトに等しいかどうかを判別します。 指定されたオブジェクトがnullではなく、DocFlavorのインスタンスであり、このdocフレーバ・オブジェクトのMIMEタイプと等価なMIMEタイプを保持する(つまり、MIMEタイプが同じメディア・タイプ、メディア・サブタイプ、およびパラメータを保持する)場合、およびこのdocフレーバ・オブジェクトと同じ表現クラス名を保持する場合、2つのオブジェクトは等しくなります。 このため、2つのdocフレーバ・オブジェクトのMIMEタイプがコメントを除き同一の場合、これらは等しいと見なされます。 ただし、MIMEタイプ「text/plain」および「text/plain; charset=US-ASCII」を保持する2つのdocフレーバ・オブジェクトは、同じメディア・タイプを表す場合でも、等しいとは見なされません(プレーン・テキストのデフォルト文字セットがUS-ASCIIであるため)。
        オーバーライド:
        equals、クラス: Object
        パラメータ:
        obj - 判定されるオブジェクト。
        戻り値:
        このdocフレーバ・オブジェクトがobjに等しい場合はtrue、そうでない場合はfalse。
        関連項目:
        Object.hashCode(), HashMap