Provides the principal classes and interfaces for the Java Print
Service API. The Java Print Service API enables client and server
applications to:
Discover and select print services based on their capabilities
Specify the format of print data
Submit print jobs to services that support the document type to be
printed.
Print Service Discovery
An application invokes the static methods of the abstract class
PrintServiceLookup
to locate print
services that have the capabilities to satisfy the application's print
request. For example, to print a double-sided document, the application first
needs to find printers that have the double-sided printing capability.
The JDK includes
PrintServiceLookup
implementations that can locate
the standard platform printers. To locate other types of printers, such as
IPP printers or JINI printers, a print-service provider can write
implementations of
PrintServiceLookup
. The print-service provider can
dynamically install these
PrintServiceLookup
implementations using
the
ServiceLoader
facility.
Attribute Definitions
The
javax.print.attribute
and
javax.print.attribute.standard
packages define print attributes, which describe the capabilities of a print
service, specify the requirements of a print job, and track the progress of a
print job.
The
javax.print.attribute
package describes the types of attributes
and how they can be collected into sets. The
javax.print.attribute.standard
package enumerates all of the standard
attributes supported by the API, most of which are implementations of
attributes specified in the IETF Specification,
RFC 2911 Internet Printing
Protocol, 1.1: Model and Semantics
, dated September 2000. The attributes
specified in
javax.print.attribute.standard
include common
capabilities, such as: resolution, copies, media sizes, job priority, and
page ranges.
Document Type Specification
The
DocFlavor
class represents the print data
format, such as JPEG or PostScript. A
DocFlavor
object consists of a
MIME type, which describes the format, and a document representation class
name that indicates how the document is delivered to the printer or output
stream. An application uses the
DocFlavor
and an attribute set to
find printers that can print the document type specified by the
DocFlavor
and have the capabilities specified by the attribute set.
Using the API
A typical application using the Java Print Service API performs these steps
to process a print request:
Chooses a
DocFlavor
.
Creates a set of attributes.
Locates a print service that can handle the print request as specified
by the
DocFlavor
and the attribute set.
Creates a
Doc
object encapsulating the
DocFlavor
and the actual print data, which can take many forms
including: a Postscript file, a JPEG image, a
URL
, or plain text.
Gets a print job, represented by
DocPrintJob
, from the print service.
Calls the print method of the print job.
The following code sample demonstrates a typical use of the Java Print
Service API: locating printers that can print five double-sided copies of a
Postscript document on size A4 paper, creating a print job from one of the
returned print services, and calling print.
FileInputStream psStream;
try {
psStream = new FileInputStream("file.ps");
} catch (FileNotFoundException ffne) {
if (psStream == null) {
return;
DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
Doc myDoc = new SimpleDoc(psStream, psInFormat, null);
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(new Copies(5));
aset.add(MediaSizeName.ISO_A4);
aset.add(Sides.DUPLEX);
PrintService[] services =
PrintServiceLookup.lookupPrintServices(psInFormat, aset);
if (services.length > 0) {
DocPrintJob job = services[0].createPrintJob();
try {
job.print(myDoc, aset);
} catch (PrintException pe) {}
Please note: In the
javax.print
APIs, a
null
reference
parameter to methods is incorrect unless explicitly documented on the method
as having a meaningful interpretation. Usage to the contrary is incorrect
coding and may result in a run time exception either immediately or at some
later time.
IllegalArgumentException
and
NullPointerException
are examples of typical and acceptable run time exceptions for such cases.
Provides classes and interfaces that describe the types of Java Print
Service attributes and how they can be collected into attribute sets.
Package
javax.print.event
contains event classes and listener
interfaces.
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.
This interface is used by a printing application to cancel a print job.
Interface
Doc
specifies the interface for an object that supplies one
piece of print data for a Print Job.
Class
DocFlavor
encapsulates an object that specifies the format in
which print data is supplied to a
DocPrintJob
.
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.
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.
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.
Class
DocFlavor.URL
provides predefined static constant
DocFlavor
objects.
This interface represents a print job that can print a specified document
with a set of job attributes.
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
).
Interface
MultiDoc
specifies the interface for an object that
supplies more than one piece of print data for a Print Job.
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
.
Class
PrintException
encapsulates a printing-related error condition
that occurred while using a Print Service instance.
Interface
PrintService
is the factory for a
DocPrintJob
.
Implementations of this class provide lookup services for print services
(typically equivalent to printers) of a particular type.
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.
Services may optionally provide UIs which allow different styles of
interaction in different roles.
This class is an implementation of interface
Doc
that can be used in
many common printing requests.
This class extends
PrintService
and represents a print service that
prints data in different formats to a client-provided output stream.
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.
Interface
URIException
is a mixin interface which a subclass of
PrintException
can implement to report an error
condition involving a
URI
address.
