Interface Attribute is the base interface implemented by any and every
printing attribute class to indicate that the class represents a
printing attribute. All printing attributes are serializable.

Interface AttributeSet specifies the interface for a set of printing
attributes. A printing attribute is an object whose class implements
interface Attribute.

An attribute set contains a group of attribute values,
where duplicate values are not allowed in the set.
Furthermore, each value in an attribute set is
a member of some category, and at most one value in any particular
category is allowed in the set. For an attribute set, the values are Attribute objects, and the categories are Class objects. An attribute's category is the class (or interface) at the
root of the class hierarchy for that kind of attribute. Note that an
attribute object's category may be a superclass of the attribute object's
class rather than the attribute object's class itself. An attribute
object's
category is determined by calling the getCategory() method defined in interface Attribute.

The interfaces of an AttributeSet resemble those of the Java Collections
API's java.util.Map interface, but is more restrictive in the types
it will accept, and combines keys and values into an Attribute.

Attribute sets are used in several places in the Print Service API. In
each context, only certain kinds of attributes are allowed to appear in the
attribute set, as determined by the tagging interfaces which the attribute
class implements -- DocAttribute, PrintRequestAttribute, PrintJobAttribute, and PrintServiceAttribute.
There are four specializations of an attribute set that are restricted to
contain just one of the four kinds of attribute -- DocAttributeSet, PrintRequestAttributeSet,
PrintJobAttributeSet, and PrintServiceAttributeSet, respectively. Note that
many attribute classes implement more than one tagging interface and so may
appear in more than one context.


A DocAttributeSet, containing DocAttributes, specifies the characteristics of an individual doc and the
print job settings to be applied to an individual doc.


A PrintRequestAttributeSet, containing
PrintRequestAttributes, specifies the
settings
to be applied to a whole print job and to all the docs in the print job.


A PrintJobAttributeSet, containing PrintJobAttributes, reports the status of a print job.


A PrintServiceAttributeSet, containing
PrintServiceAttributes, reports the status of
 a Print Service instance.


In some contexts, the client is only allowed to examine an attribute set's
contents but not change them (the set is read-only). In other places, the
client is allowed both to examine and to change an attribute set's contents
(the set is read-write). For a read-only attribute set, calling a mutating
operation throws an UnmodifiableSetException.

The Print Service API provides one implementation of interface
AttributeSet, class HashAttributeSet.
A client can use class HashAttributeSet or provide its own implementation of
interface AttributeSet. The Print Service API also provides
implementations of interface AttributeSet's subinterfaces -- classes HashDocAttributeSet,
HashPrintRequestAttributeSet, HashPrintJobAttributeSet, and HashPrintServiceAttributeSet.

Class AttributeSetUtilities provides static methods for manipulating
AttributeSets.

Methods for creating unmodifiable and synchronized views of attribute
sets.
operations useful for building
implementations of interface AttributeSet


An unmodifiable view U of an AttributeSet S provides a
client with "read-only" access to S. Query operations on U
"read through" to S; thus, changes in S are reflected in
U. However, any attempt to modify U,
 results in an UnmodifiableSetException.
The unmodifiable view object U will be serializable if the
attribute set object S is serializable.

A synchronized view V of an attribute set S provides a
client with synchronized (multiple thread safe) access to S. Each
operation of V is synchronized using V itself as the lock
object and then merely invokes the corresponding operation of S. In
order to guarantee mutually exclusive access, it is critical that all
access to S is accomplished through V. The synchronized view
object V will be serializable if the attribute set object S
is serializable.

As mentioned in the package description of javax.print, 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.

Class DateTimeSyntax is an abstract base class providing the common
implementation of all attributes whose value is a date and time.

Under the hood, a date-time attribute is stored as a value of class
java.util.Date. You can get a date-time attribute's Date value by
calling getValue(). A date-time attribute's
Date value is established when it is constructed (see DateTimeSyntax(Date)). Once
constructed, a date-time attribute's value is immutable.

To construct a date-time attribute from separate values of the year, month,
day, hour, minute, and so on, use a java.util.Calendar
object to construct a java.util.Date object, then use the
java.util.Date object to construct the date-time attribute.
To convert
a date-time attribute to separate values of the year, month, day, hour,
minute, and so on, create a java.util.Calendar object and
set it to the java.util.Date from the date-time attribute. Class
DateTimeSyntax stores its value in the form of a java.util.Date

rather than a java.util.Calendar because it typically takes
less memory to store and less time to compare a java.util.Date
than a java.util.Calendar.

Interface DocAttribute is a tagging interface which a printing attribute
class implements to indicate the attribute denotes a setting for a doc.
("Doc" is a short, easy-to-pronounce term that means "a piece of print
data.") The client may include a DocAttribute in a Doc's
attribute set to specify a characteristic of
that doc. If an attribute implements PrintRequestAttribute as well as DocAttribute, the client may include the
attribute in a attribute set which specifies a print job
to specify a characteristic for all the docs in that job.

Interface DocAttributeSet specifies the interface for a set of doc
attributes, i.e. printing attributes that implement interface DocAttribute. In the Print Service API, the client uses a
DocAttributeSet to specify the characteristics of an individual doc and
the print job settings to be applied to an individual doc.

A DocAttributeSet is just an AttributeSet whose
constructors and mutating operations guarantee an additional invariant,
namely that all attribute values in the DocAttributeSet must be instances
of interface DocAttribute.
The add(Attribute), and
addAll(AttributeSet) operations
are respecified below to guarantee this additional invariant.

public class Bach extends EnumSyntax {
    public static final Bach JOHANN_SEBASTIAN     = new Bach(0);
    public static final Bach WILHELM_FRIEDEMANN   = new Bach(1);
    public static final Bach CARL_PHILIP_EMMANUEL = new Bach(2);
    public static final Bach JOHANN_CHRISTIAN     = new Bach(3);
    public static final Bach P_D_Q                = new Bach(4);

    private static final String[] stringTable = {
        "Johann Sebastian Bach",
         "Wilhelm Friedemann Bach",
         "Carl Philip Emmanuel Bach",
         "Johann Christian Bach",
         "P.D.Q. Bach"
    };

    protected String[] getStringTable() {
        return stringTable;
    }

    private static final Bach[] enumValueTable = {
        JOHANN_SEBASTIAN,
         WILHELM_FRIEDEMANN,
         CARL_PHILIP_EMMANUEL,
         JOHANN_CHRISTIAN,
         P_D_Q
    };

    protected EnumSyntax[] getEnumValueTable() {
        return enumValueTable;
    }
}

Bach theComposer;
. . .
if (theComposer == Bach.JOHANN_SEBASTIAN) {
    System.out.println ("The greatest composer of all time!");
}

Class EnumSyntax is an abstract base class providing the common
implementation of all "type safe enumeration" objects. An enumeration class
(which extends class EnumSyntax) provides a group of enumeration values
(objects) that are singleton instances of the enumeration class; for example:


    public class Bach extends EnumSyntax {
        public static final Bach JOHANN_SEBASTIAN     = new Bach(0);
        public static final Bach WILHELM_FRIEDEMANN   = new Bach(1);
        public static final Bach CARL_PHILIP_EMMANUEL = new Bach(2);
        public static final Bach JOHANN_CHRISTIAN     = new Bach(3);
        public static final Bach P_D_Q                = new Bach(4);

        private static final String[] stringTable = {
            "Johann Sebastian Bach",
             "Wilhelm Friedemann Bach",
             "Carl Philip Emmanuel Bach",
             "Johann Christian Bach",
             "P.D.Q. Bach"
        };

        protected String[] getStringTable() {
            return stringTable;
        }

        private static final Bach[] enumValueTable = {
            JOHANN_SEBASTIAN,
             WILHELM_FRIEDEMANN,
             CARL_PHILIP_EMMANUEL,
             JOHANN_CHRISTIAN,
             P_D_Q
        };

        protected EnumSyntax[] getEnumValueTable() {
            return enumValueTable;
        }
    }
You can then write code that uses the == and !=
operators to test enumeration values; for example:


    Bach theComposer;
    . . .
    if (theComposer == Bach.JOHANN_SEBASTIAN) {
        System.out.println ("The greatest composer of all time!");
    }
The equals() method for an enumeration class just does a test
for identical objects (==).

You can convert an enumeration value to a string by calling toString(). The string is obtained from a table
supplied by the enumeration class.

Under the hood, an enumeration value is just an integer, a different integer
for each enumeration value within an enumeration class. You can get an
enumeration value's integer value by calling getValue(). An enumeration value's integer value is established
when it is constructed (see EnumSyntax(int)). Since the constructor is protected, the only
possible enumeration values are the singleton objects declared in the
enumeration class; additional enumeration values cannot be created at run
time.

You can define a subclass of an enumeration class that extends it with
additional enumeration values. The subclass's enumeration values' integer
values need not be distinct from the superclass's enumeration values' integer
values; the ==, !=, equals(), and
toString() methods will still work properly even if the subclass
uses some of the same integer values as the superclass. However, the
application in which the enumeration class and subclass are used may need to
have distinct integer values in the superclass and subclass.

Class HashAttributeSet provides an AttributeSet
implementation with characteristics of a hash map.

Class HashDocAttributeSet provides an attribute set which
inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface DocAttributeSet.

Class HashPrintJobAttributeSet provides an attribute set
which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface
PrintJobAttributeSet.

Class HashPrintRequestAttributeSet inherits its implementation from
class HashAttributeSet and enforces the
semantic restrictions of interface
PrintRequestAttributeSet.

Class HashPrintServiceAttributeSet provides an attribute set
which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface
PrintServiceAttributeSet.

Class IntegerSyntax is an abstract base class providing the common
implementation of all attributes with integer values.

Under the hood, an integer attribute is just an integer. You can get an
integer attribute's integer value by calling getValue(). An integer attribute's integer value is
established when it is constructed (see IntegerSyntax(int)). Once constructed, an integer attribute's
value is immutable.

PrintJobAttribute is a tagging interface which a printing attribute
class implements to indicate the attribute describes the status of a Print
Job or some other characteristic of a Print Job. A Print Service
instance adds a number of PrintJobAttributes to a Print Job's attribute set
to report the Print Job's status. If an attribute implements PrintRequestAttribute as well as PrintJobAttribute,
the client may include the attribute in a attribute set to
specify the attribute's value for the Print Job.

Interface PrintJobAttributeSet specifies the interface for a set of print
job attributes, i.e. printing attributes that implement interface PrintJobAttribute. In the Print Service API, a
service uses a PrintJobAttributeSet to report the status of a print job.

A PrintJobAttributeSet is just an AttributeSet whose
constructors and mutating operations guarantee an additional invariant,
namely that all attribute values in the PrintJobAttributeSet must be
instances of interface PrintJobAttribute.
The add(Attribute), and
>addAll(AttributeSet) operations
are respecified below to guarantee this additional invariant.

Interface PrintRequestAttribute is a tagging interface which a printing
attribute class implements to indicate the attribute denotes a
requested setting for a print job.

Attributes which are tagged with PrintRequestAttribute and are also tagged
as PrintJobAttribute, represent the subset of job attributes which
can be part of the specification of a job request.

If an attribute implements DocAttribute
as well as PrintRequestAttribute, the client may include the
attribute in a Doc}'s attribute set to specify
a job setting which pertains just to that doc.

Interface PrintRequestAttributeSet specifies the interface for a set of
print request attributes, i.e. printing attributes that implement interface
PrintRequestAttribute.
The client uses a PrintRequestAttributeSet to specify the settings to be
applied to a whole print job and to all the docs in the print job.

PrintRequestAttributeSet is just an AttributeSet whose
constructors and mutating operations guarantee an additional invariant,
namely that all attribute values in the PrintRequestAttributeSet must be
instances of interface PrintRequestAttribute.
The add(Attribute), and
addAll(AttributeSet) operations
are respecified below to guarantee this additional invariant.

Interface PrintServiceAttribute is a tagging interface which a printing
attribute class implements to indicate the attribute describes the status
of a Print Service or some other characteristic of a Print Service. A Print
Service instance adds a number of PrintServiceAttributes to a Print
service's attribute set to report the Print Service's status.

Interface PrintServiceAttributeSet specifies the interface for a set of
print job attributes, i.e. printing attributes that implement interface
PrintServiceAttribute. In the Print Service API,
the Print Service instance uses a PrintServiceAttributeSet to report the
status of the print service.

A PrintServiceAttributeSet is just an AttributeSet
whose constructors and mutating operations guarantee an additional
invariant,
namely that all attribute values in the PrintServiceAttributeSet must be
instances of interface PrintServiceAttribute.
The add(Attribute), and
addAll(AttributeSet) operations
are respecified below to guarantee this additional invariant.

Class ResolutionSyntax is an abstract base class providing the common
implementation of all attributes denoting a printer resolution.

A resolution attribute's value consists of two items, the cross feed
direction resolution and the feed direction resolution. A resolution
attribute may be constructed by supplying the two values and indicating the
units in which the values are measured. Methods are provided to return a
resolution attribute's values, indicating the units in which the values are
to be returned. The two most common resolution units are dots per inch (dpi)
and dots per centimeter (dpcm), and exported constants DPI and DPCM are provided for
indicating those units.

Once constructed, a resolution attribute's value is immutable.

Design

A resolution attribute's cross feed direction resolution and feed direction
resolution values are stored internally using units of dots per 100 inches
(dphi). Storing the values in dphi rather than, say, metric units allows
precise integer arithmetic conversions between dpi and dphi and between dpcm
and dphi: 1 dpi = 100 dphi, 1 dpcm = 254 dphi. Thus, the values can be stored
into and retrieved back from a resolution attribute in either units with no
loss of precision. This would not be guaranteed if a floating point
representation were used. However, roundoff error will in general occur if a
resolution attribute's values are created in one units and retrieved in
different units; for example, 600 dpi will be rounded to 236 dpcm, whereas
the true value (to five figures) is 236.22 dpcm.

Storing the values internally in common units of dphi lets two resolution
attributes be compared without regard to the units in which they were
created; for example, 300 dpcm will compare equal to 762 dpi, as they both
are stored as 76200 dphi. In particular, a lookup service can
match resolution attributes based on equality of their serialized
representations regardless of the units in which they were created. Again,
using integers for internal storage allows precise equality comparisons to be
done, which would not be guaranteed if a floating point representation were
used.

