模块  java.desktop
软件包  javax.print

Class 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平台支持的字符编码的更多信息，请参见character encodings 。
    • 表示类名。 这指定了实际打印数据所来自的对象类的完全限定名称，如Class.getName()方法所返回的。 （因此，对于类名byte[]是"[B" ，为char[]它是"[C" ）。
    A DocPrintJob通过接口Doc获得其打印数据。 Doc对象允许DocPrintJob确定客户端可以提供的doc风格。 Doc对象还允许DocPrintJob获取doc flavor的表示类的实例，然后DocPrintJob从中获取实际的打印数据。

    客户端格式化打印数据

    打印数据有两大类，客户端格式化打印数据和服务格式化打印数据。

    对于客户端格式化的打印数据 ，客户端确定或知道打印数据格式。 例如，客户端可以具有JPEG编码图像，用于HTML代码的URL ，或者包含可能从外部源获得的某种编码的纯文本的磁盘文件，并且需要一种方式来向打印服务描述数据格式。

    doc flavor的表示类是JPS DocPrintJob从客户端获取字符或字节序列的管道。 doc flavor的MIME类型是告诉如何解释字符或字节序列的标准媒体类型之一。 有关标准媒体类型的列表，请参阅Internet Assigned Numbers Authority（IANA） Media Types Directory 。 接口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打印数据URL来打印客户端可以看到但受打印机无法看到的限制URL的文档。 这也意味着您不应使用URL打印数据风格来打印存储在本地文件中的文档，该文档在URL处不可用，可以独立于客户端访问。 例如，HTTP服务器或FTP服务器未提供的文件。 要打印此类文档，请让客户端在URL或文件上打开输入流，并使用输入流数据风格。

    默认和平台编码

    对于doc flavor的MIME类型不包含charset参数的字节打印数据，Java Print Service实例默认采用US-ASCII字符集。 这与RFC 2046一致 ，它表示默认字符集是US-ASCII。 请注意，US-ASCII是UTF-8的子集，因此如果未来的RFC以兼容的方式认可UTF-8作为默认值，将来可能会扩大。

    另请注意，这与将字节流解释为文本数据时Java运行时的行为不同。 这假定用户的语言环境的默认编码。 因此，在将本地编码的文件假脱机到Java打印服务时，正确指定编码很重要。 在英语语言环境中工作的开发人员应该特别注意这一点，因为他们的平台编码对应于默认的mime字符集。 通过这种巧合，特定情况可以在不指定平台数据的编码的情况下工作。

    Java虚拟机的每个实例都具有在虚拟机启动期间确定的默认字符编码，并且通常取决于底层操作系统使用的语言环境和字符集。 在分布式环境中，无法保证两个VM共享相同的默认编码。 因此，希望将平台编码的文本数据从主机平台流式传输到Java Print Service实例的客户端必须显式声明charset而不依赖于默认值。

    首选形式是编码的官方IANA主要名称。 流文本数据的应用程序应始终指定mime类型中的字符集，这需要获得存储在该平台编码中的数据（例如文件）的主机平台的编码。 甲CharSet其对应于这一点，适合于在一个MIME类型使用一个DocFlavor可获自DocFlavor.hostEncoding这可能不总是这样的主IANA名称，但是保证由该VM被理解。 对于常见的风味，可以使用预定义的* HOST DocFlavors 。

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

    推荐的DocFlavors

    Java Print Service API未定义任何强制支持的DocFlavors 。 但是，以下是Java Print Service实例可能支持客户端格式化打印数据的MIME类型的一些示例。 类DocFlavor嵌套类声明这些示例doc DocFlavor预定义静态常量DocFlavor对象; class DocFlavor的构造函数可用于创建任意doc flavor。
    • 预先格式化的文字 MIME-Types and their descriptions MIME-Type Description "text/plain" Plain text in the default character set (US-ASCII) "text/plain; charset=xxx" Plain text in character set xxx "text/html" HyperText Markup Language in the default character set (US-ASCII) "text/html; charset=xxx" HyperText Markup Language in character set xxx
      通常，预先格式化的文本打印数据以面向字符的表示类（字符数组，字符串，读取器）或面向字节的表示类（字节数组，InputStream，URL）提供。
    • 预格式化页面描述语言（PDL）文档 MIME-Types and their descriptions MIME-Type Description "application/pdf" Portable Document Format document "application/postscript" PostScript document "application/vnd.hp-PCL" Printer Control Language document
      一般情况下，预先格式化的PDL打印数据在面向字节的表示形式类提供（字节数组， InputStream ， URL ）。
    • 预先格式化的图像 MIME-Types and their descriptions MIME-Type Description "image/gif" Graphics Interchange Format image "image/jpeg" Joint Photographic Experts Group image "image/png" Portable Network Graphics image
      一般情况下，预先格式化的图像打印数据在面向字节的表示形式类提供（字节数组， InputStream ， URL ）。
    • 预先格式化的自动打印打印数据 MIME-Types and their descriptions MIME-Type Description "application/octet-stream" The print data format is unspecified (just an octet stream)
      打印机决定如何解释打印数据; 这种“自动感知”的工作方式依赖于实现。 一般情况下，预先格式化的自动感测的打印数据是在面向字节的表示形式类提供（字节数组， InputStream ， URL ）。

    服务格式化打印数据

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

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

    • 可渲染图像对象 - 客户端提供实现接口RenderableImage的对象。 打印机调用该界面中的方法以获取要打印的图像。
    • 可打印对象 - 客户端提供实现接口Printable的对象。 打印机调用该接口中的方法逐个获取要打印的页面。 对于每个页面，打印机提供图形上下文，无论客户端绘制什么图形上下文都打印出来。
    • 可分页对象 - 客户端提供实现接口Pageable的对象。 打印机调用该接口中的方法逐个获取要打印的页面。 对于每个页面，打印机提供图形上下文，无论客户端绘制什么图形上下文都打印出来。

    预定义的Doc Flavors

    不需要 Java Print Service实例来支持以下打印数据格式和打印数据表示类。 事实上，使用这个类开发人员不应该假定特定的打印服务支持对应于这些预定义的doc flavor的文档类型。 始终查询打印服务以确定它支持的doc flavor。 但是，鼓励具有支持这些doc flavor的打印服务的开发人员参考此处创建的预定义单例实例。
    • 通过字节流提供的纯文本打印数据。 具体而言，建议支持以下doc flavor：
      · ("text/plain", "java.io.InputStream")
      · ("text/plain; charset=us-ascii", "java.io.InputStream")
      · ("text/plain; charset=utf-8", "java.io.InputStream")
    • 可渲染的图像对象。 具体而言，建议支持以下doc flavor：
      · ("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")
    除了上述强制性实例之外，Java Print Service实例还允许支持任何其他doc风格（或无）。

    需要支持上述doc风格，因此打印客户端可以依赖于能够在任何JPS打印机上打印，而不管打印机支持哪种doc类型。 如果打印机不支持客户端的首选doc风格，则客户端至少可以打印纯文本，或者客户端可以将其数据转换为可渲染图像并打印图像。

    此外，每个Java Print Service实例都必须满足处理纯文本打印数据的这些要求：

    • 字符对回车换行（CR-LF）表示“转到下一行的第1列”。
    • 回车（CR）字符本身意味着“转到下一行的第1列”。
    • 换行（LF）字符本身意味着“转到下一行的第1列”。
    客户端必须自己执行上述要求未解决的所有纯文本打印数据格式。

    设计理由

    类DocFlavor在包javax.print类似于类DataFlavor 。 Java打印服务（JPS）API中没有使用类DataFlavor ，原因有三个，这些原因都源于允许JPS API由其他打印服务API共享，这些API可能需要在不包含所有Java的Java配置文件上运行平台，标准版。
    1. JPS API旨在用于不支持AWT的Java配置文件。
    2. 类java.awt.datatransfer.DataFlavor实现不保证等效数据风格将具有相同的序列化表示。 DocFlavor可以，并且可以在需要它的服务中使用。
    3. 类java.awt.datatransfer.DataFlavor的实现包括人类可呈现的名称作为序列化表示的一部分。 这不适合作为服务匹配约束的一部分。
    类DocFlavor的序列化表示使用以下规范形式的MIME类型字符串。 因此，MIME类型不同但具有相同（具有相同的规范形式）的两种doc类型可以被认为是相同的。
    • 保留媒体类型，媒体子类型和参数，但丢弃所有注释和空白字符。
    • 媒体类型，媒体子类型和参数名称将转换为小写。
    • 参数值保留其原始大小写，但文本媒体类型的charset参数值将转换为小写。
    • 将删除围绕参数值的引号字符。
    • 引用参数值中的反斜杠字符将被删除。
    • 参数按参数名称的升序排列。
    类DocFlavor的序列化表示还包含表示类的完全限定类名 （ String对象），而不是表示类本身（ 类对象）。 这允许客户端检查Java Print Service实例支持的doc flavor，而无需加载表示类，这对于有限资源的客户端可能是有问题的。
    另请参见：
    Serialized Form

    • 嵌套类汇总

      嵌套类  
      变量和类型 类 描述
      static class  DocFlavor.BYTE_ARRAY
      类 DocFlavor.BYTE_ARRAY提供预定义的静态常量 DocFlavor对象，例如使用字节数组（ byte[] ）作为打印数据表示类的doc byte[] 。
      static class  DocFlavor.CHAR_ARRAY
      类 DocFlavor.CHAR_ARRAY提供预定义的静态常量 DocFlavor对象，例如使用字符数组（ char[] ）作为打印数据表示类的doc char[] 。
      static class  DocFlavor.INPUT_STREAM
      类DocFlavor.INPUT_STREAM提供预定义的静态常量DocFlavor对象，例如使用字节流（ java.io.InputStream ）作为打印数据表示类的doc flavor 。
      static class  DocFlavor.READER
      类DocFlavor.READER提供预定义的静态常量DocFlavor对象，例如使用字符流（ java.io.Reader ）作为打印数据表示类的doc flavor 。
      static class  DocFlavor.SERVICE_FORMATTED
      类 DocFlavor.SERVICE_FORMATTED提供预定义的静态常量 DocFlavor对象，例如用于服务格式化的打印数据的doc DocFlavor 。
      static class  DocFlavor.STRING
      类DocFlavor.STRING提供预定义的静态常量DocFlavor对象，例如使用字符串（ java.lang.String ）作为打印数据表示类的doc flavor 。
      static class  DocFlavor.URL
      DocFlavor.URL类提供了预定义的静态常量 DocFlavor 。

    • 字段汇总

      字段  
      变量和类型 字段 描述
      static String hostEncoding
      表示主机操作系统编码的字符串。

    • 构造方法摘要

      构造方法  
      构造器 描述
      DocFlavor​(String mimeType, String className)
      根据给定的MIME类型和表示类名构造一个新的doc flavor对象。

    • 字段详细信息

      • hostEncoding

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

    • 构造方法详细信息

      • DocFlavor

        public DocFlavor​(String mimeType,
                 String className)
        根据给定的MIME类型和表示类名构造一个新的doc flavor对象。 给定的MIME类型将转换为规范形式并在内部存储。
        参数
        mimeType - MIME媒体类型字符串
        className - 完全限定的表示形式类名称
        异常
        NullPointerException - 如果 mimeType或 className是 null
        IllegalArgumentException - 如果 mimeType不遵守MIME媒体类型字符串的语法

    • 方法详细信息

      • getMimeType

        public String getMimeType()
        基于规范形式返回此doc flavor对象的MIME类型字符串。 每个参数值都用引号括起来。
        结果
        哑剧类型

      • getMediaType

        public String getMediaType()
        返回此doc flavor对象的媒体类型（来自MIME类型）。
        结果
        媒体类型

      • getMediaSubtype

        public String getMediaSubtype()
        返回此doc flavor对象的media子类型（来自MIME类型）。
        结果
        媒体子类型

      • getParameter

        public String getParameter​(String paramName)
        返回表示MIME参数的String 。 Mime类型可以包括通常是可选的参数。 文本类型的字符集是一个非常有用的示例。 如果在此类型的mime类型中指定了一个，则此便捷方法将返回指定参数的值。
        参数
        paramName - 参数的名称。 在执行匹配之前，此名称在内部转换为规范的小写格式。
        结果
        表示mime参数的字符串，如果该参数不在mime类型字符串中， null
        异常
        NullPointerException - 如果paramName是 null

      • getRepresentationClassName

        public String getRepresentationClassName()
        返回此doc flavor对象的表示类的名称。
        结果
        表示类的名称

      • toString

        public String toString()
        将此 DocFlavor转换为字符串。
        重写：
        toString类 Object
        结果
        基于规范形式的MIME类型字符串。 每个参数值都用引号括起来。 “class =”参数附加到MIME类型字符串以指示表示类名称。

      • equals

        public boolean equals​(Object obj)
        确定此doc flavor对象是否等于给定对象。 两者相等如果给定的对象不是null ，是的一个实例DocFlavor ，具有MIME类型相当于此DocFlavor对象的MIME类型（即，MIME类型具有相同的媒体类型，媒体子类型和参数），并且具有与此doc flavor对象相同的表示类名。 因此，如果两个doc flavor对象的MIME类型除了注释之外是相同的，则它们被认为是相等的。 但是，MIME类型为“text / plain”和“text / plain; charset = US-ASCII”的两个doc flavor对象不被认为是相等的，即使它们表示相同的媒体类型（因为纯文本的默认字符集是US-ASCII）。
        重写：
        equals类 Object
        参数
        obj - Object进行测试
        结果
        true如果此doc flavor对象等于 obj ， false
        另请参见：
        Object.hashCode() ， HashMap