package.html revision 0
1N/A<html>
1N/A<head>
1N/A<title>javax.print package</title>
1N/A<!--
1N/ACopyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
1N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1N/A
1N/AThis code is free software; you can redistribute it and/or modify it
1N/Aunder the terms of the GNU General Public License version 2 only, as
1N/Apublished by the Free Software Foundation. Sun designates this
1N/Aparticular file as subject to the "Classpath" exception as provided
1N/Aby Sun in the LICENSE file that accompanied this code.
1N/A
1N/AThis code is distributed in the hope that it will be useful, but WITHOUT
1N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1N/Aversion 2 for more details (a copy is included in the LICENSE file that
1N/Aaccompanied this code).
1N/A
1N/AYou should have received a copy of the GNU General Public License version
1N/A2 along with this work; if not, write to the Free Software Foundation,
1N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1N/A
1N/APlease contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
1N/ACA 95054 USA or visit www.sun.com if you need additional information or
1N/Ahave any questions.
1N/A-->
1N/A</head>
1N/A<body bgcolor="white">
1N/AProvides the principal classes and interfaces for the
1N/AJava<sup><font size="-2">TM</font></sup> Print Service API.
1N/AThe Java Print Service API enables client and server applications to:
1N/A<ul>
1N/A<li>Discover and select print services based on their capabilities
1N/A<li>Specify the format of print data
1N/A<li>Submit print jobs to services that support the document type to
1N/Abe printed.
1N/A</ul>
1N/A
1N/A
1N/A<h3>Print Service Discovery</h3>
1N/A<p>
1N/AAn application invokes the static methods of the abstract class
1N/A{@link javax.print.PrintServiceLookup PrintServiceLookup} to locate print
1N/Aservices that have the capabilities to satisfy the application's print
1N/Arequest. For example, to print a double-sided document, the application
1N/Afirst needs to find printers that have the double-sided printing capability.
1N/A<p>
1N/AThe JDK includes <code>PrintServiceLookup</code> implementations that
1N/Acan locate the standard platform printers. To locate other types of printers,
1N/Asuch as IPP printers or JINI printers, a print-service provider can write
1N/Aimplementations of <code>PrintServiceLookup</code>. The print-service provider
1N/Acan dynamically install these <code>PrintServiceLookup</code> implementations
1N/Ausing the
1N/A<a href="/technotes/guides/jar/jar.html#Service Provider">
1N/ASPI JAR file specification</a>.
1N/A
1N/A<h3>Attribute Definitions</h3>
1N/A
1N/AThe {@link javax.print.attribute} and {@link javax.print.attribute.standard}
1N/Apackages define print attributes, which describe the capabilities of a print
1N/Aservice, specify the requirements of a print job, and track the progress of
1N/Aa print job.
1N/A<p>
1N/AThe <code>javax.print.attribute</code> package describes the types of attributes and
1N/Ahow they can be collected into sets. The <code>javax.print.attribute.standard</code>
1N/Apackage enumerates all of the standard attributes supported by the API, most
1N/Aof which are implementations of attributes specified in the IETF Specification,
1N/A<a href="http://www.ietf.org/rfc/rfc2911.txt">
1N/ARFC 2911 Internet Printing Protocol, 1.1: Model and Semantics</a>, dated
1N/ASeptember 2000. The attributes specified in <code>javax.print.attribute.standard</code>
1N/Ainclude common capabilites, such as: resolution, copies, media sizes,
1N/Ajob priority, and page ranges.
1N/A
1N/A<h3>Document Type Specification</h3>
1N/A
1N/AThe {@link javax.print.DocFlavor DocFlavor} class represents the print data
1N/Aformat, such as JPEG or PostScript. A <code>DocFlavor</code> object
1N/Aconsists of a MIME type, which describes the format, and a document
1N/Arepresentation class name that indicates how the document is delivered
1N/Ato the printer or output stream. An application uses the
1N/A<code>DocFlavor</code> and an attribute set to find printers that can
1N/Aprint the document type specified by the <code>DocFlavor</code> and have
1N/Athe capabilities specified by the attribute set.
1N/A
1N/A<h3>Using the API</h3>
1N/A
1N/AA typical application using the Java Print Service API performs these steps
1N/Ato process a print request:
1N/A<ol>
1N/A<li>Chooses a <code>DocFlavor</code>.</li>
1N/A<li>Creates a set of attributes.</li>
1N/A<li>Locates a print service that can handle the print request as specified
1N/Aby the <code>DocFlavor</code> and the attribute set.</li>
1N/A<li>Creates a {@link javax.print.Doc Doc} object encapsulating the
1N/A<code>DocFlavor</code>
1N/Aand the actual print data, which can take many forms including: a Postscript
1N/Afile, a JPEG image, a URL, or plain text.</li>
1N/A<li>Gets a print job, represented by {@link javax.print.DocPrintJob DocPrintJob},
1N/A from the print service.</li>
1N/A<li>Calls the print method of the print job.</li>
1N/A</ol>
1N/AThe following code sample demonstrates a typical use of the Java Print
1N/AService API: locating printers that can print five double-sided copies
1N/Aof a Postscript document on size A4 paper, creating a print job from
1N/Aone of the returned print services, and calling print.
1N/A
1N/A<p>
1N/A<pre>
1N/A<blockquote>
1N/AFileInputStream psStream;
1N/Atry {
1N/A psStream = new FileInputStream("file.ps");
1N/A} catch (FileNotFoundException ffne) {
1N/A}
1N/Aif (psStream == null) {
1N/A return;
1N/A}
1N/A
1N/ADocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
1N/ADoc myDoc = new SimpleDoc(psStream, psInFormat, null);
1N/APrintRequestAttributeSet aset =
1N/A new HashPrintRequestAttributeSet();
1N/Aaset.add(new Copies(5));
1N/Aaset.add(MediaSize.A4);
1N/Aaset.add(Sides.DUPLEX);
1N/APrintService[] services =
1N/A PrintServiceLookup.lookupPrintServices(psInFormat, aset);
1N/Aif (services.length > 0) {
1N/A DocPrintJob job = services[0].createPrintJob();
1N/A try {
1N/A job.print(myDoc, aset);
1N/A } catch (PrintException pe) {}
1N/A}
1N/A</blockquote>
1N/A</pre>
1N/A<P>
1N/APlease note: In the javax.print APIs, a null reference parameter to methods
1N/Ais 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.
<P>
@since 1.4
</body>
</html>