The exported constant DPI is actually the
conversion factor by which to multiply a value in dpi to get the value in
dphi. Likewise, the exported constant DPCM is the
conversion factor by which to multiply a value in dpcm to get the value in
dphi. A client can specify a resolution value in units other than dpi or dpcm
by supplying its own conversion factor. However, since the internal units of
dphi was chosen with supporting only the external units of dpi and dpcm in
mind, there is no guarantee that the conversion factor for the client's units
will be an exact integer. If the conversion factor isn't an exact integer,
resolution values in the client's units won't be stored precisely.

Class SetOfIntegerSyntax is an abstract base class providing the common
implementation of all attributes whose value is a set of nonnegative
integers. This includes attributes whose value is a single range of integers
and attributes whose value is a set of ranges of integers.

You can construct an instance of SetOfIntegerSyntax by giving it in "string
form." The string consists of zero or more comma-separated integer groups.
Each integer group consists of either one integer, two integers separated by
a hyphen (-), or two integers separated by a colon
(:). Each integer consists of one or more decimal digits
(0 through 9). Whitespace characters cannot
appear within an integer but are otherwise ignored. For example:
"", "1", "5-10", "1:2,
4".

You can also construct an instance of SetOfIntegerSyntax by giving it in
"array form." Array form consists of an array of zero or more integer groups
where each integer group is a length-1 or length-2 array of
ints; for example, int[0][],
int[][]{{1}}, int[][]{{5,10}},
int[][]{{1,2},{4}}.

In both string form and array form, each successive integer group gives a
range of integers to be included in the set. The first integer in each group
gives the lower bound of the range; the second integer in each group gives
the upper bound of the range; if there is only one integer in the group, the
upper bound is the same as the lower bound. If the upper bound is less than
the lower bound, it denotes a null range (no values). If the upper bound is
equal to the lower bound, it denotes a range consisting of a single value. If
the upper bound is greater than the lower bound, it denotes a range
consisting of more than one value. The ranges may appear in any order and are
allowed to overlap. The union of all the ranges gives the set's contents.
Once a SetOfIntegerSyntax instance is constructed, its value is immutable.

The SetOfIntegerSyntax object's value is actually stored in "canonical
array form." This is the same as array form, except there are no null ranges;
the members of the set are represented in as few ranges as possible (i.e.,
overlapping ranges are coalesced); the ranges appear in ascending order; and
each range is always represented as a length-two array of ints
in the form {lower bound, upper bound}. An empty set is represented as a
zero-length array.

Class SetOfIntegerSyntax has operations to return the set's members in
canonical array form, to test whether a given integer is a member of the
set, and to iterate through the members of the set.

Class Size2DSyntax is an abstract base class providing the common
implementation of all attributes denoting a size in two dimensions.

A two-dimensional size attribute's value consists of two items, the X
dimension and the Y dimension. A two-dimensional size attribute may be
constructed by supplying the two values and indicating the units in which the
values are measured. Methods are provided to return a two-dimensional size
attribute's values, indicating the units in which the values are to be
returned. The two most common size units are inches (in) and millimeters
(mm), and exported constants INCH and MM are provided for indicating those units.

Once constructed, a two-dimensional size attribute's value is immutable.

Design

A two-dimensional size attribute's X and Y dimension values are stored
internally as integers in units of micrometers (µm), where 1 micrometer
= 10-6 meter = 1/1000 millimeter = 1/25400 inch. This permits
dimensions to be represented exactly to a precision of 1/1000 mm (= 1
µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in
negative powers of two, this permits dimensions to be represented exactly to
a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch
does not equal an integral number of µm).

Storing the dimensions internally in common units of µm lets two size
attributes be compared without regard to the units in which they were
created; for example, 8.5 in will compare equal to 215.9 mm, as they both are
stored as 215900 µm. For example, a lookup service can
match resolution attributes based on equality of their serialized
representations regardless of the units in which they were created. Using
integers for internal storage allows precise equality comparisons to be done,
which would not be guaranteed if an internal floating point representation
were used. Note that if you're looking for U.S. letter sized media in metric
units, you have to search for a media size of 215.9 x 279.4 mm; rounding off
to an integral 216 x 279 mm will not match.

The exported constant INCH is actually the
conversion factor by which to multiply a value in inches to get the value in
µm. Likewise, the exported constant MM is the
conversion factor by which to multiply a value in mm to get the value in
µm. A client can specify a resolution value in units other than inches
or mm by supplying its own conversion factor. However, since the internal
units of µm was chosen with supporting only the external units of inch
and mm in mind, there is no guarantee that the conversion factor for the
client's units will be an exact integer. If the conversion factor isn't an
exact integer, resolution values in the client's units won't be stored
precisely.

Class Chromaticity is a printing attribute class, an enumeration, that
specifies monochrome or color printing. This is used by a print client
to specify how the print data should be generated or processed. It is not
descriptive of the color capabilities of the device. Query the service's
ColorSupported attribute to determine if the device
can be verified to support color printing.

The table below shows the effects of specifying a Chromaticity attribute of
MONOCHROME or COLOR
for a monochrome or color document.




ChromaticityAttribute


Effect onMonochrome Document


Effect onColor Document




MONOCHROME


Printed as is, in monochrome


Printed in monochrome, with colors converted to shades of gray




COLOR


Printed as is, in monochrome


Printed as is, in color





IPP Compatibility: Chromaticity is not an IPP attribute at present.

Class ColorSupported is a printing attribute class, an enumeration, that
identifies whether the device is capable of any type of color printing at
all, including highlight color as well as full process color. All document
instructions having to do with color are embedded within the print data (none
are attributes attached to the job outside the print data).

Note: End users are able to determine the nature and details of the color
support by querying the PrinterMoreInfoManufacturer attribute.

Don't confuse the ColorSupported attribute with the Chromaticity attribute. Chromaticity is an attribute
the client can specify for a job to tell the printer whether to print a
document in monochrome or color, possibly causing the printer to print a
color document in monochrome. ColorSupported is a printer description
attribute that tells whether the printer can print in color regardless of how
the client specifies to print any particular document.

IPP Compatibility: The IPP boolean value is "true" for SUPPORTED and
"false" for NOT_SUPPORTED. The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class Compression is a printing attribute class, an enumeration, that
specifies how print data is compressed. Compression is an attribute of the
print data (the doc), not of the Print Job. If a Compression attribute is not
specified for a doc, the printer assumes the doc's print data is uncompressed
(i.e., the default Compression value is always NONE).

IPP Compatibility: The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class Copies is an integer valued printing attribute class that specifies the
number of copies to be printed.

On many devices the supported number of collated copies will be limited by
the number of physical output bins on the device, and may be different from
the number of uncollated copies which can be supported.

The effect of a Copies attribute with a value of n on a multidoc print
job (a job with multiple documents) depends on the (perhaps defaulted) value
of the MultipleDocumentHandling attribute:


SINGLE_DOCUMENT -- The result will be n copies of a single output
document comprising all the input docs.


SINGLE_DOCUMENT_NEW_SHEET -- The result will be n copies of a single
output document comprising all the input docs, and the first impression of
each input doc will always start on a new media sheet.


SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- The result will be n copies of
the first input document, followed by n copies of the second input
document, . . . followed by n copies of the last input document.


SEPARATE_DOCUMENTS_COLLATED_COPIES -- The result will be the first input
document, the second input document, . . . the last input document, the group
of documents being repeated n times.


IPP Compatibility: The integer value gives the IPP integer value. The
category name returned by getName() gives the IPP attribute
name.

Class CopiesSupported is a printing attribute class, a set of integers, that
gives the supported values for a Copies attribute. It is
restricted to a single contiguous range of integers; multiple non-overlapping
ranges are not allowed.

IPP Compatibility: The CopiesSupported attribute's canonical array
form gives the lower and upper bound for the range of copies to be included
in an IPP "copies-supported" attribute. See class SetOfIntegerSyntax for an
explanation of canonical array form. The category name returned by
getName() gives the IPP attribute name.

Class DateTimeAtCompleted is a printing attribute class, a date-time
attribute, that indicates the date and time at which the Print Job completed
(or was canceled or aborted).

To construct a DateTimeAtCompleted attribute from separate values of the
year, month, day, hour, minute, and so on, use a Calendar object to construct a Date object, then use
the Date object to construct the DateTimeAtCompleted
attribute. To convert a DateTimeAtCompleted attribute to separate values of
the year, month, day, hour, minute, and so on, create a Calendar object and set it to the Date from the DateTimeAtCompleted attribute.

IPP Compatibility: The information needed to construct an IPP
"date-time-at-completed" attribute can be obtained as described above. The
category name returned by getName() gives the IPP attribute
name.

Class DateTimeAtCreation is a printing attribute class, a date-time
attribute, that indicates the date and time at which the Print Job was
created.

To construct a DateTimeAtCreation attribute from separate values of the year,
month, day, hour, minute, and so on, use a Calendar object to construct a Date object, then use
the Date object to construct the DateTimeAtCreation
attribute. To convert a DateTimeAtCreation attribute to separate values of
the year, month, day, hour, minute, and so on, create a Calendar object and set it to the Date from the DateTimeAtCreation attribute.

IPP Compatibility: The information needed to construct an IPP
"date-time-at-creation" attribute can be obtained as described above. The
category name returned by getName() gives the IPP attribute
name.

Class DateTimeAtProcessing is a printing attribute class, a date-time
attribute, that indicates the date and time at which the Print Job first
began processing.

To construct a DateTimeAtProcessing attribute from separate values of the
year, month, day, hour, minute, and so on, use a Calendar object to construct a Date object, then use
the Date object to construct the DateTimeAtProcessing
attribute. To convert a DateTimeAtProcessing attribute to separate values of
the year, month, day, hour, minute, and so on, create a Calendar object and set it to the Date from the DateTimeAtProcessing attribute.

IPP Compatibility: The information needed to construct an IPP
"date-time-at-processing" attribute can be obtained as described above. The
category name returned by getName() gives the IPP attribute
name.

Class Destination is a printing attribute class, a URI, that is used to
indicate an alternate destination for the spooled printer formatted
data. Many PrintServices will not support the notion of a destination
other than the printer device, and so will not support this attribute.

A common use for this attribute will be applications which want
to redirect output to a local disk file : eg."file:out.prn".
Note that proper construction of "file:" scheme URI instances should
be performed using the toURI() method of class
File.
See the documentation on that class for more information.

If a destination URI is specified in a PrintRequest and it is not
accessible for output by the PrintService, a PrintException will be thrown.
The PrintException may implement URIException to provide a more specific
cause.

IPP Compatibility: Destination is not an IPP attribute.

Class DialogTypeSelection is a printing attribute class, an enumeration,
that indicates the user dialog type to be used for specifying
printing options.
If NATIVE is specified, then where available, a native
platform dialog is displayed.
If COMMON is specified, a cross-platform print dialog is displayed.

This option to specify a native dialog for use with an IPP attribute
set provides a standard way to reflect back of the setting and option
changes made by a user to the calling application, and integrates
the native dialog into the Java printing APIs.
But note that some options and settings in a native dialog may not
necessarily map to IPP attributes as they may be non-standard platform,
or even printer specific options.

IPP Compatibility: This is not an IPP attribute.

Class DocumentName is a printing attribute class, a text attribute, that
specifies the name of a document. DocumentName is an attribute of the print
data (the doc), not of the Print Job. A document's name is an arbitrary
string defined by the client.
However if a JobName is not specified, the DocumentName should be used
instead, which implies that supporting specification of DocumentName
requires reporting of JobName and vice versa.
See JobName for more information.

IPP Compatibility: The string value gives the IPP name value. The
locale gives the IPP natural language. The category name returned by
getName() gives the IPP attribute name.

Class Fidelity is a printing attribute class, an enumeration,
that indicates whether total fidelity to client supplied print request
attributes is required.
If FIDELITY_TRUE is specified and a service cannot print the job exactly
as specified it must reject the job.
If FIDELITY_FALSE is specified a reasonable attempt to print the job is
acceptable. If not supplied the default is FIDELITY_FALSE.


IPP Compatibility: The IPP boolean value is "true" for FIDELITY_TRUE
and "false" for FIDELITY_FALSE. The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.
See RFC 2911 Section 15.1 for
a fuller description of the IPP fidelity attribute.

Class Finishings is a printing attribute class, an enumeration, that
identifies whether the printer applies a finishing operation of some kind
of binding to each copy of each printed document in the job. For multidoc
print jobs (jobs with multiple documents), the
MultipleDocumentHandling attribute determines what constitutes a "copy"
for purposes of finishing.

Standard Finishings values are:






NONE


STAPLE


EDGE_STITCH







BIND


SADDLE_STITCH


COVER







The following Finishings values are more specific; they indicate a
corner or an edge as if the document were a portrait document:






STAPLE_TOP_LEFT


EDGE_STITCH_LEFT


STAPLE_DUAL_LEFT










STAPLE_BOTTOM_LEFT


EDGE_STITCH_TOP


STAPLE_DUAL_TOP










STAPLE_TOP_RIGHT


EDGE_STITCH_RIGHT


STAPLE_DUAL_RIGHT










STAPLE_BOTTOM_RIGHT


EDGE_STITCH_BOTTOM


STAPLE_DUAL_BOTTOM







The STAPLE_XXX values are specified with respect to the
document as if the document were a portrait document. If the document is
actually a landscape or a reverse-landscape document, the client supplies the
appropriate transformed value. For example, to position a staple in the upper
left hand corner of a landscape document when held for reading, the client
supplies the STAPLE_BOTTOM_LEFT value (since landscape is
defined as a 90 degree rotation from portrait, i.e., anti-clockwise). On the
other hand, to position a staple in the upper left hand corner of a
reverse-landscape document when held for reading, the client supplies the
STAPLE_TOP_RIGHT value (since reverse-landscape is defined as a
-90 degree rotation from portrait, i.e., clockwise).

The angle (vertical, horizontal, angled) of each staple with respect to the
document depends on the implementation which may in turn depend on the value
of the attribute.

The effect of a Finishings attribute on a multidoc print job (a job
with multiple documents) depends on whether all the docs have the same
binding specified or whether different docs have different bindings
specified, and on the (perhaps defaulted) value of the MultipleDocumentHandling attribute.


