Класс DocFlavor

public class DocFlavor extends Object implements Serializable, Cloneable

Класс DocFlavor инкапсулирует объект, задающий формат, в котором данные для печати передаются в DocPrintJob. «Doc» — это короткий, легко произносимый термин, означающий «часть данных для печати». Формат данных для печати, или «формат документа», состоит из двух частей:

• MIME-тип. Это тип мультимедиа Multipurpose Internet Mail Extensions (MIME), определённый в RFC 2045 и RFC 2046, который задаёт способ интерпретации данных для печати. Для текстовых данных следует использовать предпочтительное имя набора символов IANA MIME или его каноническое имя, если предпочтительное имя не указано. Кроме того, могут распознаваться несколько исторических имён, поддерживаемых более ранними версиями платформы Java. Дополнительные сведения о кодировках символов, поддерживаемых на платформе Java, см. в разделе кодировки символов.
• Имя класса представления. Оно задаёт полное имя класса объекта, из которого поступают собственно данные для печати, возвращаемое методом Class.getName(). (Таким образом, имя класса для byte[] — "[B", а для char[] — "[C".)

DocPrintJob получает данные для печати с помощью интерфейса Doc. Объект Doc позволяет DocPrintJob определить формат документа, который может предоставить клиент. Объект Doc также позволяет DocPrintJob получить экземпляр класса представления формата документа, из которого DocPrintJob затем получает собственно данные для печати.

Данные для печати, форматируемые клиентом

Существует две основные категории данных для печати: данные, форматируемые клиентом, и данные, форматируемые службой.

Для данных для печати, форматируемых клиентом, клиент определяет формат данных или знает его. Например, у клиента может быть изображение в формате JPEG, URL для HTML-кода или файл на диске с обычным текстом в некоторой кодировке, возможно полученный из внешнего источника, и ему необходим способ сообщить службе печати формат этих данных.

Класс представления формата документа служит каналом, через который JPS DocPrintJob получает от клиента последовательность символов или байтов. MIME-тип формата документа относится к стандартным типам мультимедиа, указывающим, как интерпретировать эту последовательность символов или байтов. Список стандартных типов мультимедиа см. в каталоге типов мультимедиа Управления по присвоению номеров в Интернете (IANA). Интерфейс Doc предоставляет две служебные операции — getReaderForText и getStreamForBytes(), — помогающие клиенту объекта Doc извлекать данные для печати, форматируемые клиентом.

Для данных для печати, форматируемых клиентом, класс представления данных для печати обычно относится к одному из следующих типов (хотя допускаются и другие классы представления):

• Массив символов (char[]) — данные для печати состоят из символов Unicode в массиве.
• String — данные для печати состоят из символов Unicode в строке.
• Поток символов (java.io.Reader) — данные для печати состоят из символов Unicode, считываемых из потока до его конца.
• Массив байтов (byte[]) — данные для печати состоят из байтов в массиве. Байты закодированы с использованием набора символов, указанного в MIME-типе формата документа. Если MIME-тип не указывает набор символов, по умолчанию используется US-ASCII.
• Поток байтов (java.io.InputStream) — данные для печати состоят из байтов, считываемых из потока до его конца. Байты закодированы с использованием набора символов, указанного в MIME-типе формата документа. Если MIME-тип не указывает набор символов, по умолчанию используется US-ASCII.
• Унифицированный указатель ресурса (URL) — данные для печати состоят из байтов, считываемых по адресу URL. Байты закодированы с использованием набора символов, указанного в MIME-типе формата документа. Если MIME-тип не указывает набор символов, по умолчанию используется US-ASCII. Если класс представления — URL, служба печати самостоятельно обращается к документу и загружает его непосредственно по адресу URL, не привлекая клиента. Служба может быть сетевой службой печати, работающей в другой среде. Поэтому для печати документа по адресу URL с ограниченным доступом, который виден клиенту, но недоступен принтеру, не следует использовать формат данных для печати URL. Также не следует использовать формат данных для печати URL для печати документа, сохранённого в локальном файле, который недоступен по адресу URL независимо от клиента. Например, это может быть файл, не размещённый на HTTP- или FTP-сервере. Чтобы распечатать такие документы, клиенту следует открыть входной поток для URL или файла и использовать формат данных с входным потоком.

Кодировки по умолчанию и кодировки платформы

Для байтовых данных для печати, MIME-тип формата документа которых не содержит параметр charset, экземпляр Java Print Service по умолчанию предполагает набор символов US-ASCII. Это соответствует RFC 2046, согласно которому набор символов по умолчанию — US-ASCII. Обратите внимание: US-ASCII является подмножеством UTF-8, поэтому в будущем этот набор может быть расширен, если новая версия RFC утвердит UTF-8 в качестве значения по умолчанию совместимым образом.

