KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > print > PrintService


1 /*
2  * @(#)PrintService.java 1.11 04/05/05
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package javax.print;
9
10 import java.util.Locale JavaDoc;
11
12 import javax.print.attribute.Attribute JavaDoc;
13 import javax.print.attribute.AttributeSet JavaDoc;
14 import javax.print.attribute.PrintServiceAttribute JavaDoc;
15 import javax.print.attribute.PrintServiceAttributeSet JavaDoc;
16 import javax.print.event.PrintServiceAttributeListener JavaDoc;
17
18  
19 /**
20  * Interface PrintService is the factory for a DocPrintJob. A PrintService
21  * describes the capabilities of a Printer and can be queried regarding
22  * a printer's supported attributes.
23  * <P>
24  * Example:
25  * <PRE>
26  * DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
27  * PrintRequestAttributeSet aset = new HashPrintRequestHashAttributeSet();
28  * aset.add(MediaSizeName.ISO_A4);
29  * PrintService[] pservices =
30  * PrintServiceLookup.lookupPrintServices(flavor, aset);
31  * if (pservices.length > 0) {
32  * DocPrintJob pj = pservices[0].createPrintJob();
33  * // InputStreamDoc is an implementation of the Doc interface //
34  * Doc doc = new InputStreamDoc("test.ps", flavor);
35  * try {
36  * pj.print(doc, aset);
37  * } catch (PrintException e) {
38  * }
39  * }
40  * </PRE>
41  */

