軟體套件 javax.print.attribute

提供了描述 Java^TM Print Service 屬性的型別以及如何分類別這些屬性的類別和介面。

請參見：
描述

介面摘要

Attribute	介面 Attribute 是由任何一個列印屬性類別實作的基本介面，用於指示該類別表示某一列印屬性。
AttributeSet	介面 AttributeSet 為列印屬性集指定介面。
DocAttribute	介面 DocAttribute 是列印屬性類別實作的一個標記介面，用於指示屬性表示文檔 (doc) 的設置（“Doc”是一個簡短的、容易發音的術語，指“列印資料的片段”。
DocAttributeSet	介面 DocAttributeSet 指定文檔屬性（即：實作介面 DocAttribute 的列印屬性）集的介面。
PrintJobAttribute	PrintJobAttribute 是列印屬性類別實作的標記介面，以指示該屬性描述“列印作業”的狀態或“列印作業”的一些其他特徵。
PrintJobAttributeSet	介面 PrintJobAttributeSet 為列印作業屬性（即：實作介面 PrintJobAttribute 的列印屬性）集指定介面。
PrintRequestAttribute	介面 PrintRequestAttribute 是列印屬性類別實作的標記介面，以指示屬性表示用於列印作業的請求設置。
PrintRequestAttributeSet	介面 PrintRequestAttributeSet 為列印請求屬性（即：實作介面 PrintRequestAttribute 的列印屬性）的集合指定介面。
PrintServiceAttribute	介面 PrintServiceAttribute 是列印屬性類別實作的標記介面，以指示該屬性描述“列印服務”的狀態或“列印服務”的一些其他特徵。
PrintServiceAttributeSet	介面 PrintServiceAttributeSet 為列印作業屬性（即：實作介面 PrintServiceAttribute 的列印屬性）集指定介面。
SupportedValuesAttribute	介面 SupportedValuesAttribute 是列印屬性類別實作的標記介面，以指示該屬性描述用於其他屬性的支持值。

類別摘要

AttributeSetUtilities	類別 AttributeSetUtilities 為操作 AttributeSets 提供靜態方法。
DateTimeSyntax	類別 DateTimeSyntax 是一個抽象的基礎類別，它提供其值是日期和時間的所有屬性的公共實作。
EnumSyntax	類別 EnumSyntax 是一個抽象的基礎類別，它提供所有“型別安全列舉”物件的公共實作。
HashAttributeSet	類別 HashAttributeSet 提供具有雜湊映射特徵的 AttributeSet 實作。
HashDocAttributeSet	類別 HashDocAttributeSet 提供從類別 HashAttributeSet 繼承其實作的屬性集，並強制執行介面 DocAttributeSet 的語義限制。
HashPrintJobAttributeSet	類別 HashPrintJobAttributeSet 提供從類別 HashAttributeSet 繼承其實作的屬性集，並強制執行介面 PrintJobAttributeSet 的語義限制。
HashPrintRequestAttributeSet	類別 HashPrintRequestAttributeSet 從類別 HashAttributeSet 繼承其實作，並強制執行介面 PrintRequestAttributeSet 的語義限制。
HashPrintServiceAttributeSet	類別 HashPrintServiceAttributeSet 提供從類別 HashAttributeSet 繼承其實作的屬性集，並強制執行介面 PrintServiceAttributeSet 的語義限制。
IntegerSyntax	類別 IntegerSyntax 是一個抽象的基礎類別，它提供具有整數值的所有屬性的公共實作。
ResolutionSyntax	類別 ResolutionSyntax 是一種抽象的基礎類別，它提供表示印表機分辨率的所有屬性的公共實作。
SetOfIntegerSyntax	類別 SetOfIntegerSyntax 是一種抽象的基礎類別，它提供其值是非負整數集合的所有屬性的公共實作。
Size2DSyntax	類別 Size2DSyntax 是一種抽象的基礎類別，它提供表示二維大小的所有屬性的公共實作。
TextSyntax	類別 TextSyntax 是一種抽象的基礎類別，它提供其值是字元串的所有屬性的公共實作。
URISyntax	類別 URISyntax 是一種抽象的基礎類別，它提供其值是統一資源標識符 (URI) 的所有屬性的公共實作。

異常摘要

UnmodifiableSetException

