Класс DocFlavor

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

• Тип MIME. Это тип MIME (Multipurpose Internet Mail Extensions) (как определено в RFC 2045 и RFC 2046), который определяет, как интерпретируются данные печати. Кодировка символов текстовых данных должна быть предпочтительным именем IANA MIME, или каноническим именем, если предпочтительное имя не указано. Кроме того, могут быть распознаны некоторые исторические имена, поддерживаемые более ранними версиями платформы 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 — один из стандартных типов, указывающих, как интерпретировать последовательность символов или байтов. Список стандартных типов см. в Справочнике типов MIME от Internet Assigned Numbers Authority (IANA). Интерфейс 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 имеет кодировку символов по умолчанию, определяемую при запуске виртуальной машины и, как правило, зависит от кодировки символов и локали, используемых основной операционной системой. В распределенной среде нет гарантии, что две виртуальные машины используют одну и ту же кодировку по умолчанию. Таким образом, клиенты, которые хотят передавать данные текста платформенной кодировки с платформы хоста экземпляру Java Print Service, должны явно указывать кодировку и не полагаться на значения по умолчанию.

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

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

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

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

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

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

Предопределённые doc flavor

Экземпляр службы печати Java не обязан поддерживать следующие форматы данных печати и классы представления данных печати. Фактически, разработчик, использующий этот класс, никогда не должен предполагать, что определённая служба печати поддерживает типы документов, соответствующие этим предопределённым 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 может поддерживать любые другие doc flavor (или не поддерживать вообще) помимо вышеперечисленных обязательных, по усмотрению реализации.

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

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

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

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

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

Класс DocFlavor в пакете javax.print аналогичен классу DataFlavor. Класс DataFlavor не используется в API службы печати Java (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-типа. Таким образом, два doc flavor с MIME-типами, которые не идентичны, но эквивалентны (имеют одинаковый канонический вид), могут считаться равными.

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

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