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

}