モジュール 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名ではなく、このVMが理解できることが保証されています。 一般的なバーの場合、事前定義された* HOST DocFlavorsを使用することができます。

    Javaプラットフォームでサポートされている文字エンコーディングの詳細については、「文字エンコーディング」を参照してください。

    推奨されるDocFlavor

    Java Print Service APIでは、必須のDocFlavorsは定義されていません。 ただし、Java Print Serviceインスタンスが、クライアント形式の印刷データでサポートするMIMEタイプの例をいくつか示します。 クラスDocFlavor内のネストされたクラスは、これらのサンプルのフレーバの例として定義済みの静的定数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ストリームのみ)
      プリンタが、印刷データの解釈方法を判別します。この「自動認識」の動作は、実装によって異なります。 一般に、事前フォーマットされた自動感知印刷データは、バイト指向の表現クラス(バイト配列、InputStream、URL)で提供されます。

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

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

    サービス形式の印刷データの場合、印刷データ表現クラスは(他の表現クラスを利用可能な場合でも)通常次のいずれかになります。 クラスDocFlavor内のネストされたクラスは、これらのサンプルのフレーバの例として定義済みの静的定数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のクラス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オブジェクト)の完全修飾クラスnameも含まれています。 クライアントは、このクラス名を利用することで、表現クラスをロードしなくても、Java Print Serviceインスタンスがサポートするdocフレーバを検証できます。クライアントの使用可能なリソースが限られている場合、表現クラスのロードで問題が発生することがあるため、これは有用な方法です。
    関連項目:
    直列化された形式

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

      ネストされたクラス 
      修飾子と型 クラス 説明
      static class  DocFlavor.BYTE_ARRAY
      クラスDocFlavor.BYTE_ARRAYは、事前定義された静的定数DocFlavorオブジェクト(例えば、印刷データ表現クラスとしてバイト配列(byte[])を使用するdocフレーバ)を提供します。
      static class  DocFlavor.CHAR_ARRAY
      クラスDocFlavor.CHAR_ARRAYは、文字配列(char[])を印刷データ表現クラスとして使用して、docフレーバなどの事前定義された静的定数DocFlavorオブジェクトを提供します。
      static class  DocFlavor.INPUT_STREAM
      クラスDocFlavor.INPUT_STREAMは、事前定義された静的定数DocFlavorオブジェクト(例えば、印刷データ表現クラスとしてバイト・ストリーム(java.io.InputStream)を使用するdocフレーバ)を提供します。
      static class  DocFlavor.READER
      クラスDocFlavor.READERは、文字データ・ストリーム(java.io.Reader)を印刷データ表現クラスとして使用して、docフレーバなどの事前定義された静的定数DocFlavorオブジェクトを提供します。
      static class  DocFlavor.SERVICE_FORMATTED
      クラスDocFlavor.SERVICE_FORMATTEDは、定義済みの静的定数DocFlavorオブジェクト(サービス・フォーマットされた印刷データ用のdocフレーバなど)を提供します。
      static class  DocFlavor.STRING
      クラスDocFlavor.STRINGは、印刷データ表現クラスとして文字列(java.lang.String)を使用するdocフレーバなど、事前定義された静的定数DocFlavorオブジェクトを提供します。
      static class  DocFlavor.URL
      クラスDocFlavor.URLは、定義済みの静的定数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に対してのみ有効です。 これは、実行中のVM内の"HOST"の事前定義されたDocFlavorsすべての文字セットです。

    • コンストラクタの詳細

      • DocFlavor

        public DocFlavor​(String mimeType,
                 String className)
        指定されたMIMEタイプおよび表現クラス名から新規docフレーバ・オブジェクトを構築します。 指定されたMIMEタイプは、正規の形式に変換され、内部に格納されます。
        パラメータ:
        mimeType - MIMEメディア・タイプ文字列
        className - 完全修飾表現クラス名
        例外:
        NullPointerException - mimeTypeまたは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 - テストするObject
        戻り値:
        trueこのdocフレーバ・オブジェクトがobj、falseと等しい場合
        関連項目:
        Object.hashCode()、HashMap