Также следует учитывать, что это отличается от поведения среды выполнения Java при интерпретации потока байтов как текстовых данных. В этом случае предполагается кодировка по умолчанию для локали пользователя. Поэтому при передаче файла в локальной кодировке в Java Print Service важно правильно указать кодировку. Разработчикам, работающим в англоязычных локалях, следует уделить этому особое внимание, поскольку кодировка их платформы совпадает с MIME-набором символов по умолчанию. Благодаря этому совпадению в данном конкретном случае данные платформы могут обрабатываться правильно и без указания кодировки.

Для каждого экземпляра виртуальной машины Java при её запуске определяется кодировка символов по умолчанию, обычно зависящая от локали и набора символов, используемых операционной системой. В распределённой среде нет гарантии, что две виртуальные машины используют одинаковую кодировку по умолчанию. Поэтому клиенты, передающие текстовые данные в кодировке платформы с хост-платформы в экземпляр Java Print Service, должны явно указывать набор символов, а не полагаться на значения по умолчанию.

Предпочтительно использовать официальное основное имя кодировки, присвоенное IANA. Приложения, передающие текстовые данные, всегда должны указывать набор символов в MIME-типе; для этого необходимо получить кодировку хост-платформы для данных (например, файлов), сохранённых в кодировке этой платформы. CharSet, соответствующее этому требованию и пригодное для использования в MIME-типе для DocFlavor, можно получить с помощью DocFlavor.hostEncoding. Это имя не всегда является основным именем IANA, но гарантированно распознаётся данной виртуальной машиной. Для распространённых форматов можно использовать предопределённые значения *HOST DocFlavors.

Дополнительные сведения о кодировках символов, поддерживаемых на платформе Java, см. в разделе кодировки символов.

Рекомендуемые форматы документов

API Java Print Service не определяет форматы DocFlavors, обязательные для поддержки. Однако ниже приведены примеры MIME-типов, которые может поддерживать экземпляр Java Print Service для данных для печати, форматируемых клиентом. Вложенные классы класса DocFlavor объявляют предопределённые статические константы-объекты DocFlavor для этих примеров форматов документов; конструктор класса DocFlavor можно использовать для создания произвольного формата документа.

• Предварительно отформатированный текст

  MIME-типы и их описания

  MIME-тип	Описание
  "text/plain"	Обычный текст в наборе символов по умолчанию (US-ASCII)
  "text/plain; charset=xxx"	Обычный текст в наборе символов xxx
  "text/html"	Документ HTML в наборе символов по умолчанию (US-ASCII)
  "text/html; charset=xxx"	Документ HTML в наборе символов xxx

  Обычно данные для печати в виде предварительно отформатированного текста предоставляются либо в классе представления, ориентированном на символы (массив символов, String, Reader), либо в классе представления, ориентированном на байты (массив байтов, InputStream, URL).
• Предварительно отформатированные документы на языке описания страниц (PDL)

  MIME-типы и их описания

  MIME-тип	Описание
  "application/pdf"	Документ в формате Portable Document Format
  "application/postscript"	Документ PostScript
  "application/vnd.hp-PCL"	Документ Printer Control Language

  Обычно предварительно отформатированные данные для печати PDL предоставляются в классе представления, ориентированном на байты (массив байтов, InputStream, URL).
• Предварительно отформатированные изображения

  MIME-типы и их описания

  MIME-тип	Описание
  "image/gif"	Изображение Graphics Interchange Format
  "image/jpeg"	Изображение Joint Photographic Experts Group
  "image/png"	Изображение Portable Network Graphics

  Обычно предварительно отформатированные данные для печати в виде изображения предоставляются в классе представления, ориентированном на байты (массив байтов, InputStream, URL).
• Предварительно отформатированные данные для печати с автоматическим определением формата

  MIME-типы и их описания

  MIME-тип	Описание
  "application/octet-stream"	Формат данных для печати не задан (только поток октетов)

  Принтер самостоятельно определяет, как интерпретировать данные для печати; способ такого «автоматического определения» зависит от реализации. Обычно такие предварительно отформатированные данные предоставляются в классе представления, ориентированном на байты (массив байтов, InputStream, URL).

Данные для печати, форматируемые службой

Для данных для печати, форматируемых службой формат данных определяет экземпляр Java Print Service. Класс представления формата документа обозначает интерфейс, методы которого DocPrintJob вызывает для определения содержимого, которое необходимо напечатать, например интерфейс визуализируемого изображения или интерфейс Java Printable. MIME-тип формата документа имеет специальное значение "application/x-java-jvm-local-objectref", указывающее, что клиент предоставит ссылку на объект Java, реализующий интерфейс, имя которого указано в качестве класса представления. Этот MIME-тип служит лишь заполнителем; важен класс представления данных для печати.

