| /* | |
| * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved. | |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
| * | |
| * This code is free software; you can redistribute it and/or modify it | |
| * under the terms of the GNU General Public License version 2 only, as | |
| * published by the Free Software Foundation. Oracle designates this | |
| * particular file as subject to the "Classpath" exception as provided | |
| * by Oracle in the LICENSE file that accompanied this code. | |
| * | |
| * This code is distributed in the hope that it will be useful, but WITHOUT | |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| * version 2 for more details (a copy is included in the LICENSE file that | |
| * accompanied this code). | |
| * | |
| * You should have received a copy of the GNU General Public License version | |
| * 2 along with this work; if not, write to the Free Software Foundation, | |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
| * | |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | |
| * or visit www.oracle.com if you need additional information or have any | |
| * questions. | |
| */ | |
| package javax.print; | |
| import javax.print.attribute.PrintJobAttributeSet; | |
| import javax.print.attribute.PrintRequestAttributeSet; | |
| import javax.print.event.PrintJobAttributeListener; | |
| import javax.print.event.PrintJobListener; | |
| /** | |
| * This interface represents a print job that can print a specified document | |
| * with a set of job attributes. An object implementing this interface is | |
| * obtained from a print service. | |
| */ | |
| public interface DocPrintJob { | |
| /** | |
| * Determines the {@link PrintService} object to which this print job object | |
| * is bound. | |
| * | |
| * @return {@code PrintService} object | |
| */ | |
| public PrintService getPrintService(); | |
| /** | |
| * Obtains this Print Job's set of printing attributes. The returned | |
| * attribute set object is unmodifiable. The returned attribute set object | |
| * is a "snapshot" of this Print Job's attribute set at the time of the | |
| * {@code getAttributes()} method call; that is, the returned attribute | |
| * set's object's contents will not be updated if this Print Job's attribute | |
| * set's contents change in the future. To detect changes in attribute | |
| * values, call {@code getAttributes()} again and compare the new attribute | |
| * set to the previous attribute set; alternatively, register a listener for | |
| * print job events. The returned value may be an empty set but should not | |
| * be {@code null}. | |
| * | |
| * @return the print job attributes | |
| */ | |
| public PrintJobAttributeSet getAttributes(); | |
| /** | |
| * Registers a listener for event occurring during this print job. If | |
| * listener is {@code null}, no exception is thrown and no action is | |
| * performed. If listener is already registered, it will be registered | |
| * again. | |
| * | |
| * @param listener the object implementing the listener interface | |
| * @see #removePrintJobListener | |
| */ | |
| public void addPrintJobListener(PrintJobListener listener); | |
| /** | |
| * Removes a listener from this print job. This method performs no function, | |
| * nor does it throw an exception, if the listener specified by the argument | |
| * was not previously added to this print job. If listener is {@code null}, | |
| * no exception is thrown and no action is performed. If a listener was | |
| * registered more than once only one of the registrations will be removed. | |
| * | |
| * @param listener the object implementing the listener interface | |
| * @see #addPrintJobListener | |
| */ | |
| public void removePrintJobListener(PrintJobListener listener); | |
| /** | |
| * Registers a listener for changes in the specified attributes. If listener | |
| * is {@code null}, no exception is thrown and no action is performed. To | |
| * determine the attribute updates that may be reported by this job, a | |
| * client can call {@code getAttributes()} and identify the subset that are | |
| * interesting and likely to be reported to the listener. Clients expecting | |
| * to be updated about changes in a specific job attribute should verify it | |
| * is in that set, but updates about an attribute will be made only if it | |
| * changes and this is detected by the job. Also updates may be subject to | |
| * batching by the job. To minimize overhead in print job processing it is | |
| * recommended to listen on only that subset of attributes which are likely | |
| * to change. If the specified set is empty no attribute updates will be | |
| * reported to the listener. If the attribute set is {@code null}, then this | |
| * means to listen on all dynamic attributes that the job supports. This may | |
| * result in no update notifications if a job can not report any attribute | |
| * updates. | |
| * <p> | |
| * If listener is already registered, it will be registered again. | |
| * | |
| * @param listener the object implementing the listener interface | |
| * @param attributes the attributes to listen on, or {@code null} to mean | |
| * all attributes that can change, as determined by the job | |
| * @see #removePrintJobAttributeListener | |
| */ | |
| public void addPrintJobAttributeListener( | |
| PrintJobAttributeListener listener, | |
| PrintJobAttributeSet attributes); | |
| /** | |
| * Removes an attribute listener from this print job. This method performs | |
| * no function, nor does it throw an exception, if the listener specified by | |
| * the argument was not previously added to this print job. If the listener | |
| * is {@code null}, no exception is thrown and no action is performed. If a | |
| * listener is registered more than once, even for a different set of | |
| * attributes, no guarantee is made which listener is removed. | |
| * | |
| * @param listener the object implementing the listener interface | |
| * @see #addPrintJobAttributeListener | |
| */ | |
| public void removePrintJobAttributeListener( | |
| PrintJobAttributeListener listener); | |
| /** | |
| * Prints a document with the specified job attributes. This method should | |
| * only be called once for a given print job. Calling it again will not | |
| * result in a new job being spooled to the printer. The service | |
| * implementation will define policy for service interruption and recovery. | |
| * When the print method returns, printing may not yet have completed as | |
| * printing may happen asynchronously, perhaps in a different thread. | |
| * Application clients which want to monitor the success or failure should | |
| * register a {@code PrintJobListener}. | |
| * <p> | |
| * Print service implementors should close any print data streams (ie | |
| * {@code Reader} or {@code InputStream} implementations) that they obtain | |
| * from the client doc. Robust clients may still wish to verify this. An | |
| * exception is always generated if a {@code DocFlavor} cannot be printed. | |
| * | |
| * @param doc the document to be printed. It must be a flavor supported by | |
| * this PrintJob. | |
| * @param attributes the job attributes to be applied to this print job. If | |
| * this parameter is {@code null} then the default attributes are | |
| * used. | |
| * @throws PrintException the exception additionally may implement an | |
| * interface that more precisely describes the cause of the | |
| * exception | |
| * <ul> | |
| * <li>{@code FlavorException}. If the document has a flavor not | |
| * supported by this print job. | |
| * <li>{@code AttributeException}. If one or more of the | |
| * attributes are not valid for this print job. | |
| * </ul> | |
| */ | |
| public void print(Doc doc, PrintRequestAttributeSet attributes) | |
| throws PrintException; | |
| } |