javax.print

接口
类
异常

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