| J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | <html> |
| 2 | <head> |
| 3 | <title>javax.print package</title> |
| 4 | <!-- |
| 5 | Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved. |
| 6 | DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| 7 | |
| 8 | This code is free software; you can redistribute it and/or modify it |
| 9 | under the terms of the GNU General Public License version 2 only, as |
| 10 | published by the Free Software Foundation. Sun designates this |
| 11 | particular file as subject to the "Classpath" exception as provided |
| 12 | by Sun in the LICENSE file that accompanied this code. |
| 13 | |
| 14 | This code is distributed in the hope that it will be useful, but WITHOUT |
| 15 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 16 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| 17 | version 2 for more details (a copy is included in the LICENSE file that |
| 18 | accompanied this code). |
| 19 | |
| 20 | You should have received a copy of the GNU General Public License version |
| 21 | 2 along with this work; if not, write to the Free Software Foundation, |
| 22 | Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| 23 | |
| 24 | Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 25 | CA 95054 USA or visit www.sun.com if you need additional information or |
| 26 | have any questions. |
| 27 | --> |
| 28 | </head> |
| 29 | <body bgcolor="white"> |
| 30 | Provides the principal classes and interfaces for the |
| 31 | Java<sup><font size="-2">TM</font></sup> Print Service API. |
| 32 | The Java Print Service API enables client and server applications to: |
| 33 | <ul> |
| 34 | <li>Discover and select print services based on their capabilities |
| 35 | <li>Specify the format of print data |
| 36 | <li>Submit print jobs to services that support the document type to |
| 37 | be printed. |
| 38 | </ul> |
| 39 | |
| 40 | |
| 41 | <h3>Print Service Discovery</h3> |
| 42 | <p> |
| 43 | An application invokes the static methods of the abstract class |
| 44 | {@link javax.print.PrintServiceLookup PrintServiceLookup} to locate print |
| 45 | services that have the capabilities to satisfy the application's print |
| 46 | request. For example, to print a double-sided document, the application |
| 47 | first needs to find printers that have the double-sided printing capability. |
| 48 | <p> |
| 49 | The JDK includes <code>PrintServiceLookup</code> implementations that |
| 50 | can locate the standard platform printers. To locate other types of printers, |
| 51 | such as IPP printers or JINI printers, a print-service provider can write |
| 52 | implementations of <code>PrintServiceLookup</code>. The print-service provider |
| 53 | can dynamically install these <code>PrintServiceLookup</code> implementations |
| 54 | using the |
| 55 | <a href="../../../technotes/guides/jar/jar.html#Service Provider"> |
| 56 | SPI JAR file specification</a>. |
| 57 | |
| 58 | <h3>Attribute Definitions</h3> |
| 59 | |
| 60 | The {@link javax.print.attribute} and {@link javax.print.attribute.standard} |
| 61 | packages define print attributes, which describe the capabilities of a print |
| 62 | service, specify the requirements of a print job, and track the progress of |
| 63 | a print job. |
| 64 | <p> |
| 65 | The <code>javax.print.attribute</code> package describes the types of attributes and |
| 66 | how they can be collected into sets. The <code>javax.print.attribute.standard</code> |
| 67 | package enumerates all of the standard attributes supported by the API, most |
| 68 | of which are implementations of attributes specified in the IETF Specification, |
| 69 | <a href="http://www.ietf.org/rfc/rfc2911.txt"> |
| 70 | RFC 2911 Internet Printing Protocol, 1.1: Model and Semantics</a>, dated |
| 71 | September 2000. The attributes specified in <code>javax.print.attribute.standard</code> |
| 72 | include common capabilites, such as: resolution, copies, media sizes, |
| 73 | job priority, and page ranges. |
| 74 | |
| 75 | <h3>Document Type Specification</h3> |
| 76 | |
| 77 | The {@link javax.print.DocFlavor DocFlavor} class represents the print data |
| 78 | format, such as JPEG or PostScript. A <code>DocFlavor</code> object |
| 79 | consists of a MIME type, which describes the format, and a document |
| 80 | representation class name that indicates how the document is delivered |
| 81 | to the printer or output stream. An application uses the |
| 82 | <code>DocFlavor</code> and an attribute set to find printers that can |
| 83 | print the document type specified by the <code>DocFlavor</code> and have |
| 84 | the capabilities specified by the attribute set. |
| 85 | |
| 86 | <h3>Using the API</h3> |
| 87 | |
| 88 | A typical application using the Java Print Service API performs these steps |
| 89 | to process a print request: |
| 90 | <ol> |
| 91 | <li>Chooses a <code>DocFlavor</code>.</li> |
| 92 | <li>Creates a set of attributes.</li> |
| 93 | <li>Locates a print service that can handle the print request as specified |
| 94 | by the <code>DocFlavor</code> and the attribute set.</li> |
| 95 | <li>Creates a {@link javax.print.Doc Doc} object encapsulating the |
| 96 | <code>DocFlavor</code> |
| 97 | and the actual print data, which can take many forms including: a Postscript |
| 98 | file, a JPEG image, a URL, or plain text.</li> |
| 99 | <li>Gets a print job, represented by {@link javax.print.DocPrintJob DocPrintJob}, |
| 100 | from the print service.</li> |
| 101 | <li>Calls the print method of the print job.</li> |
| 102 | </ol> |
| 103 | The following code sample demonstrates a typical use of the Java Print |
| 104 | Service API: locating printers that can print five double-sided copies |
| 105 | of a Postscript document on size A4 paper, creating a print job from |
| 106 | one of the returned print services, and calling print. |
| 107 | |
| 108 | <p> |
| 109 | <pre> |
| 110 | <blockquote> |
| 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(MediaSize.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 | </blockquote> |
| 136 | </pre> |
| 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 | <P> |
| 145 | @since 1.4 |
| 146 | </body> |
| 147 | </html> |