If all the docs have the same binding specified, then any value of MultipleDocumentHandling makes sense, and the
printer's processing depends on the MultipleDocumentHandling value:


SINGLE_DOCUMENT -- All the input docs will be bound together as one output
document with the specified binding.


SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be bound together as one
output document with the specified binding, and the first impression of each
input doc will always start on a new media sheet.


SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each input doc will be bound
separately with the specified binding.


SEPARATE_DOCUMENTS_COLLATED_COPIES -- Each input doc will be bound separately
with the specified binding.



If different docs have different bindings specified, then only two values of
MultipleDocumentHandling make sense, and the
printer reports an error when the job is submitted if any other value is
specified:


SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each input doc will be bound
separately with its own specified binding.


SEPARATE_DOCUMENTS_COLLATED_COPIES -- Each input doc will be bound separately
with its own specified binding.



IPP Compatibility: Class Finishings encapsulates some of the
IPP enum values that can be included in an IPP "finishings" attribute, which
is a set of enums. The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.
In IPP Finishings is a multi-value attribute, this API currently allows
only one binding to be specified.

JobHoldUntil immediately = new JobHoldUntil (new Date (0L));

Class JobHoldUntil is a printing attribute class, a date-time attribute, that
specifies the exact date and time at which the job must become a candidate
for printing.

If the value of this attribute specifies a date-time that is in the future,
the printer should add the JobStateReason value of
JOB_HOLD_UNTIL_SPECIFIED to the job's JobStateReasons
attribute, must move the job to the PENDING_HELD state, and must not schedule
the job for printing until the specified date-time arrives.

When the specified date-time arrives, the printer must remove the JobStateReason value of JOB_HOLD_UNTIL_SPECIFIED from the
job's JobStateReasons attribute, if present. If there
are no other job state reasons that keep the job in the PENDING_HELD state,
the printer must consider the job as a candidate for processing by moving the
job to the PENDING state.

If the specified date-time has already passed, the job must be a candidate
for processing immediately. Thus, one way to make the job immediately become
a candidate for processing is to specify a JobHoldUntil attribute constructed
like this (denoting a date-time of January 1, 1970, 00:00:00 GMT):


    JobHoldUntil immediately = new JobHoldUntil (new Date (0L));

If the client does not supply this attribute in a Print Request and the
printer supports this attribute, the printer must use its
(implementation-dependent) default JobHoldUntil value at job submission time
(unlike most job template attributes that are used if necessary at job
processing time).

To construct a JobHoldUntil attribute from separate values of the year,
month, day, hour, minute, and so on, use a Calendar object to construct a Date object, then use
the Date object to construct the JobHoldUntil
attribute. To convert a JobHoldUntil attribute to separate values of the
year, month, day, hour, minute, and so on, create a Calendar object and set it to the Date from the
JobHoldUntil attribute.

IPP Compatibility: Although IPP supports a "job-hold-until" attribute
specified as a keyword, IPP does not at this time support a "job-hold-until"
attribute specified as a date and time. However, the date and time can be
converted to one of the standard IPP keywords with some loss of precision;
for example, a JobHoldUntil value with today's date and 9:00pm local time
might be converted to the standard IPP keyword "night". The category name
returned by getName() gives the IPP attribute name.

Class JobImpressions is an integer valued printing attribute class that
specifies the total size in number of impressions of the document(s) being
submitted. An "impression" is the image (possibly many print-stream pages in
different configurations) imposed onto a single media page.

The JobImpressions attribute describes the size of the job. This attribute is
not intended to be a counter; it is intended to be useful routing and
scheduling information if known. The printer may try to compute the
JobImpressions attribute's value if it is not supplied in the Print Request.
Even if the client does supply a value for the JobImpressions attribute in
the Print Request, the printer may choose to change the value if the printer
is able to compute a value which is more accurate than the client supplied
value. The printer may be able to determine the correct value for the
JobImpressions attribute either right at job submission time or at any later
point in time.

As with JobKOctets, the JobImpressions value must not
include the multiplicative factors contributed by the number of copies
specified by the Copies attribute, independent of whether the
device can process multiple copies without making multiple passes over the
job or document data and independent of whether the output is collated or
not. Thus the value is independent of the implementation and reflects the
size of the document(s) measured in impressions independent of the number of
copies.

As with JobKOctets, the JobImpressions value must also not
include the multiplicative factor due to a copies instruction embedded in the
document data. If the document data actually includes replications of the
document data, this value will include such replication. In other words, this
value is always the number of impressions in the source document data, rather
than a measure of the number of impressions to be produced by the job.

IPP Compatibility: The integer value gives the IPP integer value. The
category name returned by getName() gives the IPP attribute
name.

Class JobImpressionsCompleted is an integer valued printing attribute class
that specifies the number of impressions completed for the job so far. For
printing devices, the impressions completed includes interpreting, marking,
and stacking the output.

The JobImpressionsCompleted attribute describes the progress of the job. This
attribute is intended to be a counter. That is, the JobImpressionsCompleted
value for a job that has not started processing must be 0. When the job's
JobState is PROCESSING or PROCESSING_STOPPED, the
JobImpressionsCompleted value is intended to increase as the job is
processed; it indicates the amount of the job that has been processed at the
time the Print Job's attribute set is queried or at the time a print job
event is reported. When the job enters the COMPLETED, CANCELED, or ABORTED
states, the JobImpressionsCompleted value is the final value for the job.

IPP Compatibility: The integer value gives the IPP integer value. The
category name returned by getName() gives the IPP attribute
name.

Class JobImpressionsSupported is a printing attribute class, a set of
integers, that gives the supported values for a JobImpressions attribute. It is restricted to a single contiguous range of
integers; multiple non-overlapping ranges are not allowed. This gives the
lower and upper bounds of the total sizes of print jobs in number of
impressions that the printer will accept.

IPP Compatibility: The JobImpressionsSupported attribute's canonical
array form gives the lower and upper bound for the range of values to be
included in an IPP "job-impressions-supported" attribute. See class SetOfIntegerSyntax for an
explanation of canonical array form. The category name returned by
getName() gives the IPP attribute name.

Class JobKOctets is an integer valued printing attribute class that specifies
the total size of the document(s) in K octets, i.e., in units of 1024 octets
requested to be processed in the job. The value must be rounded up, so that a
job between 1 and 1024 octets must be indicated as being 1K octets, 1025 to
2048 must be 2K octets, etc. For a multidoc print job (a job with multiple
documents), the JobKOctets value is computed by adding up the individual
documents' sizes in octets, then rounding up to the next K octets value.

The JobKOctets attribute describes the size of the job. This attribute is not
intended to be a counter; it is intended to be useful routing and scheduling
information if known. The printer may try to compute the JobKOctets
attribute's value if it is not supplied in the Print Request. Even if the
client does supply a value for the JobKOctets attribute in the Print Request,
the printer may choose to change the value if the printer is able to compute
a value which is more accurate than the client supplied value. The printer
may be able to determine the correct value for the JobKOctets attribute
either right at job submission time or at any later point in time.

The JobKOctets value must not include the multiplicative factors contributed
by the number of copies specified by the Copies attribute,
independent of whether the device can process multiple copies without making
multiple passes over the job or document data and independent of whether the
output is collated or not. Thus the value is independent of the
implementation and indicates the size of the document(s) measured in K octets
independent of the number of copies.

The JobKOctets value must also not include the multiplicative factor due to a
copies instruction embedded in the document data. If the document data
actually includes replications of the document data, this value will include
such replication. In other words, this value is always the size of the source
document data, rather than a measure of the hardcopy output to be produced.

The size of a doc is computed based on the print data representation class as
specified by the doc's DocFlavor, as
shown in the table below.



Representation Class
Document Size


byte[]
Length of the byte array


java.io.InputStream
Number of bytes read from the stream


char[]
Length of the character array x 2


java.lang.String
Length of the string x 2


java.io.Reader
Number of characters read from the stream x 2


java.net.URL
Number of bytes read from the file at the given URL address


java.awt.image.renderable.RenderableImage
Implementation dependent*


java.awt.print.Printable
Implementation dependent*


java.awt.print.Pageable
Implementation dependent*



* In these cases the Print Service itself generates the print data sent
to the printer. If the Print Service supports the JobKOctets attribute, for
these cases the Print Service itself must calculate the size of the print
data, replacing any JobKOctets value the client specified.

IPP Compatibility: The integer value gives the IPP integer value. The
category name returned by getName() gives the IPP attribute
name.

Class JobKOctetsProcessed is an integer valued printing attribute class that
specifies the total number of print data octets processed so far in K octets,
i.e., in units of 1024 octets. The value must be rounded up, so that a job
between 1 and 1024 octets inclusive must be indicated as being 1K octets,
1025 to 2048 inclusive must be 2K, etc. For a multidoc print job (a job with
multiple documents), the JobKOctetsProcessed value is computed by adding up
the individual documents' number of octets processed so far, then rounding up
to the next K octets value.

The JobKOctetsProcessed attribute describes the progress of the job. This
attribute is intended to be a counter. That is, the JobKOctetsProcessed value
for a job that has not started processing must be 0. When the job's JobState is PROCESSING or PROCESSING_STOPPED, the
JobKOctetsProcessed value is intended to increase as the job is processed; it
indicates the amount of the job that has been processed at the time the Print
Job's attribute set is queried or at the time a print job event is reported.
When the job enters the COMPLETED, CANCELED, or ABORTED states, the
JobKOctetsProcessed value is the final value for the job.

For implementations where multiple copies are produced by the interpreter
with only a single pass over the data, the final value of the
JobKOctetsProcessed attribute must be equal to the value of the JobKOctets attribute. For implementations where multiple copies
are produced by the interpreter by processing the data for each copy, the
final value must be a multiple of the value of the JobKOctets attribute.

IPP Compatibility: The integer value gives the IPP integer value. The
category name returned by getName() gives the IPP attribute
name.

Class JobKOctetsSupported is a printing attribute class, a set of integers,
that gives the supported values for a JobKOctets
attribute. It is restricted to a single contiguous range of integers;
multiple non-overlapping ranges are not allowed. This gives the lower and
upper bounds of the total sizes of print jobs in units of K octets (1024
octets) that the printer will accept.

IPP Compatibility: The JobKOctetsSupported attribute's canonical array
form gives the lower and upper bound for the range of values to be included
in an IPP "job-k-octets-supported" attribute. See class SetOfIntegerSyntax for an
explanation of canonical array form. The category name returned by
getName() gives the IPP attribute name.

Class JobMediaSheets is an integer valued printing attribute class that
specifies the total number of media sheets to be produced for this job.

The JobMediaSheets attribute describes the size of the job. This attribute is
not intended to be a counter; it is intended to be useful routing and
scheduling information if known. The printer may try to compute the
JobMediaSheets attribute's value if it is not supplied in the Print Request.
Even if the client does supply a value for the JobMediaSheets attribute in
the Print Request, the printer may choose to change the value if the printer
is able to compute a value which is more accurate than the client supplied
value. The printer may be able to determine the correct value for the
JobMediaSheets attribute either right at job submission time or at any later
point in time.

Unlike the JobKOctets and JobImpressions attributes, the JobMediaSheets value must include the
multiplicative factors contributed by the number of copies specified by the
Copies attribute and a "number of copies" instruction embedded
in the document data, if any. This difference allows the system administrator
to control the lower and upper bounds of both (1) the size of the document(s)
with JobKOctetsSupported and JobImpressionsSupported and (2) the size of the job
with JobMediaSheetsSupported.

IPP Compatibility: The integer value gives the IPP integer value. The
category name returned by getName() gives the IPP attribute
name.

Class JobMediaSheetsCompleted is an integer valued printing attribute class
that specifies the number of media sheets which have completed marking and
stacking for the entire job so far, whether those sheets have been processed
on one side or on both.

The JobMediaSheetsCompleted attribute describes the progress of the job. This
attribute is intended to be a counter. That is, the JobMediaSheetsCompleted
value for a job that has not started processing must be 0. When the job's
JobState is PROCESSING or PROCESSING_STOPPED, the
JobMediaSheetsCompleted value is intended to increase as the job is
processed; it indicates the amount of the job that has been processed at the
time the Print Job's attribute set is queried or at the time a print job
event is reported. When the job enters the COMPLETED, CANCELED, or ABORTED
states, the JobMediaSheetsCompleted value is the final value for the job.

IPP Compatibility: The integer value gives the IPP integer value. The
category name returned by getName() gives the IPP attribute
name.

Class JobMediaSheetsSupported is a printing attribute class, a set of
integers, that gives the supported values for a JobMediaSheets attribute. It is restricted to a single contiguous range of
integers; multiple non-overlapping ranges are not allowed. This gives the
lower and upper bounds of the total sizes of print jobs in number of media
sheets that the printer will accept.

IPP Compatibility: The JobMediaSheetsSupported attribute's canonical
array form gives the lower and upper bound for the range of values to be
included in an IPP "job-media-sheets-supported" attribute. See class SetOfIntegerSyntax for an
explanation of canonical array form. The category name returned by
getName() gives the IPP attribute name.

Class JobMessageFromOperator is a printing attribute class, a text attribute,
that provides a message from an operator, system administrator, or
"intelligent" process to indicate to the end user the reasons for
modification or other management action taken on a job.

A Print Job's attribute set includes zero instances or one instance of a
JobMessageFromOperator attribute, not more than one instance. A new
JobMessageFromOperator attribute replaces an existing JobMessageFromOperator
attribute, if any. In other words, JobMessageFromOperator is not intended to
be a history log. If it wishes, the client can detect changes to a Print
Job's JobMessageFromOperator attribute and maintain the client's own history
log of the JobMessageFromOperator attribute values.

IPP Compatibility: The string value gives the IPP name value. The
locale gives the IPP natural language. The category name returned by
getName() gives the IPP attribute name.

Class JobName is a printing attribute class, a text attribute, that specifies
the name of a print job. A job's name is an arbitrary string defined by the
client. It does not need to be unique between different jobs. A Print Job's
JobName attribute is set to the value supplied by the client in the Print
Request's attribute set. If, however, the client does not supply a JobName
attribute in the Print Request, the printer, when it creates the Print Job,
must generate a JobName. The printer should generate the value of the Print
Job's JobName attribute from the first of the following sources that produces
a value: (1) the DocumentName attribute of the first (or
only) doc in the job, (2) the URL of the first (or only) doc in the job, if
the doc's print data representation object is a URL, or (3) any other piece
of Print Job specific and/or document content information.

