KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > print > attribute > ResolutionSyntax


1 /*
2  * @(#)ResolutionSyntax.java 1.7 04/01/07
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8
9 package javax.print.attribute;
10
11 import java.io.Serializable JavaDoc;
12
13 /**
14  * Class ResolutionSyntax is an abstract base class providing the common
15  * implementation of all attributes denoting a printer resolution.
16  * <P>
17  * A resolution attribute's value consists of two items, the cross feed
18  * direction resolution and the feed direction resolution. A resolution
19  * attribute may be constructed by supplying the two values and indicating the
20  * units in which the values are measured. Methods are provided to return a
21  * resolution attribute's values, indicating the units in which the values are
22  * to be returned. The two most common resolution units are dots per inch (dpi)
23  * and dots per centimeter (dpcm), and exported constants {@link #DPI
24  * <CODE>DPI</CODE>} and {@link #DPCM <CODE>DPCM</CODE>} are provided for
25  * indicating those units.
26  * <P>
27  * Once constructed, a resolution attribute's value is immutable.
28  * <P>
29  * <B>Design</B>
30  * <P>
31  * A resolution attribute's cross feed direction resolution and feed direction
32  * resolution values are stored internally using units of dots per 100 inches
33  * (dphi). Storing the values in dphi rather than, say, metric units allows
34  * precise integer arithmetic conversions between dpi and dphi and between dpcm
35  * and dphi: 1 dpi = 100 dphi, 1 dpcm = 254 dphi. Thus, the values can be stored
36  * into and retrieved back from a resolution attribute in either units with no
37  * loss of precision. This would not be guaranteed if a floating point
38  * representation were used. However, roundoff error will in general occur if a
39  * resolution attribute's values are created in one units and retrieved in
40  * different units; for example, 600 dpi will be rounded to 236 dpcm, whereas
41  * the true value (to five figures) is 236.22 dpcm.
42  * <P>
43  * Storing the values internally in common units of dphi lets two resolution
44  * attributes be compared without regard to the units in which they were
45  * created; for example, 300 dpcm will compare equal to 762 dpi, as they both
46  * are stored as 76200 dphi. In particular, a lookup service can
47  * match resolution attributes based on equality of their serialized
48  * representations regardless of the units in which they were created. Again,
49  * using integers for internal storage allows precise equality comparisons to be
50  * done, which would not be guaranteed if a floating point representation were
51  * used.
52  * <P>
53  * The exported constant {@link #DPI <CODE>DPI</CODE>} is actually the
54  * conversion factor by which to multiply a value in dpi to get the value in
55  * dphi. Likewise, the exported constant {@link #DPCM <CODE>DPCM</CODE>} is the
56  * conversion factor by which to multiply a value in dpcm to get the value in
57  * dphi. A client can specify a resolution value in units other than dpi or dpcm
58  * by supplying its own conversion factor. However, since the internal units of
59  * dphi was chosen with supporting only the external units of dpi and dpcm in
60  * mind, there is no guarantee that the conversion factor for the client's units
61  * will be an exact integer. If the conversion factor isn't an exact integer,
62  * resolution values in the client's units won't be stored precisely.
63  * <P>
64  *
65  * @author David Mendenhall
66  * @author Alan Kaminsky
67  */

