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 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 category the category of a PrintServiceAttribute supported
123      * by this service - may not be null.
124      * @return the value of the supported attribute or null if the
125      * attribute is not supported by this service.
126      * @exception NullPointerException if the category is null.
127      * @exception  IllegalArgumentException
128      *     (unchecked exception) if <CODE>category</CODE> is not a
129      *     <code>Class</code> that implements interface
130      *{@link javax.print.attribute.PrintServiceAttribute PrintServiceAttribute}.
131      */
132     public <T extends PrintServiceAttribute>
133         T getAttribute(Class<T> category);
134 
135     /**
136      * Determines the print data formats a client can specify when setting
137      * up a job for this <code>PrintService</code>. A print data format is
138      * designated by a "doc
139      * flavor" (class {@link javax.print.DocFlavor DocFlavor})
140      * consisting of a MIME type plus a print data representation class.
141      * <P>
142      * Note that some doc flavors may not be supported in combination
143      * with all attributes. Use <code>getUnsupportedAttributes(..)</code>
144      * to validate specific combinations.
145      *
146      * @return  Array of supported doc flavors, should have at least
147      *          one element.
148      *
149      */
150     public DocFlavor[] getSupportedDocFlavors();
151 
152     /**
153      * Determines if this print service supports a specific
154      * <code>DocFlavor</code>.  This is a convenience method to determine
155      * if the <code>DocFlavor</code> would be a member of the result of
156      * <code>getSupportedDocFlavors()</code>.
157      * <p>
158      * Note that some doc flavors may not be supported in combination
159      * with all attributes. Use <code>getUnsupportedAttributes(..)</code>
160      * to validate specific combinations.
161      *
162      * @param flavor the <code>DocFlavor</code>to query for support.
163      * @return  <code>true</code> if this print service supports the
164      * specified <code>DocFlavor</code>; <code>false</code> otherwise.
165      * @exception  NullPointerException
166      *     (unchecked exception) Thrown if <CODE>flavor</CODE> is null.
167      */
168     public boolean isDocFlavorSupported(DocFlavor flavor);
169 
170 
171     /**
172      * Determines the printing attribute categories a client can specify
173      * when setting up a job for this print service.
174      * A printing attribute category is
175      * designated by a <code>Class</code> that implements interface
176      * {@link javax.print.attribute.Attribute Attribute}. This method returns
177      * just the attribute <I>categories</I> that are supported; it does not
178      * return the particular attribute <I>values</I> that are supported.
179      * <P>
180      * This method returns all the printing attribute
181      * categories this print service supports for any possible job.
182      * Some categories may not be supported in a particular context (ie
183      * for a particular <code>DocFlavor</code>).
184      * Use one of the methods that include a <code>DocFlavor</code> to
185      * validate the request before submitting it, such as
186      * <code>getSupportedAttributeValues(..)</code>.
187      *
188      * @return  Array of printing attribute categories that the client can
189      *          specify as a doc-level or job-level attribute in a Print
190      *          Request. Each element in the array is a {@link java.lang.Class
191      *          Class} that implements interface {@link
192      *          javax.print.attribute.Attribute Attribute}.
193      *          The array is empty if no categories are supported.
194      */
195     public Class<?>[] getSupportedAttributeCategories();
196 
197     /**
198      * Determines whether a client can specify the given printing
199      * attribute category when setting up a job for this print service. A
200      * printing attribute category is designated by a <code>Class</code>
201      * that implements interface {@link javax.print.attribute.Attribute
202      * Attribute}. This method tells whether the attribute <I>category</I> is
203      * supported; it does not tell whether a particular attribute <I>value</I>
204      * is supported.
205      * <p>
206      * Some categories may not be supported in a particular context (ie
207      * for a particular <code>DocFlavor</code>).
208      * Use one of the methods which include a <code>DocFlavor</code> to
209      * validate the request before submitting it, such as
210      * <code>getSupportedAttributeValues(..)</code>.
211      * <P>
212      * This is a convenience method to determine if the category
213      * would be a member of the result of
214      * <code>getSupportedAttributeCategories()</code>.
215      *
216      * @param  category    Printing attribute category to test. It must be a
217      *                        <code>Class</code> that implements
218      *                        interface
219      *                {@link javax.print.attribute.Attribute Attribute}.
220      *
221      * @return  <code>true</code> if this print service supports
222      *          specifying a doc-level or
223      *          job-level attribute in <CODE>category</CODE> in a Print
224      *          Request; <code>false</code> if it doesn't.
225      *
226      * @exception  NullPointerException
227      *     (unchecked exception) Thrown if <CODE>category</CODE> is null.
228      * @exception  IllegalArgumentException
229      *     (unchecked exception) Thrown if <CODE>category</CODE> is not a
230      *     <code>Class</code> that implements interface
231      *     {@link javax.print.attribute.Attribute Attribute}.
232      */
233     public boolean
234         isAttributeCategorySupported(Class<? extends Attribute> category);
235 
236     /**
237      * Determines this print service's default printing attribute value in
238      * the given category. A printing attribute value is an instance of
239      * a class that implements interface
240      * {@link javax.print.attribute.Attribute Attribute}. If a client sets
241      * up a print job and does not specify any attribute value in the
242      * given category, this Print Service will use the
243      * default attribute value instead.
244      * <p>
245      * Some attributes may not be supported in a particular context (ie
246      * for a particular <code>DocFlavor</code>).
247      * Use one of the methods that include a <code>DocFlavor</code> to
248      * validate the request before submitting it, such as
249      * <code>getSupportedAttributeValues(..)</code>.
250      * <P>
251      * Not all attributes have a default value. For example the
252      * service will not have a defaultvalue for <code>RequestingUser</code>
253      * i.e. a null return for a supported category means there is no
254      * service default value for that category. Use the
255      * <code>isAttributeCategorySupported(Class)</code> method to
256      * distinguish these cases.
257      *
258      * @param  category    Printing attribute category for which the default
259      *                     attribute value is requested. It must be a {@link
260      *                        java.lang.Class Class} that implements interface
261      *                        {@link javax.print.attribute.Attribute
262      *                        Attribute}.
263      *
264      * @return  Default attribute value for <CODE>category</CODE>, or null
265      *       if this Print Service does not support specifying a doc-level or
266      *          job-level attribute in <CODE>category</CODE> in a Print
267      *          Request, or the service does not have a default value
268      *          for this attribute.
269      *
270      * @exception  NullPointerException
271      *     (unchecked exception) Thrown if <CODE>category</CODE> is null.
272      * @exception  IllegalArgumentException
273      *     (unchecked exception) Thrown if <CODE>category</CODE> is not a
274      *     {@link java.lang.Class Class} that implements interface {@link
275      *     javax.print.attribute.Attribute Attribute}.
276      */
277     public Object
278         getDefaultAttributeValue(Class<? extends Attribute> category);
279 
280     /**
281      * Determines the printing attribute values a client can specify in
282      * the given category when setting up a job for this print service. A
283      * printing
284      * attribute value is an instance of a class that implements interface
285      * {@link javax.print.attribute.Attribute Attribute}.
286      * <P>
287      * If <CODE>flavor</CODE> is null and <CODE>attributes</CODE> is null
288      * or is an empty set, this method returns all the printing attribute
289      * values this Print Service supports for any possible job. If
290      * <CODE>flavor</CODE> is not null or <CODE>attributes</CODE> is not
291      * an empty set, this method returns just the printing attribute values
292      * that are compatible with the given doc flavor and/or set of attributes.
293      * That is, a null return value may indicate that specifying this attribute
294      * is incompatible with the specified DocFlavor.
295      * Also if DocFlavor is not null it must be a flavor supported by this
296      * PrintService, else IllegalArgumentException will be thrown.
297      * <P>
298      * If the <code>attributes</code> parameter contains an Attribute whose
299      * category is the same as the <code>category</code> parameter, the service
300      * must ignore this attribute in the AttributeSet.
301      * <p>
302      * <code>DocAttribute</code>s which are to be specified on the
303      * <code>Doc</code> must be included in this set to accurately
304      * represent the context.
305      * <p>
306      * This method returns an Object because different printing attribute
307      * categories indicate the supported attribute values in different ways.
308      * The documentation for each printing attribute in package {@link
309      * javax.print.attribute.standard javax.print.attribute.standard}
310      * describes how each attribute indicates its supported values. Possible
311      * ways of indicating support include:
312      * <UL>
313      * <LI>
314      * Return a single instance of the attribute category to indicate that any
315      * value is legal -- used, for example, by an attribute whose value is an
316      * arbitrary text string. (The value of the returned attribute object is
317      * irrelevant.)
318      * <LI>
319      * Return an array of one or more instances of the attribute category,
320      * containing the legal values -- used, for example, by an attribute with
321      * a list of enumerated values. The type of the array is an array of the
322      * specified attribute category type as returned by its
323      * <code>getCategory(Class)</code>.
324      * <LI>
325      * Return a single object (of some class other than the attribute category)
326      * that indicates bounds on the legal values -- used, for example, by an
327      * integer-valued attribute that must lie within a certain range.
328      * </UL>
329      * <P>
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 }