0N/A<html>
0N/A<head>
0N/A<title>javax.print package</title>
0N/A<!--
2362N/ACopyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A
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
2362N/Apublished by the Free Software Foundation. Oracle designates this
0N/Aparticular file as subject to the "Classpath" exception as provided
2362N/Aby Oracle in the LICENSE file that accompanied this code.
0N/A
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/A
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/A
2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2365N/Aor visit www.oracle.com if you need additional information or have any
2365N/Aquestions.
0N/A-->
0N/A</head>
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<ul>
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/Abe printed.
0N/A</ul>
0N/A
0N/A
0N/A<h3>Print Service Discovery</h3>
0N/A<p>
0N/AAn application invokes the static methods of the abstract class
0N/A{@link javax.print.PrintServiceLookup PrintServiceLookup} to locate print
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/A<p>
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/Ausing the
0N/A<a href="/technotes/guides/jar/jar.html#Service Provider">
0N/ASPI JAR file specification</a>.
0N/A
0N/A<h3>Attribute Definitions</h3>
0N/A
0N/AThe {@link javax.print.attribute} and {@link javax.print.attribute.standard}
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/Aa print job.
0N/A<p>
0N/AThe <code>javax.print.attribute</code> package describes the types of attributes and
0N/Ahow they can be collected into sets. The <code>javax.print.attribute.standard</code>
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/A<a href="http://www.ietf.org/rfc/rfc2911.txt">
0N/ARFC 2911 Internet Printing Protocol, 1.1: Model and Semantics</a>, dated
0N/ASeptember 2000. The attributes specified in <code>javax.print.attribute.standard</code>
0N/Ainclude common capabilites, such as: resolution, copies, media sizes,
0N/Ajob priority, and page ranges.
0N/A
0N/A<h3>Document Type Specification</h3>
0N/A
0N/AThe {@link javax.print.DocFlavor DocFlavor} class represents the print data
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
0N/A<h3>Using the API</h3>
0N/A
0N/AA typical application using the Java Print Service API performs these steps
0N/Ato process a print request:
0N/A<ol>
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<li>Creates a {@link javax.print.Doc Doc} object encapsulating the
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<li>Gets a print job, represented by {@link javax.print.DocPrintJob DocPrintJob},
0N/A from the print service.</li>
0N/A<li>Calls the print method of the print job.</li>
0N/A</ol>
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/A
0N/A<p>
0N/A<pre>
0N/A<blockquote>
0N/AFileInputStream psStream;
0N/Atry {
0N/A psStream = new FileInputStream("file.ps");
0N/A} catch (FileNotFoundException ffne) {
0N/A}
0N/Aif (psStream == null) {
0N/A return;
0N/A}
0N/A
0N/ADocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
0N/ADoc myDoc = new SimpleDoc(psStream, psInFormat, null);
0N/APrintRequestAttributeSet aset =
0N/A new HashPrintRequestAttributeSet();
0N/Aaset.add(new Copies(5));
0N/Aaset.add(MediaSize.A4);
0N/Aaset.add(Sides.DUPLEX);
0N/APrintService[] services =
0N/A PrintServiceLookup.lookupPrintServices(psInFormat, aset);
0N/Aif (services.length > 0) {
0N/A DocPrintJob job = services[0].createPrintJob();
0N/A try {
0N/A job.print(myDoc, aset);
0N/A } catch (PrintException pe) {}
0N/A}
0N/A</blockquote>
0N/A</pre>
0N/A<P>
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.
0N/A<P>
0N/A@since 1.4
0N/A</body>
0N/A</html>