/* * 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; }