Пакет javax.print.attribute

Предоставляет классы и интерфейсы, описывающие типы атрибутов службы печати Java и способы их объединения в наборы атрибутов.

Что такое атрибут?

При настройке задания печати клиент задаёт две вещи: данные печати и инструкции по обработке. Данные печати — это фактическое содержимое, подлежащее печати. Инструкции по обработке сообщают принтеру, как печатать данные, например: какой носитель использовать, сколько копий печатать и печатать ли на одной или обеих сторонах листа. Клиент задаёт эти инструкции по обработке с помощью определений атрибутов API службы печати Java.

Данные печати и инструкции по обработке являются отдельными сущностями. Это означает, что:

• Вы можете печатать одни и те же данные печати в разное время с использованием разных инструкций по обработке.
  Например, вы можете напечатать презентацию слайдов на белой бумаге формата US Letter, двустороннюю, скреплённую степлером, в 20 копиях, чтобы сделать раздаточные материалы для доклада; и вы можете напечатать ту же презентацию слайдов на прозрачных плёнках формата US Letter, одностороннюю, в одной копии, чтобы сделать сами слайды для доклада.
• Вы можете использовать одни и те же инструкции по обработке в разное время для печати разных данных. Например, вы можете установить свои стандартные инструкции по обработке: бумага формата US Letter, двусторонняя, скреплённая степлером. При каждой печати задания оно будет напечатано с этими параметрами, если вы их явно не переопределите.

Инструкция по обработке не определяет, как задание печати обрабатывает запрос; каждая инструкция по обработке — это только описание результатов задания печати. Задание печати определяет способ достижения результатов, указанных в инструкциях по обработке. Представление инструкций по обработке как описательных элементов обеспечивает большую гибкость при реализации заданий печати.

Категории атрибутов и значения

Каждый принтер обладает набором возможностей, таких как печать на различных размерах бумаги или печать нескольких копий. Каждая из возможностей имеет диапазон значений. Например, возможность ориентации принтера может иметь такой диапазон значений: [альбомная, книжная]. Для каждого запроса на печать возможность устанавливается в одно из этих значений. API службы печати Java использует термин категория атрибута для обозначения возможности принтера и термин значение атрибута для обозначения значения возможности.

В API службы печати Java категория атрибута представлена классом Java, реализующим интерфейс Attribute. Значения атрибутов являются экземплярами такого класса или одного из его подклассов. Например, для указания количества копий приложение создаёт экземпляр класса Copies с количеством требуемых копий и использует экземпляр Copies в качестве части запроса на печать. В этом случае, класс Copies представляет категорию атрибута, а экземпляр Copies — значение атрибута.

Роли атрибутов

При отправке задания печати на принтер клиент предоставляет атрибуты, описывающие характеристики данных печати, например, имя документа, и как данные печати должны быть напечатаны, например, двусторонние, пять копий. Если задание печати состоит из нескольких фрагментов данных печати, разные фрагменты могут иметь разные инструкции по обработке, например, носитель размером 8 x 11 дюймов для первого документа и носитель размером 11 x 17 дюймов для другого документа.

После того, как принтер начинает обработку задания печати, становится доступна дополнительная информация о задании, которая может включать: состояние задания (например, завершён или в очереди) и количество напечатанных страниц. Эти элементы информации также являются атрибутами. Атрибуты также могут описывать сам принтер, например: имя принтера, местоположение принтера и количество заданий в очереди.

API службы печати Java определяет эти различные типы атрибутов с помощью пяти подинтерфейсов Attribute:

• DocAttribute определяет характеристику отдельного документа и параметры печати для применения к отдельным документам.
• PrintRequestAttribute определяет параметр, применяемый ко всему заданию печати и ко всем документам в задании печати.
• PrintJobAttribute сообщает о состоянии задания печати.
• PrintServiceAttribute сообщает о состоянии службы печати.
• SupportedValuesAttribute указывает поддерживаемые значения для другого атрибута.

