1 /* 2 * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.print; 27 28 import javax.print.attribute.Attribute; 29 import javax.print.attribute.AttributeSet; 30 import javax.print.attribute.PrintServiceAttribute; 31 import javax.print.attribute.PrintServiceAttributeSet; 32 import javax.print.event.PrintServiceAttributeListener; 33 34 /** 35 * Interface {@code PrintService} is the factory for a {@code DocPrintJob}. A 36 * {@code PrintService} describes the capabilities of a printer and can be 37 * queried regarding a printer's supported attributes. 38 * <p> 39 * Example: 40 * <pre>{@code 41 * DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT; 42 * PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet(); 43 * aset.add(MediaSizeName.ISO_A4); 44 * PrintService[] pservices = 45 * PrintServiceLookup.lookupPrintServices(flavor, aset); 46 * if (pservices.length > 0) { 47 * DocPrintJob pj = pservices[0].createPrintJob(); 48 * try { 49 * FileInputStream fis = new FileInputStream("test.ps"); 50 * Doc doc = new SimpleDoc(fis, flavor, null); 51 * pj.print(doc, aset); 52 * } catch (FileNotFoundException fe) { 53 * } catch (PrintException e) { 54 * } 55 * } 56 * }</pre> 57 */ 58 public interface PrintService { 59 60 /** 61 * Returns a string name for this print service which may be used by 62 * applications to request a particular print service. In a suitable 63 * context, such as a name service, this name must be unique. In some 64 * environments this unique name may be the same as the user friendly 65 * printer name defined as the 66 * {@link javax.print.attribute.standard.PrinterName PrinterName} attribute. 67 * 68 * @return name of the service 69 */ getName()70 public String getName(); 71 72 /** 73 * Creates and returns a {@code PrintJob} capable of handling data from any 74 * of the supported document flavors. 75 * 76 * @return a {@code DocPrintJob} object 77 */ createPrintJob()78 public DocPrintJob createPrintJob(); 79 80 /** 81 * Registers a listener for events on this {@code PrintService}. 82 * 83 * @param listener a PrintServiceAttributeListener, which monitors the 84 * status of a print service 85 * @see #removePrintServiceAttributeListener 86 */ addPrintServiceAttributeListener( PrintServiceAttributeListener listener)87 public void addPrintServiceAttributeListener( 88 PrintServiceAttributeListener listener); 89 90 /** 91 * Removes the print-service listener from this print service. This means 92 * the listener is no longer interested in {@code PrintService} events. 93 * 94 * @param listener a {@code PrintServiceAttributeListener} object 95 * @see #addPrintServiceAttributeListener 96 */ removePrintServiceAttributeListener( PrintServiceAttributeListener listener)97 public void removePrintServiceAttributeListener( 98 PrintServiceAttributeListener listener); 99 100 /** 101 * Obtains this print service's set of printer description attributes giving 102 * this Print Service's status. The returned attribute set object is 103 * unmodifiable. The returned attribute set object is a "snapshot" of this 104 * Print Service's attribute set at the time of the {@code getAttributes()} 105 * method call: that is, the returned attribute set's contents will 106 * <i>not</i> be updated if this print service's attribute set's contents 107 * change in the future. To detect changes in attribute values, call 108 * {@code getAttributes()} again and compare the new attribute set to the 109 * previous attribute set; alternatively, register a listener for print 110 * service events. 111 * 112 * @return unmodifiable snapshot of this Print Service's attribute set. May 113 * be empty, but not {@code null}. 114 */ getAttributes()115 public PrintServiceAttributeSet getAttributes(); 116 117 /** 118 * Gets the value of the single specified service attribute. This may be 119 * useful to clients which only need the value of one attribute and want to 120 * minimize overhead. 121 * 122 * @param <T> the type of the specified service attribute 123 * @param category the category of a {@code PrintServiceAttribute} 124 * supported by this service - may not be {@code null} 125 * @return the value of the supported attribute or {@code null} if the 126 * attribute is not supported by this service 127 * @throws NullPointerException if the category is {@code null} 128 * @throws IllegalArgumentException if {@code category} is not a 129 * {@code Class} that implements interface 130 * {@link PrintServiceAttribute PrintServiceAttribute} 131 */ 132 public <T extends PrintServiceAttribute> getAttribute(Class<T> category)133 T getAttribute(Class<T> category); 134 135 /** 136 * Determines the print data formats a client can specify when setting up a 137 * job for this {@code PrintService}. A print data format is designated by a 138 * "doc flavor" (class {@link DocFlavor DocFlavor}) consisting of a MIME 139 * type plus a print data representation class. 140 * <p> 141 * Note that some doc flavors may not be supported in combination with all 142 * attributes. Use {@code getUnsupportedAttributes(..)} to validate specific 143 * combinations. 144 * 145 * @return array of supported doc flavors, should have at least one element 146 */ getSupportedDocFlavors()147 public DocFlavor[] getSupportedDocFlavors(); 148 149 /** 150 * Determines if this print service supports a specific {@code DocFlavor}. 151 * This is a convenience method to determine if the {@code DocFlavor} would 152 * be a member of the result of {@code getSupportedDocFlavors()}. 153 * <p> 154 * Note that some doc flavors may not be supported in combination with all 155 * attributes. Use {@code getUnsupportedAttributes(..)} to validate specific 156 * combinations. 157 * 158 * @param flavor the {@code DocFlavor} to query for support 159 * @return {@code true} if this print service supports the specified 160 * {@code DocFlavor}; {@code false} otherwise 161 * @throws NullPointerException if {@code flavor} is {@code null} 162 */ isDocFlavorSupported(DocFlavor flavor)163 public boolean isDocFlavorSupported(DocFlavor flavor); 164 165 /** 166 * Determines the printing attribute categories a client can specify when 167 * setting up a job for this print service. A printing attribute category is 168 * designated by a {@code Class} that implements interface 169 * {@link Attribute Attribute}. This method returns just the attribute 170 * <i>categories</i> that are supported; it does not return the particular 171 * attribute <i>values</i> that are supported. 172 * <p> 173 * This method returns all the printing attribute categories this print 174 * service supports for any possible job. Some categories may not be 175 * supported in a particular context (ie for a particular 176 * {@code DocFlavor}). Use one of the methods that include a 177 * {@code DocFlavor} to validate the request before submitting it, such as 178 * {@code getSupportedAttributeValues(..)}. 179 * 180 * @return array of printing attribute categories that the client can 181 * specify as a doc-level or job-level attribute in a Print Request. 182 * Each element in the array is a {@link Class Class} that 183 * implements interface {@link Attribute Attribute}. The array is 184 * empty if no categories are supported. 185 */ getSupportedAttributeCategories()186 public Class<?>[] getSupportedAttributeCategories(); 187 188 /** 189 * Determines whether a client can specify the given printing attribute 190 * category when setting up a job for this print service. A printing 191 * attribute category is designated by a {@code Class} that implements 192 * interface {@link Attribute Attribute}. This method 193 * tells whether the attribute <i>category</i> is supported; it does not 194 * tell whether a particular attribute <i>value</i> is supported. 195 * <p> 196 * Some categories may not be supported in a particular context (ie for a 197 * particular {@code DocFlavor}). Use one of the methods which include a 198 * {@code DocFlavor} to validate the request before submitting it, such as 199 * {@code getSupportedAttributeValues(..)}. 200 * <p> 201 * This is a convenience method to determine if the category would be a 202 * member of the result of {@code getSupportedAttributeCategories()}. 203 * 204 * @param category printing attribute category to test. It must be a 205 * {@code Class} that implements interface 206 * {@link Attribute Attribute}. 207 * @return {@code true} if this print service supports specifying a 208 * doc-level or job-level attribute in {@code category} in a Print 209 * Request; {@code false} if it doesn't 210 * @throws NullPointerException if {@code category} is {@code null} 211 * @throws IllegalArgumentException if {@code category} is not a 212 * {@code Class} that implements interface 213 * {@link Attribute Attribute} 214 */ 215 public boolean isAttributeCategorySupported(Class<? extends Attribute> category)216 isAttributeCategorySupported(Class<? extends Attribute> category); 217 218 /** 219 * Determines this print service's default printing attribute value in the 220 * given category. A printing attribute value is an instance of a class that 221 * implements interface {@link Attribute Attribute}. If a client sets up a 222 * print job and does not specify any attribute value in the given category, 223 * this Print Service will use the default attribute value instead. 224 * <p> 225 * Some attributes may not be supported in a particular context (ie for a 226 * particular {@code DocFlavor}). Use one of the methods that include a 227 * {@code DocFlavor} to validate the request before submitting it, such as 228 * {@code getSupportedAttributeValues(..)}. 229 * <p> 230 * Not all attributes have a default value. For example the service will not 231 * have a default value for {@code RequestingUser} i.e. a {@code null} 232 * return for a supported category means there is no service default value 233 * for that category. Use the {@code isAttributeCategorySupported(Class)} 234 * method to distinguish these cases. 235 * 236 * @param category printing attribute category for which the default 237 * attribute value is requested. It must be a {@link Class Class} 238 * that implements interface {@link Attribute Attribute}. 239 * @return default attribute value for {@code category}, or {@code null} if 240 * this Print Service does not support specifying a doc-level or 241 * job-level attribute in {@code category} in a Print Request, or 242 * the service does not have a default value for this attribute 243 * @throws NullPointerException if {@code category} is {@code null} 244 * @throws IllegalArgumentException if {@code category} is not a 245 * {@link Class Class} that implements interface 246 * {@link Attribute Attribute} 247 */ 248 public Object getDefaultAttributeValue(Class<? extends Attribute> category)249 getDefaultAttributeValue(Class<? extends Attribute> category); 250 251 /** 252 * Determines the printing attribute values a client can specify in the 253 * given category when setting up a job for this print service. A printing 254 * attribute value is an instance of a class that implements interface 255 * {@link Attribute Attribute}. 256 * <p> 257 * If {@code flavor} is {@code null} and {@code attributes} is {@code null} 258 * or is an empty set, this method returns all the printing attribute values 259 * this Print Service supports for any possible job. If {@code flavor} is not 260 * {@code null} or {@code attributes} is not an empty set, this method 261 * returns just the printing attribute values that are compatible with the 262 * given doc flavor and/or set of attributes. That is, a {@code null} return 263 * value may indicate that specifying this attribute is incompatible with 264 * the specified DocFlavor. Also if {@code DocFlavor} is not {@code null} it 265 * must be a flavor supported by this {@code PrintService}, else 266 * {@code IllegalArgumentException} will be thrown. 267 * <p> 268 * If the {@code attributes} parameter contains an {@code Attribute} whose 269 * category is the same as the {@code category} parameter, the service must 270 * ignore this attribute in the {@code AttributeSet}. 271 * <p> 272 * {@code DocAttribute}s which are to be specified on the {@code Doc} must 273 * be included in this set to accurately represent the context. 274 * <p> 275 * This method returns an {@code Object} because different printing 276 * attribute categories indicate the supported attribute values in different 277 * ways. The documentation for each printing attribute in package 278 * {@link javax.print.attribute.standard javax.print.attribute.standard} 279 * describes how each attribute indicates its supported values. Possible 280 * ways of indicating support include: 281 * <ul> 282 * <li>Return a single instance of the attribute category to indicate that 283 * any value is legal -- used, for example, by an attribute whose value is 284 * an arbitrary text string. (The value of the returned attribute object 285 * is irrelevant.) 286 * <li>Return an array of one or more instances of the attribute category, 287 * containing the legal values -- used, for example, by an attribute with 288 * a list of enumerated values. The type of the array is an array of the 289 * specified attribute category type as returned by its 290 * {@code getCategory(Class)}. 291 * <li>Return a single object (of some class other than the attribute 292 * category) that indicates bounds on the legal values -- used, for 293 * example, by an integer-valued attribute that must lie within a certain 294 * range. 295 * </ul> 296 * 297 * @param category printing attribute category to test. It must be a 298 * {@link Class Class} that implements interface 299 * {@link Attribute Attribute}. 300 * @param flavor doc flavor for a supposed job, or {@code null} 301 * @param attributes set of printing attributes for a supposed job (both 302 * job-level attributes and document-level attributes), or 303 * {@code null} 304 * @return object indicating supported values for {@code category}, or 305 * {@code null} if this Print Service does not support specifying a 306 * doc-level or job-level attribute in {@code category} in a Print 307 * Request 308 * @throws NullPointerException if {@code category} is {@code null} 309 * @throws IllegalArgumentException if {@code category} is not a 310 * {@link Class Class} that implements interface 311 * {@link Attribute Attribute}, or {@code DocFlavor} is not 312 * supported by this service 313 */ 314 public Object getSupportedAttributeValues(Class<? extends Attribute> category, DocFlavor flavor, AttributeSet attributes)315 getSupportedAttributeValues(Class<? extends Attribute> category, 316 DocFlavor flavor, 317 AttributeSet attributes); 318 319 /** 320 * Determines whether a client can specify the given printing attribute 321 * value when setting up a job for this Print Service. A printing attribute 322 * value is an instance of a class that implements interface 323 * {@link Attribute Attribute}. 324 * <p> 325 * If {@code flavor} is {@code null} and {@code attributes} is {@code null} 326 * or is an empty set, this method tells whether this Print Service supports 327 * the given printing attribute value for some possible combination of doc 328 * flavor and set of attributes. If {@code flavor} is not {@code null} or 329 * {@code attributes} is not an empty set, this method tells whether this 330 * Print Service supports the given printing attribute value in combination 331 * with the given doc flavor and/or set of attributes. 332 * <p> 333 * Also if {@code DocFlavor} is not {@code null} it must be a flavor 334 * supported by this {@code PrintService}, else 335 * {@code IllegalArgumentException} will be thrown. 336 * <p> 337 * {@code DocAttribute}s which are to be specified on the {@code Doc} must 338 * be included in this set to accurately represent the context. 339 * <p> 340 * This is a convenience method to determine if the value would be a member 341 * of the result of {@code getSupportedAttributeValues(...)}. 342 * 343 * @param attrval printing attribute value to test 344 * @param flavor doc flavor for a supposed job, or {@code null} 345 * @param attributes set of printing attributes for a supposed job (both 346 * job-level attributes and document-level attributes), or 347 * {@code null} 348 * @return {@code true} if this Print Service supports specifying 349 * {@code attrval} as a doc-level or job-level attribute in a Print 350 * Request, {@code false} if it doesn't 351 * @throws NullPointerException if {@code attrval} is {@code null} 352 * @throws IllegalArgumentException if flavor is not supported by this 353 * {@code PrintService} 354 */ isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes)355 public boolean isAttributeValueSupported(Attribute attrval, 356 DocFlavor flavor, 357 AttributeSet attributes); 358 359 /** 360 * Identifies the attributes that are unsupported for a print request in the 361 * context of a particular {@code DocFlavor}. This method is useful for 362 * validating a potential print job and identifying the specific attributes 363 * which cannot be supported. It is important to supply only a supported 364 * {@code DocFlavor} or an {@code IllegalArgumentException} will be thrown. 365 * If the return value from this method is {@code null}, all attributes are 366 * supported. 367 * <p> 368 * {@code DocAttribute}s which are to be specified on the {@code Doc} must 369 * be included in this set to accurately represent the context. 370 * <p> 371 * If the return value is {@code non-null}, all attributes in the returned 372 * set are unsupported with this {@code DocFlavor}. The returned set does 373 * not distinguish attribute categories that are unsupported from 374 * unsupported attribute values. 375 * <p> 376 * A supported print request can then be created by removing all unsupported 377 * attributes from the original attribute set, except in the case that the 378 * {@code DocFlavor} is unsupported. 379 * <p> 380 * If any attributes are unsupported only because they are in conflict with 381 * other attributes then it is at the discretion of the service to select 382 * the attribute(s) to be identified as the cause of the conflict. 383 * <p> 384 * Use {@code isDocFlavorSupported()} to verify that a {@code DocFlavor} is 385 * supported before calling this method. 386 * 387 * @param flavor doc flavor to test, or {@code null} 388 * @param attributes set of printing attributes for a supposed job (both 389 * job-level attributes and document-level attributes), or 390 * {@code null} 391 * @return {@code null} if this Print Service supports the print request 392 * specification, else the unsupported attributes 393 * @throws IllegalArgumentException if {@code flavor} is not supported by 394 * this {@code PrintService} 395 */ getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes)396 public AttributeSet getUnsupportedAttributes(DocFlavor flavor, 397 AttributeSet attributes); 398 399 /** 400 * Returns a factory for UI components which allow users to interact with 401 * the service in various roles. Services which do not provide any UI should 402 * return {@code null}. Print Services which do provide UI but want to be 403 * supported in an environment with no UI support should ensure that the 404 * factory is not initialised unless the application calls this method to 405 * obtain the factory. See {@code ServiceUIFactory} for more information. 406 * 407 * @return {@code null} or a factory for UI components 408 */ getServiceUIFactory()409 public ServiceUIFactory getServiceUIFactory(); 410 411 /** 412 * Determines if two services are referring to the same underlying service. 413 * Objects encapsulating a print service may not exhibit equality of 414 * reference even though they refer to the same underlying service. 415 * <p> 416 * Clients should call this method to determine if two services are 417 * referring to the same underlying service. 418 * <p> 419 * Services must implement this method and return {@code true} only if the 420 * service objects being compared may be used interchangeably by the client. 421 * Services are free to return the same object reference to an underlying 422 * service if that, but clients must not depend on equality of reference. 423 * 424 * @param obj the reference object with which to compare 425 * @return {@code true} if this service is the same as the obj argument, 426 * {@code false} otherwise 427 */ equals(Object obj)428 public boolean equals(Object obj); 429 430 /** 431 * This method should be implemented consistently with 432 * {@code equals(Object)}. 433 * 434 * @return hash code of this object 435 */ hashCode()436 public int hashCode(); 437 } 438