The
javax.print.attribute.standard package enumerates all of the
standard attributes in the Java Print Service (JPS) API. Most of these
standard attributes are taken from the attributes defined in the
IETF Internet Printing Protocol (IPP) 1.1 specification. This means
that each IPP-compliant attribute class defined in
package javax.print.attribute.standard corresponds to an IPP
attribute category, and the name (as returned by getName) is the
actual IPP name for the category. The class names also usually
reflect the IPP name as closely as the coding conventions of the
Java programming language permit. Furthermore the values defined
for a category are the same as the IPP values. IPP compatibility of
each attribute category is documented in the API specification.
This section
describes the attributes that developers will probably use most
frequently. The more commonly used attributes, including the ones
listed here, implement PrintRequestAttribute because printing
applications will usually specify how an entire print job should be
printed, which is the role of a PrintRequestAttribute.
The
OrientationRequested attribute category allows you to specify the
orientation of the imaging on the paper. The possible attribute
values are: PORTRAIT, LANDSCAPE, REVERSE_PORTRAIT, and
REVERSE_LANDSCAPE. OrientationRequested.PORTRAIT is usually the
default value. This code snippet demonstrates adding an
OrientationRequested attribute to a set:
aset.add(OrientationRequested.REVERSE_PORTRAIT);
The
OrientationRequested object is a type-safe enumeration
encapsulating String values, which correspond to the possible
orientations. These values are the actual IPP keywords.
Some pre-formatted document types, such as "Postscript", might not be able to support this attribute category because pre-formatted document types embed printer language commands that are interpreted by the printer, and these commands take precedence over a client request.
Clients can discover
the supported orientation values for a particular print service by
calling PrintService.getSupportedAttributeValues(OrientationRequested.class, ...). This method returns an
array of type OrientationRequested enumerating the supported
values.
The Copies attribute
category allows you to specify the number of copies to print. The
Copies class encapsulates an integer representing the number of
copies requested. This code snippet demonstrates adding a Copies
attribute, set to five copies, to an attribute set:
aset.add(Copies(5));
Clients can discover
the range of copies that a print service supports by calling PrintService.getSupportedAttributeValues(Copies.class, ...).
This method returns a
CopiesSupported object, which encapsulates a range of integer
values representing the range of copies that the service can
handle. Calling getSupportedAttributeValues with CopiesSupported
instead of Copies always returns null because the CopiesSupported
object does not implement the PrintRequestAttribute interface, and
so a client cannot specify a CopiesSupported attribute in a print
request.
This code sample
demonstrates discovering if a print service supports printing 5
copies and adding a Copies attribute with a value of 5 copies to an
attribute set:
CopiesSupported copSupp = (CopiesSupported)
service.getSupportedAttributeValues(Copies.class, null, null);
if (copSupp != null && copSupp.contains(5)) {
requestAttrSet.add(new Copies(5));
} else {
// ...
}
Media is the IPP
attribute that identifies the medium on which to print. The Media
attribute is an important attribute to understand, but is relatively
complex.
The Java Print
Service API defines three subclasses of the abstract class Media to
reflect the overloaded Media attribute in the IPP specification:
MediaSizeName, MediaName, and MediaTray. All the Media subclasses
have the Media category, for which each subclass defines different
standard attribute values. For example, a MediaTray object can
specify a value of MANUAL for the Media attribute to indicate that
the document must be printed on paper from the printer's manual
tray. This code snippet demonstrates adding a Media attribute to a
set:
aset.add(MediaTray.MANUAL);
The value of the
Media attribute is always a String, but because the attribute is
overloaded, its value determines the type of media to which the
attribute refers. For example, the IPP pre-defined set of attribute
values include the values "a4" and "top-tray". If
Media is set to the value "a4" then the Media attribute
refers to the size of paper, but if Media is set to
"top-tray" then the Media attribute refers to the paper
source. Because the String attribute value can refer to such
diverse types of media, an application can extend the attribute set
to include values such as "company-letterhead" or
"yellow letter paper". Of course, to extend the Media
attribute in this way, an application must discover a print service
that is configured to print with this media.
In most cases,
applications will use either MediaSizeName or MediaTray. The
MediaSizeName class enumerates the media by size. The MediaTray
class enumerates the paper trays on a printer, which usually
include a main tray and a manual feed tray. The IPP 1.1
specification does not provide for specifying both the media size
and the media tray at the same time, which means, for example, that
an application cannot request size A4 paper from the manual tray. A
future revision of the IPP specification might provide for a way to
request more than one type of media at a time, in which case the
JPS API will most likely be enhanced to implement this change.
The JPS API also
includes two additional media-related Attribute classes that are
not IPP attributes: MediaSize and MediaPrintableArea.
MediaSize is not a
request attribute; it is an enumeration of paper dimensions and a
mapping to MediaSizeName instances. Each MediaSizeName instance
usually has a MediaSize object associated with it so that clients
can obtain the dimensions of the paper that the MediaSizeName
instance defines. To determine the dimensions of the MediaSizeName
instance, call:
MediaSize size = MediaSizeName.getMediaSizeForName(paper);
MediaPrintableArea is
used in a print request in conjunction with a compatible Media to
specify the area of the paper on which to print. Printer hardware
usually defines the printable area of a page, which is rarely the
entire page. For this reason, an application needs to determine
what printable area a printer defines for a particular size media
to ensure that the print data can fit within this area.
For example, to determine the supported printable area for 5" x 7" paper, the application needs to choose a media size attribute value that corresponds to this size paper and then query the print service with the media size:
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(MediaSizeName.NA_5X7);
MediaPrintableArea printableArea =
(MediaPrintableArea)service.
getSupportedAttributeValues(MediaPrintableArea.class, null, aset);
The returned value indicates the largest printable area that can be supported by that printer for that paper size.
The Destination
attribute allows you to redirect your print data to a file rather
than sending it to a printer device. The "print-to-file"
option is very common in user dialogs, but the spooled data is not
always usable because it might be a device-specific raster that can
only be interpreted by the device from which it was redirected. For
this reason, the Java Print Service API requires that the client
query the print service to determine if it can redirect the output
to a file. The service might not support the category at all, or it
might support only particular values. For example, since the JPS
API can be used in an network environment, in which the formatting
of print data does not occur on the host computer, specifying a
local file for output might not be possible because the service
formatting the data might not have access to the local file systems
of the client. The Destination attribute takes a URL as the value
of the destination, which allows a network printer to use a
protocol such as FTP to upload formatted print data. However, most
printers that support this attribute will run as part of a local
environment and can accept the "file:" protocol URL. This
code snippet redirects the output to a file called out.prn on the
c: drive:
aset.add(new Destination("file:c:\out.prn"));
The SheetCollate
attribute allows you to specify whether or not your print job is
collated when you are printing more than one copy of a multi-page
document. For example, the pages of a 3-page, 2-copy collated job
will print as (1,2,3,1,2,3), but the pages of the same document
submitted in a 2-copy uncollated job will be printed as
(1,1,2,2,3,3). This attribute is not in version 1.1 of the IPP
specification, but it is very useful and most printers support it.
This code snippet demonstrates specifying a collated job:
aset.add(SheetCollate.COLLATED);
Some printers,
particularly high-end printers, can print on both sides of the
paper. The Sides attribute allows applications to specify two-sided
printing instead of the usual default of single-sided printing.
Two-sided printing is sometimes referred to as "duplex" or "tumble"
printing. These two values are differentiated by the orientation of
the output. The Java Print Service API refers to duplex as "two
sided long edge" and tumble as "two sided short edge". Read the API
specification for Sides for further explanation. This code snippet
specifies that a job print the documents two-sided:
aset.add(Sides.DUPLEX);
The Fidelity attribute
is an IPP boolean attribute that represents whether or not a print
job should be rejected if the print service does not support any
attribute specified in the print request. Fidelity is not an
attribute many developers will need to consider, but it is an
important attribute in the context of the JPS API. The default
value is FIDELITY_FALSE, which indicates that a print job should
not be rejected if the print service does not support an attribute
specified in the print request. For example, if an application
specifies an orientation of reverse landscape, but the printer does
not support reverse landscape, the job is rejected if fidelity is
true, but if fidelity is false then the printer might substitute a
reasonable alternative, such as the landscape orientation. The
Fidelity attribute allows applications to decide whether to only
print the document exactly as specified or to print it even though
the printer might not support all attributes. This code snippet
specifies that a job should be rejected if the printer does not
support the requested attributes:
aset.add(Fidelity.FIDELITY_TRUE);
For the cases in which
fidelity is important, the Java Print Service API provides many
tools for applications to query exactly what can be supported for a
particular print request. See the various query methods on the
PrintService interface.
