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