Java javax.print 接口 Doc（JDK5）

所有类

javax.print
接口 Doc

所有已知实现类：

SimpleDoc

public interface Doc

接口 Doc 指定某个对象的接口，该接口为 PrintJob 提供部分打印数据。"Doc" 是一个简短、易于发音的术语，指“部分打印数据”。客户端向 PrintJob 传递一个实现接口 Doc 的对象，PrintJob 则在该对象上调用方法来获得打印数据。Doc 接口允许 PrintJob：

• 确定所提供的打印数据的格式，或 "doc flavor"（类 DocFlavor）。doc flavor 指定了打印数据格式（MIME 类型）和提供打印数据的对象的表示形式类。

• 获得打印数据表示形式对象，它是 doc flavor 表示形式类的实例。然后 Print Job 可从该表示形式对象获得实际的打印数据。

• 获得各种打印属性，这些属性指定该 doc 的其他特征，或者指定用于该 doc 的处理指令。打印属性在 javax.print.attribute 包中定义。doc 返回其存储在 javax.print.attribute.DocAttributeSet 中的打印属性。

每次调用接口 Doc 实现中的方法时，都允许该方法返回相同的对象。对于　Print Job　或 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 实现程序应该只为响应服务的请求才创建这种流。

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 错误。