IPP Compatibility: The string value gives the IPP name value. The
locale gives the IPP natural language. The category name returned by
getName() gives the IPP attribute name.

Class JobOriginatingUserName is a printing attribute class, a text
attribute, that contains the name of the end user that submitted the
print job. If possible, the printer sets this attribute to the most
authenticated printable user name that it can obtain from the
authentication service that authenticated the submitted Print Request.
If such is not available, the printer uses the value of the
RequestingUserName
attribute supplied by the client in the Print Request's attribute set.
If no authentication service is available, and the client did not supply
a RequestingUserName attribute,
the printer sets the JobOriginatingUserName attribute to an empty
(zero-length) string.

IPP Compatibility: The string value gives the IPP name value. The
locale gives the IPP natural language. The category name returned by
getName() gives the IPP attribute name.

Class JobPriority is an integer valued printing attribute class that
specifies a print job's priority.

If a JobPriority attribute is specified for a Print Job, it specifies a
priority for scheduling the job. A higher value specifies a higher priority.
The value 1 indicates the lowest possible priority. The value 100 indicates
the highest possible priority. Among those jobs that are ready to print, a
printer must print all jobs with a priority value of n before printing
those with a priority value of n-1 for all n.

If the client does not specify a JobPriority attribute for a Print Job and
the printer does support the JobPriority attribute, the printer must use an
implementation-defined default JobPriority value.

The client can always specify any job priority value from 1 to 100 for a job.
However, a Print Service instance may support fewer than 100 different
job priority levels. If this is the case, the Print Service instance
automatically maps the client-specified job priority value to one of the
supported job priority levels, dividing the 100 job priority values equally
among the available job priority levels.

IPP Compatibility: The integer value gives the IPP integer value. The
category name returned by getName() gives the IPP attribute
name.

Class JobPrioritySupported is an integer valued printing attribute class
that specifies whether a Print Service instance supports the JobPriority attribute and the number of different job priority
levels supported.

The client can always specify any JobPriority value
from 1 to 100 for a job. However, the Print Service instance may support
fewer than 100 different job priority levels. If this is the case, the
Print Service instance automatically maps the client-specified job priority
value to one of the supported job priority levels, dividing the 100 job
priority values equally among the available job priority levels.

IPP Compatibility: The integer value gives the IPP integer value.
The category name returned by getName() gives the IPP
attribute name.

Class JobSheets is a printing attribute class, an enumeration, that
determines which job start and end sheets, if any, must be printed with a
job. Class JobSheets declares keywords for standard job sheets values.
Implementation- or site-defined names for a job sheets attribute may also be
created by defining a subclass of class JobSheets.

The effect of a JobSheets attribute on multidoc print jobs (jobs with
multiple documents) may be affected by the MultipleDocumentHandling job attribute, depending on the meaning of the
particular JobSheets value.

IPP Compatibility:  The category name returned by
getName() is the IPP attribute name.  The
enumeration's integer value is the IPP enum value.  The
toString() method returns the IPP string representation of
the attribute value. For a subclass, the attribute value must be
localized to give the IPP name and natural language values.

JobState is a printing attribute class, an enumeration, that identifies
the current state of a print job. Class JobState defines standard job state
values. A  Print Service implementation only needs to report those job
states which are appropriate for the particular implementation; it does not
have to report every defined job state. The JobStateReasons attribute augments the JobState attribute to give more
detailed information about the job in the given job state.

IPP Compatibility: The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class JobStateReason is a printing attribute class, an enumeration, that
provides additional information about the job's current state, i.e.,
information that augments the value of the job's JobState
attribute. Class JobStateReason defines standard job state reason values. A
Print Service implementation only needs to report those job state
reasons which are appropriate for the particular implementation; it does not
have to report every defined job state reason.

Instances of JobStateReason do not appear in a Print Job's attribute set
directly. Rather, a JobStateReasons attribute appears
in the Print Job's attribute set. The JobStateReasons
attribute contains zero, one, or more than one JobStateReason objects which
pertain to the Print Job's status. The printer adds a JobStateReason object
to the Print Job's JobStateReasons attribute when the
corresponding condition becomes true of the Print Job, and the printer
removes the JobStateReason object again when the corresponding condition
becomes false, regardless of whether the Print Job's overall JobState also changed.

IPP Compatibility: The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class JobStateReasons is a printing attribute class, a set of enumeration
values, that provides additional information about the job's current state,
i.e., information that augments the value of the job's JobState attribute.

Instances of JobStateReason do not appear in a Print
Job's attribute set directly. Rather, a JobStateReasons attribute appears in
the Print Job's attribute set. The JobStateReasons attribute contains zero,
one, or more than one JobStateReason objects which
pertain to the Print Job's status. The printer adds a JobStateReason object to the Print Job's JobStateReasons attribute when the
corresponding condition becomes true of the Print Job, and the printer
removes the JobStateReason object again when the
corresponding condition becomes false, regardless of whether the Print Job's
overall JobState also changed.

Class JobStateReasons inherits its implementation from class java.util.HashSet. Unlike most printing attributes which
are immutable once constructed, class JobStateReasons is designed to be
mutable; you can add JobStateReason objects to an
existing JobStateReasons object and remove them again. However, like class
java.util.HashSet, class JobStateReasons is not
multiple thread safe. If a JobStateReasons object will be used by multiple
threads, be sure to synchronize its operations (e.g., using a synchronized
set view obtained from class java.util.Collections).

IPP Compatibility: The string value returned by each individual JobStateReason object's toString() method gives
the IPP keyword value. The category name returned by getName()
gives the IPP attribute name.

Class Media is a printing attribute class that specifies the
medium on which to print.

Media may be specified in different ways.

 it may be specified by paper source - eg paper tray
 it may be specified by a standard size - eg "A4"
 it may be specified by a name - eg "letterhead"

Each of these corresponds to the IPP "media" attribute.
The current API does not support describing media by characteristics
(eg colour, opacity).
This may be supported in a later revision of the specification.

A Media object is constructed with a value which represents
one of the ways in which the Media attribute can be specified.

IPP Compatibility:  The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class MediaName is a subclass of Media, a printing attribute class (an
enumeration) that specifies the media for a print job as a name.

This attribute can be used instead of specifying MediaSize or MediaTray.

Class MediaName currently declares a few standard media names.
Implementation- or site-defined names for a media name attribute may also
be created by defining a subclass of class MediaName.

IPP Compatibility: MediaName is a representation class for
values of the IPP "media" attribute which names media.

Class MediaPrintableArea is a printing attribute used to distinguish
the printable and non-printable areas of media.

The printable area is specified to be a rectangle, within the overall
dimensions of a media.

Most printers cannot print on the entire surface of the media, due
to printer hardware limitations. This class can be used to query
the acceptable values for a supposed print job, and to request an area
within the constraints of the printable area to be used in a print job.

To query for the printable area, a client must supply a suitable context.
Without specifying at the very least the size of the media being used
no meaningful value for printable area can be obtained.

The attribute is not described in terms of the distance from the edge
of the paper, in part to emphasise that this attribute is not independent
of a particular media, but must be described within the context of a
choice of other attributes. Additionally it is usually more convenient
for a client to use the printable area.

The hardware's minimum margins is not just a property of the printer,
but may be a function of the media size, orientation, media type, and
any specified finishings.
PrintService provides the method to query the supported
values of an attribute in a suitable context :
See  PrintService.getSupportedAttributeValues()

The rectangular printable area is defined thus:
The (x,y) origin is positioned at the top-left of the paper in portrait
mode regardless of the orientation specified in the requesting context.
For example a printable area for A4 paper in portrait or landscape
orientation will have height > width.

A printable area attribute's values are stored
internally as integers in units of micrometers (µm), where 1 micrometer
= 10-6 meter = 1/1000 millimeter = 1/25400 inch. This permits
dimensions to be represented exactly to a precision of 1/1000 mm (= 1
µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in

negative powers of two, this permits dimensions to be represented exactly to
a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch

does not equal an integral number of µm).

IPP Compatibility: MediaPrintableArea is not an IPP attribute.

Class MediaSize is a two-dimensional size valued printing attribute class
that indicates the dimensions of the medium in a portrait orientation, with
the X dimension running along the bottom edge and the Y dimension running
along the left edge. Thus, the Y dimension must be greater than or equal to
the X dimension. Class MediaSize declares many standard media size
values, organized into nested classes for ISO, JIS, North American,
engineering, and other media.

MediaSize is not yet used to specify media. Its current role is
as a mapping for named media (see MediaSizeName).
Clients can use the mapping method
MediaSize.getMediaSizeForName(MediaSizeName)
to find the physical dimensions of the MediaSizeName instances
enumerated in this API. This is useful for clients which need this
information to format & paginate printing.

Class MediaSize.Engineering includes MediaSize values
for engineering media.

Class MediaSize.ISO includes MediaSize values for ISO
media.

Class MediaSize.JIS includes MediaSize values for JIS
(Japanese) media.      *

Class MediaSize.NA includes MediaSize values for North
American media.

Class MediaSize.Other includes MediaSize values for
miscellaneous media.

Class MediaSizeName is a subclass of Media.

This attribute can be used instead of specifying MediaName or MediaTray.

Class MediaSizeName currently declares a few standard media
name values.

IPP Compatibility: MediaSizeName is a representation class for
values of the IPP "media" attribute which names media sizes.
The names of the media sizes correspond to those in the IPP 1.1 RFC
RFC 2911

Class MediaTray is a subclass of Media.
Class MediaTray is a printing attribute class, an enumeration, that
specifies the media tray or bin for the job.
This attribute can be used instead of specifying MediaSize or MediaName.

Class MediaTray declares keywords for standard media kind values.
Implementation- or site-defined names for a media kind attribute may also
be created by defining a subclass of class MediaTray.

IPP Compatibility: MediaTray is a representation class for
values of the IPP "media" attribute which name paper trays.

Class MultipleDocumentHandling is a printing attribute class, an enumeration,
that controls finishing operations and the placement of one or more
print-stream pages into impressions and onto media sheets. When the value of
the Copies attribute exceeds 1, MultipleDocumentHandling also
controls the order in which the copies that result from processing the
documents are produced. This attribute is relevant only for a multidoc print
job consisting of two or more individual docs.

Briefly, MultipleDocumentHandling determines the relationship between the
multiple input (electronic) documents fed into a multidoc print job and the
output (physical) document or documents produced by the multidoc print job.
There are two possibilities:


The multiple input documents are combined into a single output document.
Finishing operations (Finishings),
are performed on this single output
document. The Copies attribute tells how many copies of this
single output document to produce. The MultipleDocumentHandling values
SINGLE_DOCUMENT and SINGLE_DOCUMENT_NEW_SHEET specify two variations of
this  possibility.


The multiple input documents remain separate output documents. Finishing
operations (Finishings),
are performed on each output document
separately. The Copies attribute tells how many copies of each
separate output document to produce. The MultipleDocumentHandling values
SEPARATE_DOCUMENTS_UNCOLLATED_COPIES and SEPARATE_DOCUMENTS_COLLATED_COPIES
specify two variations of this possibility.


In the detailed explanations below, if "a" represents an
instance of document data, then the result of processing the data in
document "a" is a sequence of media sheets represented by
"a(*)".

The standard MultipleDocumentHandling values are:


SINGLE_DOCUMENT. If a print job has multiple
documents -- say, the document data is called a and
b -- then the result of processing all the document data
(a and then b) must be treated as a single sequence
of media sheets for finishing operations; that is, finishing would be
performed on the concatenation of the sequences a(*),b(*). The
printer must not force the data in each document instance to be formatted
onto a new print-stream page, nor to start a new impression on a new media
sheet. If more than one copy is made, the ordering of the sets of media
sheets resulting from processing the document data must be
a(*),b(*),a(*),b(*),..., and the printer object must force
each copy (a(*),b(*)) to start on a new media sheet.


SEPARATE_DOCUMENTS_UNCOLLATED_COPIES. If a print job
has multiple documents -- say, the document data is called a and
b -- then the result of processing the data in each document
instance must be treated as a single sequence of media sheets for finishing
operations; that is, the sets a(*) and b(*) would
each be finished separately. The printer must force each copy of the result
of processing the data in a single document to start on a new media sheet.
If more than one copy is made, the ordering of the sets of media sheets
resulting from processing the document data must be
a(*),a(*),...,b(*),b(*)....


SEPARATE_DOCUMENTS_COLLATED_COPIES. If a print job
has multiple documents -- say, the document data is called a and
b -- then the result of processing the data in each document
instance must be treated as a single sequence of media sheets for finishing
operations; that is, the sets a(*) and b(*) would
each be finished separately. The printer must force each copy of the result
of processing the data in a single document to start on a new media sheet.
If more than one copy is made, the ordering of the sets of media sheets
resulting from processing the document data must be
a(*),b(*),a(*),b(*),....


SINGLE_DOCUMENT_NEW_SHEET. Same as SINGLE_DOCUMENT,
except that the printer must ensure that the first impression of each
document instance in the job is placed on a new media sheet. This value
allows multiple documents to be stapled together with a single staple where
each document starts on a new sheet.


SINGLE_DOCUMENT is the same as SEPARATE_DOCUMENTS_COLLATED_COPIES with
respect to ordering of print-stream pages, but not media sheet generation,
since SINGLE_DOCUMENT will put the first page of the next document on the
back side of a sheet if an odd number of pages have been produced so far
for the job, while SEPARATE_DOCUMENTS_COLLATED_COPIES always forces the
next document or document copy on to a new sheet.

In addition, if a Finishings attribute of
STAPLE is specified, then:


With SINGLE_DOCUMENT, documents a and b are
stapled together as a single document with no regard to new sheets.


With SINGLE_DOCUMENT_NEW_SHEET, documents a and b
are stapled together as a single document, but document b
starts on a new sheet.


With SEPARATE_DOCUMENTS_UNCOLLATED_COPIES and
SEPARATE_DOCUMENTS_COLLATED_COPIES, documents a and
b are stapled separately.


Note: None of these values provide means to produce uncollated
sheets within a document, i.e., where multiple copies of sheet n
are produced before sheet n+1 of the same document.
To specify that, see the SheetCollate attribute.