Каждый класс атрибута реализует один или несколько из этих подинтерфейсов тегов для указания места использования атрибута в API. Если класс атрибута реализует несколько подинтерфейсов тегов, атрибут может использоваться в нескольких контекстах. Например, атрибут носителя может применяться к одному документу в задании печати в качестве DocAttribute или ко всему заданию печати в качестве PrintRequestAttribute. Некоторые атрибуты низкого уровня никогда не используются самостоятельно, но всегда агрегируются в атрибуты более высокого уровня. Эти классы атрибутов низкого уровня реализуют только интерфейс Attribute, а не какие-либо из подинтерфейсов тегов.

API службы печати Java определяет группу стандартных классов атрибутов, основанных на атрибутах протокола печати по Интернету (IPP) версии 1.1. Стандартные классы атрибутов находятся в подпакете javax.print.attribute.standard для концептуального отделения фактических классов атрибутов от общего аппарата, определённого в пакете javax.print.attribute.

Наборы атрибутов

Клиент обычно должен предоставить более одной инструкции по обработке при отправке задания печати. Например, клиенту может потребоваться указать размер носителя А4 и альбомную ориентацию. Чтобы отправить более одной инструкции по обработке, клиент собирает атрибуты в набор атрибутов, который API службы печати Java представляет интерфейсом AttributeSet.

Интерфейс AttributeSet аналогичен интерфейсу Map: он предоставляет отображение ключа к значениям, в котором каждый ключ уникален и может содержать не более одного значения. Однако, интерфейс AttributeSet разработан для специфических потребностей API службы печати Java. Набор AttributeSet требует, чтобы:

1. Каждый ключ в наборе AttributeSet соответствует категории, и значение ключа может быть только одним из значений атрибутов, которые относятся к категории, представленной ключом. Таким образом, в отличие от Map, набор AttributeSet ограничивает возможные значения ключа: категория атрибута не может быть установлена в значение атрибута, которое не относится к этой категории.
2. Два атрибута из одной категории не могут существовать в одном наборе. Например, набор атрибутов не должен содержать как атрибут «односторонняя печать», так и атрибут «двусторонняя печать», поскольку эти два атрибута дают принтеру противоречивые инструкции.
3. В набор могут добавляться только атрибуты, реализующие интерфейс Attribute.

Пакет javax.print.attribute включает HashAttributeSet в качестве конкретной реализации интерфейса набора атрибутов. HashAttributeSet предоставляет набор атрибутов, основанный на хэш-таблице. Вы можете использовать эту реализацию или предоставить собственную реализацию интерфейса AttributeSet.

API службы печати Java предоставляет четыре специализации набора атрибутов, которые ограничены содержанием только одного из четырёх видов атрибутов, как обсуждалось в разделе Роли атрибутов:

• DocAttributeSet
• PrintRequestAttributeSet
• PrintJobAttributeSet
• PrintServiceAttributeSet

Обратите внимание, что здесь перечислены только четыре типа наборов атрибутов, но существует пять типов атрибутов. Интерфейс SupportedValuesAttribute обозначает атрибут, который предоставляет поддерживаемые значения для другого атрибута. Атрибуты поддерживаемых значений никогда не агрегируются в наборы атрибутов, поэтому для них не определён подинтерфейс набора атрибутов.

В некоторых контекстах набор атрибутов является только для чтения, что означает, что клиент может только просматривать содержимое набора атрибутов, но не изменять его. В других контекстах набор атрибутов является для чтения и записи, что означает, что клиент может как просматривать, так и изменять содержимое набора атрибутов. Для набора атрибутов только для чтения вызов мутирующей операции вызовет UnmodifiableSetException.

Пакет javax.print.attribute включает по одной конкретной реализации каждого из подинтерфейсов набора атрибутов:

• HashDocAttributeSet
• HashPrintRequestAttributeSet,
• HashPrintJobAttributeSet,
• HashPrintServiceAttributeSet.

