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 /** 27 * Provides classes and interfaces that describe the types of Java™ Print 28 * Service attributes and how they can be collected into attribute sets. 29 * 30 * <h3>What is an Attribute?</h3> 31 * When setting up a print job, a client specifies two things: <b>print data</b> 32 * and <b>processing instructions.</b> The print data is the actual content to 33 * be printed. The processing instructions tell the printer how to print the 34 * print data, such as: what media to use, how many copies to print, and whether 35 * to print on one or both sides of a sheet. The client specifies these 36 * processing instructions with the attribute definitions of the Java Print 37 * Service API. 38 * <p> 39 * The print data and the processing instructions are separate entities. This 40 * means that: 41 * <ul> 42 * <li>You can print the same print data at different times using different 43 * processing instructions.<br>For example, you can print a slide 44 * presentation on US letter-sized white paper, double-sided, stapled, 20 45 * copies to make handouts for a talk; and you could print the same slide 46 * presentation on US letter-sized transparencies, single-sided, one copy to 47 * make the actual slides for the talk.</li> 48 * <li>You can use the same processing instructions at different times to 49 * print different data. For example, you could set your default processing 50 * instructions to: US letter-sized paper, double sided, stapled. Whenever 51 * you print a job, it prints with these settings, unless you explicitly 52 * override them.</li> 53 * </ul> 54 * <p> 55 * The processing instruction does not specify how the print job processes the 56 * request; each processing instruction is only a description of the results of 57 * a print job. The print job determines the manner in which it achieves the 58 * results specified by the processing instructions. Representing processing 59 * instructions as descriptive items provides more flexibility for implementing 60 * print jobs. 61 * 62 * <h4>Attribute Categories and Values</h4> 63 * Each printer has a set of capabilities, such as the ability to print on 64 * different paper sizes or the ability to print more than one copy. Each of the 65 * capabilities has a range of values. For example, a printer's orientation 66 * capability might have this range of values: [landscape, portrait]. For each 67 * print request, the capability is set to one of these values. The Java Print 68 * Service API uses the term <b>attribute category</b> to refer to a printer 69 * capability and the term <b>attribute value</b> to refer to the value of the 70 * capability. 71 * <p> 72 * In the Java Print Service API, an attribute category is represented by a Java 73 * class implementing the <a href="Attribute.html">Attribute</a> interface. 74 * Attribute values are instances of such a class or one of its subclasses. For 75 * example, to specify the number of copies, an application constructs an 76 * instance of the <a href="standard/Copies.html">Copies</a> class with the 77 * number of desired copies and uses the {@code Copies} instance as part of the 78 * print request. In this case, the {@code Copies} class represents the 79 * attribute category, and the {@code Copies} instance represents the attribute 80 * value. 81 * 82 * <h4><a name="role"></a>Attribute Roles</h4> 83 * When submitting a print job to a printer, the client provides the attributes 84 * describing the characteristics of the print data, such as the document name, 85 * and how the print data should be printed, such as double-sided, five copies. 86 * If a print job consists of multiple pieces of print data, different pieces 87 * might have different processing instructions, such as 8 x 11 inch media for 88 * the first document, and 11 x 17 inch media for another document. 89 * <p> 90 * Once the printer starts processing the print job, additional information 91 * about the job becomes available, which might include: the job state (such as 92 * <i>completed</i> or <i>queued</i>) and the number of pages printed so far. 93 * These pieces of information are also attributes. Attributes can also describe 94 * the printer itself, such as: the printer name, the printer location, and the 95 * number of jobs queued. 96 * <p> 97 * The Java Print Service API defines these different kinds of attributes with 98 * five subinterfaces of {@code Attribute}: 99 * <ul> 100 * <li><a href="DocAttribute.html">DocAttribute</a> specifies a 101 * characteristic of an individual document and the print job settings to be 102 * applied to an individual document.</li> 103 * <li><a href="PrintRequestAttribute.html">PrintRequestAttribute</a> 104 * specifies a setting applied to a whole print job and to all the documents 105 * in the print job.</li> 106 * <li><a href="PrintJobAttribute.html">PrintJobAttribute</a> reports the 107 * status of a print job.</li> 108 * <li><a href="PrintServiceAttribute.html">PrintServiceAttribute</a> 109 * reports the status of a print service.</li> 110 * <li><a href="SupportedValuesAttribute.html">SupportedValuesAttribute</a> 111 * gives the supported values for another attribute.</li> 112 * </ul> 113 * Each attribute class implements one or more of these tagging subinterfaces to 114 * indicate where the attribute can be used in the API. If an attribute class 115 * implements multiple tagging subinterfaces, the attribute can be used in 116 * multiple contexts. For example, the media attribute can apply to one document 117 * in a print job as a {@code DocAttribute} or to an entire print job as a 118 * {@code PrintRequestAttribute}. Certain low-level attributes are never used on 119 * their own but are always aggregated into higher-level attributes. These 120 * low-level attribute classes only implement interface 121 * <a href="Attribute.html">Attribute</a>, not any of the tagging subinterfaces. 122 * <p> 123 * The Java Print Service API defines a group of standard attribute classes 124 * modeled upon the attributes in the Internet Printing Protocol (IPP) version 125 * 1.1. The standard attribute classes are in the subpackage 126 * javax.print.attribute.standard to keep the actual attribute classes 127 * conceptually separate from the generic apparatus defined in package 128 * javax.print.attribute. 129 * 130 * <h3>Attribute Sets</h3> 131 * A client usually needs to provide more than one processing instruction when 132 * submitting a print job. For example, the client might need to specify a 133 * media size of A4 and a landscape orientation. To send more than one 134 * processing instruction, the client collects the attributes into an attribute 135 * set, which the Java Print Service API represents with the 136 * <a href="AttributeSet.html">AttributeSet</a> interface. 137 * <p> 138 * The {@code AttributeSet} interface is similar to the 139 * <a href="../../../java/util/Map.html">Map</a> interface: it provides a map of 140 * key to values, in which each key is unique and can contain no more than one 141 * value. However, the {@code AttributeSet} interface is designed to 142 * specifically support the needs of the Java Print Service API. An {@code 143 * AttributeSet} requires that: 144 * <ol type=1> 145 * <li>Each key in an {@code AttributeSet} corresponds to a category, and 146 * the value of the key can only be one of the attribute values that belong 147 * to the category represented by the key. Thus, unlike a {@code Map}, an 148 * {@code AttributeSet} restricts the possible values of a key: an attribute 149 * category cannot be set to an attribute value that does not belong to that 150 * category.</li> 151 * <li>No two attributes from the same category can exist in the same set. 152 * For example, an attribute collection must not contain both a "one-sided" 153 * attribute and a "two-sided" attribute because these two attributes give 154 * the printer conflicting instructions.</li> 155 * <li>Only attributes implementing the {@code Attribute} interface can be 156 * added to the set.</li> 157 * </ol> 158 * <p> 159 * The javax.print.attribute package includes 160 * <a href="HashAttributeSet.html">HashAttributeSet</a> as a concrete 161 * implementation of the attribute set interface. {@code HashAttributeSet} 162 * provides an attribute set based on a hash map. You can use this 163 * implementation or provide your own implementation of interface 164 * {@code AttributeSet}. 165 * <p> 166 * The Java Print Service API provides four specializations of an attribute set 167 * that are restricted to contain just one of the four kinds of attributes, as 168 * discussed in the <a href="#role">Attribute Roles</a> section: 169 * <ul> 170 * <li><a href="DocAttributeSet.html">DocAttributeSet</a></li> 171 * <li><a href="PrintRequestAttributeSet.html"> 172 * PrintRequestAttributeSet</a></li> 173 * <li><a href="PrintJobAttributeSet.html"> 174 * PrintJobAttributeSet</a></li> 175 * <li><a href="PrintServiceAttributeSet.html"> 176 * PrintServiceAttributeSet</a></li> 177 * </ul> 178 * Notice that only four kinds of attribute sets are listed here, but there are 179 * five kinds of attributes. Interface 180 * <a href="SupportedValuesAttribute.html">SupportedValuesAttribute</a> 181 * denotes an attribute that gives the supported values for another attribute. 182 * Supported-values attributes are never aggregated into attribute sets, so 183 * there is no attribute set subinterface defined for them. 184 * <p> 185 * In some contexts, an attribute set is read-only, which means that the client 186 * is only allowed to examine an attribute set's contents but not change them. 187 * In other contexts, the attribute set is read-write, which means that the 188 * client is allowed both to examine and to change an attribute set's contents. 189 * For a read-only attribute set, calling a mutating operation throws an 190 * {@code UnmodifiableSetException}. 191 * <p> 192 * Package javax.print.attribute includes one concrete implementation of each of 193 * the attribute set subinterfaces: 194 * <ul> 195 * <li><a href="HashDocAttributeSet.html"> 196 * HashDocAttributeSet</a></li> 197 * <li><a href="HashPrintRequestAttributeSet.html"> 198 * HashPrintRequestAttributeSet</a>,</li> 199 * <li><a href="HashPrintJobAttributeSet.html"> 200 * HashPrintJobAttributeSet</a>,</li> 201 * <li><a href="HashPrintServiceAttributeSet.html"> 202 * HashPrintServiceAttributeSet</a>.</li> 203 * </ul> 204 * All of these classes extend 205 * <a href="HashAttributeSet.html">HashAttributeSet</a> and enforce the 206 * restriction that the attribute set is only allowed to contain the 207 * corresponding kind of attribute. 208 * 209 * <h3>Attribute Class Design</h3> 210 * An attribute value is a small, atomic data item, such as an integer or an 211 * enumerated value. The Java Print Service API does not use primitive data 212 * types, such as int, to represent attribute values for these reasons: 213 * <ul> 214 * <li>Primitive data types are not type-safe. For example, a compiler 215 * should not allow a "copies" attribute value to be used for a "sides" 216 * attribute.</li> 217 * <li>Some attributes must be represented as a record of several values. 218 * One example is printer resolution, which requires two numbers, such as 219 * 600 and 300 representing 600 x 300 dpi.</li> 220 * </ul> 221 * For type-safety and to represent all attributes uniformly, the Java Print 222 * Service API defines each attribute category as a class, such as class 223 * {@code Copies}, class <a href="standard/Sides.html">Sides</a>, and class 224 * <a href="standard/PrinterResolution.html">PrinterResolution</a>. Each 225 * attribute class wraps one or more primitive data items containing the 226 * attribute's value. Attribute set operations perform frequent comparisons 227 * between attribute category objects when adding attributes, finding existing 228 * attributes in the same category, and looking up an attribute given its 229 * category. Because an attribute category is represented by a class, fast 230 * attribute-value comparisons can be performed with the {@code Class.equals} 231 * method. 232 * <p> 233 * Even though the Java Print Service API includes a large number of different 234 * attribute categories, there are only a few different types of attribute 235 * values. Most attributes can be represented by a small number of data types, 236 * such as: integer values, integer ranges, text, or an enumeration of integer 237 * values. The type of the attribute value that a category accepts is called the 238 * attribute's abstract syntax. To provide consistency and reduce code 239 * duplication, the Java Print Service API defines abstract syntax classes to 240 * represent each abstract syntax, and these classes are used as the parent of 241 * standard attributes whenever possible. The abstract syntax classes are: 242 * <ul> 243 * <li><a href="EnumSyntax.html">EnumSyntax</a> provides a type-safe 244 * enumeration in which enumerated values are represented as singleton 245 * objects. Each enumeration singleton is an instance of the enumeration 246 * class that wraps a hidden int value.</li> 247 * <li><a href="IntegerSyntax.html">IntegerSyntax</a> is the abstract syntax 248 * for integer-valued attributes.</li> 249 * <li><a href="TextSyntax.html">TextSyntax</a> is the abstract syntax for 250 * text-valued attributes, and includes a locale giving the text string's 251 * natural language.</li> 252 * <li><a href="SetOfIntegerSyntax.html">SetOfIntegerSyntax</a> is the 253 * abstract syntax for attributes representing a range or set of integers 254 * <li><a href="ResolutionSyntax.html">ResolutionSyntax</a> is the abstract 255 * syntax for attributes representing resolution values, such as 600x300 256 * dpi.</li> 257 * <li><a href="Size2DSyntax.html">Size2DSyntax</a> is the abstract syntax 258 * for attributes representing a two-dimensional size, such as a paper size 259 * of 8.5 x 11 inches.</li> 260 * <li><a href="DateTimeSyntax.html">DateTimeSyntax</a> is the abstract 261 * syntax for attributes whose value is a date and time.</li> 262 * <li><a href="URISyntax.html">URISyntax</a> is the abstract syntax for 263 * attributes whose value is a Uniform Resource Indicator.</li> 264 * </ul> 265 * The abstract syntax classes are independent of the attributes that use them. 266 * In fact, applications that have nothing to do with printing can use the 267 * abstract syntax classes. Although most of the standard attribute classes 268 * extend one of the abstract syntax classes, no attribute class is required to 269 * extend one of these classes. The abstract syntax classes merely provide a 270 * convenient implementation that can be shared by many attribute classes. 271 * <p> 272 * Each attribute class implements the {@code Attribute} interface, either 273 * directly or indirectly, to mark it as a printing attribute. An attribute 274 * class that can appear in restricted attribute sets in certain contexts also 275 * implements one or more subinterfaces of {@code Attribute}. Most attribute 276 * classes also extend the appropriate abstract syntax class to get the 277 * implementation. Consider the {@code Sides} attribute class: 278 * <blockquote> 279 * <pre>{@code 280 * public class Sides 281 * extends EnumSyntax 282 * implements DocAttribute, PrintRequestAttribute, PrintJobAttribute 283 * { 284 * public final Object getCategory() 285 * { 286 * return Sides.class; 287 * } 288 * ... 289 * }} 290 * </pre> 291 * </blockquote> 292 * <p> 293 * Since every attribute class implements {@code Attribute}, every attribute 294 * class must provide an implementation for the 295 * {@link javax.print.attribute.Attribute#getCategory() getCategory} method, 296 * which returns the attribute category. In the case of {@code Sides}, the 297 * {@code getCategory} method returns {@code Sides.class}. The 298 * {@code getCategory} method is final to ensure that any vendor-defined 299 * subclasses of a standard attribute class appear in the same category. Every 300 * attribute object is immutable once constructed so that attribute object 301 * references can be passed around freely. To get a different attribute value, 302 * construct a different attribute object. 303 * 304 * <h3>Attribute Vendors</h3> 305 * The Java Print Service API is designed so that vendors can: 306 * <ul> 307 * <li>define new vendor-specific values for any standard attribute defined 308 * in <a href="standard/package-summary.html">javax.print.attribute.standard 309 * </a>.</li> 310 * <li>define new attribute categories representing the vendor printer's 311 * proprietary capabilities not already supported by the standard 312 * attributes.</li> 313 * </ul> 314 * To define a new value for an attribute, a client can construct instances of 315 * such attributes with arbitrary values at runtime. However, an enumerated 316 * attribute using an abstract syntax class of {@code EnumSyntax} specifies all 317 * the possible attribute values at compile time as singleton instances of the 318 * attribute class. This means that new enumerated values cannot be constructed 319 * at run time. To define new vendor-specific values for a standard enumerated 320 * attribute, the vendor must define a new attribute class specifying the new 321 * singleton instances. To ensure that the new attribute values fall in the same 322 * category as the standard attribute values, the new attribute class must be a 323 * subclass of the standard attribute class. 324 * <p> 325 * To define a new attribute category, a vendor defines a new attribute class. 326 * This attribute class, like the standard attribute classes, implements 327 * {@code Attribute} or one of its subinterfaces and extends an abstract syntax 328 * class. The vendor can either use an existing abstract syntax class or define 329 * a new one. The new vendor-defined attribute can be used wherever an 330 * {@code Attribute} is used, such as in an {@code AttributeSet}. 331 * 332 * <h3>Using Attributes</h3> 333 * A typical printing application uses the {@code PrintRequestAttributeSet} 334 * because print-request attributes are the types of attributes that client 335 * usually specifies. This example demonstrates creating an attribute set of 336 * print-request attributes and locating a printer that can print the document 337 * according to the specified attributes: 338 * <blockquote> 339 * <pre>{@code 340 * FileInputStream psStream; 341 * try { 342 * psstream = new FileInputStream("file.ps"); 343 * } catch (FileNotFoundException ffne) { 344 * } 345 * if (psstream == null) { 346 * return; 347 * } 348 * //Set the document type. See the DocFlavor documentation for 349 * //more information. 350 * DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT; 351 * Doc myDoc = new SimpleDoc(pstream, psInFormat, null); 352 * PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet(); 353 * aset.add(new Copies(5)); 354 * aset.add(MediaSize.A4); 355 * aset.add(Sides.DUPLEX); 356 * PrintService[] services = 357 * PrintServiceLookup.lookupPrintServices(psInFormat, aset); 358 * if (services.length > 0) { 359 * DocPrintJob job = services[0].createPrintJob(); 360 * try { 361 * job.print(myDoc, aset); 362 * } catch (PrintException pe) {} 363 * } 364 * }</pre> 365 * </blockquote> 366 * <p> 367 * Please note: In the javax.print APIs, a null reference parameter to methods 368 * is incorrect unless explicitly documented on the method as having a 369 * meaningful interpretation. Usage to the contrary is incorrect coding and may 370 * result in a run time exception either immediately or at some later time. 371 * IllegalArgumentException and NullPointerException are examples of typical and 372 * acceptable run time exceptions for such cases. 373 * 374 * @since 1.4 375 */ 376 package javax.print.attribute;