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

public interface Doc

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

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

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

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

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

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

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