001 /*
002 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.print;
027
028 import javax.print.attribute.AttributeSet;
029 import javax.print.attribute.PrintJobAttributeSet;
030 import javax.print.attribute.PrintRequestAttributeSet;
031 import javax.print.event.PrintJobAttributeListener;
032 import javax.print.event.PrintJobListener;
033 import javax.print.PrintException;
034
035 /**
036 *
037 * This interface represents a print job that can print a specified
038 * document with a set of job attributes. An object implementing
039 * this interface is obtained from a print service.
040 *
041 */
042
043 public interface DocPrintJob {
044
045 /**
046 * Determines the {@link PrintService} object to which this print job
047 * object is bound.
048 *
049 * @return <code>PrintService</code> object.
050 *
051 */
052 public PrintService getPrintService();
053
054 /**
055 * Obtains this Print Job's set of printing attributes.
056 * The returned attribute set object is unmodifiable.
057 * The returned attribute set object is a "snapshot" of this Print Job's
058 * attribute set at the time of the {@link #getAttributes()} method
059 * call; that is, the returned attribute set's object's contents will
060 * not be updated if this Print Job's attribute set's contents change
061 * in the future. To detect changes in attribute values, call
062 * <code>getAttributes()</code> again and compare the new attribute
063 * set to the previous attribute set; alternatively, register a
064 * listener for print job events.
065 * The returned value may be an empty set but should not be null.
066 * @return the print job attributes
067 */
068 public PrintJobAttributeSet getAttributes();
069
070 /**
071 * Registers a listener for event occurring during this print job.
072 * If listener is null, no exception is thrown and no action is
073 * performed.
074 * If listener is already registered, it will be registered again.
075 * @see #removePrintJobListener
076 *
077 * @param listener The object implementing the listener interface
078 *
079 */
080 public void addPrintJobListener(PrintJobListener listener);
081
082 /**
083 * Removes a listener from this print job.
084 * This method performs no function, nor does it throw an exception,
085 * if the listener specified by the argument was not previously added
086 * to this component. If listener is null, no exception is thrown and
087 * no action is performed. If a listener was registered more than once
088 * only one of the registrations will be removed.
089 * @see #addPrintJobListener
090 *
091 * @param listener The object implementing the listener interface
092 */
093 public void removePrintJobListener(PrintJobListener listener);
094
095 /**
096 * Registers a listener for changes in the specified attributes.
097 * If listener is null, no exception is thrown and no action is
098 * performed.
099 * To determine the attribute updates that may be reported by this job,
100 * a client can call <code>getAttributes()</code> and identify the
101 * subset that are interesting and likely to be reported to the
102 * listener. Clients expecting to be updated about changes in a
103 * specific job attribute should verify it is in that set, but
104 * updates about an attribute will be made only if it changes and this
105 * is detected by the job. Also updates may be subject to batching
106 * by the job. To minimise overhead in print job processing it is
107 * recommended to listen on only that subset of attributes which
108 * are likely to change.
109 * If the specified set is empty no attribute updates will be reported
110 * to the listener.
111 * If the attribute set is null, then this means to listen on all
112 * dynamic attributes that the job supports. This may result in no
113 * update notifications if a job can not report any attribute updates.
114 *
115 * If listener is already registered, it will be registered again.
116 * @see #removePrintJobAttributeListener
117 *
118 * @param listener The object implementing the listener interface
119 * @param attributes The attributes to listen on, or null to mean
120 * all attributes that can change, as determined by the job.
121 */
122 public void addPrintJobAttributeListener(
123 PrintJobAttributeListener listener,
124 PrintJobAttributeSet attributes);
125
126 /**
127 * Removes an attribute listener from this print job.
128 * This method performs no function, nor does it throw an exception,
129 * if the listener specified by the argument was not previously added
130 * to this component. If the listener is null, no exception is thrown
131 * and no action is performed.
132 * If a listener is registered more than once, even for a different
133 * set of attributes, no guarantee is made which listener is removed.
134 * @see #addPrintJobAttributeListener
135 *
136 * @param listener The object implementing the listener interface
137 *
138 */
139 public void removePrintJobAttributeListener(
140 PrintJobAttributeListener listener);
141
142 /**
143 * Prints a document with the specified job attributes.
144 * This method should only be called once for a given print job.
145 * Calling it again will not result in a new job being spooled to
146 * the printer. The service implementation will define policy
147 * for service interruption and recovery.
148 * When the print method returns, printing may not yet have completed as
149 * printing may happen asynchronously, perhaps in a different thread.
150 * Application clients which want to monitor the success or failure
151 * should register a PrintJobListener.
152 * <p>
153 * Print service implementors should close any print data streams (ie
154 * Reader or InputStream implementations) that they obtain
155 * from the client doc. Robust clients may still wish to verify this.
156 * An exception is always generated if a <code>DocFlavor</code> cannot
157 * be printed.
158 *
159 * @param doc The document to be printed. If must be a flavor
160 * supported by this PrintJob.
161 *
162 * @param attributes The job attributes to be applied to this print job.
163 * If this parameter is null then the default attributes are used.
164 * @throws PrintException The exception additionally may implement
165 * an interface that more precisely describes the cause of the
166 * exception
167 * <ul>
168 * <li>FlavorException.
169 * If the document has a flavor not supported by this print job.
170 * <li>AttributeException.
171 * If one or more of the attributes are not valid for this print job.
172 * </ul>
173 */
174 public void print(Doc doc, PrintRequestAttributeSet attributes)
175 throws PrintException;
176
177 }
|