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