Класс DocFlavor

public class DocFlavor extends Object implements Serializable, Cloneable

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

• MIME тип. Это тип мультимедиа MIME (Multipurpose Internet Mail Extensions) (определён в RFC 2045 и RFC 2046), который определяет, как интерпретировать данные печати. Кодировка символов текстовых данных должна быть предпочтительным именем MIME IANA или его каноническим именем, если предпочтительное имя не указано. Дополнительно могут распознаваться некоторые исторические имена, поддерживаемые более ранними версиями платформы 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[]) — Данные печати состоят из символов Юникода в массиве.
• String — Данные печати состоят из символов Юникода в строке.
• Поток символов (java.io.Reader) — Данные печати состоят из символов Юникода, считанных из потока до конца потока.
• Массив байтов (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"	Гипертекстовый язык разметки в стандартной кодировке (US-ASCII)
  "text/html; charset=xxx"	Гипертекстовый язык разметки в кодировке xxx

  В общем случае, отформатированные текстовые данные для печати предоставляются либо в классе с ориентацией на символы (массив символов, строка, потоковый ридер), либо в классе с ориентацией на байты (массив байтов, входной поток, URL).
• Документы в формате описания страницы PDL

  Типы MIME и их описания

  Тип MIME	Описание
  "application/pdf"	Документ Portable Document Format
  "application/postscript"	Документ PostScript
  "application/vnd.hp-PCL"	Документ языка управления принтером

  В общем случае, отформатированные данные 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 определяет формат данных для печати. Класс представления doc flavor обозначает интерфейс, чьи методы вызывает DocPrintJob для определения содержимого для печати — например, интерфейс рендерируемого изображения или интерфейс печатаемого объекта Java. Тип MIME doc flavor — специальное значение "application/x-java-jvm-local-objectref", указывающее, что клиент предоставит ссылку на объект Java, реализующий интерфейс, имя которого указано в классе представления. Этот тип MIME — просто placeholder; важным является класс представления данных для печати.

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

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

Предопределенные типы Doc Flavor

Экземпляр 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 flavor (или ни одного) помимо вышеперечисленных обязательных, по выбору реализации.

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

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

• Пара carriage return-line feed (CR-LF) означает «переход к началу следующей строки»
• Символ carriage return (CR) сам по себе означает «переход к началу следующей строки»
• Символ line feed (LF) сам по себе означает «переход к началу следующей строки»

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

Обоснование проектирования

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

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

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

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

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