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 java.util.Locale;
029
030 import javax.print.attribute.Attribute;
031 import javax.print.attribute.AttributeSet;
032 import javax.print.attribute.PrintServiceAttribute;
033 import javax.print.attribute.PrintServiceAttributeSet;
034 import javax.print.event.PrintServiceAttributeListener;
035
036 /**
037 * Interface PrintService is the factory for a DocPrintJob. A PrintService
038 * describes the capabilities of a Printer and can be queried regarding
039 * a printer's supported attributes.
040 * <P>
041 * Example:
042 * <PRE>
043 * DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
044 * PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
045 * aset.add(MediaSizeName.ISO_A4);
046 * PrintService[] pservices =
047 * PrintServiceLookup.lookupPrintServices(flavor, aset);
048 * if (pservices.length > 0) {
049 * DocPrintJob pj = pservices[0].createPrintJob();
050 * try {
051 * FileInputStream fis = new FileInputStream("test.ps");
052 * Doc doc = new SimpleDoc(fis, flavor, null);
053 * pj.print(doc, aset);
054 * } catch (FileNotFoundException fe) {
055 * } catch (PrintException e) {
056 * }
057 * }
058 * </PRE>
059 */
060 public interface PrintService {
061
062 /** Returns a String name for this print service which may be used
063 * by applications to request a particular print service.
064 * In a suitable context, such as a name service, this name must be
065 * unique.
066 * In some environments this unique name may be the same as the user
067 * friendly printer name defined as the
068 * {@link javax.print.attribute.standard.PrinterName PrinterName}
069 * attribute.
070 * @return name of the service.
071 */
072 public String getName();
073
074 /**
075 * Creates and returns a PrintJob capable of handling data from
076 * any of the supported document flavors.
077 * @return a DocPrintJob object
078 */
079 public DocPrintJob createPrintJob();
080
081 /**
082 * Registers a listener for events on this PrintService.
083 * @param listener a PrintServiceAttributeListener, which
084 * monitors the status of a print service
085 * @see #removePrintServiceAttributeListener
086 */
087 public void addPrintServiceAttributeListener(
088 PrintServiceAttributeListener listener);
089
090 /**
091 * Removes the print-service listener from this print service.
092 * This means the listener is no longer interested in
093 * <code>PrintService</code> events.
094 * @param listener a PrintServiceAttributeListener object
095 * @see #addPrintServiceAttributeListener
096 */
097 public void removePrintServiceAttributeListener(
098 PrintServiceAttributeListener listener);
099
100 /**
101 * Obtains this print service's set of printer description attributes
102 * giving this Print Service's status. The returned attribute set object
103 * is unmodifiable. The returned attribute set object is a "snapshot" of
104 * this Print Service's attribute set at the time of the
105 * <CODE>getAttributes()</CODE> method call: that is, the returned
106 * attribute set's contents will <I>not</I> be updated if this print
107 * service's attribute set's contents change in the future. To detect
108 * changes in attribute values, call <CODE>getAttributes()</CODE> again
109 * and compare the new attribute set to the previous attribute set;
110 * alternatively, register a listener for print service events.
111 *
112 * @return Unmodifiable snapshot of this Print Service's attribute set.
113 * May be empty, but not null.
114 */
115 public PrintServiceAttributeSet getAttributes();
116
117 /**
118 * Gets the value of the single specified service attribute.
119 * This may be useful to clients which only need the value of one
120 * attribute and want to minimise overhead.
121 * @param category the category of a PrintServiceAttribute supported
122 * by this service - may not be null.
123 * @return the value of the supported attribute or null if the
124 * attribute is not supported by this service.
125 * @exception NullPointerException if the category is null.
126 * @exception IllegalArgumentException
127 * (unchecked exception) if <CODE>category</CODE> is not a
128 * <code>Class</code> that implements interface
129 *{@link javax.print.attribute.PrintServiceAttribute PrintServiceAttribute}.
130 */
131 public <T extends PrintServiceAttribute> T getAttribute(
132 Class<T> category);
133
134 /**
135 * Determines the print data formats a client can specify when setting
136 * up a job for this <code>PrintService</code>. A print data format is
137 * designated by a "doc
138 * flavor" (class {@link javax.print.DocFlavor DocFlavor})
139 * consisting of a MIME type plus a print data representation class.
140 * <P>
141 * Note that some doc flavors may not be supported in combination
142 * with all attributes. Use <code>getUnsupportedAttributes(..)</code>
143 * to validate specific combinations.
144 *
145 * @return Array of supported doc flavors, should have at least
146 * one element.
147 *
148 */
149 public DocFlavor[] getSupportedDocFlavors();
150
151 /**
152 * Determines if this print service supports a specific
153 * <code>DocFlavor</code>. This is a convenience method to determine
154 * if the <code>DocFlavor</code> would be a member of the result of
155 * <code>getSupportedDocFlavors()</code>.
156 * <p>
157 * Note that some doc flavors may not be supported in combination
158 * with all attributes. Use <code>getUnsupportedAttributes(..)</code>
159 * to validate specific combinations.
160 *
161 * @param flavor the <code>DocFlavor</code>to query for support.
162 * @return <code>true</code> if this print service supports the
163 * specified <code>DocFlavor</code>; <code>false</code> otherwise.
164 * @exception NullPointerException
165 * (unchecked exception) Thrown if <CODE>flavor</CODE> is null.
166 */
167 public boolean isDocFlavorSupported(DocFlavor flavor);
168
169 /**
170 * Determines the printing attribute categories a client can specify
171 * when setting up a job for this print service.
172 * A printing attribute category is
173 * designated by a <code>Class</code> that implements interface
174 * {@link javax.print.attribute.Attribute Attribute}. This method returns
175 * just the attribute <I>categories</I> that are supported; it does not
176 * return the particular attribute <I>values</I> that are supported.
177 * <P>
178 * This method returns all the printing attribute
179 * categories this print service supports for any possible job.
180 * Some categories may not be supported in a particular context (ie
181 * for a particular <code>DocFlavor</code>).
182 * Use one of the methods that include a <code>DocFlavor</code> to
183 * validate the request before submitting it, such as
184 * <code>getSupportedAttributeValues(..)</code>.
185 *
186 * @return Array of printing attribute categories that the client can
187 * specify as a doc-level or job-level attribute in a Print
188 * Request. Each element in the array is a {@link java.lang.Class
189 * Class} that implements interface {@link
190 * javax.print.attribute.Attribute Attribute}.
191 * The array is empty if no categories are supported.
192 */
193 public Class<?>[] getSupportedAttributeCategories();
194
195 /**
196 * Determines whether a client can specify the given printing
197 * attribute category when setting up a job for this print service. A
198 * printing attribute category is designated by a <code>Class</code>
199 * that implements interface {@link javax.print.attribute.Attribute
200 * Attribute}. This method tells whether the attribute <I>category</I> is
201 * supported; it does not tell whether a particular attribute <I>value</I>
202 * is supported.
203 * <p>
204 * Some categories may not be supported in a particular context (ie
205 * for a particular <code>DocFlavor</code>).
206 * Use one of the methods which include a <code>DocFlavor</code> to
207 * validate the request before submitting it, such as
208 * <code>getSupportedAttributeValues(..)</code>.
209 * <P>
210 * This is a convenience method to determine if the category
211 * would be a member of the result of
212 * <code>getSupportedAttributeCategories()</code>.
213 *
214 * @param category Printing attribute category to test. It must be a
215 * <code>Class</code> that implements
216 * interface
217 * {@link javax.print.attribute.Attribute Attribute}.
218 *
219 * @return <code>true</code> if this print service supports
220 * specifying a doc-level or
221 * job-level attribute in <CODE>category</CODE> in a Print
222 * Request; <code>false</code> if it doesn't.
223 *
224 * @exception NullPointerException
225 * (unchecked exception) Thrown if <CODE>category</CODE> is null.
226 * @exception IllegalArgumentException
227 * (unchecked exception) Thrown if <CODE>category</CODE> is not a
228 * <code>Class</code> that implements interface
229 * {@link javax.print.attribute.Attribute Attribute}.
230 */
231 public boolean isAttributeCategorySupported(
232 Class<? extends Attribute> category);
233
234 /**
235 * Determines this print service's default printing attribute value in
236 * the given category. A printing attribute value is an instance of
237 * a class that implements interface
238 * {@link javax.print.attribute.Attribute Attribute}. If a client sets
239 * up a print job and does not specify any attribute value in the
240 * given category, this Print Service will use the
241 * default attribute value instead.
242 * <p>
243 * Some attributes may not be supported in a particular context (ie
244 * for a particular <code>DocFlavor</code>).
245 * Use one of the methods that include a <code>DocFlavor</code> to
246 * validate the request before submitting it, such as
247 * <code>getSupportedAttributeValues(..)</code>.
248 * <P>
249 * Not all attributes have a default value. For example the
250 * service will not have a defaultvalue for <code>RequestingUser</code>
251 * i.e. a null return for a supported category means there is no
252 * service default value for that category. Use the
253 * <code>isAttributeCategorySupported(Class)</code> method to
254 * distinguish these cases.
255 *
256 * @param category Printing attribute category for which the default
257 * attribute value is requested. It must be a {@link
258 * java.lang.Class Class} that implements interface
259 * {@link javax.print.attribute.Attribute
260 * Attribute}.
261 *
262 * @return Default attribute value for <CODE>category</CODE>, or null
263 * if this Print Service does not support specifying a doc-level or
264 * job-level attribute in <CODE>category</CODE> in a Print
265 * Request, or the service does not have a default value
266 * for this attribute.
267 *
268 * @exception NullPointerException
269 * (unchecked exception) Thrown if <CODE>category</CODE> is null.
270 * @exception IllegalArgumentException
271 * (unchecked exception) Thrown if <CODE>category</CODE> is not a
272 * {@link java.lang.Class Class} that implements interface {@link
273 * javax.print.attribute.Attribute Attribute}.
274 */
275 public Object getDefaultAttributeValue(
276 Class<? extends Attribute> category);
277
278 /**
279 * Determines the printing attribute values a client can specify in
280 * the given category when setting up a job for this print service. A
281 * printing
282 * attribute value is an instance of a class that implements interface
283 * {@link javax.print.attribute.Attribute Attribute}.
284 * <P>
285 * If <CODE>flavor</CODE> is null and <CODE>attributes</CODE> is null
286 * or is an empty set, this method returns all the printing attribute
287 * values this Print Service supports for any possible job. If
288 * <CODE>flavor</CODE> is not null or <CODE>attributes</CODE> is not
289 * an empty set, this method returns just the printing attribute values
290 * that are compatible with the given doc flavor and/or set of attributes.
291 * That is, a null return value may indicate that specifying this attribute
292 * is incompatible with the specified DocFlavor.
293 * Also if DocFlavor is not null it must be a flavor supported by this
294 * PrintService, else IllegalArgumentException will be thrown.
295 * <P>
296 * If the <code>attributes</code> parameter contains an Attribute whose
297 * category is the same as the <code>category</code> parameter, the service
298 * must ignore this attribute in the AttributeSet.
299 * <p>
300 * <code>DocAttribute</code>s which are to be specified on the
301 * <code>Doc</code> must be included in this set to accurately
302 * represent the context.
303 * <p>
304 * This method returns an Object because different printing attribute
305 * categories indicate the supported attribute values in different ways.
306 * The documentation for each printing attribute in package {@link
307 * javax.print.attribute.standard javax.print.attribute.standard}
308 * describes how each attribute indicates its supported values. Possible
309 * ways of indicating support include:
310 * <UL>
311 * <LI>
312 * Return a single instance of the attribute category to indicate that any
313 * value is legal -- used, for example, by an attribute whose value is an
314 * arbitrary text string. (The value of the returned attribute object is
315 * irrelevant.)
316 * <LI>
317 * Return an array of one or more instances of the attribute category,
318 * containing the legal values -- used, for example, by an attribute with
319 * a list of enumerated values. The type of the array is an array of the
320 * specified attribute category type as returned by its
321 * <code>getCategory(Class)</code>.
322 * <LI>
323 * Return a single object (of some class other than the attribute category)
324 * that indicates bounds on the legal values -- used, for example, by an
325 * integer-valued attribute that must lie within a certain range.
326 * </UL>
327 * <P>
328 *
329 * @param category Printing attribute category to test. It must be a
330 * {@link java.lang.Class Class} that implements
331 * interface {@link
332 * javax.print.attribute.Attribute Attribute}.
333 * @param flavor Doc flavor for a supposed job, or null.
334 * @param attributes Set of printing attributes for a supposed job
335 * (both job-level attributes and document-level
336 * attributes), or null.
337 *
338 * @return Object indicating supported values for <CODE>category</CODE>,
339 * or null if this Print Service does not support specifying a
340 * doc-level or job-level attribute in <CODE>category</CODE> in
341 * a Print Request.
342 *
343 * @exception NullPointerException
344 * (unchecked exception) Thrown if <CODE>category</CODE> is null.
345 * @exception IllegalArgumentException
346 * (unchecked exception) Thrown if <CODE>category</CODE> is not a
347 * {@link java.lang.Class Class} that implements interface {@link
348 * javax.print.attribute.Attribute Attribute}, or
349 * <code>DocFlavor</code> is not supported by this service.
350 */
351 public Object getSupportedAttributeValues(
352 Class<? extends Attribute> category, DocFlavor flavor,
353 AttributeSet attributes);
354
355 /**
356 * Determines whether a client can specify the given printing
357 * attribute
358 * value when setting up a job for this Print Service. A printing
359 * attribute value is an instance of a class that implements interface
360 * {@link javax.print.attribute.Attribute Attribute}.
361 * <P>
362 * If <CODE>flavor</CODE> is null and <CODE>attributes</CODE> is null or
363 * is an empty set, this method tells whether this Print Service supports
364 * the given printing attribute value for some possible combination of doc
365 * flavor and set of attributes. If <CODE>flavor</CODE> is not null or
366 * <CODE>attributes</CODE> is not an empty set, this method tells whether
367 * this Print Service supports the given printing attribute value in
368 * combination with the given doc flavor and/or set of attributes.
369 * <p>
370 * Also if DocFlavor is not null it must be a flavor supported by this
371 * PrintService, else IllegalArgumentException will be thrown.
372 * <p>
373 * <code>DocAttribute</code>s which are to be specified on the
374 * <code>Doc</code> must be included in this set to accurately
375 * represent the context.
376 * <p>
377 * This is a convenience method to determine if the value
378 * would be a member of the result of
379 * <code>getSupportedAttributeValues(...)</code>.
380 *
381 * @param attrval Printing attribute value to test.
382 * @param flavor Doc flavor for a supposed job, or null.
383 * @param attributes Set of printing attributes for a supposed job
384 * (both job-level attributes and document-level
385 * attributes), or null.
386 *
387 * @return True if this Print Service supports specifying
388 * <CODE>attrval</CODE> as a doc-level or job-level attribute in a
389 * Print Request, false if it doesn't.
390 *
391 * @exception NullPointerException
392 * (unchecked exception) if <CODE>attrval</CODE> is null.
393 * @exception IllegalArgumentException if flavor is not supported by
394 * this PrintService.
395 */
396 public boolean isAttributeValueSupported(Attribute attrval,
397 DocFlavor flavor, AttributeSet attributes);
398
399 /**
400 * Identifies the attributes that are unsupported for a print request
401 * in the context of a particular DocFlavor.
402 * This method is useful for validating a potential print job and
403 * identifying the specific attributes which cannot be supported.
404 * It is important to supply only a supported DocFlavor or an
405 * IllegalArgumentException will be thrown. If the
406 * return value from this method is null, all attributes are supported.
407 * <p>
408 * <code>DocAttribute</code>s which are to be specified on the
409 * <code>Doc</code> must be included in this set to accurately
410 * represent the context.
411 * <p>
412 * If the return value is non-null, all attributes in the returned
413 * set are unsupported with this DocFlavor. The returned set does not
414 * distinguish attribute categories that are unsupported from
415 * unsupported attribute values.
416 * <p>
417 * A supported print request can then be created by removing
418 * all unsupported attributes from the original attribute set,
419 * except in the case that the DocFlavor is unsupported.
420 * <p>
421 * If any attributes are unsupported only because they are in conflict
422 * with other attributes then it is at the discretion of the service
423 * to select the attribute(s) to be identified as the cause of the
424 * conflict.
425 * <p>
426 * Use <code>isDocFlavorSupported()</code> to verify that a DocFlavor
427 * is supported before calling this method.
428 *
429 * @param flavor Doc flavor to test, or null
430 * @param attributes Set of printing attributes for a supposed job
431 * (both job-level attributes and document-level
432 * attributes), or null.
433 *
434 * @return null if this Print Service supports the print request
435 * specification, else the unsupported attributes.
436 *
437 * @exception IllegalArgumentException if<CODE>flavor</CODE> is
438 * not supported by this PrintService.
439 */
440 public AttributeSet getUnsupportedAttributes(DocFlavor flavor,
441 AttributeSet attributes);
442
443 /**
444 * Returns a factory for UI components which allow users to interact
445 * with the service in various roles.
446 * Services which do not provide any UI should return null.
447 * Print Services which do provide UI but want to be supported in
448 * an environment with no UI support should ensure that the factory
449 * is not initialised unless the application calls this method to
450 * obtain the factory.
451 * See <code>ServiceUIFactory</code> for more information.
452 * @return null or a factory for UI components.
453 */
454 public ServiceUIFactory getServiceUIFactory();
455
456 /**
457 * Determines if two services are referring to the same underlying
458 * service. Objects encapsulating a print service may not exhibit
459 * equality of reference even though they refer to the same underlying
460 * service.
461 * <p>
462 * Clients should call this method to determine if two services are
463 * referring to the same underlying service.
464 * <p>
465 * Services must implement this method and return true only if the
466 * service objects being compared may be used interchangeably by the
467 * client.
468 * Services are free to return the same object reference to an underlying
469 * service if that, but clients must not depend on equality of reference.
470 * @param obj the reference object with which to compare.
471 * @return true if this service is the same as the obj argument,
472 * false otherwise.
473 */
474 public boolean equals(Object obj);
475
476 /**
477 * This method should be implemented consistently with
478 * <code>equals(Object)</code>.
479 * @return hash code of this object.
480 */
481 public int hashCode();
482
483 }
|