javax.print

接口
类
异常

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 实例必须满足这些要求：

    • 字符对回车-换行 (CR-LF) 意味着“转到下一行的第 1 列”。
    • 单个回车 (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