Пакет javax.print.attribute

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

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

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

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

Вы можете печатать одни и те же данные печати в разное время, используя разные инструкции по обработке.
Например, вы можете напечатать презентацию слайдов на белом бумаге формата Letter, двухсторонней печати, сброшюрованной, в 20 копиях, чтобы сделать раздаточные материалы для выступления; и вы могли бы напечатать ту же презентацию слайдов на прозрачных листах формата Letter, односторонней печати, в одной копии, чтобы сделать фактические слайды для выступления.
Вы можете использовать одни и те же инструкции по обработке в разное время для печати различных данных. Например, вы можете установить свои стандартные инструкции по обработке: бумага формата 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 требует, чтобы:

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

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

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

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

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

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

Все эти классы расширяют 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 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 являются примерами типичных и приемлемых исключений во время выполнения в таких случаях.

С момента:: 1.4

Интерфейс	Описание
Attribute	Интерфейс `Attribute` является базовым интерфейсом, реализуемым любым и каждым классом атрибута печати, чтобы указать, что класс представляет атрибут печати.
AttributeSet	Интерфейс `AttributeSet` определяет интерфейс для набора атрибутов печати.
DocAttribute	Интерфейс `DocAttribute` — это интерфейс разметки, который класс атрибута печати реализует для обозначения того, что атрибут обозначает настройку для документа.
DocAttributeSet	Интерфейс `DocAttributeSet` определяет интерфейс для набора атрибутов документа, т. е. атрибутов печати, которые реализуют интерфейс `DocAttribute`.
PrintJobAttribute	`PrintJobAttribute` — это интерфейс разметки, который класс атрибута печати реализует для обозначения того, что атрибут описывает состояние задания печати или какую-либо другую характеристику задания печати.
PrintJobAttributeSet	Интерфейс `PrintJobAttributeSet` определяет интерфейс для набора атрибутов задания печати, т. е. атрибутов печати, которые реализуют интерфейс `PrintJobAttribute`.
PrintRequestAttribute	Интерфейс `PrintRequestAttribute` — это интерфейс разметки, который класс атрибута печати реализует для обозначения того, что атрибут обозначает запрошенную настройку для задания печати.
PrintRequestAttributeSet	Интерфейс `PrintRequestAttributeSet` определяет интерфейс для набора атрибутов запроса на печать, т. е. атрибутов печати, которые реализуют интерфейс `PrintRequestAttribute`.
PrintServiceAttribute	Интерфейс `PrintServiceAttribute` — это интерфейс разметки, который класс атрибута печати реализует для обозначения того, что атрибут описывает состояние службы печати или какую-либо другую характеристику службы печати.
PrintServiceAttributeSet	Интерфейс `PrintServiceAttributeSet` определяет интерфейс для набора атрибутов задания печати, т. е. атрибутов печати, которые реализуют интерфейс `PrintServiceAttribute`.
SupportedValuesAttribute	Интерфейс `SupportedValuesAttribute` — это интерфейс разметки, который класс атрибута печати реализует для обозначения того, что атрибут описывает поддерживаемые значения для другого атрибута.

Класс	Описание
AttributeSetUtilities	Класс `AttributeSetUtilities` предоставляет статические методы для обработки `AttributeSets`.
DateTimeSyntax	Класс `DateTimeSyntax` является абстрактным базовым классом, предоставляющим общее реализацию всех атрибутов, значение которых является датой и временем.
EnumSyntax	Класс `EnumSyntax` является абстрактным базовым классом, предоставляющим общую реализацию всех объектов "безопасного перечисления типов".
HashAttributeSet	Класс `HashAttributeSet` предоставляет реализацию `AttributeSet` с характеристиками хеш-таблицы.
HashDocAttributeSet	Класс `HashDocAttributeSet` предоставляет набор атрибутов, который наследует свою реализацию от класса `HashAttributeSet` и соблюдает семантические ограничения интерфейса `DocAttributeSet`.
HashPrintJobAttributeSet	Класс `HashPrintJobAttributeSet` предоставляет набор атрибутов, который наследует свою реализацию от класса `HashAttributeSet` и соблюдает семантические ограничения интерфейса `PrintJobAttributeSet`.
HashPrintRequestAttributeSet	Класс `HashPrintRequestAttributeSet` наследует свою реализацию от класса `HashAttributeSet` и соблюдает семантические ограничения интерфейса `PrintRequestAttributeSet`.
HashPrintServiceAttributeSet	Класс `HashPrintServiceAttributeSet` предоставляет набор атрибутов, который наследует свою реализацию от класса `HashAttributeSet` и соблюдает семантические ограничения интерфейса `PrintServiceAttributeSet`.
IntegerSyntax	Класс `IntegerSyntax` является абстрактным базовым классом, предоставляющим общую реализацию всех атрибутов с целочисленными значениями.
ResolutionSyntax	Класс `ResolutionSyntax` является абстрактным базовым классом, предоставляющим общую реализацию всех атрибутов, обозначающих разрешение принтера.
SetOfIntegerSyntax	Класс `SetOfIntegerSyntax` является абстрактным базовым классом, предоставляющим общую реализацию всех атрибутов, значением которых является множество неотрицательных целых чисел.
Size2DSyntax	Класс `Size2DSyntax` является абстрактным базовым классом, предоставляющим общую реализацию всех атрибутов, обозначающих размер в двух измерениях.
TextSyntax	Класс `TextSyntax` является абстрактным базовым классом, предоставляющим общую реализацию всех атрибутов, значением которых является строка.
URISyntax	Класс `URISyntax` является абстрактным базовым классом, предоставляющим общую реализацию всех атрибутов, значением которых является идентификатор универсального ресурса (URI).

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

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.desktop/javax/print/attribute/package-summary.html