Все эти классы расширяют HashAttributeSet и накладывают ограничение, что набор атрибутов должен содержать только соответствующий тип атрибута.

Проектирование класса атрибута

Значение атрибута — это небольшой атомарный элемент данных, такой как целое число или перечисление. API службы печати Java не использует примитивные типы данных, такие как int, для представления значений атрибутов по следующим причинам:

• Примитивные типы данных не безопасны с точки зрения типов. Например, компилятор не должен допускать использования значения атрибута «копии» для атрибута «стороны».
• Некоторые атрибуты должны представляться как запись нескольких значений. Примером является разрешение принтера, которое требует двух чисел, таких как 600 и 300, представляющих 600 x 300 точек на дюйм.

Для обеспечения безопасности типов и единообразного представления всех атрибутов API службы печати Java определяет каждую категорию атрибута как класс, например, класс Copies, класс Sides и класс PrinterResolution. Каждый класс атрибута оборачивает один или несколько примитивных элементов данных, содержащих значение атрибута. Операции с наборами атрибутов часто сравнивают объекты категории атрибутов при добавлении атрибутов, поиске существующих атрибутов той же категории и поиске атрибута по его категории. Поскольку категория атрибута представлена классом, быстрые сравнения значений атрибутов можно выполнять с помощью метода Class.equals.

Несмотря на то, что API службы печати Java включает большое количество различных категорий атрибутов, существует всего несколько различных типов значений атрибутов. Большинство атрибутов можно представить небольшим количеством типов данных, таких как: целочисленные значения, целочисленные диапазоны, текст или перечисление целочисленных значений. Тип значения атрибута, который принимает категория, называется абстрактной синтаксической структурой атрибута. Для обеспечения согласованности и сокращения дублирования кода API службы печати Java определяет классы абстрактной синтаксической структуры для представления каждой абстрактной синтаксической структуры, и эти классы используются в качестве родительских классов стандартных атрибутов, когда это возможно. Классы абстрактной синтаксической структуры:

• EnumSyntax предоставляет безопасный по типу перечисление, в котором значения перечисления представлены как одиночные объекты. Каждый одиночный объект перечисления является экземпляром класса перечисления, который оборачивает скрытое целое число.
• IntegerSyntax — это абстрактная синтаксическая конструкция для атрибутов с целочисленными значениями.
• TextSyntax — это абстрактная синтаксическая конструкция для атрибутов со строковыми значениями, и включает локаль, определяющую естественный язык текстовой строки.
• SetOfIntegerSyntax — это абстрактная синтаксическая конструкция для атрибутов, представляющих диапазон или множество целых чисел.
• ResolutionSyntax — это абстрактная синтаксическая конструкция для атрибутов, представляющих значения разрешения, такие как 600x300 dpi.
• Size2DSyntax — это абстрактная синтаксическая конструкция для атрибутов, представляющих двумерный размер, такой как размер бумаги 8,5 x 11 дюймов.
• DateTimeSyntax — это абстрактная синтаксическая конструкция для атрибутов, значением которых является дата и время.
• URISyntax — это абстрактная синтаксическая конструкция для атрибутов, значением которых является Указатель на универсальный ресурс.

Классы абстрактного синтаксиса независимы от атрибутов, которые их используют. На самом деле, приложения, не связанные с печатью, могут использовать классы абстрактного синтаксиса. Хотя большинство стандартных классов атрибутов расширяют один из классов абстрактного синтаксиса, ни один класс атрибута не обязан расширять один из этих классов. Классы абстрактного синтаксиса просто предоставляют удобную реализацию, которую могут использовать многие классы атрибутов.

