DocPrintJob.java

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

packagejavax.print;

importjavax.print.attribute.PrintJobAttributeSet;
importjavax.print.attribute.PrintRequestAttributeSet;
importjavax.print.event.PrintJobAttributeListener;
importjavax.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.
 */
publicinterfaceDocPrintJob {

/**
 * Determines the {@link PrintService} object to which this print job object
 * is bound.
 *
 * @return {@code PrintService} object
 */
publicPrintServicegetPrintService();

/**
 * 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
 */
publicPrintJobAttributeSetgetAttributes();

/**
 * 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
 */
publicvoidaddPrintJobListener(PrintJobListenerlistener);

/**
 * 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
 */
publicvoidremovePrintJobListener(PrintJobListenerlistener);

/**
 * 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
 */
publicvoidaddPrintJobAttributeListener(
PrintJobAttributeListenerlistener,
PrintJobAttributeSetattributes);

/**
 * 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
 */
publicvoidremovePrintJobAttributeListener(
PrintJobAttributeListenerlistener);

/**
 * 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>
 */
publicvoidprint(Docdoc, PrintRequestAttributeSetattributes)
throwsPrintException;

}