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 flavor" 由兩方面的內容組成：

• MIME 型別。 這是一個多用途的 Internet 郵件擴展 (MIME) 媒體型別（在 RFC 2045 和 RFC 2046 中定義），指定了如何解釋列印資料。文本資料的字元集應該是 IANA MIME 優先名稱，如果未指定優先名稱，則使用其規範名稱。另外也可識別較早 Java 平臺版本所支持的一些歷史名稱。有關 Java 平臺所支持的字元編碼的更多資訊，請參閱字元編碼。

• 表示形式類別名。 這指定了提供實際列印資料的物件的完全限定類別名，由 Class.getName() 方法返回。（因此 byte[] 的類別名是 "[B"，char[] 的類別名是 "[C"。）

DocPrintJob 通過介面 Doc 獲得其列印資料。Doc 物件允許 DocPrintJob 來確定客戶端可以提供的 doc flavor。Doc 物件還允許 DocPrintJob 獲得一個 doc flavor 的表示形式類別的實例，然後 DocPrintJob 可從中獲得實際的列印資料。

客戶端格式化列印資料

有兩大類別的列印資料：客戶端格式的列印資料和服務格式的列印資料。

對於客戶端格式的列印資料，客戶端確定或知道該列印資料格式。例如，客戶端可能有 JPEG 編碼的圖像、HTML 程式碼的 URL 或以某種編碼形式包含純文本的磁碟檔案（可能從外部源獲得），並且需要某種方式向列印服務描述資料格式。

doc flavor 的表示形式類別是 JPS DocPrintJob 的一個管道，可從客戶端獲得字元或 byte 序列。doc flavor 的 MIME 型別是標準的媒體型別之一，通知如何解釋字元或 byte 序列。有關標準媒體型別的列表，請參閱 Internet 編號分派機構 (IANA) 的媒介型別目錄。介面 Doc 提供兩個實用操作：getReaderForText 和 getStreamForBytes()，用來說明 Doc 物件的客戶端提取客戶端格式的列印資料。

對於客戶端格式化列印資料，列印資料表示形式類別通常是以下之一（雖然也允許使用其他表示形式類別）：

• 字元陣列 (char[]) -- 列印資料由陣列中的 Unicde 字元所組成。

• String -- 列印資料由 string 中的 Unicde 字元組成。

• 字元串流 (java.io.Reader) -- 列印資料由從串流中讀取（一直讀取到串流的末尾）的 Unicode 字元組成。

• Byte 陣列 (byte[]) -- 列印資料由陣列中的 byte 所組成。這些 byte 在 doc flavor 的 MIME 型別所指定的字元集中編碼。如果 MIME 型別未指定某個字元集，則預設的字元集是 US-ASCII。

• Byte 串流 (java.io.InputStream) -- 列印資料由從串流中讀取（一直讀取到串流的末尾）的 byte 所組成。這些 byte 在 doc flavor 的 MIME 型別所指定的字元集中編碼。如果 MIME 型別未指定某個字元集，則預設的字元集是 US-ASCII。
• 統一資源定位符 (URL) -- 列印資料由從 URL 位置讀取的 byte 所組成。這些 byte 在 doc flavor 的 MIME 型別所指定的字元集中編碼。如果 MIME 型別未指定某個字元集，則預設的字元集是 US-ASCII。

  當表示形式類別是一個 URL 時，列印服務本身直接存取其 URL 位址並下載文檔，與客戶端無關。該服務可以是在不同環境中執行的某種網路列印服務形式。這意味著不應使用 URL 列印資料 flavor 來列印位於受限制 URL 處的文檔，在這種 URL 處，客戶端可以看到該文檔但印表機無法看到。這還意味著不應使用 URL 列印資料 flavor 來列印存儲在本地檔案中的文檔，在客戶端可獨立存取的 URL 處無法提供這種文檔。例如，一個並非由 HTTP 伺服器或 FTP 伺服器所提供的檔案。要列印這種文檔，應該讓客戶端在該 URL 或檔案上打開一個輸入串流並使用輸入串流資料 flavor。

預設編碼和平臺編碼

