Пакет javax.print.attribute

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

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

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

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

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

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

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

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

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

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

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

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

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, представляющих 600x300 точек на дюйм.

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