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