Module java.desktop

Package javax.print

Class 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 类型。 这是一个多用途互联网邮件扩展（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 从客户端获取字符或字节序列的通道。doc flavor 的 MIME 类型是标准媒体类型之一，告诉如何解释字符或字节序列。有关标准媒体类型的列表，请参见互联网分配号码管理局（IANA）的 媒体类型目录。接口 Doc 提供两个实用操作，getReaderForText 和 getStreamForBytes()，以帮助 Doc 对象的客户端提取客户端格式化的打印数据。

对于客户端格式化的打印数据，打印数据表示类通常是以下之一（尽管允许使用其他表示类）：

• 字符数组（char[]）-- 打印数据由数组中的 Unicode 字符组成。
• String -- 打印数据由字符串中的 Unicode 字符组成。
• 字符流（java.io.Reader）-- 打印数据由从流中读取的 Unicode 字符组成，直到流结束。
• 字节数组（byte[]）-- 打印数据由数组中的字节组成。字节使用 doc flavor 的 MIME 类型指定的字符集进行编码。如果 MIME 类型未指定字符集，则默认字符集为 US-ASCII。
• 字节流（java.io.InputStream）-- 打印数据由从流中读取的字节组成，直到流结束。字节使用 doc flavor 的 MIME 类型指定的字符集进行编码。如果 MIME 类型未指定字符集，则默认字符集为 US-ASCII。
• 统一资源定位符（URL）-- 打印数据由从 URL 地址读取的字节组成。字节使用 doc flavor 的 MIME 类型指定的字符集进行编码。如果 MIME 类型未指定字符集，则默认字符集为 US-ASCII。当表示类是一个 URL 时，打印服务本身直接从其 URL 地址访问和下载文档，而不涉及客户端。服务可能是某种在不同环境中执行的网络打印服务。这意味着不应该使用 URL 打印数据 flavor 来打印打印机无法看到但客户端可以看到的受限制的 URL 中的文档。这也意味着不应该使用 URL 打印数据 flavor 来打印存储在本地文件中的文档，该文件无法在独立于客户端的 URL 中访问。例如，不是由 HTTP 服务器或 FTP 服务器提供的文件。要打印这样的文档，让客户端在 URL 或文件上打开输入流，并使用输入流数据 flavor。

默认和平台编码

对于打印数据的字节，如果 doc flavor 的 MIME 类型不包括 charset 参数，Java 打印服务实例默认假定为 US-ASCII 字符集。这符合 RFC 2046 的规定，该规定说默认字符集是 US-ASCII。请注意，US-ASCII 是 UTF-8 的子集，因此在未来，如果未来的 RFC 以兼容的方式认可 UTF-8 作为默认值，则可能会扩展此行为。

还请注意，这与 Java 运行时解释字节流作为文本数据的行为不同。后者假定用户区域设置的默认编码。因此，在将本地编码的文件传送到 Java 打印服务时，重要的是正确指定编码。在英语区域设置中工作的开发人员应特别注意这一点，因为他们的平台编码对应于默认的 mime 字符集。由于这种巧合，该特定情况可能无需指定平台数据的编码即可工作。

每个 Java 虚拟机实例在虚拟机启动期间确定了一个默认字符编码，通常取决于底层操作系统使用的区域设置和字符集。在分布式环境中，不能保证两个 VM 共享相同的默认编码。因此，希望从主机平台流式传输平台编码的文本数据到 Java 打印服务实例的客户端必须显式声明字符集，而不依赖于默认值。

首选形式是编码的官方 IANA 主要名称。流式传输文本数据的应用程序应始终在 mime 类型中指定字符集，这需要获取主机平台数据（例如文件）存储在该平台编码中的编码。可以从 DocFlavor.hostEncoding 获取与此相对应且适合用于 DocFlavor 的 mime 类型的 CharSet。这可能不总是主要的 IANA 名称，但保证在此 VM 中被理解。对于常见的 flavors，可以使用预定义的 *HOST DocFlavors。

有关 Java 平台支持的字符编码的更多信息，请参见 字符编码。

推荐的 DocFlavors