對於其 doc flavor 的 MIME 型別未包括 charset 參數的 byte 列印資料而言，Java 列印服務實例假定預設的字元集是 US-ASCII。這與 RFC 2046 保持一致，它宣告預設的字元集是 US-ASCII。注意，US-ASCII 是一個 UTF-8 子集，所以如果未來 RFC 以相容的方式將 UTF-8 作為預設值，則可能會擴大該字元集。

還要注意，當以文本資料的形式解釋 byte 串流時，這與 Java 運行時的行為有所不同。這假定了用於使用者語言環境的預設編碼。因此，當以本地編碼形式使用 Java 列印服務後台列印某個檔案時，正確指定編碼很重要。在英語語言環境中工作的開發人員應該特別注意這一點，因為其平臺編碼對應於預設的 mime 字元集。在這種純屬巧合的特定情況下，不指定平臺資料的編碼也可工作。

每個 Java 虛擬機器實例都具有在虛擬機器啟動期間所確定的預設字元編碼，並且該預設編碼通常取決於底層作業系統使用的語言環境和字元集。在分佈式環境中，不保證兩個 VM 共享同一預設編碼。因此，希望以串流的形式將平臺編碼文本資料從主機平臺發送到 Java 列印服務實例的客戶端，必須顯式地宣告字元集，而不能依賴於預設值。

首選的形式是正式的 IANA 編碼主名稱。以串流形式發送文本資料的應用程序應該始終在 mime 型別中指定字元集，這就需要為資料（如檔案，以該平臺的編碼形式存儲）獲得主機平臺的編碼形式。可從 DocFlavor.hostEncoding 獲得與此對應且適合以 DocFlavor 的 mime 型別所使用的 CharSet。這可能不會總是主 IANA 名稱，但是可保證是此 VM 所理解的 CharSet。對於公共的 flavor，可以使用預定義的 *HOST DocFlavor。

有關 Java 平臺所支持的字元編碼的更多資訊，請參閱字元編碼。

推薦的 DocFlavor

Java Print Service API 未定義任何強制支持的 DocFlavor。但是，對於客戶端格式化列印資料，以下是 Java Print Service 實例可以支持的 MIME 型別的範例。類別 DocFlavor 內的巢狀類別為這些範例 doc flavor 宣告了預定義的靜態常數 DocFlavor 物件；可使用類別 DocFlavor 的建構子來創建任意的 doc flavor。

• 預格式化的文本

  MIME 型別	描述
  "text/plain"	預設字元集 (US-ASCII) 中的純文本
  "text/plain; charset=xxx"	字元集 xxx 中的純文本
  "text/html"	預設字元集形式 (US-ASCII) 的超文本標記語言
  "text/html; charset=xxx"	字元集 xxx 形式的超文本標記語言

  一般情況下，預先格式化的文本列印資料要麼由表示形式類別以字元方式提供（字元陣列、String、Reader），要麼由表示形式類別以 byte 方式提供（byte 陣列、InputStream、URL）。

• 預格式化的頁面描述語言 (PDL) 文檔

  MIME 型別	描述
  "application/pdf"	便攜文檔格式文檔
  "application/postscript"	PostScript 文檔
  "application/vnd.hp-PCL"	印表機控制語言文檔

  一般情況下，預格式化的 PDL 列印資料在導向 byte 的表示形式類別（byte 陣列、InputStream、URL）中提供。

• 預格式化的圖像

  MIME 型別	描述
  "image/gif"	圖形交換格式圖像
  "image/jpeg"	聯合圖像專家組圖像
  "image/png"	便攜網路圖形圖像

  一般情況下，預格式化的圖像列印資料在導向 byte 的表示形式類別（byte 陣列、InputStream、URL）中提供。