當由於設置不可修改而無法執行請求的操作時，拋出該異常。

軟體套件 javax.print.attribute 的描述

提供了描述 Java^TM Print Service 屬性的型別以及如何分類別這些屬性的類別和介面。

什麼是屬性？

設置列印作業時，客戶端會指定兩件事情：列印資料和處理指令。列印資料是要列印的實際內容。處理指令告知印表機如何列印該列印資料，如：使用什麼介質，列印多少副本，在紙上是單面列印還是雙面列印。客戶端使用 Java Print Service API 的屬性定義來指定這些處理指令。

列印資料和處理指令都是獨立的實體。這意味著：您可以在不同時間使用不同的處理指令列印同一列印資料。

• 
  例如，您可以在美國信函大小的白紙上雙面、裝訂列印 20 張幻燈片演示文稿副本作為演講的講義；還可以在美國信函大小的透明介質上單面列印一份相同的幻燈片演示文稿作為演講的實際幻燈片。
• 您可以在不同時間使用相同的處理指令列印不同的資料。例如，您可以將預設處理指令設置為：美國信函大小的紙張、雙面、裝訂。每當列印一項作業時，會使用這些設置進行列印，除非顯式覆寫它們。

處理指令不指定列印作業處理該請求的方式；每條處理指令僅是對列印作業結果的描述。列印作業確定實作處理指令所指定結果的方式。將處理指令表示為描述項可為實作列印作業提供更大的靈活性。

屬性類別別和值

每個印表機都有一組功能，如在不同大小的紙張上列印或列印多個副本。每個功能都有一個範圍值。例如，印表機的方向功能可能有以下範圍值：[landscape, portrait]。對於每個列印請求，可以將該功能設置為這些值之一。Java Print Service API 使用術語屬性類別別指印表機功能，使用術語屬性值指該功能的值。

在 Java Print Service API 中，通過實作 Attribute 介面的 Java 類別來表示屬性類別別。屬性值是這樣的類別或其某個子類別的實例。例如，要指定副本數，應用程序會建構一個具有所需副本數的 Copies 類別的實例，並將 Copies 實例用作列印請求的一部分。在這種情況下，Copies 類別表示屬性類別別，Copies 實例表示屬性值。

屬性職責

將列印作業提交給印表機時，客戶端將提供描述列印資料特徵的屬性（如，文檔名稱），以及應如何列印列印資料（如，雙面、五份）。如果列印作業由多部分列印資料組成，則不同部分可能具有不同的處理指令，如將 8 × 11 英吋的介質用於第一個文檔，11 × 17 英吋的介質用於另一個文檔。

印表機開始處理列印作業之後，關於該作業的其他資訊將可供使用，可能包括：作業狀態（如完成 或排隊）和到目前為止已列印的頁數。這些資訊片段也是屬性。屬性還可描述印表機本身，如：印表機名稱、印表機位置和已排隊的作業數。

Java Print Service API 使用 Attribute 的五個子介面定義這些不同型別的屬性：

• DocAttribute 指定每個文檔的特徵和應用到每個文檔的列印作業設置。
• PrintRequestAttribute 指定應用到整個列印作業和列印作業中所有文檔的設置。
• PrintJobAttribute 報告列印作業的狀態。
• PrintServiceAttribute 報告列印服務的狀態。
• SupportedValuesAttribute 為另一個屬性提供支持的值。

每個屬性類別實作一個或多個這些標記子介面，以指示在 API 中可以使用該屬性的位置。如果屬性類別實作多個標記子介面，則可以在多個上下文中使用該屬性。例如，介質屬性可以作為 DocAttribute 應用到列印作業中的一個文檔，或作為 PrintRequestAttribute 應用到整個列印作業。某些低層級別屬性從不用於其自身，但是，總是可以將它們彙集到高層級別屬性中。這此低層級別屬性類別僅實作介面 Attribute，不能實作任何標記子介面。

Java Print Service API 定義了一組標準屬性類別，它可以按照 Internet Printing Protocol (IPP) 版本 1.1 對屬性進行建模。標準屬性類別位於子包 javax.print.attribute.standard 中，目的是保持實際屬性類別在概念上與包 javax.print.attribute 中定義的一般設備分開。

屬性集

