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:   <T extends PrintServiceAttribute> T getAttribute(Class<T> 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<? 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: }