Java 打印服务 API 不定义任何强制支持的 DocFlavors。但是，这里有一些 Java 打印服务实例可能支持的客户端格式化打印数据的 MIME 类型示例。类 DocFlavor 内部的嵌套类声明了这些示例 doc flavor 的预定义静态常量 DocFlavor 对象；类 DocFlavor 的构造函数可用于创建任意的 doc flavor。

• 预格式化文本

  MIME类型及其描述

  MIME类型	描述
  "text/plain"	默认字符集（US-ASCII）中的纯文本
  "text/plain; charset=xxx"	字符集为 xxx 的纯文本
  "text/html"	默认字符集（US-ASCII）中的超文本标记语言
  "text/html; charset=xxx"	字符集为 xxx 的超文本标记语言

  一般来说，预格式化文本打印数据以字符导向表示类（字符数组、字符串、Reader）或以字节导向表示类（字节数组、InputStream、URL）提供。
• 预格式化页面描述语言（PDL）文档

  MIME类型及其描述

  MIME类型	描述
  "application/pdf"	便携式文档格式文档
  "application/postscript"	PostScript文档
  "application/vnd.hp-PCL"	打印机控制语言文档

  一般来说，预格式化PDL打印数据以字节导向表示类（字节数组、InputStream、URL）提供。
• 预格式化图像

  MIME类型及其描述

  MIME类型	描述
  "image/gif"	图形交换格式图像
  "image/jpeg"	联合图像专家组图像
  "image/png"	便携式网络图形图像

  一般来说，预格式化图像打印数据以字节导向表示类（字节数组、InputStream、URL）提供。
• 预格式化自动感知打印数据

  MIME类型及其描述

  MIME类型	描述
  "application/octet-stream"	打印数据格式未指定（只是一个八位字节流）

  打印机决定如何解释打印数据；这种“自动感知”工作方式取决于实现。一般来说，预格式化自动感知打印数据以字节导向表示类（字节数组、InputStream、URL）提供。

服务格式化打印数据

对于 服务格式化打印数据，Java打印服务实例确定打印数据格式。文档风味的表示类表示一个接口，其中的方法由 DocPrintJob 调用以确定要打印的内容，例如可渲染图像接口或Java可打印接口。文档风味的MIME类型是特殊值 "application/x-java-jvm-local-objectref"，表示客户端将提供一个实现表示类命名接口的Java对象的引用。这种MIME类型只是一个占位符；重要的是打印数据表示类。

对于服务格式化打印数据，打印数据表示类通常是以下之一（尽管允许使用其他表示类）。在 DocFlavor 类内部的嵌套类声明了这些示例文档风味的预定义静态常量 DocFlavor 对象；类 DocFlavor 的构造函数可用于创建任意文档风味。

• 可渲染图像对象 -- 客户端提供一个实现接口 RenderableImage 的对象。打印机调用该接口中的方法以获取要打印的图像。
• 可打印对象 -- 客户端提供一个实现接口 Printable 的对象。打印机调用该接口中的方法以逐个获取要打印的页面。对于每个页面，打印机提供一个图形上下文，客户端在该图形上下文中绘制的内容将被打印。
• 可分页对象 -- 客户端提供一个实现接口 Pageable 的对象。打印机调用该接口中的方法以逐个获取要打印的页面。对于每个页面，打印机提供一个图形上下文，客户端在该图形上下文中绘制的内容将被打印。

预定义文档风味

Java打印服务实例不 必须 支持以下打印数据格式和打印数据表示类。实际上，使用此类的开发人员不应 假设 特定打印服务支持与这些预定义文档风味对应的文档类型。始终查询打印服务以确定它支持哪些文档风味。但是，支持这些文档风味的打印服务的开发人员被鼓励参考此处创建的预定义单例实例。

• 通过字节流提供的纯文本打印数据。具体来说，建议支持以下文档风味：
  · ("text/plain", "java.io.InputStream")
  · ("text/plain; charset=us-ascii", "java.io.InputStream")
  · ("text/plain; charset=utf-8", "java.io.InputStream")
• 可渲染图像对象。具体来说，建议支持以下文档风味：
  · ("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")

Java打印服务实例允许支持任何其他文档风味（或不支持），除了上述强制性的选择，由实现自行决定。

