< prev index next >
src/java.desktop/share/classes/javax/print/DocPrintJob.java
Print this page
@@ -1,7 +1,7 @@
/*
- * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
+ * 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
@@ -27,149 +27,135 @@
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.
- *
+ * 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.
+ * 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 {@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()} 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.
+ * 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 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
+ * 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 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
+ * 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
+ * @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 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 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.
- *
+ * 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.
- * @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.
+ * @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 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
+ * 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.
+ * 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.
+ * 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
- * 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} 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
+ * {@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>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.
+ * <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;
< prev index next >