javax.print
介面 Doc

所有已知實作類別：

SimpleDoc

public interface Doc

介面 Doc 指定某個物件的介面，該介面為 PrintJob 提供部分列印資料。"Doc" 是一個簡短、易於發音的術語，指“部分列印資料”。客戶端向 PrintJob 傳遞一個實作介面 Doc 的物件，PrintJob 則在該物件上調用方法來獲得列印資料。Doc 介面允許 PrintJob：

• 確定所提供的列印資料的格式，或 "doc flavor"（類別 DocFlavor）。doc flavor 指定了列印資料格式（MIME 型別）和提供列印資料的物件的表示形式類別。

• 獲得列印資料表示形式物件，它是 doc flavor 表示形式類別的實例。然後 PrintJob 可從該表示形式物件獲得實際的列印資料。

• 獲得各種列印屬性，這些屬性指定該 doc 的其他特徵，或者指定用於該 doc 的處理指令。列印屬性在 javax.print.attribute 套件中定義。doc 返回其存儲在 javax.print.attribute.DocAttributeSet 中的列印屬性。

每次調用介面 Doc 實作中的方法時，都允許該方法返回相同的物件。對於　PrintJob　或 doc 物件的其他調用者也是這樣，其中，當調用者獲得列印資料時，其列印資料表示形式物件「使用」該列印資料，例如作為串流的列印資料表示形式物件。一旦 PrintJob 已經調用了 getPrintData() 並且獲得了該串流，則對 getPrintData() 的所有其他調用都返回相同的串流物件（對它的讀取可能已經進行），而不是 從頭開始重新讀取列印資料的新串流物件。指定 doc 物件具有此行為可簡化 doc 物件的實作，根據 doc 只向一個 PrintJob 傳送列印資料，而不是向多個 PrintJob 傳送列印資料可以證明。（要向多個不同的 PrintJob 傳送相同的列印資料，必須在同一列印資料源上創建多個不同的 doc 物件。）

介面 Doc 提供了極佳的實作靈活性。建構 doc 物件時，列印資料可能已經存在。在這種情況下，可將 doc 的方法所返回的物件提供給該 doc 的建構子、提前存儲在該 doc 中，以及只是在調用時返回該物件。另外，建構 doc 物件時，列印資料可能不存在。在這種情況下，doc 物件可能延遲提供一個實作，該實作僅在 PrintJob 為它調用方法（當 PrintJob 調用 getPrintData() 方法）時才產生列印資料表示形式物件（和/或列印資料）。

對於共時存取同一個 doc 的客戶端執行緒數目沒有限制。因此，介面 Doc 的所有實作必須設計為多執行緒安全的。

但是對於從 Doc 所獲得的列印資料而言，只能有一個使用者。

如果從客戶端獲得作為串流的列印資料（通過調用 Doc 的 getReaderForText() 或 getStreamForBytes() 方法），或者因為列印資料源已經是一個 InputStream 或 Reader，則 PrintService 在所有作業完成的情況下，始終應該關閉客戶端的這些串流。注意以下警告。如果列印資料本身是一個串流，則 PrintService 總是關閉它。如果列印資料是可以以串流形式請求的其他內容，則 PrintService 僅在其終止前已獲得串流的情況下才關閉該串流。也就是說，僅僅因為 PrintService 可能請求串流形式的資料並不意味著（也不暗含著），這些依賴 PrintService 來關閉它們的 Doc 實作程序應該只為回應服務的請求才創建這種串流。

方法摘要

DocAttributeSet	getAttributes() 獲取此 doc 物件的列印屬性集。
DocFlavor	getDocFlavor() 確定此 doc 物件提供其部分列印資料所用的 DocFlavor。
Object	getPrintData() 獲得列印資料表示形式物件，該物件包含此 doc 物件的部分列印資料，其格式對應於受支持的 DocFlavor。
Reader	getReaderForText() 獲得一個從此 doc 中提取字元列印資料的 reader。
InputStream	getStreamForBytes() 獲得一個從此 doc 中提取 byte 列印資料的輸入串流。

方法詳細資訊

getDocFlavor

DocFlavor getDocFlavor()

確定此 doc 物件提供其部分列印資料所用的 DocFlavor。

返回：

Doc flavor。

getPrintData

Object getPrintData()
                    throws IOException

獲得列印資料表示形式物件，該物件包含此 doc 物件的部分列印資料，其格式對應於受支持的 DocFlavor。getPrintData() 方法返回一個表示形式類別的實例，其名稱由 getDocFlavor()、getRepresentationClassName() 給定，可將返回值從類別 Object 強制轉換為該表示形式類別。

返回：

列印資料表示形式物件。

拋出：

IOException - 如果表示形式類別是一個串流且在建構該串流時存在 I/O 錯誤。

getAttributes

DocAttributeSet getAttributes()

獲取此 doc 物件的列印屬性集。如果返回的屬性集包括特定屬性 X 的實例，則印表機必須為此 doc 使用該屬性值，該值覆寫作業屬性集中屬性 X 的所有值。如果返回的屬性集不包括特定屬性 X 的實例，或者返回 null，則印表機必須參考該作業的屬性集來獲得屬性 X 的值，如果在該集合中未找到該屬性值，則印表機必須使用一個與實作相關的預設值。返回的屬性集是不可修改的。

返回：

此 doc 不可修改的列印屬性集，或者為 null，以從該作業的屬性集中獲得所有屬性值。

getReaderForText

Reader getReaderForText()
                        throws IOException

獲得一個從此 doc 中提取字元列印資料的 reader。如果 DocFlavor 具有以下列印資料表示形式類別之一，則需要 Doc 實作支持此方法，否則返回 null：

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

為了從列印資料表示形式物件中以字元串流的形式讀取列印資料，使用 doc 的列印資料表示形式物件來建構並返回一個 Reader。但是，如果列印資料表示形式物件本身就是一個 Reader，則只是返回該列印資料表示形式物件。

返回：

從此 doc 中讀取列印資料字元的 Reader。如果因為此 doc 不符合上述標準而無法提供 reader，則返回 null。

拋出：

IOException - 如果創建 reader 時存在 I/O 錯誤。

getStreamForBytes

InputStream getStreamForBytes()
                              throws IOException

獲得一個從此 doc 中提取 byte 列印資料的輸入串流。如果 DocFlavor 具有以下列印資料表示形式類別之一，則需要 Doc 實作支持此方法，否則返回 null：

• byte[]
• java.io.InputStream

獲得此 doc 的列印資料表示形式物件，然後為了從列印資料表示形式物件中以 byte 串流的形式讀取列印資料，需要創建並返回一個輸入串流。但是，如果列印資料表示形式物件本身就是一個輸入串流，則只是返回該列印資料表示形式物件。

返回：

從此 doc 中讀取列印資料 byte 的輸入串流。如果因為此 doc 不符合上述標準而無法提供輸入串流，則返回 null。

拋出：

IOException - 如果創建輸入串流時存在 I/O 錯誤。