支持上述文档风味是可取的，这样打印客户端就可以依赖能够在任何JPS打印机上打印，而不管打印机支持哪些文档风味。如果打印机不支持客户端首选的文档风味，客户端至少可以打印纯文本，或者客户端可以将其数据转换为可渲染图像并打印图像。

此外，每个Java打印服务实例必须满足以下要求以处理纯文本打印数据：

• 回车换行（CR-LF）字符对表示“转到下一行的第1列”。
• 单独的回车（CR）字符表示“转到下一行的第1列”。
• 单独的换行（LF）字符表示“转到下一行的第1列”。

客户端必须自行执行所有未涵盖上述要求的纯文本打印数据格式化。

设计原理

包 javax.print 中的类 DocFlavor 类似于 DataFlavor 类。类 DataFlavor 在Java打印服务（JPS）API中不被使用，原因有三个，这三个原因都根植于允许JPS API被其他可能需要在不包括所有Java平台标准版的Java配置文件上运行的打印服务API共享。

1. JPS API设计用于在不支持AWT的Java配置文件中使用。
2. 类 java.awt.datatransfer.DataFlavor 的实现不能保证等效的数据风味具有相同的序列化表示。 DocFlavor 可以，并且可以在需要此功能的服务中使用。
3. 类 java.awt.datatransfer.DataFlavor 的实现包含人类可读名称作为序列化表示的一部分。这不适合作为服务匹配约束的一部分。

类 DocFlavor 的序列化表示使用MIME类型字符串的以下规范形式。因此，具有不同但等效的MIME类型（具有相同规范形式）的两个文档风味可能被视为相等。

• 保留媒体类型、媒体子类型和参数，但丢弃所有注释和空白字符。
• 将媒体类型、媒体子类型和参数名称转换为小写。
• 参数值保留其原始大小写，但文本媒体类型的字符集参数值转换为小写。
• 删除参数值周围的引号字符。
• 删除参数值内部的转义字符。
• 按参数名称的升序排列参数。

类 DocFlavor 的序列化表示还包含表示类的完全限定类 名（一个 String 对象），而不是表示类本身（一个 Class 对象）。这允许客户端检查Java打印服务实例支持的文档风味，而无需加载表示类，这对于资源有限的客户端可能会有问题。

参见:

• 序列化形式

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	DocFlavor.BYTE_ARRAY	类 DocFlavor.BYTE_ARRAY 提供了预定义的静态常量 DocFlavor 对象，用于使用字节数组（byte[]）作为打印数据表示类的示例文档格式。
static class	DocFlavor.CHAR_ARRAY	类 DocFlavor.CHAR_ARRAY 提供了预定义的静态常量 DocFlavor 对象，用于使用字符数组（char[]）作为打印数据表示类的示例文档格式。
static class	DocFlavor.INPUT_STREAM	类 DocFlavor.INPUT_STREAM 提供了预定义的静态常量 DocFlavor 对象，用于使用字节流（java.io.InputStream）作为打印数据表示类的示例文档格式。
static class	DocFlavor.READER	类 DocFlavor.READER 提供了预定义的静态常量 DocFlavor 对象，用于使用字符流（java.io.Reader）作为打印数据表示类的示例文档格式。
static class	DocFlavor.SERVICE_FORMATTED	类 DocFlavor.SERVICE_FORMATTED 提供了预定义的静态常量 DocFlavor 对象，用于服务格式化打印数据的示例文档格式。
static class	DocFlavor.STRING	类 DocFlavor.STRING 提供了预定义的静态常量 DocFlavor 对象，用于使用字符串（java.lang.String）作为打印数据表示类的示例文档格式。
static class	DocFlavor.URL	类 DocFlavor.URL 提供了预定义的静态常量 DocFlavor 对象。

Field Summary

Fields

Modifier and Type	Field	Description
static final String	hostEncoding	表示主机操作系统编码的字符串。

Constructor Summary

Constructors

