Module  java.desktop
软件包  javax.print

Class DocFlavor

  • All Implemented Interfaces:
    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平台上支持的字符编码的更多信息，请参阅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's） 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处不可用。 例如，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运行时的行为。 这假定用户区域设置的默认编码。 因此，当将本地编码中的文件假脱机到Java打印服务时，正确指定编码很重要。 在英文语言环境中工作的开发人员应特别注意这一点，因为它们的平台编码对应于默认的mime字符集。 通过这个巧合，特定的情况可以在没有指定平台数据的编码的情况下工作。

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

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

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

    推荐DocFlavors

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

    • 预格式文本 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 flavor的预定义静态常量DocFlavor对象; DocFlavor类的构造函数可用于创建任意的doc风格。

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

    预定义文件风味

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

    允许Java Print Service实例支持任何其他文档风格（或无）除了上述强制性文件外，在实现的选择。

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

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

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

    客户端必须自己执行所有不符合上述要求的纯文本打印数据格式。

    设计理由

    包javax.print.data中的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课程的java.awt.datatransfer.DataFlavor包括人类可呈现的名称作为序列化表示的一部分。 这不适合作为服务匹配约束的一部分。

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

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

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

    另请参见：
    Serialized Form

    • Nested Class Summary

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

    • Field Summary

      Fields  
      Modifier and Type Field 描述
      static String hostEncoding
      代表主机操作系统编码的字符串。

    • 构造方法摘要

      构造方法  
      Constructor 描述
      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为空，则抛出。
        IllegalArgumentException - （未检查异常）如果 mimeType不符合MIME媒体类型字符串的语法，则抛出。

    • 方法详细信息

      • getMimeType

        public String getMimeType​()
        根据规范表单返回此doc风格对象的MIME类型字符串。 每个参数值都用引号括起来。
        结果
        mime类型

      • getMediaType

        public String getMediaType​()
        返回此文档flavor对象的媒体类型（从MIME类型）。
        结果
        媒体类型

      • getMediaSubtype

        public String getMediaSubtype​()
        返回此文档flavor对象的媒体子类型（从MIME类型）。
        结果
        媒体子类型

      • getParameter

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

      • getRepresentationClassName

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

      • toString

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

      • equals

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