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

public interface Doc

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

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

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

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

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

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

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