package-info.java revision 16866:708f958bee98
1/*
2 * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26/**
27 * Provides the principal classes and interfaces for the Java™ Print
28 * Service API. The Java Print Service API enables client and server
29 * applications to:
30 * <ul>
31 *     <li>Discover and select print services based on their capabilities</li>
32 *     <li>Specify the format of print data</li>
33 *     <li>Submit print jobs to services that support the document type to be
34 *     printed.</li>
35 * </ul>
36 *
37 * <h3>Print Service Discovery</h3>
38 * An application invokes the static methods of the abstract class
39 * {@link javax.print.PrintServiceLookup PrintServiceLookup} to locate print
40 * services that have the capabilities to satisfy the application's print
41 * request. For example, to print a double-sided document, the application first
42 * needs to find printers that have the double-sided printing capability.
43 * <p>
44 * The JDK includes {@code PrintServiceLookup} implementations that can locate
45 * the standard platform printers. To locate other types of printers, such as
46 * IPP printers or JINI printers, a print-service provider can write
47 * implementations of {@code PrintServiceLookup}. The print-service provider can
48 * dynamically install these {@code PrintServiceLookup} implementations using
49 * the <a href="../../../technotes/guides/jar/jar.html#Service%20Provider">
50 * SPI JAR file specification</a>.
51 *
52 * <h3>Attribute Definitions</h3>
53 * The {@link javax.print.attribute} and {@link javax.print.attribute.standard}
54 * packages define print attributes, which describe the capabilities of a print
55 * service, specify the requirements of a print job, and track the progress of
56 * a print job.
57 * <p>
58 * The {@code javax.print.attribute} package describes the types of attributes
59 * and how they can be collected into sets. The
60 * {@code javax.print.attribute.standard} package enumerates all of the standard
61 * attributes supported by the API, most of which are implementations of
62 * attributes specified in the IETF Specification,
63 * <a href="http://www.ietf.org/rfc/rfc2911.txt"> RFC 2911 Internet Printing
64 * Protocol, 1.1: Model and Semantics</a>, dated September 2000. The attributes
65 * specified in {@code javax.print.attribute.standard} include common
66 * capabilities, such as: resolution, copies, media sizes, job priority, and
67 * page ranges.
68 *
69 * <h3>Document Type Specification</h3>
70 * The {@link javax.print.DocFlavor DocFlavor} class represents the print data
71 * format, such as JPEG or PostScript. A {@code DocFlavor} object consists of a
72 * MIME type, which describes the format, and a document representation class
73 * name that indicates how the document is delivered to the printer or output
74 * stream. An application uses the {@code DocFlavor} and an attribute set to
75 * find printers that can print the document type specified by the
76 * {@code DocFlavor} and have the capabilities specified by the attribute set.
77 *
78 * <h3>Using the API</h3>
79 * A typical application using the Java Print Service API performs these steps
80 * to process a print request:
81 * <ol>
82 *     <li>Chooses a {@code DocFlavor}.</li>
83 *     <li>Creates a set of attributes.</li>
84 *     <li>Locates a print service that can handle the print request as
85 *     specified by the {@code DocFlavor} and the attribute set.</li>
86 *     <li>Creates a {@link javax.print.Doc Doc} object encapsulating the
87 *     {@code DocFlavor} and the actual print data, which can take many forms
88 *     including: a Postscript file, a JPEG image, a URL, or plain text.</li>
89 *     <li>Gets a print job, represented by
90 *     {@link javax.print.DocPrintJob DocPrintJob}, from the print service.</li>
91 *     <li>Calls the print method of the print job.</li>
92 * </ol>
93 * The following code sample demonstrates a typical use of the Java Print
94 * Service API: locating printers that can print five double-sided copies of a
95 * Postscript document on size A4 paper, creating a print job from one of the
96 * returned print services, and calling print.
97 * <blockquote>
98 * <pre>{@code
99 * FileInputStream psStream;
100 * try {
101 *     psStream = new FileInputStream("file.ps");
102 * } catch (FileNotFoundException ffne) {
103 * }
104 * if (psStream == null) {
105 *     return;
106 * }
107 * DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
108 * Doc myDoc = new SimpleDoc(psStream, psInFormat, null);
109 * PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
110 * aset.add(new Copies(5));
111 * aset.add(MediaSizeName.ISO_A4);
112 * aset.add(Sides.DUPLEX);
113 * PrintService[] services =
114 * PrintServiceLookup.lookupPrintServices(psInFormat, aset);
115 * if (services.length > 0) {
116 *     DocPrintJob job = services[0].createPrintJob();
117 *     try {
118 *         job.print(myDoc, aset);
119 *     } catch (PrintException pe) {}
120 * }
121 * }</pre>
122 * </blockquote>
123 * <P>
124 * Please note: In the javax.print APIs, a null reference parameter to methods
125 * is incorrect unless explicitly documented on the method as having a
126 * meaningful interpretation. Usage to the contrary is incorrect coding and may
127 * result in a run time exception either immediately or at some later time.
128 * IllegalArgumentException and NullPointerException are examples of typical and
129 * acceptable run time exceptions for such cases.
130 *
131 * @since 1.4
132 */
133package javax.print;
134