1 /*
2 * Copyright (c) 2000, 2006, 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 minimise 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 }