Пакет javax.print.attribute

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

API Java Print Service определяет набор стандартных классов атрибутов, созданных по образцу атрибутов версии 1.1 Internet Printing Protocol (IPP). Стандартные классы атрибутов находятся в подпакете javax.print.attribute.standard, чтобы концептуально отделить собственно классы атрибутов от общих средств, определённых в пакете javax.print.attribute.

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

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

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

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

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

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

• DocAttributeSet
• PrintRequestAttributeSet
• PrintJobAttributeSet
• PrintServiceAttributeSet

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

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

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

• HashDocAttributeSet
• HashPrintRequestAttributeSet,
• HashPrintJobAttributeSet,
• HashPrintServiceAttributeSet.

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

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

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

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

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

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

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

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

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