DocPrintJob


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 }
160
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags