View Javadoc
1   /*
2    * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.print;
27  
28  import javax.print.attribute.PrintJobAttributeSet;
29  import javax.print.attribute.PrintRequestAttributeSet;
30  import javax.print.event.PrintJobAttributeListener;
31  import javax.print.event.PrintJobListener;
32  import javax.print.PrintException;
33  
34  /**
35   *
36   * This interface represents a print job that can print a specified
37   * document with a set of job attributes.  An object implementing
38   * this interface is obtained from a print service.
39   *
40   */
41  
42  public interface DocPrintJob {
43  
44      /**
45       * Determines the {@link PrintService} object to which this print job
46       * object is bound.
47       *
48       * @return  <code>PrintService</code> object.
49       *
50       */
51      public PrintService getPrintService();
52  
53      /**
54       * Obtains this Print Job's set of printing attributes.
55       * The returned attribute set object is unmodifiable.
56       * The returned attribute set object is a "snapshot" of this Print Job's
57       * attribute set at the time of the {@link #getAttributes()} method
58       * call; that is, the returned attribute set's object's contents will
59       * not be updated if this Print Job's attribute set's contents change
60       * in the future. To detect changes in attribute values, call
61       * <code>getAttributes()</code> again and compare the new attribute
62       * set to the previous attribute set; alternatively, register a
63       * listener for print job events.
64       * The returned value may be an empty set but should not be null.
65       * @return the print job attributes
66       */
67       public PrintJobAttributeSet getAttributes();
68  
69      /**
70       * Registers a listener for event occurring during this print job.
71       * If listener is null, no exception is thrown and no action is
72       * performed.
73       * If listener is already registered, it will be registered again.
74       * @see #removePrintJobListener
75       *
76       * @param listener  The object implementing the listener interface
77       *
78       */
79      public void addPrintJobListener(PrintJobListener listener);
80  
81      /**
82       * Removes a listener from this print job.
83       * This method performs no function, nor does it throw an exception,
84       * if the listener specified by the argument was not previously added
85       * to this component. If listener is null, no exception is thrown and
86       * no action is performed. If a listener was registered more than once
87       * only one of the registrations will be removed.
88       * @see #addPrintJobListener
89       *
90       * @param listener  The object implementing the listener interface
91       */
92      public void removePrintJobListener(PrintJobListener listener);
93  
94      /**
95       * Registers a listener for changes in the specified attributes.
96       * If listener is null, no exception is thrown and no action is
97       * performed.
98       * To determine the attribute updates that may be reported by this job,
99       * a client can call <code>getAttributes()</code> and identify the
100      * subset that are interesting and likely to be reported to the
101      * listener. Clients expecting to be updated about changes in a
102      * specific job attribute should verify it is in that set, but
103      * updates about an attribute will be made only if it changes and this
104      * is detected by the job. Also updates may be subject to batching
105      * by the job. To minimize overhead in print job processing it is
106      * recommended to listen on only that subset of attributes which
107      * are likely to change.
108      * If the specified set is empty no attribute updates will be reported
109      * to the listener.
110      * If the attribute set is null, then this means to listen on all
111      * dynamic attributes that the job supports. This may result in no
112      * update notifications if a job can not report any attribute updates.
113      *
114      * If listener is already registered, it will be registered again.
115      * @see #removePrintJobAttributeListener
116      *
117      * @param listener  The object implementing the listener interface
118      * @param attributes The attributes to listen on, or null to mean
119      * all attributes that can change, as determined by the job.
120      */
121     public void addPrintJobAttributeListener(
122                                   PrintJobAttributeListener listener,
123                                   PrintJobAttributeSet attributes);
124 
125     /**
126      * Removes an attribute listener from this print job.
127      * This method performs no function, nor does it throw an exception,
128      * if the listener specified by the argument was not previously added
129      * to this component. If the listener is null, no exception is thrown
130      * and no action is performed.
131      * If a listener is registered more than once, even for a different
132      * set of attributes, no guarantee is made which listener is removed.
133      * @see #addPrintJobAttributeListener
134      *
135      * @param listener  The object implementing the listener interface
136      *
137      */
138     public void removePrintJobAttributeListener(
139                                       PrintJobAttributeListener listener);
140 
141     /**
142      * Prints a document with the specified job attributes.
143      * This method should only be called once for a given print job.
144      * Calling it again will not result in a new job being spooled to
145      * the printer. The service implementation will define policy
146      * for service interruption and recovery.
147      * When the print method returns, printing may not yet have completed as
148      * printing may happen asynchronously, perhaps in a different thread.
149      * Application clients which  want to monitor the success or failure
150      * should register a PrintJobListener.
151      * <p>
152      * Print service implementors should close any print data streams (ie
153      * Reader or InputStream implementations) that they obtain
154      * from the client doc. Robust clients may still wish to verify this.
155      * An exception is always generated if a <code>DocFlavor</code> cannot
156      * be printed.
157      *
158      * @param doc       The document to be printed. If must be a flavor
159      *                                  supported by this PrintJob.
160      *
161      * @param attributes The job attributes to be applied to this print job.
162      *        If this parameter is null then the default attributes are used.
163      * @throws PrintException The exception additionally may implement
164      * an interface that more precisely describes the cause of the
165      * exception
166      * <ul>
167      * <li>FlavorException.
168      *  If the document has a flavor not supported by this print job.
169      * <li>AttributeException.
170      *  If one or more of the attributes are not valid for this print job.
171      * </ul>
172      */
173     public void print(Doc doc, PrintRequestAttributeSet attributes)
174           throws PrintException;
175 
176 }