Java Print Service API User Guide: 2

Attribute Sets

A client usually needs to provide more than one processing instruction when submitting a print job. For example, the client might need to specify an A4 media and a landscape orientation. To send more than one processing instruction to the printer, the client collects the attributes representing the instructions into an attribute set, which the Java Print Service API represents with the AttributeSet interface.

The AttributeSet interface is similar to the java.util.Map interface: It provides a map of keys to values, in which each key is unique and can contain no more than one value. However, the AttributeSet interface is designed to specifically support the needs of the Java Print Service API. An AttributeSet requires that:

Each key in an AttributeSet correspond to a category, and the value of the key can only be one of the attribute values that belong to the category represented by the key. Thus, unlike a Map, an AttributeSet restricts the possible values of a key: An attribute category cannot be set to an attribute value that does not belong to that category.
Only attributes implementing the Attribute interface can be added to the attribute set.
Only one attribute from a particular category can exist in an AttributeSet. For example, if an attribute set already contains a Media attribute, adding another Media attribute overwrites the first one.

Like a single attribute, an attribute set has a role. The roles are defined by the AttributeSet subinterfaces, which parallel the Attribute subinterfaces mentioned in the Attribute Roles section. The AttributeSet subinterfaces are: PrintRequestAttributeSet, PrintJobAttributeSet, DocAttributeSet, and PrintServiceAttributeSet. The role of the attribute set determines what kind of attributes it contains: a print request attribute set can contain only print request attributes.

The Java Print Service API includes HashAttributeSet as a concrete implementation of the AttributeSet interface, but developers can provide their own implementation. Rather than using HashAttributeSet directly, applications will more often use one of the subclasses of HashAttributeSet, which are: HashPrintRequestAttributeSet, HashPrintJobAttributeSet, HashDocumentAttributeSet, and HashPrintServiceAttributeSet. These subclasses implement the corresponding AttributeSet subinterfaces. For example PrintRequestAttributeSet extends AttributeSet, and HashPrintRequestAttributeSet is the concrete implementation of PrintRequestAttributeSet. An attribute set created with HashPrintRequestAttributeSet or any implementation of PrintRequestAttributeSet can contain only request attributes.

Unlike its subclasses, a HashAttributeSet can contain any kind of attribute. An application uses a HashAttributeSet directly when it needs a set to contain more than one kind of attribute. One example is the set returned by the getUnsupportedAttributes method of PrintService. The unsupported attributes returned might belong to more than one attribute role.

As with single attributes, applications will more often create request attribute sets because specifying print requests is the printing application's primary function. To create a request attribute set, use one of the constructors from the HashPrintRequestAttributeSet class:

PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();

The next section describes some of the more commonly used attributes that you can add to a set.

CONTENTS | PREV | NEXT