829N/ACopyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved. 829N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 829N/AThis code is free software; you can redistribute it and/or modify it 829N/Aunder the terms of the GNU General Public License version 2 only, as 829N/Apublished by the Free Software Foundation. Oracle designates this 829N/Aparticular file as subject to the "Classpath" exception as provided 829N/Aby Oracle in the LICENSE file that accompanied this code. 829N/AThis code is distributed in the hope that it will be useful, but WITHOUT 829N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 829N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 829N/Aversion 2 for more details (a copy is included in the LICENSE file that 829N/AYou should have received a copy of the GNU General Public License version 829N/A2 along with this work; if not, write to the Free Software Foundation, 829N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 829N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 829N/AProvides the principal classes and interfaces for the
829N/AJava<
sup><
font size="-2">TM</
font></
sup> Print Service API.
829N/AThe Java Print Service API enables client and server applications to:
829N/A<
li>Discover and select print services based on their capabilities
829N/A<
li>Specify the format of print data
829N/A<
li>Submit print jobs to services that support the document type to
829N/A<
h3>Print Service Discovery</
h3>
829N/AAn application invokes the static methods of the abstract class
829N/Aservices that have the capabilities to satisfy the application's print
829N/Arequest. For example, to print a double-sided document, the application
829N/Afirst needs to find printers that have the double-sided printing capability.
829N/AThe JDK includes <
code>PrintServiceLookup</
code> implementations that
829N/Acan locate the standard platform printers. To locate other types of printers,
829N/Asuch as IPP printers or JINI printers, a print-service provider can write
829N/Aimplementations of <
code>PrintServiceLookup</
code>. The print-service provider
829N/Acan dynamically install these <
code>PrintServiceLookup</
code> implementations
829N/ASPI JAR file specification</
a>.
829N/A<
h3>Attribute Definitions</
h3>
829N/Apackages define print attributes, which describe the capabilities of a print
829N/Aservice, specify the requirements of a print job, and track the progress of
829N/Apackage enumerates all of the standard attributes supported by the API, most
829N/Aof which are implementations of attributes specified in the IETF Specification,
829N/ARFC 2911 Internet Printing Protocol, 1.1: Model and Semantics</
a>, dated
829N/Ainclude common capabilites, such as: resolution, copies, media sizes,
829N/Ajob priority, and page ranges.
829N/A<
h3>Document Type Specification</
h3>
format, such as JPEG or PostScript. A <
code>DocFlavor</
code> 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
<
code>DocFlavor</
code> and an attribute set to find printers that can
print the document type specified by the <
code>DocFlavor</
code> and have
the capabilities specified by the attribute set.
A typical application using the Java Print Service API performs these steps
to process a print request:
<
li>Chooses a <
code>DocFlavor</
code>.</
li>
<
li>Creates a set of attributes.</
li>
<
li>Locates a print service that can handle the print request as specified
by the <
code>DocFlavor</
code> and the attribute set.</
li>
<
li>Creates a {@link
javax.
print.
Doc Doc} object encapsulating the
and the actual print data, which can take many forms including: a Postscript
file, a JPEG image, a URL, or plain text.</
li>
from the print service.</
li>
<
li>Calls the print method of the print job.</
li>
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;
psStream = new FileInputStream("
file.ps");
} catch (FileNotFoundException ffne) {
Doc myDoc = new SimpleDoc(psStream, psInFormat, null);
PrintRequestAttributeSet aset =
new HashPrintRequestAttributeSet();
PrintService[] services =
DocPrintJob job = services[0].createPrintJob();
} 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.