IPP Compatibility: The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class NumberOfDocuments is an integer valued printing attribute that
indicates the number of individual docs the printer has accepted for this
job, regardless of whether the docs' print data has reached the printer or
not.

IPP Compatibility: The integer value gives the IPP integer value. The
category name returned by getName() gives the IPP attribute
name.

Class NumberOfInterveningJobs is an integer valued printing attribute that
indicates the number of jobs that are ahead of this job in the relative
chronological order of expected time to complete (i.e., the current
scheduled order).

IPP Compatibility: The integer value gives the IPP integer value.
The category name returned by getName() gives the IPP
attribute name.

Class NumberUp is an integer valued printing attribute class that specifies
the number of print-stream pages to impose upon a single side of an
instance of a selected medium. That is, if the NumberUp value is n,
the printer must place n print-stream pages on a single side of
an instance of the
selected medium. To accomplish this, the printer may add some sort of
translation, scaling, or rotation. This attribute primarily controls the
translation, scaling and rotation of print-stream pages.

The effect of a NumberUp attribute on a multidoc print job (a job with
multiple documents) depends on whether all the docs have the same number up
values specified or whether different docs have different number up values
specified, and on the (perhaps defaulted) value of the MultipleDocumentHandling attribute.


If all the docs have the same number up value n specified, then any
value of MultipleDocumentHandling makes
sense, and the printer's processing depends on the MultipleDocumentHandling value:


SINGLE_DOCUMENT -- All the input docs will be combined together into one
output document. Each media impression will consist of nm
 print-stream pages from the output document.


SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together
into one output document. Each media impression will consist of n
print-stream pages from the output document. However, the first impression of
each input doc will always start on a new media sheet; this means the last
impression of an input doc may have fewer than n print-stream pages
 on it.


SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- The input docs will remain separate.
Each media impression will consist of n print-stream pages from the
input doc. Since the input docs are separate, the first impression of each
input doc will always start on a new media sheet; this means the last
impression of an input doc may have fewer than n print-stream pages on
it.


SEPARATE_DOCUMENTS_COLLATED_COPIES -- The input docs will remain separate.
Each media impression will consist of n print-stream pages from the
input doc. Since the input docs are separate, the first impression of each
input doc will always start on a new media sheet; this means the last
impression of an input doc may have fewer than n print-stream pages
on it.



SINGLE_DOCUMENT -- All the input docs will be combined together into one
output document. Each media impression will consist of ni
print-stream pages from the output document, where i is the number of
the input doc corresponding to that point in the output document. When the
next input doc has a different number up value from the previous input doc,
the first print-stream page of the next input doc goes at the start of the
next media impression, possibly leaving fewer than the full number of
print-stream pages on the previous media impression.


SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together
into one output document. Each media impression will consist of n
print-stream pages from the output document. However, the first impression of
each input doc will always start on a new media sheet; this means the last
impression of an input doc may have fewer than n print-stream pages
on it.


SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- The input docs will remain separate.
For input doc i, each media impression will consist of
ni print-stream pages from the input doc. Since the input
docs are separate, the first impression of each input doc will always start
on a new media sheet; this means the last impression of an input doc may have
fewer than ni print-stream pages on it.


SEPARATE_DOCUMENTS_COLLATED_COPIES -- The input docs will remain separate.
For input doc i, each media impression will consist of
ni print-stream pages from the input doc. Since the input
docs are separate, the first impression of each input doc will always start
on a new media sheet; this means the last impression of an input doc may
have fewer than ni print-stream pages on it.


IPP Compatibility: The integer value gives the IPP integer value.
The category name returned by getName() gives the IPP
attribute name.

Class NumberUpSupported is a printing attribute class, a set of integers,
that gives the supported values for a NumberUp attribute.

IPP Compatibility: The NumberUpSupported attribute's canonical array
form gives the lower and upper bound for each range of number-up to be
included in an IPP "number-up-supported" attribute. See class SetOfIntegerSyntax for an
explanation of canonical array form. The category name returned by
getName() gives the IPP attribute name.

Class OrientationRequested is a printing attribute class, an enumeration,
that indicates the desired orientation for printed print-stream pages; it
does not describe the orientation of the client-supplied print-stream
pages.

For some document formats (such as "application/postscript"),
the desired orientation of the print-stream pages is specified within the
document data. This information is generated by a device driver prior to
the submission of the print job. Other document formats (such as
"text/plain") do not include the notion of desired orientation
within the document data. In the latter case it is possible for the printer
to bind the desired orientation to the document data after it has been
submitted. It is expected that a printer would only support the
OrientationRequested attribute for some document formats (e.g.,
"text/plain" or "text/html") but not others (e.g.
"application/postscript"). This is no different from any other
job template attribute, since a print job can always impose constraints
among the values of different job template attributes.
 However, a special mention
is made here since it is very likely that a printer will support the
OrientationRequested attribute for only a subset of the supported document
formats.

IPP Compatibility: The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class OutputDeviceAssigned is a printing attribute class, a text attribute,
that identifies the output device to which the service has assigned this
job. If an output device implements an embedded Print Service instance, the
printer need not set this attribute. If a print server implements a
Print Service instance, the value may be empty (zero- length string) or not
returned until the service assigns an output device to the job. This
attribute is particularly useful when a single service supports multiple
devices (so called "fan-out").

IPP Compatibility: The string value gives the IPP name value. The
locale gives the IPP natural language. The category name returned by
getName() gives the IPP attribute name.

Class PageRanges is a printing attribute class, a set of integers, that
identifies the range(s) of print-stream pages that the Printer object uses
for each copy of each document which are to be printed. Nothing is printed
for any pages identified that do not exist in the document(s). The attribute
is associated with print-stream pages, not application-numbered pages
(for example, the page numbers found in the headers and or footers for
certain word processing applications).

In most cases, the exact pages to be printed will be generated by a device
driver and this attribute would not be required. However, when printing an
archived document which has already been formatted, the end user may elect to
print just a subset of the pages contained in the document. In this case, if
a page range of "n-m" is specified, the first page
to be printed will be page n. All subsequent pages of the document
will be printed through and including page m.

If a PageRanges attribute is not specified for a print job, all pages of
the document will be printed. In other words, the default value for the
PageRanges attribute is always {{1, Integer.MAX_VALUE}}.

The effect of a PageRanges attribute on a multidoc print job (a job with
multiple documents) depends on whether all the docs have the same page ranges
specified or whether different docs have different page ranges specified, and
on the (perhaps defaulted) value of the MultipleDocumentHandling attribute.


If all the docs have the same page ranges specified, then any value of MultipleDocumentHandling makes sense, and the
printer's processing depends on the MultipleDocumentHandling value:


SINGLE_DOCUMENT -- All the input docs will be combined together into one
output document. The specified page ranges of that output document will be
printed.


SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together
into one output document, and the first impression of each input doc will
always start on a new media sheet. The specified page ranges of that output
document will be printed.


SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, the
specified page ranges will be printed.


SEPARATE_DOCUMENTS_COLLATED_COPIES -- For each separate input doc, the
specified page ranges will be printed.



SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, its own
specified page ranges will be printed..


SEPARATE_DOCUMENTS_COLLATED_COPIES -- For each separate input doc, its own
specified page ranges will be printed..



IPP Compatibility: The PageRanges attribute's canonical array form
gives the lower and upper bound for each range of pages to be included in
and IPP "page-ranges" attribute. See class SetOfIntegerSyntax for an
explanation of canonical array form. The category name returned by
getName() gives the IPP attribute name.

Class PagesPerMinute is an integer valued printing attribute that indicates
the nominal number of pages per minute to the nearest whole number which may
be generated by this printer (e.g., simplex, black-and-white). This attribute
is informative, not a service guarantee. Generally, it is the value used in
the marketing literature to describe the device. A value of 0 indicates a
device that takes more than two minutes to process a page.

IPP Compatibility: The integer value gives the IPP integer value. The
category name returned by getName() gives the IPP attribute
name.

Class PagesPerMinuteColor is an integer valued printing attribute that
indicates the nominal number of pages per minute to the nearest whole number
which may be generated by this printer when printing color (e.g., simplex,
color). For purposes of this attribute, "color" means the same as for the
ColorSupported attribute, namely, the device is
capable of any type of color printing at all, including highlight color as
well as full process color. This attribute is informative, not a service
guarantee. Generally, it is the value used in the marketing literature to
describe the color capabilities of this device. A value of 0 indicates a
device that takes more than two minutes to process a page. If a color device
has several color modes, it may use the pages-per- minute value for this
attribute that corresponds to the mode that produces the highest number.

A black and white only printer must not include the PagesPerMinuteColor
attribute in its attribute set or service registration. If this attribute is
present, then the ColorSupported printer description
attribute must also be present and have a value of SUPPORTED.

IPP Compatibility: The integer value gives the IPP integer value. The
category name returned by getName() gives the IPP attribute
name.

Class PDLOverrideSupported is a printing attribute class, an enumeration,
that expresses the printer's ability to attempt to override processing
instructions embedded in documents' print data with processing instructions
specified as attributes outside the print data.

IPP Compatibility: The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class PresentationDirection is a printing attribute class, an enumeration,
that is used in conjunction with the NumberUp attribute to
indicate the layout of multiple print-stream pages to impose upon a
single side of an instance of a selected medium.
This is useful to mirror the text layout conventions of different scripts.
For example, English is "toright-tobottom", Hebrew is "toleft-tobottom"
 and Japanese is usually "tobottom-toleft".

IPP Compatibility:  This attribute is not an IPP 1.1
attribute; it is an attribute in the Production Printing Extension
(PDF)
of IPP 1.1.  The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class PrinterInfo is a printing attribute class, a text attribute, that
provides descriptive information about a printer. This could include things
like: "This printer can be used for printing color transparencies for
HR presentations", or "Out of courtesy for others, please
print only small (1-5 page) jobs at this printer", or even \
"This printer is going away on July 1, 1997, please find a new
printer".

IPP Compatibility: The string value gives the IPP name value. The
locale gives the IPP natural language. The category name returned by
getName() gives the IPP attribute name.

Class PrinterIsAcceptingJobs is a printing attribute class, an enumeration,
that indicates whether the printer is currently able to accept jobs. This
value is independent of the PrinterState and PrinterStateReasons attributes because its value does
not affect the current job; rather it affects future jobs. If the value is
NOT_ACCEPTING_JOBS, the printer will reject jobs even when the PrinterState is IDLE. If value is ACCEPTING_JOBS, the Printer
will accept jobs even when the PrinterState is STOPPED.

IPP Compatibility: The IPP boolean value is "true" for ACCEPTING_JOBS
and "false" for NOT_ACCEPTING_JOBS. The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class PrinterLocation is a printing attribute class, a text attribute, that
identifies the location of the device. This could include things like:
"in Room 123A, second floor of building XYZ".

IPP Compatibility: The string value gives the IPP name value. The
locale gives the IPP natural language. The category name returned by
getName() gives the IPP attribute name.

Class PrinterMakeAndModel is a printing attribute class, a text attribute,
that the make and model of the printer.

IPP Compatibility: The string value gives the IPP name value. The
locale gives the IPP natural language. The category name returned by
getName() gives the IPP attribute name.

Class PrinterMessageFromOperator is a printing attribute class, a text
attribute, that provides a message from an operator, system administrator,
or "intelligent" process to indicate to the end user information about or
status of the printer, such as why it is unavailable or when it is
expected to be available.

A Print Service's attribute set includes zero instances or one instance of
a
PrinterMessageFromOperator attribute, not more than one instance. A new
PrinterMessageFromOperator attribute replaces an existing
PrinterMessageFromOperator attribute, if any. In other words,
PrinterMessageFromOperator is not intended to be a history log.
If it wishes, the client can detect changes to a Print Service's
PrinterMessageFromOperator
attribute and maintain the client's own history log of the
PrinterMessageFromOperator attribute values.

IPP Compatibility: The string value gives the IPP name value. The
locale gives the IPP natural language. The category name returned by
getName() gives the IPP attribute name.

Class PrinterMoreInfo is a printing attribute class, a URI, that is used to
obtain more information about this specific printer. For example, this
could be an HTTP type URI referencing an HTML page accessible to a web
browser. The information obtained from this URI is intended for end user
consumption. Features outside the scope of the Print Service API can be
accessed from this URI.
The information is intended to be specific to this printer instance and
site specific services (e.g. job pricing, services offered, end user
assistance).

In contrast, the PrinterMoreInfoManufacturer attribute is used to find out more information
about this general kind of printer rather than this specific printer.

IPP Compatibility: The string form returned by
toString()  gives the IPP uri value.
The category name returned by getName()
gives the IPP attribute name.

Class PrinterMoreInfoManufacturer is a printing attribute class, a URI,
that is used to obtain more information about this type of device.
The information obtained from this URI is intended for end user
consumption. Features outside the scope of the Print Service API
can be accessed from this URI (e.g.,
latest firmware, upgrades, service proxies, optional features available,
details on color support). The information is intended to be germane to
this kind of printer without regard to site specific modifications or
services.

In contrast, the PrinterMoreInfo attribute is used
to find out more information about this specific printer rather than this
general kind of printer.


IPP Compatibility: The string form returned by
toString() gives the IPP uri value.
The category name returned by getName()
gives the IPP attribute name.

Class PrinterName is a printing attribute class, a text attribute, that
specifies the name of a printer. It is a name that is more end-user friendly
than a URI. An administrator determines a printer's name and sets this
attribute to that name. This name may be the last part of the printer's URI
or it may be unrelated. In non-US-English locales, a name may contain
characters that are not allowed in a URI.

IPP Compatibility: The string value gives the IPP name value. The
locale gives the IPP natural language. The category name returned by
getName() gives the IPP attribute name.

Class PrinterResolution is a printing attribute class that specifies an
exact resolution supported by a printer or to be used for a print job.
This attribute assumes that printers have a small set of device resolutions
at which they can operate rather than a continuum.

PrinterResolution is used in multiple ways:


When a client searches looking for a printer that supports the client's
desired resolution exactly (no more, no less), the client specifies
an instance of class PrinterResolution indicating the exact resolution the
client wants. Only printers supporting that exact resolution will match the
search.


When a client needs to print a job using the client's desired resolution
exactly (no more, no less), the client specifies an instance of class
PrinterResolution as an attribute of the Print Job. This will fail if the
Print Job doesn't support that exact resolution, and Fidelity is set to
true.