68 public abstract class ResolutionSyntax implements Serializable JavaDoc, Cloneable JavaDoc {
69
70     private static final long serialVersionUID = 2706743076526672017L;
71
72     /**
73      * Cross feed direction resolution in units of dots per 100 inches (dphi).
74      * @serial
75      */

76     private int crossFeedResolution;
77
78     /**
79      * Feed direction resolution in units of dots per 100 inches (dphi).
80      * @serial
81      */

82     private int feedResolution;
83
84     /**
85      * Value to indicate units of dots per inch (dpi). It is actually the
86      * conversion factor by which to multiply dpi to yield dphi (100).
87      */

88     public static final int DPI = 100;
89
90     /**
91      * Value to indicate units of dots per centimeter (dpcm). It is actually
92      * the conversion factor by which to multiply dpcm to yield dphi (254).
93      */

94     public static final int DPCM = 254;
95
96
97     /**
98      * Construct a new resolution attribute from the given items.
99      *
100      * @param crossFeedResolution
101      * Cross feed direction resolution.
102      * @param feedResolution
103      * Feed direction resolution.
104      * @param units
105      * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
106      * {@link #DPCM <CODE>DPCM</CODE>}.
107      *
108      * @exception IllegalArgumentException
109      * (unchecked exception) Thrown if <CODE>crossFeedResolution</CODE> <
110      * 1 or <CODE>feedResolution</CODE> < 1 or <CODE>units</CODE> < 1.
111      */

112     public ResolutionSyntax(int crossFeedResolution, int feedResolution,
113                 int units) {
114
115     if (crossFeedResolution < 1) {
116         throw new IllegalArgumentException JavaDoc("crossFeedResolution is < 1");
117     }
118     if (feedResolution < 1) {
119         throw new IllegalArgumentException JavaDoc("feedResolution is < 1");
120     }
121     if (units < 1) {
122         throw new IllegalArgumentException JavaDoc("units is < 1");
123     }
124
125     this.crossFeedResolution = crossFeedResolution * units;
126     this.feedResolution = feedResolution * units;
127     }
128
129     /**
130      * Convert a value from dphi to some other units. The result is rounded to
131      * the nearest integer.
132      *
133      * @param dphi
134      * Value (dphi) to convert.
135      * @param units
136      * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
137      * {@link #DPCM <CODE>DPCM</CODE>}.
138      *
139      * @return The value of <CODE>dphi</CODE> converted to the desired units.
140      *
141      * @exception IllegalArgumentException
142      * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
143      */

144     private static int convertFromDphi(int dphi, int units) {
145     if (units < 1) {
146         throw new IllegalArgumentException JavaDoc(": units is < 1");
147     }
148     int round = units / 2;
149     return (dphi + round) / units;
150     }
151     
152     /**
153      * Get this resolution attribute's resolution values in the given units.
154      * The values are rounded to the nearest integer.
155      *
156      * @param units
157      * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
158      * {@link #DPCM <CODE>DPCM</CODE>}.
159      *
160      * @return A two-element array with the cross feed direction resolution
161      * at index 0 and the feed direction resolution at index 1.
162      *
163      * @exception IllegalArgumentException
164      * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
165      */

166     public int[] getResolution(int units) {
167     return new int[] { getCrossFeedResolution(units),
168                    getFeedResolution(units)
169                    };
170     }
171
172     /**
173      * Returns this resolution attribute's cross feed direction resolution in
174      * the given units. The value is rounded to the nearest integer.
175      *
176      * @param units
177      * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
178      * {@link #DPCM <CODE>DPCM</CODE>}.
179      *
180      * @return Cross feed direction resolution.
181      *
182      * @exception IllegalArgumentException
183      * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
184      */

185     public int getCrossFeedResolution(int units) {
186     return convertFromDphi (crossFeedResolution, units);
187     }
188
189     /**
190      * Returns this resolution attribute's feed direction resolution in the
191      * given units. The value is rounded to the nearest integer.
192      *
193      * @param units
194      * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or {@link
195      * #DPCM <CODE>DPCM</CODE>}.
196      *
197      * @return Feed direction resolution.
198      *
199      * @exception IllegalArgumentException
200      * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
201      */

202     public int getFeedResolution(int units) {
203     return convertFromDphi (feedResolution, units);
204     }
205     
206     /**
207      * Returns a string version of this resolution attribute in the given units.
208      * The string takes the form <CODE>"<I>C</I>x<I>F</I> <I>U</I>"</CODE>,
209      * where <I>C</I> is the cross feed direction resolution, <I>F</I> is the
210      * feed direction resolution, and <I>U</I> is the units name. The values are
211      * rounded to the nearest integer.
212      *
213      * @param units
214      * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or {@link
215      * #DPCM <CODE>DPCM</CODE>}.
216      * @param unitsName
217      * Units name string, e.g. <CODE>"dpi"</CODE> or <CODE>"dpcm"</CODE>. If
218      * null, no units name is appended to the result.
219      *
220      * @return String version of this resolution attribute.
221      *
222      * @exception IllegalArgumentException
223      * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
224      */

225     public String JavaDoc toString(int units, String JavaDoc unitsName) {
226     StringBuffer JavaDoc result = new StringBuffer JavaDoc();
227     result.append(getCrossFeedResolution (units));
228     result.append('x');
229     result.append(getFeedResolution (units));
230     if (unitsName != null) {
231         result.append (' ');
232         result.append (unitsName);
233     }
234     return result.toString();
235     }
236
237     
238     /**
239      * Determine whether this resolution attribute's value is less than or
240      * equal to the given resolution attribute's value. This is true if all
241      * of the following conditions are true:
242      * <UL>
243      * <LI>
244      * This attribute's cross feed direction resolution is less than or equal to
245      * the <CODE>other</CODE> attribute's cross feed direction resolution.
246      * <LI>
247      * This attribute's feed direction resolution is less than or equal to the
248      * <CODE>other</CODE> attribute's feed direction resolution.
249      * </UL>
250      *
251      * @param other Resolution attribute to compare with.
252      *
253      * @return True if this resolution attribute is less than or equal to the
254      * <CODE>other</CODE> resolution attribute, false otherwise.
255      *
256      * @exception NullPointerException
257      * (unchecked exception) Thrown if <CODE>other</CODE> is null.
258      */

259     public boolean lessThanOrEquals(ResolutionSyntax JavaDoc other) {
260     return (this.crossFeedResolution <= other.crossFeedResolution &&
261         this.feedResolution <= other.feedResolution);
262     }
263
264
265     /**
266      * Returns whether this resolution attribute is equivalent to the passed in
267      * object. To be equivalent, all of the following conditions must be true:
268      * <OL TYPE=1>
269      * <LI>
270      * <CODE>object</CODE> is not null.
271      * <LI>
272      * <CODE>object</CODE> is an instance of class ResolutionSyntax.
273      * <LI>
274      * This attribute's cross feed direction resolution is equal to
275      * <CODE>object</CODE>'s cross feed direction resolution.
276      * <LI>
277      * This attribute's feed direction resolution is equal to
278      * <CODE>object</CODE>'s feed direction resolution.
279      * </OL>
280      *
281      * @param object Object to compare to.
282      *
283      * @return True if <CODE>object</CODE> is equivalent to this resolution
284      * attribute, false otherwise.
285      */

286     public boolean equals(Object JavaDoc object) {
287
288     return(object != null &&
289            object instanceof ResolutionSyntax JavaDoc &&
290            this.crossFeedResolution ==
291            ((ResolutionSyntax JavaDoc) object).crossFeedResolution &&
292            this.feedResolution ==
293            ((ResolutionSyntax JavaDoc) object).feedResolution);
294     }
295     
296     /**
297      * Returns a hash code value for this resolution attribute.
298      */

299     public int hashCode() {
300     return(((crossFeedResolution & 0x0000FFFF)) |
301            ((feedResolution & 0x0000FFFF) << 16));
302     }
303     
304     /**
305      * Returns a string version of this resolution attribute. The string takes
306      * the form <CODE>"<I>C</I>x<I>F</I> dphi"</CODE>, where <I>C</I> is the
307      * cross feed direction resolution and <I>F</I> is the feed direction
308      * resolution. The values are reported in the internal units of dphi.
309      */

310     public String JavaDoc toString() {
311     StringBuffer JavaDoc result = new StringBuffer JavaDoc();
312     result.append(crossFeedResolution);
313     result.append('x');
314     result.append(feedResolution);
315     result.append(" dphi");
316     return result.toString();
317     }
318
319
320     /**
321      * Returns this resolution attribute's cross feed direction resolution in
322      * units of dphi. (For use in a subclass.)
323      *
324      * @return Cross feed direction resolution.
325      */

326     protected int getCrossFeedResolutionDphi() {
327     return crossFeedResolution;
328     }
329
330     /**
331      * Returns this resolution attribute's feed direction resolution in units
332      * of dphi. (For use in a subclass.)
333      *
334      * @return Feed direction resolution.
335      */

336     protected int getFeedResolutionDphi() {
337     return feedResolution;
338     }
339
340 }
341
Popular Tags