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 package javax.print.attribute;
27
28 import java.io.Serializable;
29
30 /**
31 * Class {@code ResolutionSyntax} is an abstract base class providing the common
32 * implementation of all attributes denoting a printer resolution.
33 * <p>
34 * A resolution attribute's value consists of two items, the cross feed
35 * direction resolution and the feed direction resolution. A resolution
36 * attribute may be constructed by supplying the two values and indicating the
37 * units in which the values are measured. Methods are provided to return a
38 * resolution attribute's values, indicating the units in which the values are
39 * to be returned. The two most common resolution units are dots per inch (dpi)
40 * and dots per centimeter (dpcm), and exported constants {@link #DPI DPI} and
41 * {@link #DPCM DPCM} are provided for indicating those units.
42 * <p>
43 * Once constructed, a resolution attribute's value is immutable.
44 * <p>
45 * <b>Design</b>
46 * <p>
47 * A resolution attribute's cross feed direction resolution and feed direction
48 * resolution values are stored internally using units of dots per 100 inches
49 * (dphi). Storing the values in dphi rather than, say, metric units allows
50 * precise integer arithmetic conversions between dpi and dphi and between dpcm
51 * and dphi: 1 dpi = 100 dphi, 1 dpcm = 254 dphi. Thus, the values can be stored
52 * into and retrieved back from a resolution attribute in either units with no
53 * loss of precision. This would not be guaranteed if a floating point
54 * representation were used. However, roundoff error will in general occur if a
55 * resolution attribute's values are created in one units and retrieved in
56 * different units; for example, 600 dpi will be rounded to 236 dpcm, whereas
57 * the true value (to five figures) is 236.22 dpcm.
58 * <p>
59 * Storing the values internally in common units of dphi lets two resolution
60 * attributes be compared without regard to the units in which they were
61 * created; for example, 300 dpcm will compare equal to 762 dpi, as they both
62 * are stored as 76200 dphi. In particular, a lookup service can match
63 * resolution attributes based on equality of their serialized representations
64 * regardless of the units in which they were created. Again, using integers for
65 * internal storage allows precise equality comparisons to be done, which would
66 * not be guaranteed if a floating point representation were used.
67 * <p>
68 * The exported constant {@link #DPI DPI} is actually the conversion factor by
69 * which to multiply a value in dpi to get the value in dphi. Likewise, the
70 * exported constant {@link #DPCM DPCM} is the conversion factor by which to
71 * multiply a value in dpcm to get the value in dphi. A client can specify a
72 * resolution value in units other than dpi or dpcm by supplying its own
73 * conversion factor. However, since the internal units of dphi was chosen with
74 * supporting only the external units of dpi and dpcm in mind, there is no
75 * guarantee that the conversion factor for the client's units will be an exact
76 * integer. If the conversion factor isn't an exact integer, resolution values
77 * in the client's units won't be stored precisely.
78 *
79 * @author David Mendenhall
80 * @author Alan Kaminsky
81 */
82 public abstract class ResolutionSyntax implements Serializable, Cloneable {
83
84 /**
85 * Use serialVersionUID from JDK 1.4 for interoperability.
86 */
87 private static final long serialVersionUID = 2706743076526672017L;
88
89 /**
90 * Cross feed direction resolution in units of dots per 100 inches (dphi).
91 *
92 * @serial
93 */
94 private int crossFeedResolution;
95
96 /**
97 * Feed direction resolution in units of dots per 100 inches (dphi).
98 *
99 * @serial
100 */
101 private int feedResolution;
102
103 /**
104 * Value to indicate units of dots per inch (dpi). It is actually the
105 * conversion factor by which to multiply dpi to yield dphi (100).
106 */
107 public static final int DPI = 100;
108
109 /**
110 * Value to indicate units of dots per centimeter (dpcm). It is actually the
111 * conversion factor by which to multiply dpcm to yield dphi (254).
112 */
113 public static final int DPCM = 254;
114
115 /**
116 * Construct a new resolution attribute from the given items.
117 *
118 * @param crossFeedResolution cross feed direction resolution
119 * @param feedResolution feed direction resolution
120 * @param units unit conversion factor, e.g. {@link #DPI DPI} or
121 * {@link #DPCM DPCM}
122 * @throws IllegalArgumentException if {@code crossFeedResolution < 1} or
123 * {@code feedResolution < 1} or {@code units < 1}
124 */
125 public ResolutionSyntax(int crossFeedResolution, int feedResolution,
126 int units) {
127
128 if (crossFeedResolution < 1) {
129 throw new IllegalArgumentException("crossFeedResolution is < 1");
130 }
131 if (feedResolution < 1) {
132 throw new IllegalArgumentException("feedResolution is < 1");
133 }
134 if (units < 1) {
135 throw new IllegalArgumentException("units is < 1");
136 }
137
138 this.crossFeedResolution = crossFeedResolution * units;
139 this.feedResolution = feedResolution * units;
140 }
141
142 /**
143 * Convert a value from dphi to some other units. The result is rounded to
144 * the nearest integer.
145 *
146 * @param dphi value (dphi) to convert
147 * @param units unit conversion factor, e.g. {@link #DPI DPI} or
148 * {@link #DPCM DPCM}
149 * @return the value of {@code dphi} converted to the desired units
150 * @throws IllegalArgumentException if {@code units < 1}
151 */
152 private static int convertFromDphi(int dphi, int units) {
153 if (units < 1) {
154 throw new IllegalArgumentException(": units is < 1");
155 }
156 int round = units / 2;
157 return (dphi + round) / units;
158 }
159
160 /**
161 * Get this resolution attribute's resolution values in the given units. The
162 * values are rounded to the nearest integer.
163 *
164 * @param units unit conversion factor, e.g. {@link #DPI DPI} or
165 * {@link #DPCM DPCM}
166 * @return a two-element array with the cross feed direction resolution at
167 * index 0 and the feed direction resolution at index 1
168 * @throws IllegalArgumentException if {@code units < 1}
169 */
170 public int[] getResolution(int units) {
171 return new int[] { getCrossFeedResolution(units),
172 getFeedResolution(units)
173 };
174 }
175
176 /**
177 * Returns this resolution attribute's cross feed direction resolution in
178 * the given units. The value is rounded to the nearest integer.
179 *
180 * @param units unit conversion factor, e.g. {@link #DPI DPI} or
181 * {@link #DPCM DPCM}
182 * @return cross feed direction resolution
183 * @throws IllegalArgumentException if {@code units < 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 unit conversion factor, e.g. {@link #DPI DPI} or
194 * {@link #DPCM DPCM}
195 * @return feed direction resolution
196 * @throws IllegalArgumentException if {@code units < 1}
197 */
198 public int getFeedResolution(int units) {
199 return convertFromDphi (feedResolution, units);
200 }
201
202 /**
203 * Returns a string version of this resolution attribute in the given units.
204 * The string takes the form <code>"<i>C</i>x<i>F</i> <i>U</i>"</code>,
205 * where <i>C</i> is the cross feed direction resolution, <i>F</i> is the
206 * feed direction resolution, and <i>U</i> is the units name. The values are
207 * rounded to the nearest integer.
208 *
209 * @param units unit conversion factor, e.g. {@link #DPI CODE>DPI} or
210 * {@link #DPCM DPCM}
211 * @param unitsName units name string, e.g. {@code "dpi"} or
212 * {@code "dpcm"}. If {@code null}, no units name is appended to the
213 * result.
214 * @return string version of this resolution attribute
215 * @throws IllegalArgumentException if {@code units < 1}
216 */
217 public String toString(int units, String unitsName) {
218 StringBuilder result = new StringBuilder();
219 result.append(getCrossFeedResolution (units));
220 result.append('x');
221 result.append(getFeedResolution (units));
222 if (unitsName != null) {
223 result.append (' ');
224 result.append (unitsName);
225 }
226 return result.toString();
227 }
228
229 /**
230 * Determine whether this resolution attribute's value is less than or equal
231 * to the given resolution attribute's value. This is true if all of the
232 * following conditions are true:
233 * <ul>
234 * <li>This attribute's cross feed direction resolution is less than or
235 * equal to the {@code other} attribute's cross feed direction resolution.
236 * <li>This attribute's feed direction resolution is less than or equal to
237 * the {@code other} attribute's feed direction resolution.
238 * </ul>
239 *
240 * @param other resolution attribute to compare with
241 * @return {@code true} if this resolution attribute is less than or equal
242 * to the {@code other} resolution attribute, {@code false}
243 * otherwise
244 * @throws NullPointerException if {@code other} is {@code null}
245 */
246 public boolean lessThanOrEquals(ResolutionSyntax other) {
247 return (this.crossFeedResolution <= other.crossFeedResolution &&
248 this.feedResolution <= other.feedResolution);
249 }
250
251 /**
252 * Returns whether this resolution attribute is equivalent to the passed in
253 * object. To be equivalent, all of the following conditions must be true:
254 * <ol type=1>
255 * <li>{@code object} is not {@code null}.
256 * <li>{@code object} is an instance of class {@code ResolutionSyntax}.
257 * <li>This attribute's cross feed direction resolution is equal to
258 * {@code object}'s cross feed direction resolution.
259 * <li>This attribute's feed direction resolution is equal to
260 * {@code object}'s feed direction resolution.
261 * </ol>
262 *
263 * @param object {@code Object} to compare to
264 * @return {@code true} if {@code object} is equivalent to this resolution
265 * attribute, {@code false} otherwise
266 */
267 public boolean equals(Object object) {
268
269 return(object != null &&
270 object instanceof ResolutionSyntax &&
271 this.crossFeedResolution ==
272 ((ResolutionSyntax) object).crossFeedResolution &&
273 this.feedResolution ==
274 ((ResolutionSyntax) object).feedResolution);
275 }
276
277 /**
278 * Returns a hash code value for this resolution attribute.
279 */
280 public int hashCode() {
281 return(((crossFeedResolution & 0x0000FFFF)) |
282 ((feedResolution & 0x0000FFFF) << 16));
283 }
284
285 /**
286 * Returns a string version of this resolution attribute. The string takes
287 * the form <code>"<i>C</i>x<i>F</i> dphi"</code>, where <i>C</i> is the
288 * cross feed direction resolution and <i>F</i> is the feed direction
289 * resolution. The values are reported in the internal units of dphi.
290 */
291 public String toString() {
292 StringBuilder result = new StringBuilder();
293 result.append(crossFeedResolution);
294 result.append('x');
295 result.append(feedResolution);
296 result.append(" dphi");
297 return result.toString();
298 }
299
300 /**
301 * Returns this resolution attribute's cross feed direction resolution in
302 * units of dphi. (For use in a subclass.)
303 *
304 * @return cross feed direction resolution
305 */
306 protected int getCrossFeedResolutionDphi() {
307 return crossFeedResolution;
308 }
309
310 /**
311 * Returns this resolution attribute's feed direction resolution in units of
312 * dphi. (For use in a subclass.)
313 *
314 * @return feed direction resolution
315 */
316 protected int getFeedResolutionDphi() {
317 return feedResolution;
318 }
319 }