javax.print

インタフェースDoc

既知のすべての実装クラス:

SimpleDoc

public interface Doc

Docインタフェースは、Print Job用印刷データの一部を提供するオブジェクトに対するインタフェースを指定します。「Doc」は、印刷データの一部を意味する、短く発音しやすい用語です。クライアントはPrint JobにDocインタフェースを実装するオブジェクトを渡し、Print Jobはオブジェクトに対してメソッドを呼び出して印刷データを取得します。Docインタフェースを使用することで、Print Jobは次の操作が実行可能になります。

• 印刷データが利用可能な形式または「docフレーバ」(DocFlavorクラス)を判別する。docフレーバは、印刷データ形式(MIMEタイプ)および印刷データの送信元オブジェクトの表現クラスを指す。

• docフレーバの表現クラスのインスタンスである、印刷データの表現オブジェクトを取得する。取得後に、Print Jobは、表現オブジェクトから実印刷データを取得できる。

• docの追加特性を指定する、またはdocに適用する処理命令を指定する印刷属性を取得する。印刷属性は、パッケージjavax.print.attribute内で定義される。docは、javax.print.attribute.DocAttributeSet内に格納された出力属性を返す。

Docインタフェースの実装内の各メソッドでは、メソッドの呼出しで常に同じオブジェクトを返すことが許可されます。これは、Print Jobまたはdocオブジェクトの他の呼出し側の場合、呼出し側が印刷データを取得する際、その印刷データ表現オブジェクトが、ストリームである印刷データ表現オブジェクトなどの印刷データを「消費する」ことを示します。Print JobがgetPrintData()を呼び出してストリームを取得した後でgetPrintData()を呼び出すと、すでに読込み中の同じストリーム・オブジェクトが返されます。印刷データをもう一度最初から読み込む新規ストリーム・オブジェクトが返されることはありません。このような動作を実行するdocオブジェクトを指定すると、docオブジェクトの実装を簡略化できます。これは、特定のdocが1つのPrint Job (複数の異なるPrint Jobではなく)に印刷データを送信することを考えると、理にかなっています。(同一の印刷データを複数の異なるPrint Jobに送信する場合は、1つの印刷データ・ソースの最上位に複数の異なるdocオブジェクトを作成する必要があります)。

Docインタフェースでは、実装にかなり柔軟性を持たせることができます。docオブジェクトの構築時には、印刷データがすでに存在している場合があります。この場合、docのメソッドにより返されるオブジェクトをdocのコンストラクタに提供し、前もってdoc内に格納しておくことで、呼出し時にそのまま返すだけで済みます。また、docオブジェクトの構築時に印刷データがまだ存在していない場合もあります。この場合、docオブジェクトは「レイジー」実装を提供できます。Print JobがgetPrintData()メソッドを呼び出した場合のみ、「レイジー」実装は印刷データ表現オブジェクト(や印刷データ)を生成します。

1つのdocに同時アクセス可能なクライアント・スレッド数に制限はありません。このため、Docインタフェースの実装はすべて、複数のスレッド・セーフであるように設計する必要があります。

ただし、Docから取得された印刷データのコンシューマは1つである必要があります。

DocのgetReaderForText()やgetStreamForBytes()メソッドを呼び出す、または印刷データ・ソースがInputStreamまたはReader内に存在するために、印刷データがクライアントからストリームとして取得される場合、印刷サービスはどのジョブ完了条件の場合にもクライアントに対してこれらのストリームを常に閉じる必要があります。次の点に注意してください。印刷データ自体がストリームの場合、サービスは常に印刷データを閉じます。印刷データが別の方法でストリームとして要求可能で、終了前にストリームを取得済みの場合、サービスはストリームを閉じるだけです。つまり、印刷サービスがデータをストリームとして要求する可能性があるということだけで、ストリームを閉じるサービスを利用するDoc実装者がサービスからの要求に応答してストリームを作成しなければならないわけではありません。

メソッドのサマリー