在提交列印作業時，客戶端通常需要提供多個處理指令。例如，客戶端可能需要指定大小為 A4 的介質和橫向方向。要發送多個處理指令，客戶端將屬性收集到 Java Print Service API 通過 AttributeSet 介面所表示的屬性集中。

AttributeSet 介面類似於 Map 介面：它提供鍵到值的映射，其中每個鍵都是唯一的，並且只能包含一個值。但是，AttributeSet 介面設計用於專門支持 Java Print Service API 的需求。AttributeSet 要求：

1. AttributeSet 中的每個鍵對應於一個類別別，鍵的值只能是屬性值之一，它屬於該鍵表示的類別別。因此，與 Map 不同，AttributeSet 限制了鍵的可能值：不能將屬性類別別設置為不屬於該類別別的屬性值。
2. 在同一集合中，不能存在同一類別別的兩個屬性。例如，屬性集合決不能同時包含“單面”屬性和“雙面”屬性，因為這兩個屬性會導致印表機指令衝突。
3. 只可以將實作 Attribute 介面的屬性添加到該集合。

javax.print.attribute 套件中包括了作為屬性集介面具體實作的 HashAttributeSet。HashAttributeSet 提供基於雜湊映射的屬性集。您可以使用此實作，或提供自已的介面 AttributeSet 實作。

Java Print Service API 提供屬性集的四個規範，它們限於僅包含四種屬性之一，如屬性職責一節所討論的：

• DocAttributeSet
• PrintRequestAttributeSet
• PrintJobAttributeSet
• PrintServiceAttributeSet

注意，這裡僅列出了四種屬性集，但是有五種屬性。介面 SupportedValuesAttribute 表示為另一個屬性提供支持值的屬性。永遠不可能將支持值屬性彙集到屬性集中，因此不存在為它們定義的屬性集子介面。

在某些上下文中，屬性集是只讀的，這意味著只允許客戶端檢查屬性集的內容，但不能更改它們。在其他上下文中，屬性集是可讀寫的，這意味著允許客戶端檢查和更改屬性集的內容。對於只讀屬性集，調用更改操作會拋出 UnmodifiableSetException。

包 javax.print.attribute 套件括每個屬性集子介面的一個具體實作：

• HashDocAttributeSet
• HashPrintRequestAttributeSet,
• HashPrintJobAttributeSet,
• HashPrintServiceAttributeSet.

所有這些類別都擴展 HashAttributeSet，並強制要求只允許屬性集包含相應型別屬性的限制。

屬性類別設計

屬性值是一個小的原子資料項，如整數或列舉值。Java Print Service API 不使用基本資料型別（如 int）來表示屬性值，原因如下：

• 基本資料型別不是型別安全的。例如，編譯器不應允許將“copies”屬性值用於“sides”屬性。
• 一些屬性必須表示為幾個值的記錄。印表機分辨率就是一個例子，它需要兩個數（如，表示 600 × 300 dpi 的 600 和 300）。

對於型別安全性和要統一表示所有屬性，Java Print Service API 將每個屬性類別別定義為類別，如類別 Copies、類別 Sides 和 類別 PrinterResolution。每個屬性類別可以包裹一個或多個包含屬性值的基本資料項。屬性集操作在添加屬性、在同一類別別中尋找現有屬性和尋找給定其類別別的屬性時經常執行屬性類別別物件之間的比較。因為屬性類別別由類別表示，所以使用 Class.equals 方法可以執行快速的屬性值比較。

儘管 Java Print Service API 套件括大量不同的屬性類別別，但是僅存在很少的不同型別的屬性值。大多數屬性可由少量資料型別表示，如：整數值、整數範圍、文本或整數值的列舉。類別別接受的屬性值型別稱為屬性的抽象語法。為了提供一致性並減少程式碼重複，Java Print Service API 定義了抽象語法類別，以表示每個抽象語法，並且只要可能，可以將這些類別用作標準屬性的父級。抽象語法類別是：

