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

public interface Doc

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

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

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

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

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

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

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