Пакет 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.

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

Клиенту обычно необходимо предоставить более одной инструкции по обработке при отправке задания печати. Например, клиенту может потребоваться указать размер носителя A4 и альбомную ориентацию. Для отправки более чем одной инструкции по обработке клиент собирает атрибуты в набор атрибутов, который 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 предоставляет безопасный тип перечисления, в котором перечисленные значения представлены как одиночные объекты. Каждый одиночный объект перечисления является экземпляром класса перечисления, который оборачивает скрытое целое значение int.
• IntegerSyntax — это абстрактная синтаксическая структура для целочисленных атрибутов.
• TextSyntax — это абстрактная синтаксическая структура для текстовых атрибутов, и включает локаль, указывающую естественный язык текстовой строки.
• SetOfIntegerSyntax — это абстрактная синтаксическая структура для атрибутов, представляющих диапазон или множество целых чисел.
• ResolutionSyntax — это абстрактная синтаксическая структура для атрибутов, представляющих значения разрешения, такие как 600x300 точек на дюйм.
• 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 является финальным, чтобы гарантировать, что все подклассы атрибутов, определенные поставщиком, будут отображаться в той же категории. Каждый объект атрибута неизменяем после создания, чтобы ссылки на объекты атрибутов могли свободно передаваться. Для получения другого значения атрибута необходимо создать другой объект атрибута.

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

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

• определять новые значения, специфичные для поставщика, для любого стандартного атрибута, определенного в 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 являются примерами типичных и приемлемых исключений времени выполнения в таких случаях.