javax.print
介面 PrintService

所有已知子介面：

MultiDocPrintService

所有已知實作類別：

StreamPrintService

public interface PrintService

介面 PrintService 是 DocPrintJob 的處理器。PrintService 描述了印表機的功能，並可查詢它來瞭解印表機支持的屬性。

範例：

   DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
   PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
   aset.add(MediaSizeName.ISO_A4);
   PrintService[] pservices =
                 PrintServiceLookup.lookupPrintServices(flavor, aset);
   if (pservices.length > 0) {
       DocPrintJob pj = pservices[0].createPrintJob();
       try {
           FileInputStream fis = new FileInputStream("test.ps");
           Doc doc = new SimpleDoc(fis, flavor, null);
           pj.print(doc, aset);
        } catch (FileNotFoundException fe) {
        } catch (PrintException e) { 
        }
   }
   

方法摘要

void	addPrintServiceAttributeListener(PrintServiceAttributeListener listener) 為此 PrintService 上的事件註冊一個偵聽器。
DocPrintJob	createPrintJob() 創建並返回一個 PrintJob，它應能夠處理取自任意受支持的 docflavor 的資料。
boolean	equals(Object obj) 確定兩個服務是否參考相同的底層服務。
<T extends PrintServiceAttribute> T	getAttribute(Class<T> category) 獲取單個指定服務屬性的值。
PrintServiceAttributeSet	getAttributes() 獲得此 PrintService 的印表機描述屬性集，這些屬性給出了此 PrintService 的狀態。
Object	getDefaultAttributeValue(Class<? extends Attribute> category) 確定給定類別別中此 PrintService 的預設列印屬性值。
String	getName() 返回此 PrintService 的 String 名稱，應用程序可以使用該名稱來請求特定的 PrintService。
ServiceUIFactory	getServiceUIFactory() 返回 UI 元件的處理器方法，該元件允許使用者通過各種角色與服務交互。
Class<?>[]	getSupportedAttributeCategories() 確定客戶端在設置此 PrintService 的作業時，可以指定的列印屬性類別別。
Object	getSupportedAttributeValues(Class<? extends Attribute> category, DocFlavor flavor, AttributeSet attributes) 確定客戶端在設置此 PrintService 的作業時，是否可以指定給定類別別中的列印屬性值。
DocFlavor[]	getSupportedDocFlavors() 確定在設置此 PrintService 的作業時，客戶端可以指定的列印資料格式。
AttributeSet	getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes) 標識在特定 DocFlavor 的上下文中列印請求不支持的屬性。
int	hashCode() 此方法的實作方式應該與 equals(Object) 具有一致性。
boolean	isAttributeCategorySupported(Class<? extends Attribute> category) 確定客戶端在設置此 PrintService 的作業時，是否可以指定給定列印屬性類別別。
boolean	isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes) 確定客戶端在設置此 PrintService 的作業時，是否可以指定給定的列印屬性值。
boolean	isDocFlavorSupported(DocFlavor flavor) 確定此 PrintService 是否支持具體 DocFlavor。
void	removePrintServiceAttributeListener(PrintServiceAttributeListener listener) 移除此 PrintService 的 PrintService 偵聽器。

方法詳細資訊

getName

String getName()

返回此 PrintService 的 String 名稱，應用程序可以使用該名稱來請求特定的 PrintService。在適合的上下文（如名稱服務）中，此名稱必須是唯一的。在某些環境中，此唯一的名稱可能與在 PrinterName 屬性中定義的、使用者友好的印表機名相同。

返回：

服務名。

createPrintJob

DocPrintJob createPrintJob()

創建並返回一個 PrintJob，它應能夠處理取自任意受支持的 docflavor 的資料。

返回：

DocPrintJob 物件

addPrintServiceAttributeListener

void addPrintServiceAttributeListener(PrintServiceAttributeListener listener)

為此 PrintService 上的事件註冊一個偵聽器。

參數：

listener - PrintServiceAttributeListener，它監視 PrintService 的狀態

另請參見：

removePrintServiceAttributeListener(javax.print.event.PrintServiceAttributeListener)

removePrintServiceAttributeListener

void removePrintServiceAttributeListener(PrintServiceAttributeListener listener)

移除此 PrintService 的 PrintService 偵聽器。這意味著該偵聽器不再偵聽 PrintService 事件。

參數：

