1. /*

  2.  * @(#)DocPrintJob.java	1.10 03/12/19

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package javax.print;

  9. 

  10. import javax.print.attribute.AttributeSet;

  11. import javax.print.attribute.PrintJobAttributeSet;

  12. import javax.print.attribute.PrintRequestAttributeSet;

  13. import javax.print.event.PrintJobAttributeListener;

  14. import javax.print.event.PrintJobListener;

  15. import javax.print.PrintException;

  16. 

  17. /**

  18.  *

  19.  * This interface represents a print job that can print a specified

  20.  * document with a set of job attributes.  An object implementing

  21.  * this interface is obtained from a print service.

  22.  *

  23.  */

  24. 

  25. public interface DocPrintJob {

  26. 

  27.     /**

  28.      * Determines the {@link PrintService} object to which this print job 

  29.      * object is bound. 

  30.      *

  31.      * @return  <code>PrintService</code> object.

  32.      *

  33.      */

  34.     public PrintService getPrintService();

  35.     

  36.     /**

  37.      * Obtains this Print Job's set of printing attributes.

  38.      * The returned attribute set object is unmodifiable. 

  39.      * The returned attribute set object is a "snapshot" of this Print Job's

  40.      * attribute set at the time of the {@link #getAttributes()} method

  41.      * call; that is, the returned attribute set's object's contents will

  42.      * not be updated if this Print Job's attribute set's contents change

  43.      * in the future. To detect changes in attribute values, call

  44.      * <code>getAttributes()</code> again and compare the new attribute

  45.      * set to the previous attribute set; alternatively, register a

  46.      * listener for print job events.

  47.      * The returned value may be an empty set but should not be null.

  48.      * @return the print job attributes

  49.      */

  50.      public PrintJobAttributeSet getAttributes();

  51. 

  52.     /**

  53.      * Registers a listener for event occurring during this print job.

  54.      * If listener is null, no exception is thrown and no action is

  55.      * performed.

  56.      * If listener is already registered, it will be registered again.

  57.      * @see #removePrintJobListener

  58.      *

  59.      * @param listener  The object implementing the listener interface

  60.      *

  61.      */

  62.     public void addPrintJobListener(PrintJobListener listener);

  63.     

  64.     /**

  65.      * Removes a listener from this print job.

  66.      * This method performs no function, nor does it throw an exception,

  67.      * if the listener specified by the argument was not previously added

  68.      * to this component. If listener is null, no exception is thrown and

  69.      * no action is performed. If a listener was registered more than once

  70.      * only one of the registrations will be removed.

  71.      * @see #addPrintJobListener

  72.      * 

  73.      * @param listener  The object implementing the listener interface

  74.      */

  75.     public void removePrintJobListener(PrintJobListener listener);

  76. 

  77.     /**

  78.      * Registers a listener for changes in the specified attributes.

  79.      * If listener is null, no exception is thrown and no action is

  80.      * performed.

  81.      * To determine the attribute updates that may be reported by this job,

  82.      * a client can call <code>getAttributes()/<code> and identify the

  83.      * subset that are interesting and likely to be reported to the

  84.      * listener. Clients expecting to be updated about changes in a

  85.      * specific job attribute should verify it is in that set, but

  86.      * updates about an attribute will be made only if it changes and this

  87.      * is detected by the job. Also updates may be subject to batching

  88.      * by the job. To minimise overhead in print job processing it is

  89.      * recommended to listen on only that subset of attributes which

  90.      * are likely to change.

  91.      * If the specified set is empty no attribute updates will be reported

  92.      * to the listener.

  93.      * If the attribute set is null, then this means to listen on all

  94.      * dynamic attributes that the job supports. This may result in no

  95.      * update notifications if a job can not report any attribute updates.

  96.      * 

  97.      * If listener is already registered, it will be registered again.

  98.      * @see #removePrintJobAttributeListener

  99.      *

  100.      * @param listener  The object implementing the listener interface

  101.      * @param attributes The attributes to listen on, or null to mean

  102.      * all attributes that can change, as determined by the job.

  103.      */

  104.     public void addPrintJobAttributeListener(

  105.                                   PrintJobAttributeListener listener,

  106.                                   PrintJobAttributeSet attributes);

  107.     

  108.     /**

  109.      * Removes an attribute listener from this print job.

  110.      * This method performs no function, nor does it throw an exception,

  111.      * if the listener specified by the argument was not previously added

  112.      * to this component. If the listener is null, no exception is thrown

  113.      * and no action is performed.

  114.      * If a listener is registered more than once, even for a different

  115.      * set of attributes, no guarantee is made which listener is removed.

  116.      * @see #addPrintJobAttributeListener

  117.      *

  118.      * @param listener  The object implementing the listener interface

  119.      *

  120.      */

  121.     public void removePrintJobAttributeListener(

  122.                                       PrintJobAttributeListener listener);

  123. 

  124.     /**

  125.      * Prints a document with the specified job attributes.

  126.      * This method should only be called once for a given print job.

  127.      * Calling it again will not result in a new job being spooled to

  128.      * the printer. The service implementation will define policy

  129.      * for service interruption and recovery.

  130.      * When the print method returns, printing may not yet have completed as

  131.      * printing may happen asynchronously, perhaps in a different thread.

  132.      * Application clients which  want to monitor the success or failure

  133.      * should register a PrintJobListener.

  134.      * <p>

  135.      * Print service implementors should close any print data streams (ie

  136.      * Reader or InputStream implementations) that they obtain

  137.      * from the client doc. Robust clients may still wish to verify this.

  138.      * An exception is always generated if a <code>DocFlavor</code> cannot

  139.      * be printed.

  140.      *

  141.      * @param doc	The document to be printed. If must be a flavor

  142.      *					supported by this PrintJob.

  143.      *

  144.      * @param attributes The job attributes to be applied to this print job.

  145.      *	      If this parameter is null then the default attributes are used.

  146.      * @throws PrintException The exception additionally may implement 

  147.      * an interface that more precisely describes the cause of the

  148.      * exception

  149.      * <ul>

  150.      * <li>FlavorException.

  151.      *	If the document has a flavor not supported by this print job.

  152.      * <li>AttributeException.

  153.      *	If one or more of the attributes are not valid for this print job.

  154.      * </ul>

  155.      */

  156.     public void print(Doc doc, PrintRequestAttributeSet attributes)

  157.           throws PrintException;

  158.     		

  159. }