001 /* PrintService.java -- 002 Copyright (C) 2004, 2006 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package javax.print; 040 041 import javax.print.attribute.Attribute; 042 import javax.print.attribute.AttributeSet; 043 import javax.print.attribute.PrintServiceAttribute; 044 import javax.print.attribute.PrintServiceAttributeSet; 045 import javax.print.event.PrintServiceAttributeListener; 046 047 /** 048 * A <code>PrintService</code> represents a printer available for printing. 049 * <p> 050 * The print service hereby may be a real physical printer device, a printer 051 * group with same capabilities or a logical print service (like for example 052 * a PDF writer). The print service is used to query the capabilities of the 053 * represented printer instance. If a suitable print service is found it is 054 * used to create a print job for the actual printing process. 055 * </p> 056 * @see javax.print.DocPrintJob 057 * 058 * @author Michael Koch (konqueror@gmx.de) 059 */ 060 public interface PrintService 061 { 062 /** 063 * Creates and returns a new print job which is capable to handle all 064 * the document flavors supported by this print service. 065 * 066 * @return The created print job object. 067 */ 068 DocPrintJob createPrintJob(); 069 070 /** 071 * Determines if two services refer to the same underlying service. 072 * 073 * @param obj the service to check against 074 * 075 * @return <code>true</code> if both services refer to the same underlying 076 * service, <code>false</code> otherwise. 077 */ 078 boolean equals(Object obj); 079 080 /** 081 * Returns the value of the single specified attribute. 082 * 083 * @param category the category of a <code>PrintServiceAttribute</code> 084 * 085 * @return The value of the attribute, or <code>null</code> if the attribute 086 * category is not supported by this print service implementation. 087 * 088 * @throws NullPointerException if category is <code>null</code>. 089 * @throws IllegalArgumentException if category is not a class that 090 * implements <code>PrintServiceAttribute</code>. 091 */ 092 <T extends PrintServiceAttribute> T getAttribute(Class<T> category); 093 094 /** 095 * Returns the attributes describing this print service. The returned 096 * attributes set is unmodifiable and represents the current state of 097 * the print service. As some print service attributes may change 098 * (depends on the print service implementation) a subsequent call to 099 * 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 }