Пакет 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 Print Service включает большое количество различных категорий атрибутов, существует всего несколько различных типов значений атрибутов. Большинство атрибутов могут быть представлены небольшим количеством типов данных, таких как: целые значения, целые диапазоны, текст или перечисление целых значений. Тип значения атрибута, который принимает категория, называется абстрактной синтаксической конструкцией атрибута. Для обеспечения согласованности и сокращения дублирования кода, API Java Print Service определяет классы абстрактной синтаксической конструкции для представления каждой абстрактной синтаксической конструкции, и эти классы используются в качестве родительских классов стандартных атрибутов, когда это возможно. Классы абстрактной синтаксической конструкции:

• EnumSyntax предоставляет безопасное перечисление типов, в котором перечисленные значения представлены как одиночные объекты. Каждый одиночный элемент перечисления является экземпляром класса перечисления, который оборачивает скрытое целое значение int.
• 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 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 являются примерами типичных и приемлемых исключений во время выполнения в таких случаях.