If a client wants to locate a printer supporting a resolution
greater than some required minimum, then it may be necessary to exclude
this attribute from a lookup request and to directly query the set of
supported resolutions, and specify the one that most closely meets
the client's requirements.
In some cases this may be more simply achieved by specifying a
PrintQuality attribute which often controls resolution.


IPP Compatibility: The information needed to construct an IPP
"printer-resolution" attribute can be obtained by calling
methods on the PrinterResolution object. The category name returned by
getName() gives the IPP attribute name.

Class PrinterState is a printing attribute class, an enumeration, that
identifies the current state of a printer. Class PrinterState defines
standard printer state values. A Print Service implementation only needs
to report those printer states which are appropriate for the particular
implementation; it does not have to report every defined printer state. The
PrinterStateReasons attribute augments the
PrinterState attribute to give more detailed information about the printer
in  given printer state.

IPP Compatibility: The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class PrinterStateReason is a printing attribute class, an enumeration,
that provides additional information about the printer's current state,
i.e., information that augments the value of the printer's
PrinterState attribute.
Class PrinterStateReason defines standard printer
state reason values. A Print Service implementation only needs to report
those printer state reasons which are appropriate for the particular
implementation; it does not have to report every defined printer state
reason.

Instances of PrinterStateReason do not appear in a Print Service's
attribute set directly.
Rather, a PrinterStateReasons
attribute appears in the Print Service's attribute set. The PrinterStateReasons attribute contains zero, one, or
more than one PrinterStateReason objects which pertain to the
Print Service's status, and each PrinterStateReason object is
associated with a Severity level of REPORT (least severe),
WARNING, or ERROR (most severe). The printer adds a PrinterStateReason
object to the Print Service's
PrinterStateReasons attribute when the
corresponding condition becomes true of the printer, and the printer
removes the PrinterStateReason object again when the corresponding
condition becomes false, regardless of whether the Print Service's overall
PrinterState also changed.

IPP Compatibility:
The string values returned by each individual PrinterStateReason and
associated Severity object's toString()
methods, concatenated together with a hyphen ("-") in
between, gives the IPP keyword value for a PrinterStateReasons.
The category name returned by getName() gives the IPP
attribute name.

Class PrinterStateReasons is a printing attribute class, a set of
enumeration values, that provides additional information about the
printer's current state, i.e., information that augments the value of the
printer's PrinterState attribute.

Instances of PrinterStateReason do not appear in
 a Print Service's attribute set directly. Rather, a PrinterStateReasons
attribute appears in the Print Service's attribute set. The
PrinterStateReasons attribute contains zero, one, or more than one PrinterStateReason objects which pertain to the Print
Service's status, and each PrinterStateReason
object is associated with a Severity level of REPORT
 (least severe), WARNING, or ERROR (most severe). The printer adds a PrinterStateReason object to the Print Service's
PrinterStateReasons attribute when the corresponding condition becomes true
of the printer, and the printer removes the PrinterStateReason object again when the corresponding condition becomes
false, regardless of whether the Print Service's overall
PrinterState also changed.

Class PrinterStateReasons inherits its implementation from class java.util.HashMap. Each entry in the map consists of a
PrinterStateReason object (key) mapping to a
Severity object (value):

Unlike most printing attributes which are immutable once constructed, class
PrinterStateReasons is designed to be mutable; you can add PrinterStateReason objects to an existing
PrinterStateReasons object and remove them again. However, like class
 java.util.HashMap, class PrinterStateReasons is
not multiple thread safe. If a PrinterStateReasons object will be used by
multiple threads, be sure to synchronize its operations (e.g., using a
synchronized map view obtained from class java.util.Collections).

IPP Compatibility: The string values returned by each individual
PrinterStateReason object's and the associated
Severity object's toString() methods,
concatenated
together with a hyphen ("-") in between, gives the IPP keyword
value. The category name returned by getName() gives the IPP
attribute name.

Class PrinterURI is a printing attribute class, a URI, that specifies the
globally unique name of a printer.  If it has such a name, an administrator
determines a printer's URI and sets this attribute to that name.

IPP Compatibility:  This implements the
IPP printer-uri attribute. The string form returned by
toString()  gives the IPP printer-uri value.
The category name returned by getName()
gives the IPP attribute name.

Class PrintQuality is a printing attribute class, an enumeration,
that specifies the print quality that the printer uses for the job.

IPP Compatibility: The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class QueuedJobCount is an integer valued printing attribute that indicates
the number of jobs in the printer whose JobState is either
PENDING, PENDING_HELD, PROCESSING, or PROCESSING_STOPPED.

IPP Compatibility: The integer value gives the IPP integer value.
The category name returned by getName() gives the IPP
attribute name.

Class ReferenceUriSchemesSupported is a printing attribute class
an enumeration, that indicates a "URI scheme," such as "http:" or "ftp:",
that a printer can use to retrieve print data stored at a URI location.
If a printer supports doc flavors with a print data representation class of
"java.net.URL", the printer uses instances of class
ReferenceUriSchemesSupported to advertise the URI schemes it can accept.
The acceptable URI schemes are included as service attributes in the
lookup service; this lets clients search the
for printers that can get print data using a certain URI scheme. The
acceptable URI schemes can also be queried using the capability methods in
interface PrintService. However,
ReferenceUriSchemesSupported attributes are used solely for determining
acceptable URI schemes, they are never included in a doc's,
print request's, print job's, or print service's attribute set.

The Internet Assigned Numbers Authority maintains the
official
list of URI schemes.

Class ReferenceUriSchemesSupported defines enumeration values for widely
used URI schemes. A printer that supports additional URI schemes
can define them in a subclass of class ReferenceUriSchemesSupported.

IPP Compatibility:  The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Class RequestingUserName is a printing attribute class, a text attribute,
that specifies the name of the end user that submitted the print job. A
requesting user name is an arbitrary string defined by the client. The
printer does not put the client-specified RequestingUserName attribute into
the Print Job's attribute set; rather, the printer puts in a JobOriginatingUserName attribute.
This means that services which support specifying a username with this
attribute should also report a JobOriginatingUserName in the job's
attribute set. Note that many print services may have a way to independently
authenticate the user name, and so may state support for a
requesting user name, but in practice will then report the user name
authenticated by the service rather than that specified via this
attribute.

IPP Compatibility: The string value gives the IPP name value. The
locale gives the IPP natural language. The category name returned by
getName() gives the IPP attribute name.

Class Severity is a printing attribute class, an enumeration, that denotes
the severity of a PrinterStateReason attribute.

Instances of Severity do not appear in a Print Service's attribute set
directly. Rather, a PrinterStateReasons
attribute appears in the Print Service's attribute set.
 The PrinterStateReasons attribute contains zero, one, or more than one PrinterStateReason objects which pertain to the Print
Service's status, and each PrinterStateReason
object is associated with a Severity level of REPORT (least severe),
WARNING, or ERROR (most severe).
The printer adds a PrinterStateReason object to the Print Service's
PrinterStateReasons attribute when the
corresponding condition becomes true
of the printer, and the printer removes the PrinterStateReason object again when the corresponding condition becomes
false, regardless of whether the Print Service's overall
PrinterState also changed.

IPP Compatibility:
Severity.toString() returns either "error", "warning", or
"report".  The string values returned by
each individual PrinterStateReason and
associated Severity object's toString()
methods, concatenated together with a hyphen ("-") in
between, gives the IPP keyword value for a PrinterStateReasons.
The category name returned by getName() gives the IPP
attribute name.

Class SheetCollate is a printing attribute class, an enumeration, that
specifies whether or not the media sheets of each copy of each printed
document in a job are to be in sequence, when multiple copies of the document
are specified by the Copies attribute. When SheetCollate is
COLLATED, each copy of each document is printed with the print-stream sheets
in sequence. When SheetCollate is UNCOLLATED, each print-stream sheet is
printed a number of times equal to the value of the Copies
attribute in succession. For example, suppose a document produces two media
sheets as output, Copies is 6, and SheetCollate is UNCOLLATED;
in this case six copies of the first media sheet are printed followed by
six copies of the second media sheet.

Whether the effect of sheet collation is achieved by placing copies of a
document in multiple output bins or in the same output bin with
implementation defined document separation is implementation dependent.
Also whether it is achieved by making multiple passes over the job or by
using an output sorter is implementation dependent.

If a printer does not support the SheetCollate attribute (meaning the client
cannot specify any particular sheet collation), the printer must behave as
though SheetCollate were always set to COLLATED.

The SheetCollate attribute interacts with the MultipleDocumentHandling attribute. The MultipleDocumentHandling attribute describes the collation of entire
documents, and the SheetCollate attribute describes the semantics of
collating individual pages within a document.

The effect of a SheetCollate attribute on a multidoc print job (a job with
multiple documents) depends on whether all the docs have the same sheet
collation specified or whether different docs have different sheet
collations specified, and on the (perhaps defaulted) value of the MultipleDocumentHandling attribute.


If all the docs have the same sheet collation specified, then the following
combinations of SheetCollate and MultipleDocumentHandling are permitted, and the printer reports an error
when the job is submitted if any other combination is specified:


SheetCollate = COLLATED, MultipleDocumentHandling = SINGLE_DOCUMENT -- All the input docs will be
combined into one output document. Multiple copies of the output document
will be produced with pages in collated order, i.e. pages 1, 2, 3, . . .,
1, 2, 3, . . .


SheetCollate = COLLATED, MultipleDocumentHandling = SINGLE_DOCUMENT_NEW_SHEET -- All the input docs
will be combined into one output document, and the first impression of each
input doc will always start on a new media sheet. Multiple copies of the
output document will be produced with pages in collated order, i.e. pages
1, 2, 3, . . ., 1, 2, 3, . . .


SheetCollate = COLLATED, MultipleDocumentHandling = SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each
input doc will remain a separate output document. Multiple copies of each
output document (call them A, B, . . .) will be produced with each document's
pages in collated order, but the documents themselves in uncollated order,
i.e. pages A1, A2, A3, . . ., A1, A2, A3, . . ., B1, B2, B3, . . ., B1, B2,
B3, . . .


SheetCollate = COLLATED, MultipleDocumentHandling = SEPARATE_DOCUMENTS_COLLATED_COPIES -- Each input
doc will remain a separate output document. Multiple copies of each output
document (call them A, B, . . .) will be produced with each document's pages
in collated order, with the documents themselves also in collated order, i.e.
pages A1, A2, A3, . . ., B1, B2, B3, . . ., A1, A2, A3, . . ., B1, B2, B3,
. . .


SheetCollate = UNCOLLATED, MultipleDocumentHandling = SINGLE_DOCUMENT -- All the input docs will be
combined into one output document. Multiple copies of the output document
will be produced with pages in uncollated order, i.e. pages 1, 1, . . .,
2, 2, . . ., 3, 3, . . .


SheetCollate = UNCOLLATED, MultipleDocumentHandling = SINGLE_DOCUMENT_NEW_SHEET -- All the input docs
will be combined into one output document, and the first impression of each
input doc will always start on a new media sheet. Multiple copies of the
output document will be produced with pages in uncollated order, i.e. pages
1, 1, . . ., 2, 2, . . ., 3, 3, . . .


SheetCollate = UNCOLLATED, MultipleDocumentHandling = SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each
input doc will remain a separate output document. Multiple copies of each
output document (call them A, B, . . .) will be produced with each document's
pages in uncollated order, with the documents themselves also in uncollated
order, i.e. pages A1, A1, . . ., A2, A2, . . ., A3, A3, . . ., B1, B1, . . .,
B2, B2, . . ., B3, B3, . . .



If different docs have different sheet collations specified, then only one
value of MultipleDocumentHandling is
permitted, and the printer reports an error when the job is submitted if any
other value is specified:


MultipleDocumentHandling =
SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each input doc will remain a separate
output document. Multiple copies of each output document (call them A, B,
. . .) will be produced with each document's pages in collated or uncollated
order as the corresponding input doc's SheetCollate attribute specifies, and
with the documents themselves in uncollated order. If document A had
SheetCollate = UNCOLLATED and document B had SheetCollate = COLLATED, the
following pages would be produced: A1, A1, . . ., A2, A2, . . ., A3, A3,
. . ., B1, B2, B3, . . ., B1, B2, B3, . . .



IPP Compatibility: SheetCollate is not an IPP attribute at present.

Class Sides is a printing attribute class, an enumeration, that specifies
how print-stream pages are to be imposed upon the sides of an instance of a
selected medium, i.e., an impression.

The effect of a Sides attribute on a multidoc print job (a job with multiple
documents) depends on whether all the docs have the same sides values
specified or whether different docs have different sides values specified,
and on the (perhaps defaulted) value of the MultipleDocumentHandling attribute.


If all the docs have the same sides value n specified, then any value
of MultipleDocumentHandling makes sense,
and the printer's processing depends on the MultipleDocumentHandling value:


SINGLE_DOCUMENT -- All the input docs will be combined together into one
output document. Each media sheet will consist of n impressions from
the output document.


SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together
into one output document. Each media sheet will consist of n
impressions from the output document. However, the first impression of each
input doc will always start on a new media sheet; this means the last media
sheet of an input doc may have only one impression on it.


SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- The input docs will remain separate.
Each media sheet will consist of n impressions from the input doc.
Since the input docs are separate, the first impression of each input doc
will always start on a new media sheet; this means the last media sheet of
an input doc may have only one impression on it.


SEPARATE_DOCUMENTS_COLLATED_COPIES -- The input docs will remain separate.
Each media sheet will consist of n impressions from the input doc.
Since the input docs are separate, the first impression of each input doc
will always start on a new media sheet; this means the last media sheet of
an input doc may have only one impression on it.




SINGLE_DOCUMENT -- All the input docs will be combined together into one
output document. Each media sheet will consist of ni
impressions from the output document, where i is the number of the
input doc corresponding to that point in the output document. When the next
input doc has a different sides value from the previous input doc, the first
print-stream page of the next input doc goes at the start of the next media
sheet, possibly leaving only one impression on the previous media sheet.


SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together
into one output document. Each media sheet will consist of n
impressions from the output document. However, the first impression of each
input doc will always start on a new media sheet; this means the last
impression of an input doc may have only one impression on it.


SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- The input docs will remain separate.
For input doc i, each media sheet will consist of ni
impressions from the input doc. Since the input docs are separate, the first
impression of each input doc will always start on a new media sheet; this
means the last media sheet of an input doc may have only one impression on
it.


SEPARATE_DOCUMENTS_COLLATED_COPIES -- The input docs will remain separate.
For input doc i, each media sheet will consist of ni
impressions from the input doc. Since the input docs are separate, the first
impression of each input doc will always start on a new media sheet; this
means the last media sheet of an input doc may have only one impression on
it.



IPP Compatibility: The category name returned by
getName() is the IPP attribute name.  The enumeration's
integer value is the IPP enum value.  The toString() method
returns the IPP string representation of the attribute value.

Interface SupportedValuesAttribute is a tagging interface which a printing
attribute class implements to indicate the attribute describes the supported
values for another attribute. For example, if a Print Service instance
supports the Copies
attribute, the Print Service instance will have a CopiesSupported attribute,
which is a SupportedValuesAttribute giving the legal values a client may
specify for the Copies
attribute.

Class TextSyntax is an abstract base class providing the common
implementation of all attributes whose value is a string. The text attribute
includes a locale to indicate the natural language. Thus, a text attribute
always represents a localized string. Once constructed, a text attribute's
value is immutable.

Thrown to indicate that the requested operation cannot be performed
because the set is unmodifiable.

Class URISyntax is an abstract base class providing the common
implementation of all attributes whose value is a Uniform Resource
Identifier (URI). Once constructed, a URI attribute's value is immutable.

Interface AttributeException is a mixin interface which a subclass of
PrintException can implement to report an error condition
involving one or more printing attributes that a particular Print
Service instance does not support. Either the attribute is not supported at
all, or the attribute is supported but the particular specified value is not
supported. The Print Service API does not define any print exception
classes that implement interface AttributeException, that being left to the
Print Service implementor's discretion.

This interface is used by a printing application to cancel a
print job.  This interface extends DocPrintJob.  A
DocPrintJob implementation returned from a print
service implements this interface if the print job can be
cancelled.  Before trying to cancel
a print job, the client needs to test if the
DocPrintJob object returned from the print service
actually implements this interface.  Clients should never assume
that a DocPrintJob implements this interface.  A
print service might support cancellation only for certain types
of print data and representation class names.  This means that
only some of the DocPrintJob objects returned from
a service will implement this interface.

Service implementors are encouraged to implement this optional interface
and to deliver a javax.print.event.PrintJobEvent.JOB_CANCELLED event
to any listeners if a job is successfully cancelled with an
implementation of this interface. Services should also note that an
implementation of this method may be made from a separate client thread
than that which made the print request.  Thus the implementation of
this interface must be made thread safe.

Interface Doc specifies the interface for an object that supplies one piece
of print data for a Print Job. "Doc" is a short, easy-to-pronounce term
that means "a piece of print data." The client passes to the Print Job an
object that implements interface Doc, and the Print Job calls methods on
that object to obtain the print data. The Doc interface lets a Print Job:


Determine the format, or "doc flavor" (class DocFlavor),
in which the print data is available. A doc flavor designates the print
data format (a MIME type) and the representation class of the object
from which the print data comes.


Obtain the print data representation object, which is an instance of the
doc flavor's representation class. The Print Job can then obtain the actual
print data from the representation object.


Obtain the printing attributes that specify additional characteristics of
the doc or that specify processing instructions to be applied to the doc.
Printing attributes are defined in package javax.print.attribute. The doc returns its printing attributes stored in
an javax.print.attribute.DocAttributeSet.


Each method in an implementation of interface Doc is permitted always to
return the same object each time the method is called.
This has implications
for a Print Job or other caller of a doc object whose print data
representation object "consumes" the print data as the caller obtains the
print data, such as a print data representation object which is a stream.
Once the Print Job has called getPrintData() and obtained the stream, any further calls to
getPrintData() will return the same
stream object upon which reading may already be in progress, not a new
stream object that will re-read the print data from the beginning. Specifying
a doc object to behave this way simplifies the implementation of doc objects,
and is justified on the grounds that a particular doc is intended to convey
print data only to one Print Job, not to several different Print Jobs. (To
convey the same print data to several different Print Jobs, you have to
create several different doc objects on top of the same print data source.)

Interface Doc affords considerable implementation flexibility. The print data
might already be in existence when the doc object is constructed. In this
case the objects returned by the doc's methods can be supplied to the doc's
constructor, be stored in the doc ahead of time, and simply be returned when
called for. Alternatively, the print data might not exist yet when the doc
object is constructed. In this case the doc object might provide a "lazy"
implementation that generates the print data representation object (and/or
the print data) only when the Print Job calls for it (when the Print Job
calls the getPrintData() method).

There is no restriction on the number of client threads that may be
simultaneously accessing the same doc. Therefore, all implementations of
interface Doc must be designed to be multiple thread safe.

However there can only be one consumer of the print data obtained from a
Doc.

If print data is obtained from the client as a stream, by calling Doc's
getReaderForText() or getStreamForBytes()
methods, or because the print data source is already an InputStream or
Reader, then the print service should always close these streams for the
client on all job completion conditions. With the following caveat.
If the print data is itself a stream, the service will always close it.
If the print data is otherwise something that can be requested as a stream,
the service will only close the stream if it has obtained the stream before
terminating. That is, just because a print service might request data as
a stream does not mean that it will, with the implications that Doc
implementors which rely on the service to close them should create such
streams only in response to a request from the service.

Class DocFlavor encapsulates an object that specifies the
format in which print data is supplied to a DocPrintJob.
"Doc" is a short, easy-to-pronounce term that means "a piece of print data."
The print data format, or "doc flavor", consists of two things:


MIME type. This is a Multipurpose Internet Mail Extensions (MIME)
media type (as defined in RFC
2045 and RFC 2046)
that specifies how the print data is to be interpreted.
The charset of text data should be the IANA MIME-preferred name, or its
canonical name if no preferred name is specified. Additionally a few
historical names supported by earlier versions of the Java platform may
be recognized.
See
character encodings for more information on the character encodings
supported on the Java platform.


Representation class name. This specifies the fully-qualified name of
the class of the object from which the actual print data comes, as returned
by the Class.getName() method.
(Thus the class name for byte[] is "[B", for
char[] it is "[C".)


A DocPrintJob obtains its print data by means of interface
Doc. A Doc object lets the DocPrintJob
determine the doc flavor the client can supply.  A Doc object
also lets the DocPrintJob obtain an instance of the doc flavor's
representation class, from which the DocPrintJob then obtains
the actual print data.


Client Formatted Print Data
There are two broad categories of print data, client formatted print data
and service formatted print data.

For client formatted print data, the client determines or knows the
print data format.
For example the client may have a JPEG encoded image, a URL for
HTML code, or a disk file containing plain text in some encoding,
possibly obtained from an external source, and
requires a way to describe the data format to the print service.

The doc flavor's representation class is a conduit for the JPS
DocPrintJob to obtain a sequence of characters or
bytes from the client. The
doc flavor's MIME type is one of the standard media types telling how to
interpret the sequence of characters or bytes. For a list of standard media
types, see the Internet Assigned Numbers Authority's (IANA's) Media Types
Directory. Interface Doc provides two utility operations,
getReaderForText and
getStreamForBytes(), to help a
Doc object's client extract client formatted print data.

For client formatted print data, the print data representation class is
typically one of the following (although other representation classes are
permitted):


Character array (char[]) -- The print data consists of the
Unicode characters in the array.


String  --
The print data consists of the Unicode characters in the string.


Character stream (java.io.Reader)
-- The print data consists of the Unicode characters read from the stream
up to the end-of-stream.


Byte array (byte[]) -- The print data consists of the bytes in
the array. The bytes are encoded in the character set specified by the doc
flavor's MIME type. If the MIME type does not specify a character set, the
default character set is US-ASCII.


Byte stream (java.io.InputStream) --
The print data consists of the bytes read from the stream up to the
end-of-stream. The bytes are encoded in the character set specified by the
doc flavor's MIME type. If the MIME type does not specify a character set,
the default character set is US-ASCII.


Uniform Resource Locator (URL)
-- The print data consists of the bytes read from the URL location.
The bytes are encoded in the character set specified by the doc flavor's
MIME type. If the MIME type does not specify a character set, the default
character set is US-ASCII.

When the representation class is a URL, the print service itself accesses
and downloads the document directly from its URL address, without involving
the client. The service may be some form of network print service which
is executing in a different environment.
This means you should not use a URL print data flavor to print a
document at a restricted URL that the client can see but the printer cannot
see. This also means you should not use a URL print data flavor to print a
document stored in a local file that is not available at a URL
accessible independently of the client.
For example, a file that is not served up by an HTTP server or FTP server.
To print such documents, let the client open an input stream on the URL
or file and use an input stream data flavor.



Default and Platform Encodings

For byte print data where the doc flavor's MIME type does not include a
charset parameter, the Java Print Service instance assumes the
US-ASCII character set by default. This is in accordance with
RFC 2046, which says the
default character set is US-ASCII. Note that US-ASCII is a subset of
UTF-8, so in the future this may be widened if a future RFC endorses
UTF-8 as the default in a compatible manner.

Also note that this is different than the behaviour of the Java runtime
when interpreting a stream of bytes as text data. That assumes the
default encoding for the user's locale. Thus, when spooling a file in local
encoding to a Java Print Service it is important to correctly specify
the encoding. Developers working in the English locales should
be particularly conscious of this, as their platform encoding corresponds
to the default mime charset. By this coincidence that particular
case may work without specifying the encoding of platform data.

Every instance of the Java virtual machine has a default character encoding
determined during virtual-machine startup and typically depends upon the
locale and charset being used by the underlying operating system.
In a distributed environment there is no guarantee that two VM share
the same default encoding. Thus clients which want to stream platform
encoded text data from the host platform to a Java Print Service instance
must explicitly declare the charset and not rely on defaults.

The preferred form is the official IANA primary name for an encoding.
Applications which stream text data should always specify the charset
in the mime type, which necessitates obtaining the encoding of the host
platform for data (eg files) stored in that platform's encoding.
A CharSet which corresponds to this and is suitable for use in a
mime-type for a DocFlavor can be obtained
from DocFlavor.hostEncoding
This may not always be the primary IANA name but is guaranteed to be
understood by this VM.
For common flavors, the pre-defined *HOST DocFlavors may be used.


See
character encodings for more information on the character encodings
supported on the Java platform.


Recommended DocFlavors

The Java Print Service API does not define any mandatorily supported
DocFlavors.
However, here are some examples of MIME types that a Java Print Service
instance might support for client formatted print data.
Nested classes inside class DocFlavor declare predefined static
constant DocFlavor objects for these example doc flavors; class DocFlavor's
constructor can be used to create an arbitrary doc flavor.

Preformatted text



 MIME-TypeDescription


"text/plain"
Plain text in the default character set (US-ASCII)


"text/plain; charset=xxx"
Plain text in character set xxx


"text/html"
HyperText Markup Language in the default character set (US-ASCII)


"text/html; charset=xxx"
HyperText Markup Language in character set xxx



In general, preformatted text print data is provided either in a character
oriented representation class (character array, String, Reader) or in a
byte oriented representation class (byte array, InputStream, URL).

 Preformatted page description language (PDL) documents



 MIME-TypeDescription


"application/pdf"
Portable Document Format document


"application/postscript"
PostScript document


"application/vnd.hp-PCL"
Printer Control Language document



In general, preformatted PDL print data is provided in a byte oriented
representation class (byte array, InputStream, URL).

 Preformatted images



 MIME-TypeDescription



"image/gif"
Graphics Interchange Format image


"image/jpeg"
Joint Photographic Experts Group image


"image/png"
Portable Network Graphics image



In general, preformatted image print data is provided in a byte oriented
representation class (byte array, InputStream, URL).

 Preformatted autosense print data



 MIME-TypeDescription



"application/octet-stream"
The print data format is unspecified (just an octet stream)


The printer decides how to interpret the print data; the way this
"autosensing" works is implementation dependent. In general, preformatted
autosense print data is provided in a byte oriented representation class
(byte array, InputStream, URL).



Service Formatted Print Data

For service formatted print data, the Java Print Service instance
determines the print data format. The doc flavor's representation class
denotes an interface whose methods the DocPrintJob invokes to
determine the content to be printed -- such as a renderable image
interface or a Java printable interface.
The doc flavor's MIME type is the special value
"application/x-java-jvm-local-objectref" indicating the client
will supply a reference to a Java object that implements the interface
named as the representation class.
This MIME type is just a placeholder; what's
important is the print data representation class.

For service formatted print data, the print data representation class is
typically one of the following (although other representation classes are
permitted). Nested classes inside class DocFlavor declare predefined static
constant DocFlavor objects for these example doc flavors; class DocFlavor's
constructor can be used to create an arbitrary doc flavor.


Renderable image object -- The client supplies an object that implements
interface
RenderableImage. The
printer calls methods
in that interface to obtain the image to be printed.


Printable object -- The client supplies an object that implements interface
Printable.
The printer calls methods in that interface to obtain the pages to be
printed, one by one.
For each page, the printer supplies a graphics context, and whatever the
client draws in that graphics context gets printed.


Pageable object -- The client supplies an object that implements interface
Pageable. The printer calls
methods in that interface to obtain the pages to be printed, one by one.
For each page, the printer supplies a graphics context, and whatever
the client draws in that graphics context gets printed.





Pre-defined Doc Flavors
A Java Print Service instance is not required to support the
following print data formats and print data representation classes.  In
fact, a developer using this class should never assume that a
particular print service supports the document types corresponding to
these pre-defined doc flavors.  Always query the print service
to determine what doc flavors it supports.  However,
developers who have print services that support these doc flavors are
encouraged to refer to the predefined singleton instances created here.


Plain text print data provided through a byte stream. Specifically, the
following doc flavors are recommended to be supported:
·
("text/plain", "java.io.InputStream")
·
("text/plain; charset=us-ascii", "java.io.InputStream")
·
("text/plain; charset=utf-8", "java.io.InputStream")


Renderable image objects. Specifically, the following doc flavor is
recommended to be supported:
·
("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")


A Java Print Service instance is allowed to support any other doc flavors
(or none) in addition to the above mandatory ones, at the implementation's
choice.

