Документация интерфейса

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

• Определить формат или «тип Doc» (класс DocFlavor), в котором доступны данные для печати. Тип Doc определяет формат данных для печати (тип MIME) и класс представления объекта, из которого берутся данные для печати.
• Получить объект представления данных для печати, который является экземпляром класса представления типа Doc. Затем задание печати может получить фактические данные печати из объекта представления.
• Получить атрибуты печати, которые определяют дополнительные характеристики Doc или указывают инструкции обработки, которые необходимо применить к Doc. Атрибуты печати определены в пакете javax.print.attribute. Doc возвращает свои атрибуты печати, хранящиеся в javax.print.attribute.DocAttributeSet.

Каждый метод в реализации интерфейса Doc разрешено всегда возвращать один и тот же объект каждый раз при вызове метода. Это имеет последствия для задания печати или другого вызывающего объекта Doc, чей объект представления данных для печати «потребляет» данные для печати при получении данных вызывающим объектом, например, объект представления данных для печати, который является потоком. После того, как задание печати вызвало getPrintData() и получило поток, все дальнейшие вызовы getPrintData() будут возвращать тот же объект потока, чтение из которого, возможно, уже в процессе, а не новый объект потока, который будет повторно считывать данные для печати с начала. Указание объекту Doc такого поведения упрощает реализацию объектов Doc и оправдано тем, что конкретный Doc предназначен для передачи данных для печати только одному заданию печати, а не нескольким разным заданиям печати. (Чтобы передать одни и те же данные для печати нескольким различным заданиям печати, нужно создать несколько разных объектов Doc поверх того же источника данных для печати.)

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

Нет ограничений на количество клиентских потоков, которые могут одновременно обращаться к одному и тому же Doc. Поэтому все реализации интерфейса Doc должны быть спроектированы для многопоточной безопасности.

Однако может быть только один потребитель данных для печати, полученных от Doc.

Если данные для печати получаются от клиента в виде потока, вызывая методы Doc getReaderForText() или getStreamForBytes(), или потому что источник данных для печати уже является InputStream или Reader, то служба печати должна всегда закрывать эти потоки для клиента при всех завершающих условиях задания. С следующим замечанием. Если данные для печати сами по себе являются потоком, служба всегда закроет его. Если данные для печати — это что-то иное, что можно запросить как поток, служба закроет поток только в том случае, если она получила поток до завершения работы. То есть, просто потому, что служба печати может запросить данные в виде потока, не означает, что она это сделает, с тем подразумеванием, что реализаторы Doc, которые полагаются на службу для их закрытия, должны создавать такие потоки только в ответ на запрос от службы.

Методы

getDocFlavor

DocFlavor getDocFlavor()

Определяет тип Doc, в котором этот объект Doc предоставит свой фрагмент данных для печати.

Возвращает:

Тип Doc.

getPrintData

Object getPrintData()
             throws IOException

Получает объект представления данных для печати, который содержит фрагмент данных для печати этого объекта Doc в формате, соответствующем поддерживаемому типу Doc. Метод getPrintData() возвращает экземпляр класса представления, имя которого задано getDocFlavor().getRepresentationClassName(), и возвращаемое значение можно привести из класса Object к этому классу представления.

Возвращает:

Объект представления данных для печати.

Выбрасывает:

IOException - Выбрасывается, если класс представления — поток, и при построении потока произошла ошибка ввода-вывода.

getAttributes

DocAttributeSet getAttributes()

Получает набор атрибутов печати для этого объекта Doc. Если возвращаемый набор атрибутов содержит экземпляр конкретного атрибута X, принтер должен использовать значение этого атрибута для этого Doc, переопределяя любое значение атрибута X в наборе атрибутов задания. Если возвращаемый набор атрибутов не содержит экземпляр конкретного атрибута X или возвращается null, принтер должен обратиться к набору атрибутов задания, чтобы получить значение атрибута X, и если оно там не найдено, принтер должен использовать зависимое от реализации значение по умолчанию. Возвращаемый набор атрибутов неизменяем.

Возвращает:

Неизменяемый набор атрибутов печати для этого Doc или null, чтобы получить все значения атрибутов из набора атрибутов задания.

getReaderForText

Reader getReaderForText()
                 throws IOException

Возвращает:

Reader для чтения символов данных для печати из этого объекта Doc. Если ридер не может быть предоставлен, потому что этот объект Doc не соответствует указанным выше критериям, возвращается null.

Выбрасывает:

IOException - Выбрасывается, если при создании ридера произошла ошибка ввода-вывода.

getStreamForBytes

InputStream getStreamForBytes()
                       throws IOException

Возвращает:

Входной поток для чтения байтов данных для печати из этого объекта Doc. Если входной поток не может быть предоставлен, потому что этот объект Doc не соответствует указанным выше критериям, возвращается null.

Выбрасывает:

IOException - Выбрасывается, если при создании входного потока произошла ошибка ввода-вывода.