Source for javax.print.PrintService

   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: }