0N/ACopyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved. 0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/AThis code is free software; you can redistribute it and/or modify it 0N/Aunder the terms of the GNU General Public License version 2 only, as 0N/Apublished by the Free Software Foundation. Sun designates this 0N/Aparticular file as subject to the "Classpath" exception as provided 0N/Aby Sun in the LICENSE file that accompanied this code. 0N/AThis code is distributed in the hope that it will be useful, but WITHOUT 0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/Aversion 2 for more details (a copy is included in the LICENSE file that 0N/Aaccompanied this code). 0N/AYou should have received a copy of the GNU General Public License version 0N/A2 along with this work; if not, write to the Free Software Foundation, 0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/APlease contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/ACA 95054 USA or visit www.sun.com if you need additional information or 0N/A<
body bgcolor="white">
0N/AProvides the principal classes and interfaces for the
0N/AJava<
sup><
font size="-2">TM</
font></
sup> Print Service API.
0N/AThe Java Print Service API enables client and server applications to:
0N/A<
li>Discover and select print services based on their capabilities
0N/A<
li>Specify the format of print data
0N/A<
li>Submit print jobs to services that support the document type to
0N/A<
h3>Print Service Discovery</
h3>
0N/AAn application invokes the static methods of the abstract class
0N/Aservices that have the capabilities to satisfy the application's print
0N/Arequest. For example, to print a double-sided document, the application
0N/Afirst needs to find printers that have the double-sided printing capability.
0N/AThe JDK includes <
code>PrintServiceLookup</
code> implementations that
0N/Acan locate the standard platform printers. To locate other types of printers,
0N/Asuch as IPP printers or JINI printers, a print-service provider can write
0N/Aimplementations of <
code>PrintServiceLookup</
code>. The print-service provider
0N/Acan dynamically install these <
code>PrintServiceLookup</
code> implementations
0N/ASPI JAR file specification</
a>.
0N/A<
h3>Attribute Definitions</
h3>
0N/Apackages define print attributes, which describe the capabilities of a print
0N/Aservice, specify the requirements of a print job, and track the progress of
0N/Apackage enumerates all of the standard attributes supported by the API, most
0N/Aof which are implementations of attributes specified in the IETF Specification,
0N/ARFC 2911 Internet Printing Protocol, 1.1: Model and Semantics</
a>, dated
0N/Ainclude common capabilites, such as: resolution, copies, media sizes,
0N/Ajob priority, and page ranges.
0N/A<
h3>Document Type Specification</
h3>
0N/Aformat, such as JPEG or PostScript. A <
code>DocFlavor</
code> object
0N/Aconsists of a MIME type, which describes the format, and a document
0N/Arepresentation class name that indicates how the document is delivered
0N/Ato the printer or output stream. An application uses the
0N/A<
code>DocFlavor</
code> and an attribute set to find printers that can
0N/Aprint the document type specified by the <
code>DocFlavor</
code> and have
0N/Athe capabilities specified by the attribute set.
0N/A<
h3>Using the API</
h3>
0N/AA typical application using the Java Print Service API performs these steps
0N/Ato process a print request:
0N/A<
li>Chooses a <
code>DocFlavor</
code>.</
li>
0N/A<
li>Creates a set of attributes.</
li>
0N/A<
li>Locates a print service that can handle the print request as specified
0N/Aby the <
code>DocFlavor</
code> and the attribute set.</
li>
0N/A<
code>DocFlavor</
code>
0N/Aand the actual print data, which can take many forms including: a Postscript
0N/Afile, a JPEG image, a URL, or plain text.</
li>
0N/A from the print service.</
li>
0N/A<
li>Calls the print method of the print job.</
li>
0N/AThe following code sample demonstrates a typical use of the Java Print
0N/AService API: locating printers that can print five double-sided copies
0N/Aof a Postscript document on size A4 paper, creating a print job from
0N/Aone of the returned print services, and calling print.
0N/AFileInputStream psStream;
0N/A} catch (FileNotFoundException ffne) {
0N/Aif (psStream == null) {
0N/ADoc myDoc = new SimpleDoc(psStream, psInFormat, null);
0N/APrintRequestAttributeSet aset =
0N/A new HashPrintRequestAttributeSet();
0N/APrintService[] services =
0N/A DocPrintJob job = services[0].createPrintJob();
0N/A } catch (PrintException pe) {}
0N/APlease note: In the
javax.print APIs, a null reference parameter to methods
0N/Ais incorrect unless explicitly documented on the method as having a meaningful
0N/Ainterpretation. Usage to the contrary is incorrect coding and may result
0N/Ain a run time exception either immediately or at some later time.
0N/AIllegalArgumentException and NullPointerException are examples of
0N/Atypical and acceptable run time exceptions for such cases.