CONTENTS | PREV | NEXT

Java Print Service API User Guide

---

Standard Attributes

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

---