Constructor	Description
DocFlavor(String mimeType, String className)	从给定的 MIME 类型和表示类名称构造一个新的文档格式对象。

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object obj)	确定此文档格式对象是否等于给定的对象。
String	getMediaSubtype()	返回此文档格式对象的媒体子类型（来自 MIME 类型）。
String	getMediaType()	返回此文档格式对象的媒体类型（来自 MIME 类型）。
String	getMimeType()	基于规范形式返回此文档格式对象的 MIME 类型字符串。
String	getParameter(String paramName)	返回表示 MIME 参数的 String。
String	getRepresentationClassName()	返回此文档格式对象的表示类名称。
int	hashCode()	返回此文档格式对象的哈希码。
String	toString()	将此 DocFlavor 转换为字符串。

Methods declared in class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

hostEncoding

             public static final String hostEncoding
            

表示主机操作系统编码的字符串。这将遵循文档中记录的约定 RFC 2278: IANA Charset Registration Procedures，除非为了与 Java 平台先前版本的兼容性而返回历史名称。从方法返回的值仅对返回它的 VM 有效，用于 DocFlavor 中。这是执行 VM 中所有“HOST”预定义 DocFlavors 的字符集。

Constructor Details

DocFlavor

             public DocFlavor(String mimeType, String className)
            

从给定的 MIME 类型和表示类名称构造一个新的文档格式对象。给定的 MIME 类型将被转换为规范形式并在内部存储。

参数:

mimeType - MIME 媒体类型字符串

className - 完全限定的表示类名称

抛出:

NullPointerException - 如果 mimeType 或 className 为 null

IllegalArgumentException - 如果 mimeType 不符合 MIME 媒体类型字符串的语法

Method Details

getMimeType

             public String getMimeType()
            

基于规范形式返回此文档格式对象的 MIME 类型字符串。每个参数值都用引号括起来。

返回:

MIME 类型

getMediaType

             public String getMediaType()
            

返回此文档格式对象的媒体类型（来自 MIME 类型）。

返回:

媒体类型

getMediaSubtype

             public String getMediaSubtype()
            

返回此文档格式对象的媒体子类型（来自 MIME 类型）。

返回:

媒体子类型

getParameter

             public String getParameter(String paramName)
            

返回表示 MIME 参数的 String。MIME 类型可能包括通常是可选的参数。文本类型的字符集是一个常用的示例。此便利方法将返回此文档格式的 MIME 类型中指定参数的值，如果为此格式的 MIME 类型指定了参数。

参数:

paramName - 参数的名称。在执行匹配之前，此名称会被内部转换为规范小写格式。

返回:

表示 MIME 参数的字符串，如果该参数不在 MIME 类型字符串中，则返回 null

抛出:

NullPointerException - 如果 paramName 为 null

getRepresentationClassName

             public String getRepresentationClassName()
            

返回此文档格式对象的表示类名称。

返回:

表示类名称

toString

             public String toString()
            

将此 DocFlavor 转换为字符串。

覆盖:

toString 在类 Object

返回:

基于规范形式的 MIME 类型字符串。每个参数值都用引号括起来。一个“class=”参数将附加到 MIME 类型字符串，以指示表示类名称。

hashCode

             public int hashCode()
            

返回此文档格式对象的哈希码。

覆盖:

hashCode 在类 Object

返回:

对象的哈希码值。

参见:

• Object.equals(java.lang.Object)
• System.identityHashCode(java.lang.Object)

equals

             public boolean equals(Object obj)
            

确定此文档格式对象是否等于给定的对象。如果给定对象不为 null，是 DocFlavor 的一个实例，具有等效于此文档格式对象的 MIME 类型（即，MIME 类型具有相同的媒体类型、媒体子类型和参数），并且具有与此文档格式对象相同的表示类名称，则两者相等。因此，如果两个文档格式对象的 MIME 类型除了注释外相同，则它们被视为相等。但是，具有 MIME 类型为“text/plain”和“text/plain; charset=US-ASCII”的两个文档格式对象不被视为相等，即使它们表示相同的媒体类型（因为纯文本的默认字符集为 US-ASCII）。

覆盖:

equals 在类 Object

参数:

obj - 要测试的 Object

返回:

如果此文档格式对象等于 obj，则返回 true，否则返回 false

参见:

• Object.hashCode()
• HashMap