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