javax.print

クラス DocFlavor

java.lang.Object

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[]) -- 印刷データは、配列内の Unicde 文字で構成される。

• 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 タイプ	説明
  "text/plain"	デフォルト文字セット (US-ASCII) のプレーンテキスト
  "text/plain; charset=xxx"	文字セット xxx のプレーンテキスト
  "text/html"	デフォルト文字セット (US-ASCII) のハイパーテキストマークアップ言語
  "text/html; charset=xxx"	文字セット xxx のハイパーテキストマークアップ言語

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

• 書式設定済みのページ記述言語 (PDL) ドキュメント

  MIME タイプ	説明
  "application/pdf"	Portable Document Format ドキュメント
  "application/postscript"	PostScript ドキュメント
  "application/vnd.hp-PCL"	Printer Control Language ドキュメント

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

• 書式設定済みのイメージ

  MIME タイプ	説明
  "image/gif"	Graphics Interchange Format イメージ
  "image/jpeg"	Joint Photographic Experts Group イメージ
  "image/png"	Portable Network Graphics イメージ

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

• 書式設定の autosense 印刷データ

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

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

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

  サービス形式の印刷データの場合、Java Print Service インスタンスが印刷データ形式を判別します。doc フレーバの表現クラスが示すインタフェース (描画可能なイメージインタフェースや Java で印刷可能なインタフェースなど) のメソッドが、DocPrintJob により呼び出され、印刷する内容が決定されます。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 フレーバのサポートが推奨されているため、印刷を行うクライアントは、プリンタがサポートする doc フレーバに関係なく、任意の JPS プリンタに印刷可能であると判断して差し支えありません。プリンタがクライアントの優先 doc フレーバをサポートしない場合、クライアントは少なくともプレーンテキストは印刷できます。 また、データを描画可能なイメージに変換してからイメージを印刷することも可能です。

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

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

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

  設計の根拠

  javax.print.data パッケージ内の DocFlavor クラスは、DataFlavor クラスに類似しています。Java Print Service (JPS) API では、DataFlavor クラスは次の 3 つの理由で使用されません。これらの理由はどれも、JSP 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 フレーバオブジェクトを構築します。

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
boolean	equals(Object obj) この doc フレーバオブジェクトが指定されたオブジェクトに等しいかどうかを判別します。
String	getMediaSubtype() この doc フレーバオブジェクトのメディアサブタイプを (MIME タイプから) 返します。
String	getMediaType() この doc フレーバオブジェクトのメディアタイプを (MIME タイプから) 返します。
String	getMimeType() この doc フレーバオブジェクトの MIME タイプ文字列を、正規の形式で返します。
String	getParameter(String paramName) MIME パラメータを表す String を返します。
String	getRepresentationClassName() この doc フレーバオブジェクトの表現クラスの名前が返されます。
int	hashCode() この doc フレーバオブジェクトのハッシュコードを返します。
String	toString() この DocFlavor を文字列に変換します。

クラス java.lang.Object から継承されたメソッド

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

フィールドの詳細

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。

例外:

throws - paramName が null の場合に NullPointerException がスローされる。

getRepresentationClassName

public String getRepresentationClassName()

この doc フレーバオブジェクトの表現クラスの名前が返されます。

戻り値:

表現クラスの名前

toString

public String toString()

この DocFlavor を文字列に変換します。

オーバーライド:

toString、クラス: Object

戻り値:

正規の形式に基づく MIME タイプ文字列。各パラメータ値は、引用符で囲まれる。表現クラス名を示すために、「class=」パラメータが MIME タイプ文字列に追加される。

hashCode

public int hashCode()

この doc フレーバオブジェクトのハッシュコードを返します。

オーバーライド:

hashCode、クラス: Object

戻り値:

このオブジェクトのハッシュコード値。

関連項目:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

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