listener - PrintServiceAttributeListener 物件

另請參見：

addPrintServiceAttributeListener(javax.print.event.PrintServiceAttributeListener)

getAttributes

PrintServiceAttributeSet getAttributes()

獲得此 PrintService 的印表機描述屬性集，這些屬性給出了此 PrintService 的狀態。返回的屬性集物件是不可修改的。返回的屬性集物件是調用 getAttributes() 方法時此 PrintService 的屬性集的一個“快照”：也就是說，如果以後此 PrintService 屬性集的內容更改了，則不 更新返回的屬性集的內容。要檢測屬性值的更改，可再次調用 getAttributes() 並將新的屬性集與以前的屬性集進行比較；或者可為 PrintService 事件註冊一個偵聽器。

返回：

此 PrintService 屬性集不可修改的快照。可以為空，但不能為 null。

getAttribute

<T extends PrintServiceAttribute> T getAttribute(Class<T> category)

獲取單個指定服務屬性的值。這對於只需要一個屬性值並且希望最大限度降低開銷的客戶端而言是很有用的。

參數：

category - 此服務所支持的 PrintServiceAttribute 類別別 - 不可以為 null。

返回：

所支持的屬性的值，如果此服務不支持該屬性，則返回 null。

拋出：

NullPointerException - 如果 category 為 null。

IllegalArgumentException - （未經檢查的異常）如果 category 並非實作了介面 PrintServiceAttribute 的 Class。

getSupportedDocFlavors

DocFlavor[] getSupportedDocFlavors()

確定在設置此 PrintService 的作業時，客戶端可以指定的列印資料格式。列印資料格式由 "doc flavor"（類別 DocFlavor）所指定，該 "doc flavor" 則由 MIME 型別和列印資料表示形式類別所組成。

注意，在組合使用所有屬性時，可能不支持某些 doc flavor。使用 getUnsupportedAttributes(..) 來驗證具體屬性組合是否支持 doc flavor。

返回：

受支持的 doc flavor 的陣列，至少應該有一個元素。

isDocFlavorSupported

boolean isDocFlavorSupported(DocFlavor flavor)

確定此 PrintService 是否支持具體 DocFlavor。這是確定該 DocFlavor 是否為所得 getSupportedDocFlavors() 成員的便捷方法。

注意，在組合使用所有屬性時，可能不支持某些 doc flavor。使用 getUnsupportedAttributes(..) 來驗證指定的屬性組合是否支持 doc flavor。

參數：

flavor - 查詢是否支持 DocFlavor。

返回：

如果此 PrintService 支持指定的 DocFlavor，則返回 true；否則返回 false

拋出：

NullPointerException - （未經檢查的異常）如果 flavor 為 null，則拋出該異常。

getSupportedAttributeCategories

Class<?>[] getSupportedAttributeCategories()

確定客戶端在設置此 PrintService 的作業時，可以指定的列印屬性類別別。列印屬性類別別由實作了介面 Attribute 的 Class 所指定。此方法只返回受支持的屬性類別別；並不返回受支持的特定屬性值。

此方法為任何可能的作業返回此 PrintService 支持的所有列印屬性類別別。在特定的上下文（即特定的 DocFlavor）中可能不支持某些類別別。提交請求前使用包括了 DocFlavor 的某個方法來驗證該請求，如 getSupportedAttributeValues(..)。

返回：

列印屬性類別別的陣列，客戶端可在列印請求中以 doc 級或作業級屬性來指定這些類別別。該陣列中的每個元素都是一個實作了介面 Attribute 的 Class。如果沒有支持的類別別，則該陣列為空。

isAttributeCategorySupported

boolean isAttributeCategorySupported(Class<? extends Attribute> category)

確定客戶端在設置此 PrintService 的作業時，是否可以指定給定列印屬性類別別。列印屬性類別別由實作了介面 Attribute 的 Class 所指定。此方法通知是否支持該屬性類別別；它不通知是否支持特定的屬性值。

在特定的上下文（即特定的 DocFlavor）中可能不支持某些類別別。提交請求前使用包括了 DocFlavor 的某個方法來驗證該請求，如 getSupportedAttributeValues(..)。

這是確定該類別別是否為所得 getSupportedAttributeCategories() 成員的便捷方法。

參數：

category - 要測試的列印屬性類別別。它必須是實作了介面 Attribute 的 Class。

返回：