Support for the above doc flavors is desirable so a printing client can rely
on being able to print on any JPS printer, regardless of which doc flavors
the printer supports. If the printer doesn't support the client's preferred
doc flavor, the client can at least print plain text, or the client can
convert its data to a renderable image and print the image.

Furthermore, every Java Print Service instance must fulfill these
requirements for processing plain text print data:


The character pair carriage return-line feed (CR-LF) means
"go to column 1 of the next line."

A carriage return (CR) character standing by itself means
"go to column 1 of the next line."

A line feed (LF) character standing by itself means
"go to column 1 of the next line."



The client must itself perform all plain text print data formatting not
addressed by the above requirements.

Design Rationale

Class DocFlavor in package javax.print.data is similar to class
DataFlavor. Class
DataFlavor
is not used in the Java Print Service (JPS) API
for three reasons which are all rooted in allowing the JPS API to be
shared by other print services APIs which may need to run on Java profiles
which do not include all of the Java Platform, Standard Edition.


The JPS API is designed to be used in Java profiles which do not support
AWT.


The implementation of class java.awt.datatransfer.DataFlavor
does not guarantee that equivalent data flavors will have the same
serialized representation. DocFlavor does, and can be used in services
which need this.


The implementation of class java.awt.datatransfer.DataFlavor
includes a human presentable name as part of the serialized representation.
This is not appropriate as part of a service matching constraint.


Class DocFlavor's serialized representation uses the following
canonical form of a MIME type string. Thus, two doc flavors with MIME types
that are not identical but that are equivalent (that have the same
canonical form) may be considered equal.

 The media type, media subtype, and parameters are retained, but all
     comments and whitespace characters are discarded.
 The media type, media subtype, and parameter names are converted to
     lowercase.
 The parameter values retain their original case, except a charset
     parameter value for a text media type is converted to lowercase.
 Quote characters surrounding parameter values are removed.
 Quoting backslash characters inside parameter values are removed.
 The parameters are arranged in ascending order of parameter name.


Class DocFlavor's serialized representation also contains the
fully-qualified class name of the representation class
(a String object), rather than the representation class itself
(a Class object). This allows a client to examine the doc flavors a
Java Print Service instance supports without having
to load the representation classes, which may be problematic for
limited-resource clients.

Class DocFlavor.BYTE_ARRAY provides predefined static constant
DocFlavor objects for example doc flavors using a byte array
(byte[]) as the print data representation class.

Class DocFlavor.CHAR_ARRAY provides predefined static constant
DocFlavor objects for example doc flavors using a character array
(char[]) as the print data representation class. As such,
the character set is Unicode.

Class DocFlavor.INPUT_STREAM provides predefined static constant
DocFlavor objects for example doc flavors using a byte stream (java.io.InputStream) as the print
data representation class.

Class DocFlavor.READER provides predefined static constant DocFlavor
objects for example doc flavors using a character stream (java.io.Reader) as the print data
representation class. As such, the character set is Unicode.

Class DocFlavor.SERVICE_FORMATTED provides predefined static constant
DocFlavor objects for example doc flavors for service formatted print
data.

Class DocFlavor.STRING provides predefined static constant DocFlavor
objects for example doc flavors using a string (java.lang.String) as the print data representation class.
As such, the character set is Unicode.

Class DocFlavor.URL provides predefined static constant DocFlavor
objects.
For example doc flavors using a Uniform Resource Locator (java.net.URL) as the print data
representation  class.

This interface represents a print job that can print a specified
document with a set of job attributes.  An object implementing
this interface is obtained from a print service.

Class PrintEvent is the super class of all Print Service API events.

An abstract adapter class for receiving print job events.
The methods in this class are empty.
This class exists as a convenience for creating listener objects.
Extend this class to create a PrintJobEvent listener and override
the methods for the events of interest.  Unlike the
ComponentListener
interface, this abstract interface provides null methods so that you
only need to define the methods you need, rather than all of the methods.

Class PrintJobAttributeEvent encapsulates an event a PrintService
reports to let the client know that one or more printing attributes for a
PrintJob have changed.

Implementations of this interface are attached to a
DocPrintJob to monitor
the status of attribute changes associated with the print job.

Class PrintJobEvent encapsulates common events a print job
reports to let a listener know of progress in the processing of the
DocPrintJob.

Implementations of this listener interface should be attached to a
DocPrintJob to monitor the status of
the printer job.
These callback methods may be invoked on the thread processing the
print job, or a service created notification thread. In either case
the client should not perform lengthy processing in these callbacks.

Class PrintServiceAttributeEvent encapsulates an event a
Print Service instance reports to let the client know of
changes in the print service state.

Implementations of this listener interface are attached to a
PrintService to monitor
the status of the print service.

To monitor a particular job see PrintJobListener and
PrintJobAttributeListener.

Interface FlavorException is a mixin interface which a subclass of PrintException can implement to report an error condition
involving a doc flavor or flavors (class DocFlavor). The Print Service API does not define any print exception
classes that implement interface FlavorException, that being left to the
Print Service implementor's discretion.

 void processMultiDoc(MultiDoc theMultiDoc) {

     MultiDoc current = theMultiDoc;

     while (current != null) {
         processDoc (current.getDoc());
         current = current.next();
     }
 }

Interface MultiDoc specifies the interface for an object that supplies more
than one piece of print data for a Print Job. "Doc" is a short,
easy-to-pronounce term that means "a piece of print data," and a "multidoc"
is a group of several docs. The client passes to the Print Job an object
that implements interface MultiDoc, and the Print Job calls methods on
 that object to obtain the print data.

Interface MultiDoc provides an abstraction similar to a "linked list" of
docs. A multidoc object is like a node in the linked list, containing the
current doc in the list and a pointer to the next node (multidoc) in the
list. The Print Job can call the multidoc's getDoc() method to get the current doc. When it's ready to go
on to the next doc, the Print Job can call the multidoc's next() method to get the next multidoc, which contains the
next doc. So Print Job code for accessing a multidoc might look like this:


     void processMultiDoc(MultiDoc theMultiDoc) {

         MultiDoc current = theMultiDoc;

         while (current != null) {
             processDoc (current.getDoc());
             current = current.next();
         }
     }

Of course, interface MultiDoc can be implemented in any way that fulfills
the contract; it doesn't have to use a linked list in the implementation.

To get all the print data for a multidoc print job, a Print Service
proxy could use either of two patterns:


The interleaved pattern: Get the doc from the current multidoc. Get
the print data representation object from the current doc. Get all the print
data from the print data representation object. Get the next multidoc from
the current multidoc, and repeat until there are no more. (The code example
above uses the interleaved pattern.)


The all-at-once pattern: Get the doc from the current multidoc, and
save the doc in a list. Get the next multidoc from the current multidoc, and
repeat until there are no more. Then iterate over the list of saved docs. Get
the print data representation object from the current doc. Get all the print
data from the print data representation object. Go to the next doc in the
list, and repeat until there are no more.

Now, consider a printing client that is generating print data on the fly and
does not have the resources to store more than one piece of print data at a
time. If the print service proxy used the all-at-once pattern to get the
print data, it would pose a problem for such a client; the client would have
to keep all the docs' print data around until the print service proxy comes
back and asks for them, which the client is not able to do. To work with such
a client, the print service proxy must use the interleaved pattern.

To address this problem, and to simplify the design of clients providing
multiple docs to a Print Job, every Print Service proxy that supports
multidoc print jobs is required to access a MultiDoc object using the
interleaved pattern. That is, given a MultiDoc object, the print service
proxy will call getDoc() one or more times
until it successfully obtains the current Doc object. The print service proxy
will then obtain the current doc's print data, not proceeding until all the
print data is obtained or an unrecoverable error occurs. If it is able to
continue, the print service proxy will then call next() one or more times until it successfully obtains either
the next MultiDoc object or an indication that there are no more. An
implementation of interface MultiDoc can assume the print service proxy will
follow this interleaved pattern; for any other pattern of usage, the MultiDoc
implementation's behavior is unspecified.

There is no restriction on the number of client threads that may be
simultaneously accessing the same multidoc. Therefore, all implementations of
interface MultiDoc must be designed to be multiple thread safe. In fact, a
client thread could be adding docs to the end of the (conceptual) list while
a Print Job thread is simultaneously obtaining docs from the beginning of the
list; provided the multidoc object synchronizes the threads properly, the two
threads will not interfere with each other

Obtained from a MultiDocPrintService, a MultiDocPrintJob can print a
specified collection of documents as a single print job with a set of
job attributes.

Interface MultiPrintService is the factory for a MultiDocPrintJob.
A MultiPrintService
describes the capabilities of a Printer and can be queried regarding
a printer's supported attributes.

Class PrintException encapsulates a printing-related error condition that
occurred while using a Print Service instance. This base class
furnishes only a string description of the error. Subclasses furnish more
detailed information if applicable.

Interface PrintService is the factory for a DocPrintJob. A PrintService
describes the capabilities of a Printer and can be queried regarding
a printer's supported attributes.

Example:


  DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
  PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
  aset.add(MediaSizeName.ISO_A4);
  PrintService[] pservices =
                PrintServiceLookup.lookupPrintServices(flavor, aset);
  if (pservices.length > 0) {
      DocPrintJob pj = pservices[0].createPrintJob();
      try {
          FileInputStream fis = new FileInputStream("test.ps");
          Doc doc = new SimpleDoc(fis, flavor, null);
          pj.print(doc, aset);
       } catch (FileNotFoundException fe) {
       } catch (PrintException e) {
       }
  }

Implementations of this class provide lookup services for
print services (typically equivalent to printers) of a particular type.

Multiple implementations may be installed concurrently.
All implementations must be able to describe the located printers
as instances of a PrintService.
Typically implementations of this service class are located
automatically in JAR files (see the SPI JAR file specification).
These classes must be instantiable using a default constructor.
Alternatively applications may explicitly register instances
at runtime.

Applications use only the static methods of this abstract class.
The instance methods are implemented by a service provider in a subclass
and the unification of the results from all installed lookup classes
are reported by the static methods of this class when called by
the application.

A PrintServiceLookup implementor is recommended to check for the
SecurityManager.checkPrintJobAccess() to deny access to untrusted code.
Following this recommended policy means that untrusted code may not
be able to locate any print services. Downloaded applets are the most
common example of untrusted code.

This check is made on a per lookup service basis to allow flexibility in
the policy to reflect the needs of different lookup services.

Services which are registered by registerService(PrintService)
will not be included in lookup results if a security manager is
installed and its checkPrintJobAccess() method denies access.

This class is a collection of UI convenience methods which provide a
 graphical user dialog for browsing print services looked up through the Java
 Print Service API.

 The dialogs follow a standard pattern of acting as a continue/cancel option
for a user as well as allowing the user to select the print service to use
and specify choices such as paper size and number of copies.


 The dialogs are designed to work with pluggable print services though the
 public APIs of those print services.

 If a print service provides any vendor extensions these may be made
 accessible to the user through a vendor supplied tab panel Component.
 Such a vendor extension is encouraged to use Swing! and to support its
 accessibility APIs.
 The vendor extensions should return the settings as part of the
 AttributeSet.
 Applications which want to preserve the user settings should use those
 settings to specify the print job.
 Note that this class is not referenced by any other part of the Java
 Print Service and may not be included in profiles which cannot depend
 on the presence of the AWT packages.

Services may optionally provide UIs which allow different styles
of interaction in different roles.
One role may be end-user browsing and setting of print options.
Another role may be administering the print service.

Although the Print Service API does not presently provide standardised
support for administering a print service, monitoring of the print
service is possible and a UI may provide for private update mechanisms.

The basic design intent is to allow applications to lazily locate and
initialize services only when needed without any API dependencies
except in an environment in which they are used.

Swing UIs are preferred as they provide a more consistent L&F
and can support accessibility APIs.

Example usage:


 ServiceUIFactory factory = printService.getServiceUIFactory();
 if (factory != null) {
     JComponent swingui = (JComponent)factory.getUI(
                                        ServiceUIFactory.MAIN_UIROLE,
                                        ServiceUIFactory.JCOMPONENT_UI);
     if (swingui != null) {
         tabbedpane.add("Custom UI", swingui);
     }
 }

This class is an implementation of interface Doc that can
be used in many common printing requests.
It can handle all of the presently defined "pre-defined" doc flavors
defined as static variables in the DocFlavor class.

In particular this class implements certain required semantics of the
Doc specification as follows:

constructs a stream for the service if requested and appropriate.
ensures the same object is returned for each call on a method.
ensures multiple threads can access the Doc
performs some validation of that the data matches the doc flavor.

Clients who want to re-use the doc object in other jobs,
or need a MultiDoc will not want to use this class.

If the print data is a stream, or a print job requests data as a
stream, then SimpleDoc does not monitor if the service
properly closes the stream after data transfer completion or job
termination.
Clients may prefer to use provide their own implementation of doc that
adds a listener to monitor job completion and to validate that
resources such as streams are freed (ie closed).

This class extends PrintService and represents a
 print service that prints data in different formats to a
 client-provided output stream.
 This is principally intended for services where
 the output format is a document type suitable for viewing
 or archiving.
 The output format must be declared as a mime type.
 This is equivalent to an output document flavor where the
 representation class is always "java.io.OutputStream"
 An instance of the StreamPrintService class is
 obtained from a StreamPrintServiceFactory instance.

 Note that a StreamPrintService is different from a
 PrintService, which supports a
 Destination
 attribute.  A StreamPrintService always requires an output
 stream, whereas a PrintService optionally accepts a
 Destination. A StreamPrintService
 has no default destination for its formatted output.
 Additionally a StreamPrintService is expected to generate
output in
 a format useful in other contexts.
 StreamPrintService's are not expected to support the Destination attribute.

A StreamPrintServiceFactory is the factory for
StreamPrintService instances,
which can print to an output stream in a particular
document format described as a mime type.
A typical output document format may be Postscript(TM).

This class is implemented by a service and located by the
implementation using the

SPI JAR File specification.

Applications locate instances of this class by calling the
lookupStreamPrintServiceFactories(DocFlavor, String) method.

Applications can use a StreamPrintService obtained from a
factory in place of a PrintService which represents a
physical printer device.

Interface URIException is a mixin interface which a subclass of PrintException can implement to report an error condition
involving a URI address. The Print Service API does not define any print
exception classes that implement interface URIException, that being left to
the Print Service implementor's discretion.