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