如果此 PrintService 支持在列印請求的 category 中指定 doc 級或作業級的屬性，則返回 true；否則返回 false。

拋出：

NullPointerException - （未經檢查的異常）如果 category 為 null，則拋出該異常。

IllegalArgumentException - （未經檢查的異常）如果 category 並非實作了介面 Attribute 的 Class。

getDefaultAttributeValue

Object getDefaultAttributeValue(Class<? extends Attribute> category)

確定給定類別別中此 PrintService 的預設列印屬性值。列印屬性值是實作了介面 Attribute 的類別的實例。如果客戶端設置了列印作業但未指定給定類別別中的任何屬性值，則此 PrintService 將使用預設屬性值。

在特定的上下文（即特定的 DocFlavor）中可能不支持某些屬性。提交請求前使用包括了 DocFlavor 的某個方法來驗證該請求，如 getSupportedAttributeValues(..)。

並非所有的屬性都具有預設值。例如，服務沒有 RequestingUser 的預設值，即對於不受支持的類別別返回 null 意味著沒有該類別別的服務預設值。使用 isAttributeCategorySupported(Class) 方法來區分這些情況。

參數：

category - 列印屬性類別別，其預設屬性值被請求。它必須是實作了介面 Attribute 的 Class。

返回：

category 的預設屬性值，如果此 PrintService 不支持在列印請求的 category 中指定 doc 級或作業級的屬性，或者服務沒有此屬性的預設值，則返回 null。

拋出：

NullPointerException - （未經檢查的異常）如果 category 為 null，則拋出該異常。

IllegalArgumentException - （未經檢查的異常）如果 category 並非實作了介面 Attribute 的 Class。

getSupportedAttributeValues

Object getSupportedAttributeValues(Class<? extends Attribute> category,
                                   DocFlavor flavor,
                                   AttributeSet attributes)

確定客戶端在設置此 PrintService 的作業時，是否可以指定給定類別別中的列印屬性值。列印屬性值是實作了介面 Attribute 的類別的實例。

如果 flavor 為 null 並且 attributes 為 null 或是一個空集合，則此方法為任何可能的作業返回此 PrintService 支持的所有列印屬性值。如果 flavor 不為 null 或 attributes 不是空集合，則此方法只返回與給定 doc flavor 和/或屬性集相容的列印屬性值。也就是說，null 返回值可能指示指定此屬性與指定的 DocFlavor 不相容。另外，如果 DocFlavor 不為 null，則它必須是此 PrintService 支持的 flavor，否則將拋出 IllegalArgumentException。

如果 attributes 參數包含其類別別與 category 參數相同的 Attribute，則該服務必須忽略 AttributeSet 中的此屬性。

為了準確表示上下文，在此集合中必須包括要在 Doc 上指定的 DocAttribute。

此方法返回一個 Object，因為不同的列印屬性類別別以不同的方式指示受支持的屬性值。包 javax.print.attribute.standard 中每個列印屬性的文檔都描述了每個屬性如何指示其受支持的值。指示這種支持的可能方式包括：

• 返回屬性類別別的單個實例來指示所使用的任何值都是合法的，例如由其值是任意文本字元串的屬性所使用的值。（與返回的屬性物件的值無關。）
• 返回一個或多個屬性類別別實例的陣列，其中包含所使用的合法值，例如由具有列舉值列表的屬性所使用的值。陣列的型別是一個指定屬性類別別型別的陣列，由其 getCategory(Class) 方法返回。
• 返回（某個類別而不是屬性類別別）的單個物件，指示有關所用合法值的綁定，例如由其值必須位於一定範圍內的整數值屬性所使用的值。

參數：

category - 要測試的列印屬性類別別。它必須是實作了介面 Attribute 的 Class。

flavor - 用於假定作業的 Doc flavor，或者為 null。

attributes - 用於假定作業的列印屬性集（包括作業級屬性和 doc 級屬性），或者為 null。

返回：

指示 category 受支持的值的 Object，如果此 PrintService 不支持在列印請求的 category 中指定 doc 級或作業級的屬性，則返回 null。

拋出：

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

IllegalArgumentException - （未經檢查的異常）如果 category 並非實作了介面 Attribute 的 Class，或者此服務不支持 DocFlavor。

isAttributeValueSupported

boolean isAttributeValueSupported(Attribute attrval,
                                  DocFlavor flavor,
                                  AttributeSet attributes)

