| /* |
| * Copyright (c) 2000, 2006, 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; |
| import javax.print.PrintException; |
| |
| /** |
| * |
| * 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</code> 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 {@link #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()</code> 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 null. |
| * @return the print job attributes |
| */ |
| public PrintJobAttributeSet getAttributes(); |
| |
| /** |
| * Registers a listener for event occurring during this print job. |
| * If listener is null, no exception is thrown and no action is |
| * performed. |
| * If listener is already registered, it will be registered again. |
| * @see #removePrintJobListener |
| * |
| * @param listener The object implementing the listener interface |
| * |
| */ |
| 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 component. If listener is 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. |
| * @see #addPrintJobListener |
| * |
| * @param listener The object implementing the listener interface |
| */ |
| public void removePrintJobListener(PrintJobListener listener); |
| |
| /** |
| * Registers a listener for changes in the specified attributes. |
| * If listener is 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()</code> 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 minimise 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 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. |
| * |
| * If listener is already registered, it will be registered again. |
| * @see #removePrintJobAttributeListener |
| * |
| * @param listener The object implementing the listener interface |
| * @param attributes The attributes to listen on, or null to mean |
| * all attributes that can change, as determined by the job. |
| */ |
| 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 component. If the listener is 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. |
| * @see #addPrintJobAttributeListener |
| * |
| * @param listener The object implementing the listener interface |
| * |
| */ |
| 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 PrintJobListener. |
| * <p> |
| * Print service implementors should close any print data streams (ie |
| * Reader or 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</code> cannot |
| * be printed. |
| * |
| * @param doc The document to be printed. If must be a flavor |
| * supported by this PrintJob. |
| * |
| * @param attributes The job attributes to be applied to this print job. |
| * If this parameter is 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>FlavorException. |
| * If the document has a flavor not supported by this print job. |
| * <li>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; |
| |
| } |
