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