Класс DocFlavor

Все реализованные интерфейсы:
Serializable, Cloneable
Непосредственные известные подклассы:
DocFlavor.BYTE_ARRAY, DocFlavor.CHAR_ARRAY, DocFlavor.INPUT_STREAM, DocFlavor.READER, DocFlavor.SERVICE_FORMATTED, DocFlavor.STRING, DocFlavor.URL 
public class DocFlavor
extends Object
implements Serializable, Cloneable

Класс 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 — это один из стандартных типов носителей, указывающий, как интерпретировать последовательность символов или байтов. Список стандартных типов носителей см. в Справочнике по типам носителей Инициативы по присвоению имен в Интернете (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 важно правильно указать кодировку. Разработчики, работающие в языках среды locale Английского региона, должны быть особенно внимательны к этому, так как кодировка их платформы соответствует кодировке mime по умолчанию. По этому совпадению, этот конкретный случай может работать без указания кодировки данных платформы.

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

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

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

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

API Java Print Service не определяет никаких обязательных поддерживаемых DocFlavors. Однако здесь приведены некоторые примеры типов MIME, которые экземпляр Java Print Service может поддерживать для данных печати с форматированием клиента. Вложенные классы внутри класса DocFlavor объявляют предварительно определенные статические константные объекты DocFlavor для этих примеров типов doc; конструктор класса DocFlavor может использоваться для создания произвольного типа doc.
Тип 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" Документ языка управления принтером
    В общем случае данные печати форматированного PDL предоставляются в классе представления, ориентированном на байты (массив байтов, InputStream, URL).
  • Предварительно отформатированные изображения
    Тип MIME Описание
    "image/gif" Изображение формата Graphics Interchange Format
    "image/jpeg" Изображение формата Joint Photographic Experts Group
    "image/png" Изображение формата Portable Network Graphics
    В общем случае данные печати предварительно отформатированного изображения предоставляются в классе представления, ориентированном на байты (массив байтов, InputStream, URL).
  • Предварительно отформатированные данные печати с автоматическим определением
    Тип MIME Описание
    "application/octet-stream" Формат данных печати не указан (только поток октетов)
    Принтер определяет, как интерпретировать данные печати; способ работы этого «автоматического определения» зависит от реализации. В общем случае данные печати предварительно отформатированных данных с автоматическим определением предоставляются в классе представления, ориентированном на байты (массив байтов, InputStream, URL).

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

Для данных печати с форматированием сервиса экземпляр Java Print Service определяет формат данных печати. Класс представления типа doc обозначает интерфейс, методы которого вызывает DocPrintJob для определения содержимого для печати — например, интерфейс рендерируемого изображения или интерфейс Java printable. Тип MIME типа doc — специальное значение "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) означает "перейти к колонке 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-типа. Таким образом, два типа документов с MIME-типами, которые не идентичны, но эквивалентны (которые имеют одинаковый канонический формат), могут считаться равными.
  • Тип носителя, подтип носителя и параметры сохраняются, но все комментарии и пробелы удаляются.
  • Тип носителя, подтип носителя и имена параметров преобразуются в нижний регистр.
  • Значения параметров сохраняют свой исходный регистр, за исключением значения параметра charset для типа носителя текста, которое преобразуется в нижний регистр.
  • Знаки кавычек вокруг значений параметров удаляются.
  • Знаки кавычек обратной косой черты внутри значений параметров удаляются.
  • Параметры упорядочиваются по возрастанию имени параметра.
Сериализованное представление класса DocFlavor также содержит полностью квалифицированное имя класса класса представления (объект String) вместо самого класса представления (объект Class). Это позволяет клиенту просмотреть типы документов, поддерживаемые экземпляром службы печати Java, не загружая классы представления, что может быть проблематично для клиентов с ограниченными ресурсами.
См. также:
Сериализованная форма

Вложенные классы

Модификатор и тип Класс Описание
static class  DocFlavor.BYTE_ARRAY

Класс DocFlavor.BYTE_ARRAY предоставляет предопределённые статические константы DocFlavor объекты для примеров типов документов, использующих массив байтов (byte[]) в качестве класса представления данных печати.
static class  DocFlavor.CHAR_ARRAY

Класс DocFlavor.CHAR_ARRAY предоставляет предопределённые статические константы DocFlavor объекты для примеров типов документов, использующих массив символов (char[]) в качестве класса представления данных печати.
static class  DocFlavor.INPUT_STREAM

Класс DocFlavor.INPUT_STREAM предоставляет предопределённые статические константы DocFlavor объекты для примеров типов документов, использующих поток байтов (java.io.InputStream) в качестве класса представления данных печати.
static class  DocFlavor.READER

Класс DocFlavor.READER предоставляет предопределённые статические константы DocFlavor объекты для примеров типов документов, использующих поток символов (java.io.Reader) в качестве класса представления данных печати.
static class  DocFlavor.SERVICE_FORMATTED

Класс DocFlavor.SERVICE_FORMATTED предоставляет предопределённые статические константы DocFlavor объекты для примеров типов документов для данных печати в формате службы.
static class  DocFlavor.STRING

Класс DocFlavor.STRING предоставляет предопределённые статические константы DocFlavor объекты для примеров типов документов, использующих строку (java.lang.String) в качестве класса представления данных печати.
static class  DocFlavor.URL

Класс DocFlavor.URL предоставляет предопределённые статические константы DocFlavor объекты.

Поля

Модификатор и тип Поле Описание
static String hostEncoding

Строка, представляющая кодировку операционной системы хоста.

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

Конструктор Описание
DocFlavor​(String mimeType, String className)

Создаёт новый объект типа документа из заданного MIME-типа и имени класса представления.

Методы

Модификатор и тип Метод Описание
boolean equals​(Object obj)

Определяет, равен ли этот объект типа документа данному объекту.
String getMediaSubtype()

Возвращает подтип носителя этого объекта типа документа (из MIME-типа).
String getMediaType()

Возвращает тип носителя этого объекта типа документа (из MIME-типа).
String getMimeType()

Возвращает строку MIME-типа этого объекта типа документа, основанную на каноническом формате.
String getParameter​(String paramName)

Возвращает String , представляющий параметр MIME.
String getRepresentationClassName()

Возвращает имя класса представления этого объекта типа документа.
int hashCode()

Возвращает хэш-код для этого объекта типа документа.
String toString()

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

Методы, объявленные в классе java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Поля

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 или 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)

Возвращает строку, представляющую параметр MIME. Типы MIME могут содержать параметры, которые обычно являются необязательными. Кодировка символов для текстовых типов — это полезный пример. Этот метод возвращает значение указанного параметра, если он был указан в типе MIME для этого объекта.

Параметры:
paramName - имя параметра. Это имя внутренне преобразуется в каноническую форму с нижним регистром перед выполнением сопоставления.
Возвращает:
строка, представляющая параметр MIME, или null если этот параметр отсутствует в строке типа MIME
Исключения:
NullPointerException - если paramName null

getRepresentationClassName

public String getRepresentationClassName()

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

Возвращает:
имя класса представления

toString

public String toString()

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

Переопределяет:
toString в классе Object
Возвращает:
строку типа MIME, основанную на канонической форме. Каждое значение параметра заключено в кавычки. Параметр "class=" добавляется к строке типа MIME для указания имени класса представления.

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 - Object для проверки
Возвращает:
true если этот объект doc flavor равен obj, false в противном случае
См. также:
Object.hashCode(), HashMap

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.desktop/javax/print/DocFlavor.html

Spec-Zone .ru
спецификации, руководства, описания, API