Класс DocFlavor

Класс DocFlavor инкапсулирует объект, который определяет формат, в котором данные печати предоставляются интерфейсу DocPrintJob. "Doc" — краткое и легко произносимое обозначение "данных печати". Формат данных печати, или "тип 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, который может предоставить клиент. Объект Doc также позволяет объекту DocPrintJob получить экземпляр класса представления типа doc, из которого DocPrintJob получает фактические данные печати.

Данные печати в формате клиента

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

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

Класс представления типа doc служит посредником для JPS DocPrintJob в получении последовательности символов или байтов от клиента. Тип MIME типа doc — один из стандартных типов медиа, указывающий, как интерпретировать последовательность символов или байтов. Список стандартных типов медиа можно найти в каталоге типов медиа (Media Types Directory) Internet Assigned Numbers Authority (IANA) по адресу http://www.iana.org/assignments/media-types/. Интерфейс Doc предоставляет два вспомогательных метода, getReaderForText и getStreamForBytes(), для помощи объекту Doc в извлечении данных печати в формате клиента.

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

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

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

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

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

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

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

Дополнительную информацию о поддерживаемых на Java платформе кодировках символов можно найти в кодировках символов.

Рекомендованные типы DocFlavors

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

• Форматированный текст

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

  Тип MIME	Описание
  "text/plain"	Простой текст в наборе символов по умолчанию (US-ASCII)
  "text/plain; charset=xxx"	Простой текст в наборе символов xxx
  "text/html"	HyperText Markup Language в наборе символов по умолчанию (US-ASCII)
  "text/html; charset=xxx"	HyperText Markup Language в наборе символов 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 определяет формат данных печати. Класс представления doc flavor определяет интерфейс, методы которого DocPrintJob вызывает для определения содержимого, подлежащего печати — например, интерфейс рендерируемого изображения или интерфейс печатаемого Java-объекта. Тип MIME doc flavor — специальное значение "application/x-java-jvm-local-objectref" , указывающее, что клиент предоставит ссылку на Java-объект, реализующий интерфейс, имя которого указано в классе представления. Этот тип MIME — просто заполнитель; важным является класс представления данных печати.

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

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

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

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

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

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

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

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

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

Обоснование дизайна

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

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

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

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

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