Для данных для печати, форматируемых службой, класс представления данных для печати обычно относится к одному из следующих типов (хотя допускаются и другие классы представления). Вложенные классы класса DocFlavor объявляют предопределённые статические константы-объекты DocFlavor для этих примеров форматов документов; конструктор класса DocFlavor можно использовать для создания произвольного формата документа.

• Объект визуализируемого изображения — клиент предоставляет объект, реализующий интерфейс RenderableImage. Принтер вызывает методы этого интерфейса, чтобы получить изображение для печати.
• Объект Printable — клиент предоставляет объект, реализующий интерфейс Printable. Принтер последовательно вызывает методы этого интерфейса, чтобы получить страницы для печати. Для каждой страницы принтер предоставляет графический контекст, и всё, что клиент рисует в этом графическом контексте, отправляется на печать.
• Объект Pageable — клиент предоставляет объект, реализующий интерфейс Pageable. Принтер последовательно вызывает методы этого интерфейса, чтобы получить страницы для печати. Для каждой страницы принтер предоставляет графический контекст, и всё, что клиент рисует в этом графическом контексте, отправляется на печать.

Предопределённые форматы документов

Экземпляр Java Print Service не обязан поддерживать следующие форматы данных для печати и классы представления данных для печати. Разработчик, использующий этот класс, ни в коем случае не должен предполагать, что определённая служба печати поддерживает типы документов, соответствующие этим предопределённым форматам. Всегда запрашивайте у службы печати список поддерживаемых форматов документов. Однако разработчикам, использующим службы печати с поддержкой этих форматов, рекомендуется обращаться к предопределённым одиночным экземплярам, созданным здесь.

• Данные в виде обычного текста, предоставляемые через поток байтов. В частности, рекомендуется поддерживать следующие форматы документов:
  · ("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 Print Service может поддерживать любые другие форматы документов (или не поддерживать их вовсе) дополнительно к перечисленным обязательным форматам — по выбору реализации.

Поддержка указанных выше форматов документов желательна, чтобы клиент печати мог рассчитывать на возможность печати на любом принтере JPS независимо от поддерживаемых им форматов документов. Если принтер не поддерживает предпочтительный формат клиента, клиент может хотя бы напечатать обычный текст или преобразовать свои данные в визуализируемое изображение и напечатать его.

Кроме того, каждый экземпляр Java Print Service должен выполнять следующие требования при обработке данных для печати в виде обычного текста:

• Пара символов «возврат каретки — перевод строки» (CR-LF) означает «перейти к столбцу 1 следующей строки».
• Символ возврата каретки (CR), используемый отдельно, означает «перейти к столбцу 1 следующей строки».
• Символ перевода строки (LF), используемый отдельно, означает «перейти к столбцу 1 следующей строки».

Клиент самостоятельно выполняет всё форматирование данных для печати в виде обычного текста, не предусмотренное приведёнными выше требованиями.

Обоснование проектных решений

Класс DocFlavor в пакете javax.print похож на класс DataFlavor. Класс DataFlavor не используется в API Java Print Service (JPS) по трём причинам, связанным с тем, что API JPS должен быть доступен и другим API служб печати, которым может потребоваться работать в профилях Java, не включающих всю платформу Java, Standard Edition.

1. API JPS предназначен для использования в профилях Java, не поддерживающих AWT.
2. Реализация класса java.awt.datatransfer.DataFlavor не гарантирует, что эквивалентные форматы данных будут иметь одинаковое сериализованное представление. DocFlavor это гарантирует и может использоваться в службах, которым это необходимо.
3. Реализация класса java.awt.datatransfer.DataFlavor включает человекочитаемое имя в сериализованное представление. Это неуместно для использования в качестве ограничения при сопоставлении служб.

Сериализованное представление класса DocFlavor использует следующую каноническую форму строки MIME-типа. Таким образом, два формата документов с MIME-типами, которые не идентичны, но эквивалентны (имеют одинаковую каноническую форму), могут считаться равными.

• Тип мультимедиа, подтип мультимедиа и параметры сохраняются, но все комментарии и пробельные символы удаляются.
• Тип мультимедиа, подтип мультимедиа и имена параметров переводятся в нижний регистр.
• Значения параметров сохраняют исходный регистр, за исключением значения параметра charset для текстового типа мультимедиа, которое переводится в нижний регистр.
• Кавычки, окружающие значения параметров, удаляются.
• Экранирование обратной косой черты внутри значений параметров удаляется.
• Параметры располагаются в порядке возрастания имён.

Сериализованное представление класса DocFlavor также содержит полное имя класса представления (объекта String), а не сам класс представления (объект Class). Это позволяет клиенту проверить, какие форматы документов поддерживает экземпляр Java Print Service, не загружая классы представления, что может быть проблематично для клиентов с ограниченными ресурсами.