Source for javax.print.PrintService

   1: /* PrintService.java --
   2:    Copyright (C) 2004 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:  * @author Michael Koch (konqueror@gmx.de)
  49:  */
  50: public interface PrintService
  51: {
  52:   /**
  53:    * Returns a new print job capable to handle all supported document flavors.
  54:    * 
  55:    * @return the new print job
  56:    */
  57:   DocPrintJob createPrintJob();
  58:   
  59:   /**
  60:    * Determines if two services refer to the same underlying service.
  61:    * 
  62:    * @param obj the service to check against
  63:    * 
  64:    * @return <code>true</code> if both services refer to the sam underlying
  65:    * service, <code>false</code> otherwise
  66:    */
  67:   boolean equals(Object obj);
  68:   
  69:   /**
  70:    * Returns the value of a single specified attribute.
  71:    * 
  72:    * @param category the category of a <code>PrintServiceAttribute</code>
  73:    * 
  74:    * @return the value of the attribute
  75:    * 
  76:    * @throws NullPointerException if category is null
  77:    * @throws IllegalArgumentException if category is not a class that
  78:    * implements <code>PrintServiceAttribute</code>
  79:    */
  80:   PrintServiceAttribute getAttribute(Class category);
  81:   
  82:   /**
  83:    * Returns all attributes of this printer service
  84:    * 
  85:    * @return all attributes of this print service
  86:    */
  87:   PrintServiceAttributeSet getAttributes();
  88: 
  89:   /**
  90:    * Returns the service's default value for a given attribute.
  91:    * 
  92:    * @param category the category of the attribute
  93:    * 
  94:    * @return the default value
  95:    * 
  96:    * @throws NullPointerException if <code>category</code> is null
  97:    * @throws IllegalArgumentException if <code>category</code> is a class
  98:    * not implementing <code>Attribute</code> 
  99:    */
 100:   Object getDefaultAttributeValue(Class category);
 101:   
 102:   /**
 103:    * Returns the name of this print service.
 104:    * 
 105:    * @return the name
 106:    */
 107:   String getName();
 108:   
 109:   /**
 110:    * Returns a factory for UI components.
 111:    * 
 112:    * @return the factory
 113:    */
 114:   ServiceUIFactory getServiceUIFactory();
 115:   
 116:   /**
 117:    * Returns all supported attribute categories.
 118:    * 
 119:    * @return an array of all supported attribute categories
 120:    */
 121:   Class[] getSupportedAttributeCategories();
 122:   
 123:   /**
 124:    * Returns all supported attribute values a client can use when setting up
 125:    * a print job with this service.
 126:    * 
 127:    * @param category the attribute category to test
 128:    * @param flavor the document flavor to use, or null
 129:    * @param attributes set of printing attributes for a supposed job, or null
 130:    * 
 131:    * @return object indicating supported values for <code>category</code>,
 132:    * or null if this print service doesnt support specifying doc-level or
 133:    * job-level attribute in a print request.
 134:    * 
 135:    * @throws NullPointerException if <code>category</code> is null
 136:    * @throws IllegalArgumentException if <code>category</code> is a class not
 137:    * implementing <code>Attribute</code>, or if <code>flavor</code> is not
 138:    * supported
 139:    */
 140:   Object getSupportedAttributeValues(Class category, DocFlavor flavor, AttributeSet attributes);
 141:   
 142:   /**
 143:    * Returns an array of all supproted document flavors.
 144:    * 
 145:    * @return the supported document flavors
 146:    */
 147:   DocFlavor[] getSupportedDocFlavors();
 148:   
 149:   /**
 150:    * Returns all attributes that are unsupported for a print request in the
 151:    * context of a particular document flavor.
 152:    * 
 153:    * @param flavor document flavor to test, or null
 154:    * @param attributes set of printing attributes for a supposed job
 155:    * 
 156:    * @return null if this <code>PrintService</code> supports the print request
 157:    * specification, else the unsupported attributes
 158:    * 
 159:    * @throws IllegalArgumentException if <code>flavor</code> is unsupported
 160:    */
 161:   AttributeSet getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes);
 162:   
 163:   /**
 164:    * Returns a hashcode for this printer service.
 165:    * 
 166:    * @return the hashcode
 167:    */
 168:   int hashCode();
 169:   
 170:   /**
 171:    * Determines a given attribute category is supported or not.
 172:    * 
 173:    * @param category the category to check
 174:    * 
 175:    * @return <code>true</code> if <code>category</code> is supported,
 176:    * <code>false</code> otherwise
 177:    * 
 178:    * @throws NullPointerException if <code>category</code> is null
 179:    * @throws IllegalArgumentException if <code>category</code> is a class not
 180:    * implementing <code>Attribute</code>.
 181:    */
 182:   boolean isAttributeCategorySupported(Class category);
 183:   
 184:   /**
 185:    * Determines a given attribute value is supported when creating a print job
 186:    * for this print service.
 187:    * 
 188:    * @param attrval the attribute value to check
 189:    * @param flavor the document flavor to use, or null
 190:    * @param attributes set of printing attributes to use, or null
 191:    * 
 192:    * @return <code>true</code> if the attribute value is supported,
 193:    * <code>false</code> otherwise
 194:    * 
 195:    * @throws NullPointerException if <code>attrval</code> is null
 196:    * @throws IllegalArgumentException if <code>flavor</code> is not supported
 197:    * by this print service
 198:    */
 199:   boolean isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes);
 200:   
 201:   /**
 202:    * Determines a given document flavor is supported or not.
 203:    * 
 204:    * @param flavor the document flavor to check
 205:    * 
 206:    * @return <code>true</code> if <code>flavor</code> is supported,
 207:    * <code>false</code> otherwise
 208:    * 
 209:    * @throws NullPointerException if <code>flavor</code> is null
 210:    */
 211:   boolean isDocFlavorSupported(DocFlavor flavor);
 212:   
 213:   /**
 214:    * Registers a print service attribute listener to this print service.
 215:    * 
 216:    * @param listener the listener to add
 217:    */
 218:   void addPrintServiceAttributeListener(PrintServiceAttributeListener listener);
 219:   
 220:   /**
 221:    * De-registers a print service attribute listener from this print service.
 222:    * 
 223:    * @param listener the listener to remove
 224:    */
 225:   void removePrintServiceAttributeListener(PrintServiceAttributeListener listener);
 226: }