• 預格式化的自動檢測列印資料

  MIME 型別	描述
  "application/octet-stream"	列印資料格式是未指定的（就是一個八位組串流）

  印表機決定如何解釋該列印資料；這種“自動檢測”的工作方式與實作相關。一般情況下，預格式化的自動檢測列印資料在導向 byte 的表示形式類別（byte 陣列、InputStream、URL）中提供。

  服務格式化列印資料

  對於服務格式化列印資料，Java Print Service 實例確定列印資料格式。doc flavor 的表示形式類別表示一個介面（例如 RenderableImage 介面或 Java printable 介面），DocPrintJob 調用該介面的方法來確定要列印的內容。doc flavor 的 MIME 型別是特殊值 "application/x-java-jvm-local-objectref" 時，指示客戶端將提供對 Java 物件的參考，該物件實作了以表示形式類別命名的介面。此 MIME 型別只是一個佔位符；重要的是列印資料表示形式類別。

  對於服務格式化列印資料，列印資料表示形式類別通常是以下之一（雖然也允許使用其他表示形式類別）：類別 DocFlavor 內的巢狀類別為這些範例 doc flavor 宣告了預定義的靜態常數 DocFlavor 物件；可使用類別 DocFlavor 的建構子來創建任意的 doc flavor。

  • RenderableImage 物件 -- 客戶端提供一個實作了介面 RenderableImage 的物件。印表機調用該介面內的方法來獲得要列印的圖像。

  • Printable 物件 -- 客戶端提供一個實作了介面 Printable 的物件。印表機調用該介面內的方法來依次獲得要列印的頁面。對於每個頁面，印表機都提供一個圖形上下文，而客戶端在該圖形上下文中繪製的所有內容都會被列印。

  • Pageable 物件 -- 客戶端提供一個實作了介面 Pageable 的物件。印表機調用該介面內的方法來依次獲得要列印的頁面。對於每個頁面，印表機都提供一個圖形上下文，而客戶端在該圖形上下文中繪製的所有內容都會被列印。

  預定義的 Doc Flavor

  無需 Java 列印服務支持以下列印資料格式和列印資料表示形式類別。實際上，使用此類別的開發人員不應該假定特定的列印服務支持與這些預定義的 doc flavor 相對應的文檔型別。應該始終查詢列印服務來確定該服務支持的 doc flavor。但是鼓勵那些具有支持這些 doc flavor 的列印服務的開發人員參考此處預定義的一個實例。
  • 通過 byte 串流提供純文本列印資料。需要特別說明的是，建議支持以下 doc flavor：
    · ("text/plain", "java.io.InputStream")
    · ("text/plain; charset=us-ascii", "java.io.InputStream")
    · ("text/plain; charset=utf-8", "java.io.InputStream")

  • RenderableImage 物件。需要特別說明的是，建議支持以下 doc flavor：
    · ("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")

  根據實作的選擇，除了上述強制要求的以外，還允許 Java Print Service 實例支持任意其他 doc flavor（或一個都不支持）。

  支持上述 doc flavor 是很值得的，這樣進行列印的客戶端可以依賴於是否能夠在任意 JPS 印表機上進行列印，而不管該印表機支持哪些 doc flavor。如果印表機不支持客戶端的首選 doc flavor，則客戶端至少可以列印純文本，或者客戶端可以將其資料轉換為 Renderable 圖像並列印該圖像。

  另外，為了處理純文本列印資料，每個 Java Print Service 實例必須滿足這些要求：

  • 字元對回車(Enter)-換行 (CR-LF) 意味著“轉到下一行的第 1 列”。
  • 單個回車(Enter) (CR) 字元本身意味著“轉到下一行的第 1 列”。
  • 單個換行 (LF) 字元本身意味著“轉到下一行的列第 1 列”。

  客戶端本身必須執行不滿足上述要求的所有純文本列印資料的格式化工作。

  設計基本原理

  javax.print.data 套件中的類別 DocFlavor 與類別 DataFlavor 相似。在 Java 列印服務 (JPS) API 中不使用類別 DataFlavor 的原因有三個，這些原因的根源都在於允許其他列印服務 API 共享 JPS API，而這些列印服務 API 可能需要在 Java 配置檔案上運行，但不包括 Java 平臺、Standard Edition 的配置檔案。

  1. JPS API 設計用於不支持 AWT 的 Java 配置檔案中。

  2. 類別 java.awt.datatransfer.DataFlavor 的實作不保證等效的 DataFlavor 具有相同的序列化表示形式。DocFlavor 確實並且可以用於需要此內容的服務中。

  3. 類別 java.awt.datatransfer.DataFlavor 的實作包括可讀的名稱，該名稱作為序列化表示形式的一部分。該名稱作為服務比對約束的一部分是不合適的。

  類別 DocFlavor 的序列化表示形式使用以下 MIME 型別字元串的規範形式。因此，MIME 型別不同但等效（具有相同的規範形式）的兩個 doc flavor 可認為是相等的。

  • 保留媒體型別、媒體子型別和參數，但是丟棄所有註釋和空白字元。
  • 媒體型別、媒體子型別和參數名都轉換為小寫。
  • 參數值保留其原始狀況，但將文本媒體型別的 charset 參數值轉換為小寫。
  • 移除參數值兩側的引號字元。
  • 移除參數值內的參考反斜線字元。
  • 按參數名的升序順序排列各個參數。

  類別 DocFlavor 的序列化表示形式還包含表示形式類別的完全限定類別名，而不是表示形式類別本身（一個 Class 物件）。這就允許客戶端在不必載入表示形式類別的情況下，就可以檢查 Java Print Service 實例支持的 doc flavor，否則這對於資源有限的客戶端來說是個問題。

  另請參見：

  序列化表格

  巢狀類別摘要

  static class	DocFlavor.BYTE_ARRAY 類別 DocFlavor.BYTE_ARRAY 提供了預定義的靜態常數 DocFlavor 物件，例如使用 byte 陣列 (byte[]) 作為列印資料表示形式類別的 DocFlavor。
  static class	DocFlavor.CHAR_ARRAY 類別 DocFlavor.CHAR_ARRAY 提供了預定義的靜態常數 DocFlavor 物件，例如使用字元陣列 (char[]) 作為列印資料表示形式類別的 DocFlavor。
  static class	DocFlavor.INPUT_STREAM 類別 DocFlavor.INPUT_STREAM 提供了預定義的靜態常數 DocFlavor 物件，例如使用 byte 串流 (java.io.InputStream) 作為列印資料表示形式類別的 DocFlavor。
  static class	DocFlavor.READER 類別 DocFlavor.READER 提供了預定義的靜態常數 DocFlavor 物件，例如使用字元串流 (java.io.Reader) 作為列印資料表示形式類別的 DocFlavor。
  static class	DocFlavor.SERVICE_FORMATTED 類別 DocFlavor.SERVICE_FORMATTED 提供了預定義的靜態常數 DocFlavor 物件，例如用於服務格式化列印資料的 DocFlavor。
  static class	DocFlavor.STRING 類別 DocFlavor.STRING 提供了預定義的靜態常數 DocFlavor 物件，例如使用字元串 (java.lang.String) 作為列印資料表示形式類別的 DocFlavor。
  static class	DocFlavor.URL 類別 DocFlavor.URL 提供了預定義的靜態常數 DocFlavor 物件。

  欄位摘要

  static String

  hostEncoding 表示主機作業系統編碼的 String。

  建構子摘要

  DocFlavor(String mimeType, String className)
  根據給定的 MIME 型別和表示形式類別名建構新的 DocFlavor 物件。

  方法摘要

  boolean	equals(Object obj) 確定此 DocFlavor 物件是否等於給定的物件。
  String	getMediaSubtype() 返回此 DocFlavor 物件的媒體子型別（根據 MIME 型別）。
  String	getMediaType() 返回此 DocFlavor 物件的媒體型別（根據 MIME 型別）。
  String	getMimeType() 根據 MIME 型別的規範形式返回此 DocFlavor 物件的 MIME 型別字元串。
  String	getParameter(String paramName) 返回表示 MIME 參數的 String。
  String	getRepresentationClassName() 返回此 DocFlavor 物件的表示形式類別名。
  int	hashCode() 返回此 DocFlavor 物件的雜湊碼。
  String	toString() 將此 DocFlavor 轉換為字元串。

  從類別 java.lang.Object 繼承的方法

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

  欄位詳細資訊

  hostEncoding

  public static final String hostEncoding

  表示主機作業系統編碼的 String。該 String 遵循 RFC 2278: IANA Charset Registration Procedures 中所記錄的約定，但為了與以前的 Java 平臺版本保持相容，要返回歷史名稱的情況除外。此方法返回的值僅對返回它的 VM 有效，僅用於 DocFlavor 中。這是正在執行的 VM 中所有 "HOST" 預定義 DocFlavor 的 charset。

  建構子詳細資訊

  DocFlavor

  public DocFlavor(String mimeType,
                   String className)

  根據給定的 MIME 型別和表示形式類別名建構新的 DocFlavor 物件。給定的 MIME 型別被轉換為規範形式並進行內部存儲。

  參數：

  mimeType - MIME 媒體型別字元串。

  className - 完全限定表示形式類別名。

  拋出：

  NullPointerException - （未經檢查的異常）如果 mimeType 為 null 或 className 為 null。

  IllegalArgumentException - （未經檢查的異常）如果 mimeType 未遵守 MIME 媒體型別字元串的語法約定。

  方法詳細資訊

  getMimeType

  public String getMimeType()

  根據 MIME 型別的規範形式返回此 DocFlavor 物件的 MIME 型別字元串。每個參數值都在單引號內。

  返回：

  MIME 型別

  getMediaType

  public String getMediaType()

  返回此 DocFlavor 物件的媒體型別（根據 MIME 型別）。

  返回：

  媒體型別

  getMediaSubtype

  public String getMediaSubtype()

  返回此 DocFlavor 物件的媒體子型別（根據 MIME 型別）。

  返回：

  媒體子型別

  getParameter

  public String getParameter(String paramName)

  返回表示 MIME 參數的 String。Mime 型別可能包括通常是可選的參數。文本型別的 charset 通常是一個有用的範例。如果在 MIME 型別中為此 flavor 指定了某個參數，則此便捷方法返回該指定參數的值。

  參數：

  paramName - 參數名。執行比對操作前，此名稱被內部轉換為規範的小寫格式。

  返回：

  MIME 參數的 String 表示形式，如果該 MIME 型別字元串中沒有該參數，則返回 null。

  拋出：

  NullPointerException - 如果 paramName 為 null。

  getRepresentationClassName

  public String getRepresentationClassName()

  返回此 DocFlavor 物件的表示形式類別名。

  返回：

  表示形式類別名。

  toString

  public String toString()

  將此 DocFlavor 轉換為字元串。

  覆寫：

  類別 Object 中的 toString

  返回：

  規範形式的 MIME 型別字元串。每個參數值都在單引號內。將 "class=" 參數添加到 MIME 型別字元串中，以指示表示形式類別名。

  hashCode

  public int hashCode()

  返回此 DocFlavor 物件的雜湊碼。

  覆寫：

  類別 Object 中的 hashCode

  返回：

  此物件的一個雜湊碼值。

  另請參見：

  Object.equals(java.lang.Object), Hashtable

  equals

  public boolean equals(Object obj)

  確定此 DocFlavor 物件是否等於給定的物件。如果給定的物件不為 null、是一個 DocFlavor 實例、具有和此 DocFlavor 物件的 MIME 型別等效的 MIME 型別（也就是說，兩個 MIME 型別具有相同的媒體型別、媒體子型別和參數），並且具有和此 DocFlavor 物件相同的表示形式類別名，則兩個物件是相等的。因此，如果兩個 DocFlavor 物件的 MIME 型別除註釋外都相同，則認為這兩個物件是相等的。但是，分別具有 "text/plain" 和 "text/plain; charset=US-ASCII" MIME 型別的兩個 DocFlavor 物件被認為是不相等的，即使它們表示相同的媒體型別也是如此（因為純文本的預設字元集是 US-ASCII）。

  覆寫：

  類別 Object 中的 equals

  參數：

  obj - 要測試的 Object。

  返回：

  如果此 DocFlavor 物件等於 obj，則返回 true；否則返回 false。

  另請參見：

  Object.hashCode(), Hashtable