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

public DocFlavor getDocFlavor()

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

戻り値:

Doc フレーバ

getPrintData

public Object getPrintData()
                    throws IOException

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

戻り値:

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

例外:

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

getAttributes

public DocAttributeSet getAttributes()

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

戻り値:

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

getReaderForText

public Reader getReaderForText()
                        throws IOException

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

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

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

戻り値:

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

例外:

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

getStreamForBytes

public InputStream getStreamForBytes()
                              throws IOException

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

• byte[]
• java.io.InputStream

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

戻り値:

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

例外:

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