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