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 package javax.print; 27 28 import javax.print.attribute.PrintJobAttributeSet; 29 import javax.print.attribute.PrintRequestAttributeSet; 30 import javax.print.event.PrintJobAttributeListener; 31 import javax.print.event.PrintJobListener; 32 33 /** 34 * This interface represents a print job that can print a specified document 35 * with a set of job attributes. An object implementing this interface is 36 * obtained from a print service. 37 */ 38 public interface DocPrintJob { 39 40 /** 41 * Determines the {@link PrintService} object to which this print job object 42 * is bound. 43 * 44 * @return {@code PrintService} object 45 */ getPrintService()46 public PrintService getPrintService(); 47 48 /** 49 * Obtains this Print Job's set of printing attributes. The returned 50 * attribute set object is unmodifiable. The returned attribute set object 51 * is a "snapshot" of this Print Job's attribute set at the time of the 52 * {@code getAttributes()} method call; that is, the returned attribute 53 * set's object's contents will not be updated if this Print Job's attribute 54 * set's contents change in the future. To detect changes in attribute 55 * values, call {@code getAttributes()} again and compare the new attribute 56 * set to the previous attribute set; alternatively, register a listener for 57 * print job events. The returned value may be an empty set but should not 58 * be {@code null}. 59 * 60 * @return the print job attributes 61 */ getAttributes()62 public PrintJobAttributeSet getAttributes(); 63 64 /** 65 * Registers a listener for event occurring during this print job. If 66 * listener is {@code null}, no exception is thrown and no action is 67 * performed. If listener is already registered, it will be registered 68 * again. 69 * 70 * @param listener the object implementing the listener interface 71 * @see #removePrintJobListener 72 */ addPrintJobListener(PrintJobListener listener)73 public void addPrintJobListener(PrintJobListener listener); 74 75 /** 76 * Removes a listener from this print job. This method performs no function, 77 * nor does it throw an exception, if the listener specified by the argument 78 * was not previously added to this print job. If listener is {@code null}, 79 * no exception is thrown and no action is performed. If a listener was 80 * registered more than once only one of the registrations will be removed. 81 * 82 * @param listener the object implementing the listener interface 83 * @see #addPrintJobListener 84 */ removePrintJobListener(PrintJobListener listener)85 public void removePrintJobListener(PrintJobListener listener); 86 87 /** 88 * Registers a listener for changes in the specified attributes. If listener 89 * is {@code null}, no exception is thrown and no action is performed. To 90 * determine the attribute updates that may be reported by this job, a 91 * client can call {@code getAttributes()} and identify the subset that are 92 * interesting and likely to be reported to the listener. Clients expecting 93 * to be updated about changes in a specific job attribute should verify it 94 * is in that set, but updates about an attribute will be made only if it 95 * changes and this is detected by the job. Also updates may be subject to 96 * batching by the job. To minimize overhead in print job processing it is 97 * recommended to listen on only that subset of attributes which are likely 98 * to change. If the specified set is empty no attribute updates will be 99 * reported to the listener. If the attribute set is {@code null}, then this 100 * means to listen on all dynamic attributes that the job supports. This may 101 * result in no update notifications if a job can not report any attribute 102 * updates. 103 * <p> 104 * If listener is already registered, it will be registered again. 105 * 106 * @param listener the object implementing the listener interface 107 * @param attributes the attributes to listen on, or {@code null} to mean 108 * all attributes that can change, as determined by the job 109 * @see #removePrintJobAttributeListener 110 */ addPrintJobAttributeListener( PrintJobAttributeListener listener, PrintJobAttributeSet attributes)111 public void addPrintJobAttributeListener( 112 PrintJobAttributeListener listener, 113 PrintJobAttributeSet attributes); 114 115 /** 116 * Removes an attribute listener from this print job. This method performs 117 * no function, nor does it throw an exception, if the listener specified by 118 * the argument was not previously added to this print job. If the listener 119 * is {@code null}, no exception is thrown and no action is performed. If a 120 * listener is registered more than once, even for a different set of 121 * attributes, no guarantee is made which listener is removed. 122 * 123 * @param listener the object implementing the listener interface 124 * @see #addPrintJobAttributeListener 125 */ removePrintJobAttributeListener( PrintJobAttributeListener listener)126 public void removePrintJobAttributeListener( 127 PrintJobAttributeListener listener); 128 129 /** 130 * Prints a document with the specified job attributes. This method should 131 * only be called once for a given print job. Calling it again will not 132 * result in a new job being spooled to the printer. The service 133 * implementation will define policy for service interruption and recovery. 134 * When the print method returns, printing may not yet have completed as 135 * printing may happen asynchronously, perhaps in a different thread. 136 * Application clients which want to monitor the success or failure should 137 * register a {@code PrintJobListener}. 138 * <p> 139 * Print service implementors should close any print data streams (ie 140 * {@code Reader} or {@code InputStream} implementations) that they obtain 141 * from the client doc. Robust clients may still wish to verify this. An 142 * exception is always generated if a {@code DocFlavor} cannot be printed. 143 * 144 * @param doc the document to be printed. It must be a flavor supported by 145 * this PrintJob. 146 * @param attributes the job attributes to be applied to this print job. If 147 * this parameter is {@code null} then the default attributes are 148 * used. 149 * @throws PrintException the exception additionally may implement an 150 * interface that more precisely describes the cause of the 151 * exception 152 * <ul> 153 * <li>{@code FlavorException}. If the document has a flavor not 154 * supported by this print job. 155 * <li>{@code AttributeException}. If one or more of the 156 * attributes are not valid for this print job. 157 * </ul> 158 */ print(Doc doc, PrintRequestAttributeSet attributes)159 public void print(Doc doc, PrintRequestAttributeSet attributes) 160 throws PrintException; 161 162 } 163