Класс 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 типа документа — один из стандартных типов медиа, определяющий, как интерпретировать последовательность символов или байтов. Список стандартных типов медиа см. в каталоге типов медиа на сайте Internet Assigned Numbers Authority (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 имеет кодировку символов по умолчанию, определяемую при запуске виртуальной машины, и обычно зависит от локали и кодировки, используемых основной операционной системой. В распределенной среде нет гарантии, что две VM используют одну и ту же кодировку по умолчанию. Таким образом, клиенты, которые хотят передавать данные платформенного текста из кодировки хост-платформы в экземпляр Java Print Service, должны явно объявлять кодировку и не полагаться на значения по умолчанию.

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

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

Рекомендуемые DocFlavor

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

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

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

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

• Документы предварительно отформатированного языка описания страницы (PDL)

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

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

• Предварительно отформатированные изображения

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

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

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

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

  Принтер сам решает, как интерпретировать данные печати; способ работы этого "автоматического определения" зависит от реализации. В общем случае данные предварительно отформатированной печати с автоматическим определением формата предоставляются в классе представления, ориентированном на байты (массив байтов, поток байтов, URL).

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

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

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

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

Поля

hostEncoding

public static final String hostEncoding

Строка, представляющая кодировку хостовой операционной системы. Она будет следовать соглашениям, описанным в RFC 2278: Процедуры регистрации наборов символов IANA, за исключением случаев, когда для совместимости с предыдущими версиями платформы Java возвращаются исторические имена. Значение, возвращаемое методом, допустимо только для виртуальной машины, которая его возвращает, для использования в DocFlavor. Это кодировка символов для всех предварительно определённых DocFlavors "HOST" в выполняемой виртуальной машине.

Конструкторы

DocFlavor

public DocFlavor(String mimeType,
                 String className)

Создаёт новый объект типа doc flavor из заданного типа MIME и имени класса представления. Указанный тип MIME преобразуется в каноническую форму и сохраняется во внутренней памяти.

Параметры:

mimeType - Строка типа MIME.

className - Полное имя класса представления.

Исключения:

NullPointerException - (исключение, не проверяемое) Бросается, если mimeType равно null или className равно null.

IllegalArgumentException - (исключение, не проверяемое) Бросается, если mimeType не соответствует синтаксису строки типа MIME.

Методы

getMimeType

public String getMimeType()

Возвращает строку типа MIME объекта doc flavor, основанную на канонической форме. Каждое значение параметра заключено в кавычки.

Возвращает:

тип MIME

getMediaType

public String getMediaType()

Возвращает тип носителя объекта doc flavor (из типа MIME).

Возвращает:

тип носителя

getMediaSubtype

public String getMediaSubtype()

Возвращает подтип носителя объекта doc flavor (из типа MIME).

Возвращает:

подтип носителя

getParameter

public String getParameter(String paramName)

Параметры:

paramName - имя параметра. Это имя внутренне преобразуется в канонический нижний регистр перед выполнением сопоставления.

Возвращает:

Строка, представляющая параметр MIME, или null, если этот параметр отсутствует в строке типа MIME.

Исключения:

NullPointerException - если paramName равно null.

getRepresentationClassName

public String getRepresentationClassName()

Возвращает имя класса представления этого объекта doc flavor.

Возвращает:

имя класса представления.

toString

public String toString()

Преобразует этот объект DocFlavor в строку.

Переопределяет:

toString в классе Object

Возвращает:

Строку типа MIME, основанную на канонической форме. К строке типа MIME добавляется параметр "class=" для указания имени класса представления.

hashCode

public int hashCode()

Возвращает хеш-код для этого объекта doc flavor.

Переопределяет:

hashCode в классе Object

Возвращает:

значение хеш-кода для этого объекта.

См. также:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

equals

public boolean equals(Object obj)

Определяет, равен ли этот объект doc flavor заданному объекту. Два объекта равны, если заданный объект не равен null, является экземпляром DocFlavor, имеет тип MIME, эквивалентный типу MIME этого объекта doc flavor (то есть типы MIME имеют одинаковый тип носителя, подтип носителя и параметры), и имеет то же имя класса представления, что и этот объект doc flavor. Таким образом, если два объекта doc flavor имеют одинаковые типы MIME, за исключением комментариев, они считаются равными. Однако два объекта doc flavor с типами MIME "text/plain" и "text/plain; charset=US-ASCII" не считаются равными, даже если они представляют тот же тип носителя (потому что значение по умолчанию для кодировки символов для простого текста — US-ASCII).

Переопределяет:

equals в классе Object

Параметры:

obj - Объект для проверки.

Возвращает:

True, если этот объект doc flavor равен obj, иначе false.

См. также:

Object.hashCode(), HashMap