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