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