• EnumSyntax 提供型別安全的列舉，其中列舉值表示為單個物件。每個列舉都是包裹隱藏 int 值的列舉類別實例。
• IntegerSyntax 是用於整數值屬性的抽象語法。
• TextSyntax 是用於文本值屬性的抽象語法，並且包括立提供文本字元串的自然語言的語言環境。
• SetOfIntegerSyntax 是表示整數範圍或整數集的屬性的抽象語法。
• ResolutionSyntax 是表示分辨率值（如 600×300 dpi）的屬性的抽象語法。
• Size2DSyntax 是表示二維大小（如，紙張大小為 8.5 × 11 英吋）的屬性的抽象語法。
• DateTimeSyntax 是其值為日期和時間的屬性的抽象語法。
• URISyntax 是其值為統一資源定位符的屬性的抽象語法。

抽象語法類別獨立於使用它們的屬性。事實上，與列印無關的應用程序可以使用抽象語法類別。雖然多數標準屬性類別會擴展某個抽象語法類別，但不需要任何屬性類別擴展上述類別之一。抽象語法類別僅提供許多屬性類別可以共享的便捷實作。

每個屬性類別可以直接或間接實作 Attribute 介面，以便將其標記為列印屬性。在某些上下文的限制屬性集中出現的屬性類別也實作 Attribute 的一個或多個子介面。多數屬性類別也擴展適當的抽象語法類別，以獲取該實作。考慮 Sides 屬性類別：

public class Sides
  extends EnumSyntax
  implements DocAttribute, PrintRequestAttribute, PrintJobAttribute
  {
  public final Object getCategory()
    {
    return Sides.class;
    }
  ...
  }
  

由於每個屬性類別會實作 Attribute，所以每個屬性類別必須提供返回屬性類別別的 getCategory 方法的實作。對於屬性 Sides，getCategory 方法返回 Sides.class。getCategory 方法最終確保了標準屬性類別的所有供應商定義的子類別都顯示在同一類別別中。每個屬性物件在建構之後都是不可變的，這樣可以隨意地傳遞屬性物件參考。要獲取不同的屬性值，請建構不同的屬性物件。

屬性供應商

Java Print Service API 被設計成可讓供應商：

• 為 javax.print.attribute.standard 中定義的所有標準屬性定義新的特定於供應商的值。
• 定義表示供應商印表機專用功能（標準屬性已不支持）的新屬性類別別。

要為屬性定義一個新值，客戶端可以使用任意值在運行時建構此屬性的實例。但是，使用 EnumSyntax 的抽象語法類別的列舉屬性在編譯時將所有的可能屬性值指定為屬性類別的單個實例。這意味著在運行時無法建構新的列舉值。要為標準列舉屬性定義新的特定於供應商的值，供應商必須定義一個指定單個新實例的新屬性類別。要確保新的屬性值與標準屬性值在相同的類別別中，新的屬性類別必須是標準屬性類別的子類別。

要定義新的屬性類別別，供應商需要定義新的屬性類別。此屬性類別（與標準屬性類別類似）實作 Attribute 或其子介面之一，並擴展抽象語法類別。供應商可以使用現有的抽象語法類別，或者定義新的抽象語法類別。無論在哪裡（如在 AttributeSet 中）使用 Attribute，都可以使用供應商定義的新屬性。

使用屬性

典型的列印應用程序使用 PrintRequestAttributeSet，因為列印請求屬性是客戶端通常指定的屬性型別。下面的範例介紹如何創建列印請求屬性的屬性集，並尋找可以按照指定的屬性列印文檔的印表機：

FileInputStream psStream;
try {
   psstream = new FileInputStream("file.ps");
} catch (FileNotFoundException ffne) {
}
if (psstream == null) {
return;
}
//Set the document type.  See the DocFlavor documentation for
//more information.
DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
Doc myDoc = new SimpleDoc(pstream, psInFormat, null);  
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(new Copies(5));
aset.add(MediaSize.A4);
aset.add(Sides.DUPLEX);

PrintService[] services = 
                PrintServiceLookup.lookupPrintServices(psInFormat, aset);
if (services.length > 0) {
   DocPrintJob job = services[0].createPrintJob();
   try {
        job.print(myDoc, aset);
   } catch (PrintException pe) {}
}

請注意：在 javax.print API 中，只有方法中顯式地記錄 null 參考具有有意義的解釋時，方法的 null 參考參數才是正確的。與之相反的用法是不正確的編碼，可能立即或在稍後某一時間導致運行時異常。IllegalArgumentException 和 NullPointerException 是針對這種情況的典型的、可接受的運行時異常的範例。

從以下版本開始：

1.4