Класс 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-кода или файл на диске с обычным текстом в некоторой кодировке, возможно полученный из внешнего источника, и ему требуется способ сообщить формат данных службе печати.

Класс представления формата документа служит каналом, через который DocPrintJob JPS получает от клиента последовательность символов или байтов. Тип MIME формата документа — это один из стандартных типов мультимедиа, указывающий, как интерпретировать последовательность символов или байтов. Список стандартных типов мультимедиа см. в каталоге типов мультимедиа Internet Assigned Numbers Authority (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) означает «перейти к первому столбцу следующей строки».
• Отдельный символ возврата каретки (CR) означает «перейти к первому столбцу следующей строки».
• Отдельный символ перевода строки (LF) означает «перейти к первому столбцу следующей строки».

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

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

Класс DocFlavor в пакете javax.print похож на класс DataFlavor. Класс DataFlavor не используется в API Java Print Service (JPS) по трём причинам, каждая из которых связана с тем, что API JPS должен быть доступен для использования другими API служб печати, которым может потребоваться работа в профилях Java, не включающих все компоненты Java Platform, 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, не загружая классы представления, что может быть проблематично для клиентов с ограниченными ресурсами.