42 public interface PrintService {
43
44     /** Returns a String name for this print service which may be used
45       * by applications to request a particular print service.
46       * In a suitable context, such as a name service, this name must be
47       * unique.
48       * In some environments this unique name may be the same as the user
49       * friendly printer name defined as the
50       * {@link javax.print.attribute.standard.PrinterName PrinterName}
51       * attribute.
52       * @return name of the service.
53       */

54     public String JavaDoc getName();
55
56     /**
57      * Creates and returns a PrintJob capable of handling data from
58      * any of the supported document flavors.
59      * @return a DocPrintJob object
60      */

61     public DocPrintJob JavaDoc createPrintJob();
62
63     /**
64      * Registers a listener for events on this PrintService.
65      * @param listener a PrintServiceAttributeListener, which
66      * monitors the status of a print service
67      * @see #removePrintServiceAttributeListener
68      */

69     public void addPrintServiceAttributeListener(
70                                        PrintServiceAttributeListener JavaDoc listener);
71
72     /**
73      * Removes the print-service listener from this print service.
74      * This means the listener is no longer interested in
75      * <code>PrintService</code> events.
76      * @param listener a PrintServiceAttributeListener object
77      * @see #addPrintServiceAttributeListener
78      */

79     public void removePrintServiceAttributeListener(
80                                        PrintServiceAttributeListener JavaDoc listener);
81
82     /**
83      * Obtains this print service's set of printer description attributes
84      * giving this Print Service's status. The returned attribute set object
85      * is unmodifiable. The returned attribute set object is a "snapshot" of
86      * this Print Service's attribute set at the time of the
87      * <CODE>getAttributes()</CODE> method call: that is, the returned
88      * attribute set's contents will <I>not</I> be updated if this print
89      * service's attribute set's contents change in the future. To detect
90      * changes in attribute values, call <CODE>getAttributes()</CODE> again
91      * and compare the new attribute set to the previous attribute set;
92      * alternatively, register a listener for print service events.
93      *
94      * @return Unmodifiable snapshot of this Print Service's attribute set.
95      * May be empty, but not null.
96      */

97     public PrintServiceAttributeSet JavaDoc getAttributes();
98
99     /**
100      * Gets the value of the single specified service attribute.
101      * This may be useful to clients which only need the value of one
102      * attribute and want to minimise overhead.
103      * @param category the category of a PrintServiceAttribute supported
104      * by this service - may not be null.
105      * @return the value of the supported attribute or null if the
106      * attribute is not supported by this service.
107      * @exception NullPointerException if the category is null.
108      * @exception IllegalArgumentException
109      * (unchecked exception) if <CODE>category</CODE> is not a
110      * <code>Class</code> that implements interface
111      *{@link javax.print.attribute.PrintServiceAttribute PrintServiceAttribute}.
112      */

113     public <T extends PrintServiceAttribute JavaDoc>
114     T getAttribute(Class JavaDoc<T> category);
115
116     /**
117      * Determines the print data formats a client can specify when setting
118      * up a job for this <code>PrintService</code>. A print data format is
119      * designated by a "doc
120      * flavor" (class {@link javax.print.DocFlavor DocFlavor})
121      * consisting of a MIME type plus a print data representation class.
122      * <P>
123      * Note that some doc flavors may not be supported in combination
124      * with all attributes. Use <code>getUnsupportedAttributes(..)</code>
125      * to validate specific combinations.
126      *
127      * @return Array of supported doc flavors, should have at least
128      * one element.
129      *
130      */

131     public DocFlavor JavaDoc[] getSupportedDocFlavors();
132
133     /**
134      * Determines if this print service supports a specific
135      * <code>DocFlavor</code>. This is a convenience method to determine
136      * if the <code>DocFlavor</code> would be a member of the result of
137      * <code>getSupportedDocFlavors()</code>.
138      * <p>
139      * Note that some doc flavors may not be supported in combination
140      * with all attributes. Use <code>getUnsupportedAttributes(..)</code>
141      * to validate specific combinations.
142      *
143      * @param flavor the <code>DocFlavor</code>to query for support.
144      * @return <code>true</code> if this print service supports the
145      * specified <code>DocFlavor</code>; <code>false</code> otherwise.
146      * @exception NullPointerException
147      * (unchecked exception) Thrown if <CODE>flavor</CODE> is null.
148      */

149     public boolean isDocFlavorSupported(DocFlavor JavaDoc flavor);
150
151
152     /**
153      * Determines the printing attribute categories a client can specify
154      * when setting up a job for this print service.
155      * A printing attribute category is
156      * designated by a <code>Class</code> that implements interface
157      * {@link javax.print.attribute.Attribute Attribute}. This method returns
158      * just the attribute <I>categories</I> that are supported; it does not
159      * return the particular attribute <I>values</I> that are supported.
160      * <P>
161      * This method returns all the printing attribute
162      * categories this print service supports for any possible job.
163      * Some categories may not be supported in a particular context (ie
164      * for a particular <code>DocFlavor</code>).
165      * Use one of the methods that include a <code>DocFlavor</code> to
166      * validate the request before submitting it, such as
167      * <code>getSupportedAttributeValues(..)</code>.
168      *
169      * @return Array of printing attribute categories that the client can
170      * specify as a doc-level or job-level attribute in a Print
171      * Request. Each element in the array is a {@link java.lang.Class
172      * Class} that implements interface {@link
173      * javax.print.attribute.Attribute Attribute}.
174      * The array is empty if no categories are supported.
175      */

176     public Class JavaDoc<?>[] getSupportedAttributeCategories();
177         
178     /**
179      * Determines whether a client can specify the given printing
180      * attribute category when setting up a job for this print service. A
181      * printing attribute category is designated by a <code>Class</code>
182      * that implements interface {@link javax.print.attribute.Attribute
183      * Attribute}. This method tells whether the attribute <I>category</I> is
184      * supported; it does not tell whether a particular attribute <I>value</I>
185      * is supported.
186      * <p>
187      * Some categories may not be supported in a particular context (ie
188      * for a particular <code>DocFlavor</code>).
189      * Use one of the methods which include a <code>DocFlavor</code> to
190      * validate the request before submitting it, such as
191      * <code>getSupportedAttributeValues(..)</code>.
192      * <P>
193      * This is a convenience method to determine if the category
194      * would be a member of the result of
195      * <code>getSupportedAttributeCategories()</code>.
196      *
197      * @param category Printing attribute category to test. It must be a
198      * <code>Class</code> that implements
199      * interface
200      * {@link javax.print.attribute.Attribute Attribute}.
201      *
202      * @return <code>true</code> if this print service supports
203      * specifying a doc-level or
204      * job-level attribute in <CODE>category</CODE> in a Print
205      * Request; <code>false</code> if it doesn't.
206      *
207      * @exception NullPointerException
208      * (unchecked exception) Thrown if <CODE>category</CODE> is null.
209      * @exception IllegalArgumentException
210      * (unchecked exception) Thrown if <CODE>category</CODE> is not a
211      * <code>Class</code> that implements interface
212      * {@link javax.print.attribute.Attribute Attribute}.
213      */

214     public boolean
215     isAttributeCategorySupported(Class JavaDoc<? extends Attribute JavaDoc> category);
216     
217     /**
218      * Determines this print service's default printing attribute value in
219      * the given category. A printing attribute value is an instance of
220      * a class that implements interface
221      * {@link javax.print.attribute.Attribute Attribute}. If a client sets
222      * up a print job and does not specify any attribute value in the
223      * given category, this Print Service will use the
224      * default attribute value instead.
225      * <p>
226      * Some attributes may not be supported in a particular context (ie
227      * for a particular <code>DocFlavor</code>).
228      * Use one of the methods that include a <code>DocFlavor</code> to
229      * validate the request before submitting it, such as
230      * <code>getSupportedAttributeValues(..)</code>.
231      * <P>
232      * Not all attributes have a default value. For example the
233      * service will not have a defaultvalue for <code>RequestingUser</code>
234      * i.e. a null return for a supported category means there is no
235      * service default value for that category. Use the
236      * <code>isAttributeCategorySupported(Class)</code> method to
237      * distinguish these cases.
238      *
239      * @param category Printing attribute category for which the default
240      * attribute value is requested. It must be a {@link
241      * java.lang.Class Class} that implements interface
242      * {@link javax.print.attribute.Attribute
243      * Attribute}.
244      *
245      * @return Default attribute value for <CODE>category</CODE>, or null
246      * if this Print Service does not support specifying a doc-level or
247      * job-level attribute in <CODE>category</CODE> in a Print
248      * Request, or the service does not have a default value
249      * for this attribute.
250      *
251      * @exception NullPointerException
252      * (unchecked exception) Thrown if <CODE>category</CODE> is null.
253      * @exception IllegalArgumentException
254      * (unchecked exception) Thrown if <CODE>category</CODE> is not a
255      * {@link java.lang.Class Class} that implements interface {@link
256      * javax.print.attribute.Attribute Attribute}.
257      */

258     public Object JavaDoc
259     getDefaultAttributeValue(Class JavaDoc<? extends Attribute JavaDoc> category);
260
261     /**
262      * Determines the printing attribute values a client can specify in
263      * the given category when setting up a job for this print service. A
264      * printing
265      * attribute value is an instance of a class that implements interface
266      * {@link javax.print.attribute.Attribute Attribute}.
267      * <P>
268      * If <CODE>flavor</CODE> is null and <CODE>attributes</CODE> is null
269      * or is an empty set, this method returns all the printing attribute
270      * values this Print Service supports for any possible job. If
271      * <CODE>flavor</CODE> is not null or <CODE>attributes</CODE> is not
272      * an empty set, this method returns just the printing attribute values
273      * that are compatible with the given doc flavor and/or set of attributes.
274      * That is, a null return value may indicate that specifying this attribute
275      * is incompatible with the specified DocFlavor.
276      * Also if DocFlavor is not null it must be a flavor supported by this
277      * PrintService, else IllegalArgumentException will be thrown.
278      * <P>
279      * If the <code>attributes</code> parameter contains an Attribute whose
280      * category is the same as the <code>category</code> parameter, the service
281      * must ignore this attribute in the AttributeSet.
282      * <p>
283      * <code>DocAttribute</code>s which are to be specified on the
284      * <code>Doc</code> must be included in this set to accurately
285      * represent the context.
286      * <p>
287      * This method returns an Object because different printing attribute
288      * categories indicate the supported attribute values in different ways.
289      * The documentation for each printing attribute in package {@link
290      * javax.print.attribute.standard javax.print.attribute.standard}
291      * describes how each attribute indicates its supported values. Possible
292      * ways of indicating support include:
293      * <UL>
294      * <LI>
295      * Return a single instance of the attribute category to indicate that any
296      * value is legal -- used, for example, by an attribute whose value is an
297      * arbitrary text string. (The value of the returned attribute object is
298      * irrelevant.)
299      * <LI>
300      * Return an array of one or more instances of the attribute category,
301      * containing the legal values -- used, for example, by an attribute with
302      * a list of enumerated values. The type of the array is an array of the
303      * specified attribute category type as returned by its
304      * <code>getCategory(Class)</code>.
305      * <LI>
306      * Return a single object (of some class other than the attribute category)
307      * that indicates bounds on the legal values -- used, for example, by an
308      * integer-valued attribute that must lie within a certain range.
309      * </UL>
310      * <P>
311      *
312      * @param category Printing attribute category to test. It must be a
313      * {@link java.lang.Class Class} that implements
314      * interface {@link
315      * javax.print.attribute.Attribute Attribute}.
316      * @param flavor Doc flavor for a supposed job, or null.
317      * @param attributes Set of printing attributes for a supposed job
318      * (both job-level attributes and document-level
319      * attributes), or null.
320      *
321      * @return Object indicating supported values for <CODE>category</CODE>,
322      * or null if this Print Service does not support specifying a
323      * doc-level or job-level attribute in <CODE>category</CODE> in
324      * a Print Request.
325      *
326      * @exception NullPointerException
327      * (unchecked exception) Thrown if <CODE>category</CODE> is null.
328      * @exception IllegalArgumentException
329      * (unchecked exception) Thrown if <CODE>category</CODE> is not a
330      * {@link java.lang.Class Class} that implements interface {@link
331      * javax.print.attribute.Attribute Attribute}, or
332      * <code>DocFlavor</code> is not supported by this service.
333      */

334     public Object JavaDoc
335     getSupportedAttributeValues(Class JavaDoc<? extends Attribute JavaDoc> category,
336                     DocFlavor JavaDoc flavor,
337                     AttributeSet JavaDoc attributes);
338
339     /**
340      * Determines whether a client can specify the given printing
341      * attribute
342      * value when setting up a job for this Print Service. A printing
343      * attribute value is an instance of a class that implements interface
344      * {@link javax.print.attribute.Attribute Attribute}.
345      * <P>
346      * If <CODE>flavor</CODE> is null and <CODE>attributes</CODE> is null or
347      * is an empty set, this method tells whether this Print Service supports
348      * the given printing attribute value for some possible combination of doc
349      * flavor and set of attributes. If <CODE>flavor</CODE> is not null or
350      * <CODE>attributes</CODE> is not an empty set, this method tells whether
351      * this Print Service supports the given printing attribute value in
352      * combination with the given doc flavor and/or set of attributes.
353      * <p>
354      * Also if DocFlavor is not null it must be a flavor supported by this
355      * PrintService, else IllegalArgumentException will be thrown.
356      * <p>
357      * <code>DocAttribute</code>s which are to be specified on the
358      * <code>Doc</code> must be included in this set to accurately
359      * represent the context.
360      * <p>
361      * This is a convenience method to determine if the value
362      * would be a member of the result of
363      * <code>getSupportedAttributeValues(...)</code>.
364      *
365      * @param attrval Printing attribute value to test.
366      * @param flavor Doc flavor for a supposed job, or null.
367      * @param attributes Set of printing attributes for a supposed job
368      * (both job-level attributes and document-level
369      * attributes), or null.
370      *
371      * @return True if this Print Service supports specifying
372      * <CODE>attrval</CODE> as a doc-level or job-level attribute in a
373      * Print Request, false if it doesn't.
374      *
375      * @exception NullPointerException
376      * (unchecked exception) if <CODE>attrval</CODE> is null.
377      * @exception IllegalArgumentException if flavor is not supported by
378      * this PrintService.
379      */

380     public boolean isAttributeValueSupported(Attribute JavaDoc attrval,
381                                              DocFlavor JavaDoc flavor,
382                                              AttributeSet JavaDoc attributes);
383
384
385     /**
386      * Identifies the attributes that are unsupported for a print request
387      * in the context of a particular DocFlavor.
388      * This method is useful for validating a potential print job and
389      * identifying the specific attributes which cannot be supported.
390      * It is important to supply only a supported DocFlavor or an
391      * IllegalArgumentException will be thrown. If the
392      * return value from this method is null, all attributes are supported.
393      * <p>
394      * <code>DocAttribute</code>s which are to be specified on the
395      * <code>Doc</code> must be included in this set to accurately
396      * represent the context.
397      * <p>
398      * If the return value is non-null, all attributes in the returned
399      * set are unsupported with this DocFlavor. The returned set does not
400      * distinguish attribute categories that are unsupported from
401      * unsupported attribute values.
402      * <p>
403      * A supported print request can then be created by removing
404      * all unsupported attributes from the original attribute set,
405      * except in the case that the DocFlavor is unsupported.
406      * <p>
407      * If any attributes are unsupported only because they are in conflict
408      * with other attributes then it is at the discretion of the service
409      * to select the attribute(s) to be identified as the cause of the
410      * conflict.
411      * <p>
412      * Use <code>isDocFlavorSupported()</code> to verify that a DocFlavor
413      * is supported before calling this method.
414      *
415      * @param flavor Doc flavor to test, or null
416      * @param attributes Set of printing attributes for a supposed job
417      * (both job-level attributes and document-level
418      * attributes), or null.
419      *
420      * @return null if this Print Service supports the print request
421      * specification, else the unsupported attributes.
422      *
423      * @exception IllegalArgumentException if<CODE>flavor</CODE> is
424      * not supported by this PrintService.
425      */

426     public AttributeSet JavaDoc getUnsupportedAttributes(DocFlavor JavaDoc flavor,
427                        AttributeSet JavaDoc attributes);
428
429     /**
430      * Returns a factory for UI components which allow users to interact
431      * with the service in various roles.
432      * Services which do not provide any UI should return null.
433      * Print Services which do provide UI but want to be supported in
434      * an environment with no UI support should ensure that the factory
435      * is not initialised unless the application calls this method to
436      * obtain the factory.
437      * See <code>ServiceUIFactory</code> for more information.
438      * @return null or a factory for UI components.
439      */

440     public ServiceUIFactory JavaDoc getServiceUIFactory();
441
442     /**
443      * Determines if two services are referring to the same underlying
444      * service. Objects encapsulating a print service may not exhibit
445      * equality of reference even though they refer to the same underlying
446      * service.
447      * <p>
448      * Clients should call this method to determine if two services are
449      * referring to the same underlying service.
450      * <p>
451      * Services must implement this method and return true only if the
452      * service objects being compared may be used interchangeably by the
453      * client.
454      * Services are free to return the same object reference to an underlying
455      * service if that, but clients must not depend on equality of reference.
456      * @param obj the reference object with which to compare.
457      * @return true if this service is the same as the obj argument,
458      * false otherwise.
459      */

460     public boolean equals(Object JavaDoc obj);
461
462     /**
463      * This method should be implemented consistently with
464      * <code>equals(Object)</code>.
465      * @return hash code of this object.
466      */

467     public int hashCode();
468
469 }
470
Popular Tags