0N/ACopyright (c) 2000, 2003, Oracle and/or its affiliates. All rights reserved. 0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/AThis code is free software; you can redistribute it and/or modify it 0N/Aunder the terms of the GNU General Public License version 2 only, as 0N/Apublished by the Free Software Foundation. Oracle designates this 0N/Aparticular file as subject to the "Classpath" exception as provided 0N/Aby Oracle in the LICENSE file that accompanied this code. 0N/AThis code is distributed in the hope that it will be useful, but WITHOUT 0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/Aversion 2 for more details (a copy is included in the LICENSE file that 0N/Aaccompanied this code). 1472N/AYou should have received a copy of the GNU General Public License version 1472N/A2 along with this work; if not, write to the Free Software Foundation, 0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/APlease contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/ACA 95054 USA or visit www.sun.com if you need additional information or 0N/AProvides classes and interfaces
1892N/Athat describe the types of Java<
sup><
font size="-2">TM</
font></
sup> Print
1892N/AService attributes and how they can be collected into attribute sets.
0N/A<
H3>What is an Attribute?</
H3>
1892N/AWhen setting up a print job,
0N/Aa client specifies two things:
1892N/A<
B>print data</
B> and <
B>processing instructions.</
B>
1892N/AThe print data is the actual content to be printed.
0N/AThe processing instructions tell the printer how to print the print data,
0N/Asuch as: what media to use, how many copies to print, and
0N/Awhether to print on one or both sides of a sheet. The client specifies
1892N/Athese processing instructions with the attribute definitions of the Java
0N/AThe print data and the processing instructions
0N/Aare separate entities. This means that:
0N/A<
li>You can print the same print data
0N/Aat different times using different processing instructions.
0N/AFor example, you can print a slide presentation
0N/Aon US letter-sized white paper,
0N/Adouble-sided, stapled, 20 copies
0N/Ato make handouts for a talk;
0N/Aand you could print the same slide presentation
0N/Aon US letter-sized transparencies,
0N/Ato make the actual slides for the talk.
3178N/A<
li>You can use the same processing instructions
3178N/Aat different times to print different data.
0N/AFor example, you could set your default processing
1892N/Ainstructions to: US letter-sized paper, double sided, stapled.
1892N/AWhenever you print a job, it prints with these settings,
1892N/Aunless you explicitly override them.
1892N/AThe processing instruction does not specify how the print job
1892N/Aprocesses the request; each processing instruction is only a description
1892N/Aof the results of a print job. The print job determines the manner in
1892N/Awhich it achieves the results specified by the processing instructions.
1892N/ARepresenting processing instructions as descriptive items
1892N/Aprovides more flexibility for implementing print jobs.
1892N/A<
h4>Attribute Categories and Values</
h4>
3178N/AEach printer has a set of capabilities, such as the ability to print on
0N/Adifferent paper sizes or the ability to print more than one copy. Each of
1892N/Athe capabilities has a range of values. For example, a printer's orientation
1892N/Acapability might have this range of values: [landscape, portrait].
3178N/AFor each print request, the capability is set to one of these values. The
0N/AJava Print Service API uses the term <
b>attribute category</
b> to refer to
1892N/Aa printer capability and the term <
b>attribute value</
b> to refer to the value
1892N/AIn the Java Print Service API, an attribute category is represented by a Java
1892N/AAttribute values are instances of such a class or
1892N/Aone of its subclasses. For example, to specify the number of copies, an
1892N/Aapplication constructs an instance of the
1892N/Anumber of desired copies and uses the <
code>Copies</
code> instance as part of
1892N/Athe print request. In this case, the <
code>Copies</
code> class represents the
1892N/Aattribute category, and the <
code>Copies</
code> instance represents the
<
h4><
a name="role"></
a>Attribute Roles</
h4>
When submitting a print job to a printer, the client provides the
attributes describing the characteristics of the print data, such as
the document name, and how the print data should be printed, such as
double-sided, five copies. If a print job consists of multiple
pieces of print data, different pieces might have different processing
instructions, such as 8 x 11 inch media for the first document, and
11 x 17 inch media for another document.
Once the printer starts processing the print job,
additional information about the job becomes available, which might include:
the job state (such as <
i>completed</
i> or <
i>queued</
i>) and
the number of pages printed so far. These pieces of information are also
attributes. Attributes can also describe the printer itself, such as:
the printer name, the printer location, and the number of jobs queued.
The Java Print Service API defines these different kinds of attributes
with five subinterfaces of <
code>Attribute</
code>:
of an individual document and the print job settings to be applied to an
a setting applied to a whole print job and to all the documents in
status of a print service.
the supported values for another attribute.
implements one or more of these tagging subinterfaces
to indicate where the attribute can be used in the API.
If an attribute class implements multiple tagging subinterfaces,
the attribute can be used in multiple contexts. For example, the media
attribute can apply to one document in a print job as a <
code>DocAttribute</
code>
or to an entire print job as a <
code>PrintRequestAttribute</
code>.
Certain low-level attributes
are never used on their own
but are always aggregated into higher-level attributes.
These low-level attribute classes only
not any of the tagging subinterfaces.
The Java Print Service API defines a group of
standard attribute classes modeled upon the attributes in
the Internet Printing Protocol (IPP) version 1.1. The
standard attribute classes are in the subpackage
attribute classes conceptually separate from the generic
A client usually needs to provide more than one processing
instruction when submitting a print job. For example, the client might need to
specify a media size of A4 and a landscape orientation. To send more than one
processing instruction, the client collects the attributes into an
attribute set, which the Java Print Service API represents with the
The <
code>AttributeSet</
code> interface is similar to the
key to values, in which each key is unique and can contain no more than one
value. However, the <
code>AttributeSet</
code> interface is designed to
specifically support the needs of the Java Print Service API. An
<
code>AttributeSet</
code> requires that:
<
LI>Each key in an <
code>AttributeSet</
code> corresponds 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 <
code>Map</
code>, an
<
code>AttributeSet</
code> restricts the possible values of a key: an
attribute category cannot be set to an attribute value that does not belong to
<
LI>No two attributes from the same category can exist in the same set.
For example, an attribute collection
must not contain both a "one-sided" attribute and a "two-sided" attribute
because these two attributes give the printer conflicting instructions.
<
LI>Only attributes implementing the <
code>Attribute</
code> interface can
as a concrete implementation of the attribute set interface.
<
code>HashAttributeSet</
code> provides an attribute set based on a hash map.
You can use this implementation or provide your own implementation
of interface <
code>AttributeSet</
code>.
The Java Print Service API provides four specializations of an attribute set
that are restricted to contain just one of the four kinds of attributes,
as discussed in the <
a href="#role">Attribute Roles</
a> section:
Notice that only four kinds of attribute sets are listed here, but there are
five kinds of attributes. Interface
denotes an attribute that gives the supported values for another attribute.
Supported-values attributes are never aggregated into attribute sets,
so there is no attribute set subinterface defined for them.
In some contexts, an attribute set is read-only, which means that the
client is only allowed to examine an attribute set's
contents but not change them. In other contexts, the attribute set is read-write,
which means that the client is allowed both to examine and to change an
attribute set's contents. For a read-only attribute set, calling a mutating
operation throws an <
code>UnmodifiableSetException</
code>.
one concrete implementation of each of the attribute set subinterfaces:
and enforce the restriction that the attribute set is only allowed to contain
the corresponding kind of attribute.
<
H3>Attribute Class Design</
H3>
An attribute value is a small, atomic data item,
such as an integer or an enumerated value. The Java Print Service API
does not use primitive data types, such as int, to represent attribute
values for these reasons:
<
li>Primitive data types are not type-safe. For example, a compiler
should not allow a "copies" attribute value to
be used for a "sides" attribute.
<
li>Some attributes must be represented as a record of several
values. One example is printer resolution, which requires two
numbers, such as 600 and 300 representing 600 x 300 dpi.
For type-safety and to represent all attributes uniformly, the Java
Print Service API defines each attribute category as a class, such as
attribute class wraps one or more primitive data items containing the
attribute's value. Attribute set operations perform frequent
comparisons between attribute category objects when adding attributes,
finding existing attributes in the same category, and looking
up an attribute given its category. Because an attribute category is
represented by a class, fast attribute-value comparisons can be performed
Even though the Java Print Service API includes a large number of
different attribute categories, there are only a few different types
of attribute values. Most attributes can be represented by a small
number of data types, such as: integer values, integer ranges, text,
or an enumeration of integer values. The type of the attribute value that
a category accepts is called the attribute's abstract syntax. To
provide consistency and reduce code duplication, the Java Print Service
API defines abstract syntax classes to represent each
abstract syntax, and these classes are used as the parent of standard
attributes whenever possible. The abstract syntax classes are:
provides a type-safe enumeration in which enumerated
values are represented as singleton objects. Each enumeration
singleton is an instance of the enumeration class that wraps a hidden
is the abstract syntax for integer-valued attributes.
the abstract syntax for text-valued attributes, and
includes a locale giving the text string's natural language.
is the abstract syntax for attributes
representing a range or set of integers
is the abstract syntax for attributes representing
resolution values, such as 600x300 dpi.
is the abstract syntax for attributes representing a
two-dimensional size, such as a paper size of 8.5 x 11 inches.
is the abstract syntax for attributes whose value is a date and time.
abstract syntax for attributes whose value is a Uniform Resource
The abstract syntax classes are independent of the attributes that
use them. In fact, applications that have nothing to do with
printing can use the abstract syntax classes. Although most of the
standard attribute classes extend one of the abstract syntax classes,
no attribute class is required to extend one of these classes. The
abstract syntax classes merely provide a convenient implementation that
can be shared by many attribute classes.
Each attribute class implements the <
code>Attribute</
code> interface, either
directly or indirectly, to mark it as a printing attribute. An
attribute class that can appear in restricted attribute sets in
certain contexts also implements one or more subinterfaces of
<
code>Attribute</
code>. Most attribute classes also extend the appropriate
abstract syntax class to get the implementation. Consider the
<
code>Sides</
code> attribute class:
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute
public final Object getCategory()
Since every attribute class implements <
code>Attribute</
code>, every attribute
class must provide an implementation for the
which returns the attribute category. In the case of <
code>Sides</
code>, the
<
code>getCategory</
code> method returns <
code>
Sides.class</
code>. The
<
code>getCategory</
code> method is final to ensure that any vendor-defined
subclasses of a standard attribute class appear in the same category.
Every attribute object is immutable once constructed so that attribute object
references can be passed around freely. To get a different attribute
value, construct a different attribute object.
<
h3>Attribute Vendors</
h3>
The Java Print Service API is designed so that vendors can:
<
li>define new vendor-specific values for any standard attribute
<
li>define new attribute categories representing the vendor printer's
proprietary capabilities not already supported by the standard
To define a new value for an attribute, a client can construct
instances of such attributes with arbitrary values at runtime.
However, an enumerated attribute using an abstract syntax class
of <
code>EnumSyntax</
code> specifies all the possible attribute values
at compile time as singleton instances of the attribute class. This
means that new enumerated values cannot be constructed at run time.
To define new vendor-specific values for a standard enumerated
attribute, the vendor must define a new attribute class specifying
the new singleton instances. To ensure that the new attribute values
fall in the same category as the standard attribute values, the new
attribute class must be a subclass of the standard attribute class.
To define a new attribute category, a vendor defines a new attribute
class. This attribute class, like the standard attribute classes,
implements <
code>Attribute</
code> or one of its subinterfaces and extends an
abstract syntax class. The vendor can either use an existing
abstract syntax class or define a new one. The new vendor-defined
attribute can be used wherever an <
code>Attribute</
code> is used, such as in an
<
code>AttributeSet</
code>.
<
h3>Using Attributes</
h3>
A typical printing application uses the <
code>PrintRequestAttributeSet</
code>
because print-request attributes are the types of attributes that
client usually specifies. This example demonstrates creating an attribute
set of print-request attributes and locating a printer that can
print the document according to the specified attributes:
FileInputStream psStream;
psstream = new FileInputStream("
file.ps");
} catch (FileNotFoundException ffne) {
//Set the document type. See the DocFlavor documentation for
Doc myDoc = new SimpleDoc(pstream, psInFormat, null);
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
PrintService[] services =
DocPrintJob job = services[0].createPrintJob();
} catch (PrintException pe) {}
Please note: In the
javax.print APIs, a null reference parameter to methods
is incorrect unless explicitly documented on the method as having a meaningful
interpretation. Usage to the contrary is incorrect coding and may result
in a run time exception either immediately or at some later time.
IllegalArgumentException and NullPointerException are examples of
typical and acceptable run time exceptions for such cases.