確定客戶端在設置此 PrintService 的作業時，是否可以指定給定的列印屬性值。列印屬性值是實作了介面 Attribute 的類別的實例。

如果 flavor 為 null 並且 attributes 為 null 或是一個空集合，則此方法將通知此 PrintService 是否支持針對某種可能的 doc flavor 和屬性集組合所給定的列印屬性值。如果 flavor 不為 null 或 attributes 不是空集合，則此方法通知此 PrintService 是否支持結合了給定的 doc flavor 和/或屬性集的給定的列印屬性值。

另外，如果 DocFlavor 不為 null，則它必須是此 PrintService 支持的 flavor，否則將拋出 IllegalArgumentException。

為了準確表示上下文，在此集合中必須包括要在 Doc 上指定的 DocAttribute。

這是確定該值是否為所得 getSupportedAttributeValues(...) 成員的便捷方法。

參數：

attrval - 要測試的列印屬性值。

flavor - 用於假定作業的 Doc flavor，或者為 null。

attributes - 用於假定作業的列印屬性集（包括作業級屬性和 doc 級屬性），或者為 null。

返回：

如果此 PrintService 支持將 attrval 指定為列印請求中 doc 級或作業級的屬性，則返回 true；否則返回 false。

拋出：

NullPointerException - （未經檢查的異常）如果 attrval 為 null，則拋出該異常。

IllegalArgumentException - 如果此 PrintService 不支持 flavor。

getUnsupportedAttributes

AttributeSet getUnsupportedAttributes(DocFlavor flavor,
                                      AttributeSet attributes)

標識在特定 DocFlavor 的上下文中列印請求不支持的屬性。對於驗證可能的列印作業和標識無法支持的具體的屬性而言，此方法很有用。僅提供受支持的 DocFlavor 很重要，否則將拋出 IllegalArgumentException。如果此方法的返回值為 null，則支持所有屬性。

為了準確表示上下文，在此集合中必須包括要在 Doc 上指定的 DocAttribute。

如果返回值不為 null，則返回集合中的所有屬性都是此 DocFlavor 所不支持的。返回的集合不區分不受支持的屬性類別別和不受支持的屬性值。

然後可通過從原始的屬性集中移除所有不受支持的屬性（不支持 DocFlavor 的情況除外），就可以創建一個受支持的列印請求。

如果不支持某些屬性的原因是與其他屬性有衝突，則由服務決定選擇將哪些屬性標識為衝突的原因。

調用此方法前使用 isDocFlavorSupported() 來驗證是否支持某個 DocFlavor。

參數：

flavor - 要測試的 Doc flavor，或者為 null

attributes - 用於假定作業的列印屬性集（包括作業級屬性和 doc 級屬性），或者為 null。

返回：

如果此 PrintService 支持列印請求規範，則返回 null；否則返回不受支持的屬性。

拋出：

IllegalArgumentException - 如果此 PrintService 不支持 flavor。

getServiceUIFactory

ServiceUIFactory getServiceUIFactory()

返回 UI 元件的處理器方法，該元件允許使用者通過各種角色與服務交互。不提供任何 UI 的服務應該返回 null。確實提供 UI 但是又想在沒有 UI 支持的環境中得到支持的 PrintService 應該確保該處理器是不可初始化的，除非應用程序調用此方法來獲得該處理器。有關更多資訊，請參閱 ServiceUIFactory。

返回：

null 或用於 UI 元件的處理器。

equals

boolean equals(Object obj)

確定兩個服務是否參考相同的底層服務。封裝了 PrintService 的物件即使在參考相同的底層服務時也不會表現出參考相等性。

客戶端應該調用此方法來確定兩個服務是否參考了相同的底層服務。

各個服務必須實作此方法，並且僅在客戶端可以交換地使用被比較的服務物件時才返回 true。如果返回 true，則各個服務可返回對底層服務的相同物件參考，但是客戶端不能依賴於參考相等性。

覆寫：

類別 Object 中的 equals

參數：

obj - 要與之比較的參考物件。

返回：

如果此服務與 obj 參數相同，則返回 true；否則返回 false。

另請參見：

Object.hashCode(), Hashtable

hashCode

int hashCode()

此方法的實作方式應該與 equals(Object) 具有一致性。

覆寫：

類別 Object 中的 hashCode

返回：

此物件的雜湊碼。

另請參見：

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