CONTENTS | PREV | NEXT
The javax.print.attribute.standard
package enumerates all of the standard attributes in the Java Print
Service 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(category) 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.
OrientationRequested
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.
Copies
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
Media is the IPP attribute that
identifies the medium on which to print. The Media attribute is an
important attribute to understand, butis 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
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
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.
Destination
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 filesystems 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"));
SheetCollate
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);
Sides
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 specifiesthat
a job print the documents two-sided:
aset.add(Sides.DUPLEX);
Fidelity
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.
CONTENTS | PREV | NEXT