修飾子と型	メソッドと説明
DocAttributeSet	getAttributes() このdocオブジェクトの印刷属性セットを取得します。
DocFlavor	getDocFlavor() このdocオブジェクトが印刷データの一部を提供するdocフレーバを判別します。
Object	getPrintData() このdocオブジェクトの印刷データの一部を含む印刷データ表現オブジェクトを、サポートするdocフレーバに対応する形式で取得します。
Reader	getReaderForText() このdocから文字印刷データを抽出するためのリーダーを取得します。
InputStream	getStreamForBytes() このdocからバイト印刷データを抽出するための入力ストリームを取得します。

メソッドの詳細

getDocFlavor

DocFlavor getDocFlavor()

このdocオブジェクトが印刷データの一部を提供するdocフレーバを判別します。

戻り値:

Docフレーバ

getPrintData

Object getPrintData()
             throws IOException

このdocオブジェクトの印刷データの一部を含む印刷データ表現オブジェクトを、サポートするdocフレーバに対応する形式で取得します。getPrintData()メソッドは、名前がgetDocFlavor().getRepresentationClassName()で与えられる表現クラスのインスタンスを返します。戻り値は、クラスObjectから表現クラスにキャストできます。

戻り値:

印刷データ表現オブジェクト

例外:

IOException - 表現クラスがストリームであり、そのストリームの構成中に入出力エラーが発生した場合にスローされる。

getAttributes

DocAttributeSet getAttributes()

このdocオブジェクトの印刷属性セットを取得します。返される属性セットに特定の属性Xのインスタンスが含まれる場合、プリンタはその属性値をこのdocに使用して、ジョブの属性セット内の属性Xの値をすべてオーバーライドする必要があります。返される属性セットに特定の属性Xのインスタンスが含まれない場合、またはnullが返される場合、プリンタはジョブの属性セットを参照して属性Xの値を取得する必要があります。見つからない場合、プリンタは実装依存のデフォルト値を使用する必要があります。返された属性セットは変更できません。

戻り値:

このdocの変更不可能な印刷属性セット。または、ジョブの属性セットからすべての属性値を取得する場合はnull

getReaderForText

Reader getReaderForText()
                 throws IOException

このdocから文字印刷データを抽出するためのリーダーを取得します。DocFlavorが次の印刷データ表現クラスのどれかを保持する場合、Doc実装がこのメソッドをサポートする必要があります。保持しない場合、nullが返されます。

• char[]
• java.lang.String
• java.io.Reader

docの印刷データ表現オブジェクトを使用して、印刷データを文字のストリームとして読み取るためのReaderを構築して返します。ただし、印刷データ表現オブジェクト自体がReaderの場合、印刷データ表現オブジェクトが返されるだけです。

戻り値:

このdocから印刷データ文字を読み取るためのリーダー。このdocが上記の基準を満たさないためにリーダーを使用できない場合、nullが返される。

例外:

IOException - リーダーの作成中に入出力エラーが発生した場合にスローされる。

getStreamForBytes

InputStream getStreamForBytes()
                       throws IOException

このdocからバイト印刷データを抽出するための入力ストリームを取得します。DocFlavorが次の印刷データ表現クラスのどれかを保持する場合、Doc実装がこのメソッドをサポートする必要があります。保持しない場合、nullが返されます。

• byte[]
• java.io.InputStream

このdocの印刷データ表現オブジェクトの取得後に、印刷データ表現オブジェクトから印刷データをバイト・ストリームとして読み取るための入力ストリームが作成され、返されます。ただし、印刷データ表現オブジェクト自体が入力ストリームの場合は、印刷データ表現オブジェクトが返されるだけです。

戻り値:

このdocから印刷データ・バイトを読み取るための入力ストリーム。このdocが上記の基準を満たさないために入力ストリームを使用できない場合、nullが返される。

例外:

IOException - 入力ストリームの作成中に入出力エラーが発生した場合にスローされる。