package.html revision 2365
829N/A<html>
829N/A<head>
829N/A<title>javax.print package</title>
829N/A<!--
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/A
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/A
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/Aaccompanied this code).
829N/A
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/A
829N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
829N/Aor visit www.oracle.com if you need additional information or have any
829N/Aquestions.
829N/A-->
829N/A</head>
829N/A<body bgcolor="white">
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<ul>
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/Abe printed.
829N/A</ul>
829N/A
829N/A
829N/A<h3>Print Service Discovery</h3>
829N/A<p>
829N/AAn application invokes the static methods of the abstract class
829N/A{@link javax.print.PrintServiceLookup PrintServiceLookup} to locate print
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/A<p>
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/Ausing the
829N/A<a href="/technotes/guides/jar/jar.html#Service Provider">
829N/ASPI JAR file specification</a>.
829N/A
829N/A<h3>Attribute Definitions</h3>
829N/A
829N/AThe {@link javax.print.attribute} and {@link javax.print.attribute.standard}
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/Aa print job.
829N/A<p>
829N/AThe <code>javax.print.attribute</code> package describes the types of attributes and
829N/Ahow they can be collected into sets. The <code>javax.print.attribute.standard</code>
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/A<a href="http://www.ietf.org/rfc/rfc2911.txt">
829N/ARFC 2911 Internet Printing Protocol, 1.1: Model and Semantics</a>, dated
829N/ASeptember 2000. The attributes specified in <code>javax.print.attribute.standard</code>
829N/Ainclude common capabilites, such as: resolution, copies, media sizes,
829N/Ajob priority, and page ranges.
829N/A
829N/A<h3>Document Type Specification</h3>
The {@link javax.print.DocFlavor DocFlavor} class represents the print data
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.
<h3>Using the API</h3>
A typical application using the Java Print Service API performs these steps
to process a print request:
<ol>
<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
<code>DocFlavor</code>
and the actual print data, which can take many forms including: a Postscript
file, a JPEG image, a URL, or plain text.</li>
<li>Gets a print job, represented by {@link javax.print.DocPrintJob DocPrintJob},
from the print service.</li>
<li>Calls the print method of the print job.</li>
</ol>
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.
<p>
<pre>
<blockquote>
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(MediaSize.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) {}
}
</blockquote>
</pre>
<P>
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.
<P>
@since 1.4
</body>
</html>