Каждый класс атрибута реализует интерфейс Attribute, непосредственно или косвенно, чтобы отметить его как атрибут печати. Класс атрибута, который может появляться в ограниченных наборах атрибутов в определенных контекстах, также реализует один или несколько подинтерфейсов интерфейса Attribute. Большинство классов атрибутов также расширяют соответствующий класс абстрактного синтаксиса, чтобы получить реализацию. Рассмотрим класс атрибута Sides:

 public class Sides
     extends EnumSyntax
     implements DocAttribute, PrintRequestAttribute, PrintJobAttribute
 {
     public final Object getCategory()
     {
         return Sides.class;
     }
 ...
 }
 

Поскольку каждый класс атрибута реализует Attribute, каждый класс атрибута должен предоставить реализацию метода getCategory, который возвращает категорию атрибута. В случае Sides, метод getCategory возвращает Sides.class. Метод getCategory является final, чтобы гарантировать, что все подклассы атрибута, определенные поставщиком, появляются в той же категории. Каждый объект атрибута является неизменяемым после создания, чтобы ссылки на объекты атрибутов можно было свободно передавать. Чтобы получить другое значение атрибута, создайте другой объект атрибута.

Поставщики атрибутов

API службы печати Java разработано таким образом, чтобы поставщики могли:

• определять новые значения, специфичные для поставщика, для любого стандартного атрибута, определенного в javax.print.attribute.standard.
• определять новые категории атрибутов, представляющие собственные возможности принтера поставщика, которые еще не поддерживаются стандартными атрибутами.

Чтобы определить новое значение для атрибута, клиент может создавать экземпляры таких атрибутов с произвольными значениями во время выполнения. Однако атрибут перечисления, использующий класс абстрактного синтаксиса EnumSyntax, определяет все возможные значения атрибутов во время компиляции как одиночные экземпляры класса атрибута. Это означает, что новые значения перечисления не могут быть созданы во время выполнения. Чтобы определить новые значения, специфичные для поставщика, для стандартного атрибута перечисления, поставщик должен определить новый класс атрибута, определяющий новые одиночные экземпляры. Чтобы гарантировать, что новые значения атрибутов попадают в ту же категорию, что и стандартные значения атрибутов, новый класс атрибута должен быть подклассом стандартного класса атрибута.

Чтобы определить новую категорию атрибутов, поставщик определяет новый класс атрибута. Этот класс атрибута, как и стандартные классы атрибутов, реализует Attribute или один из его подинтерфейсов и расширяет класс абстрактного синтаксиса. Поставщик может использовать существующий класс абстрактного синтаксиса или определить новый. Новый атрибут, определенный поставщиком, может использоваться везде, где используется Attribute, например, в AttributeSet.

Использование атрибутов

Типичное приложение печати использует PrintRequestAttributeSet, так как атрибуты запроса печати — это те типы атрибутов, которые обычно указывает клиент. Этот пример демонстрирует создание набора атрибутов запроса печати и поиск принтера, который может распечатать документ в соответствии с указанными атрибутами:

 FileInputStream psStream;
 try {
     psstream = new FileInputStream("file.ps");
 } catch (FileNotFoundException ffne) {
 }
 if (psstream == null) {
     return;
 }
 //Set the document type. See the DocFlavor documentation for
 //more information.
 DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
 Doc myDoc = new SimpleDoc(pstream, psInFormat, null);
 PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
 aset.add(new Copies(5));
 aset.add(MediaSize.A4);
 aset.add(Sides.DUPLEX);
 PrintService[] services =
     PrintServiceLookup.lookupPrintServices(psInFormat, aset);
 if (services.length > 0) {
     DocPrintJob job = services[0].createPrintJob();
     try {
         job.print(myDoc, aset);
     } catch (PrintException pe) {}
 }
 

Обратите внимание: в API javax.print, ссылка на параметр null в методах некорректна, если не документировано явным образом в методе, что она имеет осмысленное толкование. Использование в противном случае является неправильным кодированием и может привести к исключению во время выполнения — как сразу, так и в какой-то момент в будущем. IllegalArgumentException и NullPointerException являются примерами типичных и допустимых исключений во время выполнения для таких случаев.