001    /* PrintService.java --
002       Copyright (C) 2004, 2006 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.print;
040    
041    import javax.print.attribute.Attribute;
042    import javax.print.attribute.AttributeSet;
043    import javax.print.attribute.PrintServiceAttribute;
044    import javax.print.attribute.PrintServiceAttributeSet;
045    import javax.print.event.PrintServiceAttributeListener;
046    
047    /**
048     * A <code>PrintService</code> represents a printer available for printing.
049     * <p>
050     * The print service hereby may be a real physical printer device, a printer
051     * group with same capabilities or a logical print service (like for example
052     * a PDF writer). The print service is used to query the capabilities of the
053     * represented printer instance. If a suitable print service is found it is
054     * used to create a print job for the actual printing process.
055     * </p>
056     * @see javax.print.DocPrintJob
057     *
058     * @author Michael Koch (konqueror@gmx.de)
059     */
060    public interface PrintService
061    {
062      /**
063       * Creates and returns a new print job which is capable to handle all
064       * the document flavors supported by this print service.
065       *
066       * @return The created print job object.
067       */
068      DocPrintJob createPrintJob();
069    
070      /**
071       * Determines if two services refer to the same underlying service.
072       *
073       * @param obj the service to check against
074       *
075       * @return <code>true</code> if both services refer to the same underlying
076       * service, <code>false</code> otherwise.
077       */
078      boolean equals(Object obj);
079    
080      /**
081       * Returns the value of the single specified attribute.
082       *
083       * @param category the category of a <code>PrintServiceAttribute</code>
084       *
085       * @return The value of the attribute, or <code>null</code> if the attribute
086       * category is not supported by this print service implementation.
087       *
088       * @throws NullPointerException if category is <code>null</code>.
089       * @throws IllegalArgumentException if category is not a class that
090       * implements <code>PrintServiceAttribute</code>.
091       */
092      <T extends PrintServiceAttribute> T getAttribute(Class<T> category);
093    
094      /**
095       * Returns the attributes describing this print service. The returned
096       * attributes set is unmodifiable and represents the current state of
097       * the print service. As some print service attributes may change
098       * (depends on the print service implementation) a subsequent call to
099       * this method may return a different set. To monitor changes a
100       * <code>PrintServiceAttributeListener</code> may be registered.
101       *
102       * @return All the description attributes of this print service.
103       * @see #addPrintServiceAttributeListener(PrintServiceAttributeListener)
104       */
105      PrintServiceAttributeSet getAttributes();
106    
107      /**
108       * Determines and returns the default value for a given attribute category
109       * of this print service.
110       * <p>
111       * A return value of <code>null</code> means either that the print service
112       * does not support the attribute category or there is no default value
113       * available for this category. To distinguish these two case one can test
114       * with {@link #isAttributeCategorySupported(Class)} if the category is
115       * supported.
116       * </p>
117       *
118       * @param category the category of the attribute
119       *
120       * @return The default value, or <code>null</code>.
121       *
122       * @throws NullPointerException if <code>category</code> is <code>null</code>
123       * @throws IllegalArgumentException if <code>category</code> is a class
124       * not implementing <code>Attribute</code>
125       */
126      Object getDefaultAttributeValue(Class<? extends Attribute> category);
127    
128      /**
129       * Returns the name of this print service.
130       * This may be the value of the <code>PrinterName</code> attribute.
131       *
132       * @return The print service name.
133       */
134      String getName();
135    
136      /**
137       * Returns a factory for UI components if supported by the print service.
138       *
139       * @return A factory for UI components or <code>null</code>.
140       */
141      ServiceUIFactory getServiceUIFactory();
142    
143      /**
144       * Returns all supported attribute categories.
145       *
146       * @return The class array of all supported attribute categories.
147       */
148      Class<?>[] getSupportedAttributeCategories();
149    
150      /**
151       * Determines and returns all supported attribute values of a given
152       * attribute category a client can use when setting up a print job
153       * for this print service.
154       * <p>
155       * The returned object may be one of the following types:
156       * <ul>
157       * <li>A single instance of the attribute category to indicate that any
158       * value will be supported.</li>
159       * <li>An array of the same type as the attribute category to test,
160       * containing all the supported values for this category.</li>
161       * <li>A single object (of any other type than the attribute category)
162       * which indicates bounds on the supported values.</li>
163       * </ul>
164       * </p>
165       *
166       * @param category the attribute category to test
167       * @param flavor the document flavor to use, or <code>null</code>
168       * @param attributes set of attributes for a supposed job,
169       * or <code>null</code>
170       *
171       * @return A object (as defined above) indicating the supported values
172       * for the given attribute category, or <code>null</code> if this print
173       * service doesn't support the given attribute category at all.
174       *
175       * @throws NullPointerException if <code>category</code> is null
176       * @throws IllegalArgumentException if <code>category</code> is a class not
177       * implementing <code>Attribute</code>, or if <code>flavor</code> is not
178       * supported
179       */
180      Object getSupportedAttributeValues(Class<? extends Attribute> category,
181                                         DocFlavor flavor,
182                                         AttributeSet attributes);
183    
184      /**
185       * Determines and returns an array of all supported document flavors which
186       * can be used to supply print data to this print service.
187       * <p>
188       * The supported attribute categories may differ between the supported
189       * document flavors. To test for supported attributes one can use the
190       * {@link #getUnsupportedAttributes(DocFlavor, AttributeSet)} method with
191       * the specific doc flavor and attributes set.
192       * </p>
193       *
194       * @return the supported document flavors
195       */
196      DocFlavor[] getSupportedDocFlavors();
197    
198      /**
199       * Identifies all the unsupported attributes of the given set of attributes
200       * in the context of the specified document flavor.
201       * <p>
202       * The given flavor has to be supported by the print service (use
203       * {@link #isDocFlavorSupported(DocFlavor)} to verify). The method will
204       * return <code>null</code> if all given attributes are supported. Otherwise
205       * a set of unsupported attributes are returned. The attributes in the
206       * returned set may be completely unsupported or only the specific requested
207       * value. If flavor is <code>null</code> the default document flavor of the
208       * print service is used in the identification process.
209       * </p>
210       *
211       * @param flavor document flavor to test, or <code>null</code>.
212       * @param attributes set of printing attributes for a supposed job
213       *
214       * @return <code>null</code> if this print service supports all the given
215       * attributes for the specified doc flavor. Otherwise the set of unsupported
216       * attributes are returned.
217       *
218       * @throws IllegalArgumentException if <code>flavor</code> is unsupported
219       */
220      AttributeSet getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes);
221    
222    
223      /**
224       * Returns a hashcode for this print service.
225       *
226       * @return The hashcode.
227       */
228      int hashCode();
229    
230      /**
231       * Determines a given attribute category is supported by this
232       * print service implementation. This only tests for the category
233       * not for any specific values of this category nor in the context
234       * of a specific document flavor.
235       *
236       * @param category the category to check
237       *
238       * @return <code>true</code> if <code>category</code> is supported,
239       * <code>false</code> otherwise.
240       *
241       * @throws NullPointerException if <code>category</code> is <code>null</code>
242       * @throws IllegalArgumentException if <code>category</code> is a class not
243       * implementing <code>Attribute</code>.
244       */
245      boolean isAttributeCategorySupported(Class<? extends Attribute> category);
246    
247      /**
248       * Determines if a given attribute value is supported when creating a print
249       * job for this print service.
250       * <p>
251       * If either the document flavor or the provided attributes are
252       * <code>null</code> it is determined if the given attribute value is
253       * supported in some combination of the available document flavors and
254       * attributes of the print service. Otherwise it is checked for the
255       * specific context of the given document flavor/attributes set.
256       * </p>
257       *
258       * @param attrval the attribute value to check
259       * @param flavor the document flavor to use, or <code>null</code>.
260       * @param attributes set of attributes to use, or <code>null</code>.
261       *
262       * @return <code>true</code> if the attribute value is supported in the
263       * requested context, <code>false</code> otherwise.
264       *
265       * @throws NullPointerException if <code>attrval</code> is <code>null</code>.
266       * @throws IllegalArgumentException if <code>flavor</code> is not supported
267       * by this print service
268       */
269      boolean isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes);
270    
271      /**
272       * Determines if a given document flavor is supported or not.
273       *
274       * @param flavor the document flavor to check
275       *
276       * @return <code>true</code> if <code>flavor</code> is supported,
277       * <code>false</code> otherwise.
278       *
279       * @throws NullPointerException if <code>flavor</code> is null.
280       */
281      boolean isDocFlavorSupported(DocFlavor flavor);
282    
283      /**
284       * Registers a print service attribute listener to this print service.
285       *
286       * @param listener the listener to add
287       */
288      void addPrintServiceAttributeListener(PrintServiceAttributeListener listener);
289    
290      /**
291       * De-registers a print service attribute listener from this print service.
292       *
293       * @param listener the listener to remove
294       */
295      void removePrintServiceAttributeListener(PrintServiceAttributeListener listener);
296    }