libjava/classpath/javax/print/PrintService.java

   1 /* PrintService.java --
   2    Copyright (C) 2004, 2006 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.print;
  40
  41 import javax.print.attribute.Attribute;
  42 import javax.print.attribute.AttributeSet;
  43 import javax.print.attribute.PrintServiceAttribute;
  44 import javax.print.attribute.PrintServiceAttributeSet;
  45 import javax.print.event.PrintServiceAttributeListener;
  46
  47 /**
  48  * A <code>PrintService</code> represents a printer available for printing.
  49  * <p>
  50  * The print service hereby may be a real physical printer device, a printer
  51  * group with same capabilities or a logical print service (like for example
  52  * a PDF writer). The print service is used to query the capabilities of the
  53  * represented printer instance. If a suitable print service is found it is
  54  * used to create a print job for the actual printing process.
  55  * </p>
  56  * @see javax.print.DocPrintJob
  57  *
  58  * @author Michael Koch (konqueror@gmx.de)
  59  */
  60 public interface PrintService
  61 {
  62   /**
  63    * Creates and returns a new print job which is capable to handle all
  64    * the document flavors supported by this print service.
  65    *
  66    * @return The created print job object.
  67    */
  68   DocPrintJob createPrintJob();
  69
  70   /**
  71    * Determines if two services refer to the same underlying service.
  72    *
  73    * @param obj the service to check against
  74    *
  75    * @return <code>true</code> if both services refer to the same underlying
  76    * service, <code>false</code> otherwise.
  77    */
  78   boolean equals(Object obj);
  79
  80   /**
  81    * Returns the value of the single specified attribute.
  82    *
  83    * @param category the category of a <code>PrintServiceAttribute</code>
  84    *
  85    * @return The value of the attribute, or <code>null</code> if the attribute
  86    * category is not supported by this print service implementation.
  87    *
  88    * @throws NullPointerException if category is <code>null</code>.
  89    * @throws IllegalArgumentException if category is not a class that
  90    * implements <code>PrintServiceAttribute</code>.
  91    */
  92   PrintServiceAttribute getAttribute(Class category);
  93
  94   /**
  95    * Returns the attributes describing this print service. The returned
  96    * attributes set is unmodifiable and represents the current state of
  97    * the print service. As some print service attributes may change
  98    * (depends on the print service implementation) a subsequent call to
  99    * 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 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 category, DocFlavor flavor, AttributeSet attributes);
 181
 182   /**
 183    * Determines and returns an array of all supported document flavors which
 184    * can be used to supply print data to this print service.
 185    * <p>
 186    * The supported attribute categories may differ between the supported
 187    * document flavors. To test for supported attributes one can use the
 188    * {@link #getUnsupportedAttributes(DocFlavor, AttributeSet)} method with
 189    * the specific doc flavor and attributes set.
 190    * </p>
 191    *
 192    * @return The supported document flavors.
 193    */
 194   DocFlavor[] getSupportedDocFlavors();
 195
 196   /**
 197    * Identifies all the unsupported attributes of the given set of attributes
 198    * in the context of the specified document flavor.
 199    * <p>
 200    * The given flavor has to be supported by the print service (use
 201    * {@link #isDocFlavorSupported(DocFlavor)} to verify). The method will
 202    * return <code>null</code> if all given attributes are supported. Otherwise
 203    * a set of unsupported attributes are returned. The attributes in the
 204    * returned set may be completely unsupported or only the specific requested
 205    * value. If flavor is <code>null</code> the default document flavor of the
 206    * print service is used in the identification process.
 207    * </p>
 208    *
 209    * @param flavor document flavor to test, or <code>null</code>.
 210    * @param attributes set of printing attributes for a supposed job
 211    *
 212    * @return <code>null</code> if this print service supports all the given
 213    * attributes for the specified doc flavor. Otherwise the set of unsupported
 214    * attributes are returned.
 215    *
 216    * @throws IllegalArgumentException if <code>flavor</code> is unsupported
 217    */
 218   AttributeSet getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes);
 219
 220
 221   /**
 222    * Returns a hashcode for this print service.
 223    *
 224    * @return The hashcode.
 225    */
 226   int hashCode();
 227
 228   /**
 229    * Determines a given attribute category is supported by this
 230    * print service implementation. This only tests for the category
 231    * not for any specific values of this category nor in the context
 232    * of a specific document flavor.
 233    *
 234    * @param category the category to check
 235    *
 236    * @return <code>true</code> if <code>category</code> is supported,
 237    * <code>false</code> otherwise.
 238    *
 239    * @throws NullPointerException if <code>category</code> is <code>null</code>
 240    * @throws IllegalArgumentException if <code>category</code> is a class not
 241    * implementing <code>Attribute</code>.
 242    */
 243   boolean isAttributeCategorySupported(Class category);
 244
 245   /**
 246    * Determines if a given attribute value is supported when creating a print
 247    * job for this print service.
 248    * <p>
 249    * If either the document flavor or the provided attributes are
 250    * <code>null</code> it is determined if the given attribute value is
 251    * supported in some combination of the available document flavors and
 252    * attributes of the print service. Otherwise it is checked for the
 253    * specific context of the given document flavor/attributes set.
 254    * </p>
 255    *
 256    * @param attrval the attribute value to check
 257    * @param flavor the document flavor to use, or <code>null</code>.
 258    * @param attributes set of attributes to use, or <code>null</code>.
 259    *
 260    * @return <code>true</code> if the attribute value is supported in the
 261    * requested context, <code>false</code> otherwise.
 262    *
 263    * @throws NullPointerException if <code>attrval</code> is <code>null</code>.
 264    * @throws IllegalArgumentException if <code>flavor</code> is not supported
 265    * by this print service
 266    */
 267   boolean isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes);
 268
 269   /**
 270    * Determines if a given document flavor is supported or not.
 271    *
 272    * @param flavor the document flavor to check
 273    *
 274    * @return <code>true</code> if <code>flavor</code> is supported,
 275    * <code>false</code> otherwise.
 276    *
 277    * @throws NullPointerException if <code>flavor</code> is null.
 278    */
 279   boolean isDocFlavorSupported(DocFlavor flavor);
 280
 281   /**
 282    * Registers a print service attribute listener to this print service.
 283    *
 284    * @param listener the listener to add
 285    */
 286   void addPrintServiceAttributeListener(PrintServiceAttributeListener listener);
 287
 288   /**
 289    * De-registers a print service attribute listener from this print service.
 290    *
 291    * @param listener the listener to remove
 292    */
 293   void removePrintServiceAttributeListener(PrintServiceAttributeListener listener);
 294 }