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 Size2DSyntax} is an abstract base class providing the common
32 * implementation of all attributes denoting a size in two dimensions.
33 * <p>
34 * A two-dimensional size attribute's value consists of two items, the {@code X}
35 * dimension and the {@code Y} dimension. A two-dimensional size attribute may
36 * be constructed by supplying the two values and indicating the units in which
37 * the values are measured. Methods are provided to return a two-dimensional
38 * size attribute's values, indicating the units in which the values are to be
39 * returned. The two most common size units are inches (in) and millimeters
40 * (mm), and exported constants {@link #INCH INCH} and {@link #MM MM} are
41 * provided for indicating those units.
42 * <p>
43 * Once constructed, a two-dimensional size attribute's value is immutable.
44 * <p>
45 * <b>Design</b>
46 * <p>
47 * A two-dimensional size attribute's {@code X} and {@code Y} dimension values
48 * are stored internally as integers in units of micrometers (µm), where 1
49 * micrometer = 10<SUP>-6</SUP> meter = 1/1000 millimeter = 1/25400 inch. This
50 * permits dimensions to be represented exactly to a precision of 1/1000 mm (= 1
51 * µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in
52 * negative powers of two, this permits dimensions to be represented exactly to
53 * a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch
54 * does not equal an integral number of µm).
55 * <p>
56 * Storing the dimensions internally in common units of µm lets two size
57 * attributes be compared without regard to the units in which they were
58 * created; for example, 8.5 in will compare equal to 215.9 mm, as they both are
59 * stored as 215900 µm. For example, a lookup service can match resolution
60 * attributes based on equality of their serialized representations regardless
61 * of the units in which they were created. Using integers for internal storage
62 * allows precise equality comparisons to be done, which would not be guaranteed
63 * if an internal floating point representation were used. Note that if you're
64 * looking for {@code U.S. letter} sized media in metric units, you have to
65 * search for a media size of 215.9 x 279.4 mm; rounding off to an integral
66 * 216 x 279 mm will not match.
67 * <p>
68 * The exported constant {@link #INCH INCH} is actually the conversion factor by
69 * which to multiply a value in inches to get the value in µm. Likewise,
70 * the exported constant {@link #MM MM} is the conversion factor by which to
71 * multiply a value in mm to get the value in µm. A client can specify a
72 * resolution value in units other than inches or mm by supplying its own
73 * conversion factor. However, since the internal units of µm was chosen
74 * with supporting only the external units of inch and mm 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 Alan Kaminsky
80 */
81 public abstract class Size2DSyntax implements Serializable, Cloneable {
82
83 /**
84 * Use serialVersionUID from JDK 1.4 for interoperability.
85 */
86 private static final long serialVersionUID = 5584439964938660530L;
87
88 /**
89 * {@code X} dimension in units of micrometers (µm).
90 *
91 * @serial
92 */
93 private int x;
94
95 /**
96 * {@code Y} dimension in units of micrometers (µm).
97 *
98 * @serial
99 */
100 private int y;
101
102 /**
103 * Value to indicate units of inches (in). It is actually the conversion
104 * factor by which to multiply inches to yield µm (25400).
105 */
106 public static final int INCH = 25400;
107
108 /**
109 * Value to indicate units of millimeters (mm). It is actually the
110 * conversion factor by which to multiply mm to yield µm (1000).
111 */
112 public static final int MM = 1000;
113
114 /**
115 * Construct a new two-dimensional size attribute from the given
116 * floating-point values.
117 *
118 * @param x {@code X} dimension
119 * @param y {@code Y} dimension
120 * @param units unit conversion factor, e.g. {@link #INCH INCH} or
121 * {@link #MM MM}
122 * @throws IllegalArgumentException if {@code x < 0} or {@code y < 0} or
123 * {@code units < 1}
124 */
125 protected Size2DSyntax(float x, float y, int units) {
126 if (x < 0.0f) {
127 throw new IllegalArgumentException("x < 0");
128 }
129 if (y < 0.0f) {
130 throw new IllegalArgumentException("y < 0");
131 }
132 if (units < 1) {
133 throw new IllegalArgumentException("units < 1");
134 }
135 this.x = (int) (x * units + 0.5f);
136 this.y = (int) (y * units + 0.5f);
137 }
138
139 /**
140 * Construct a new two-dimensional size attribute from the given integer
141 * values.
142 *
143 * @param x {@code X} dimension
144 * @param y {@code Y} dimension
145 * @param units unit conversion factor, e.g. {@link #INCH INCH} or
146 * {@link #MM MM}
147 * @throws IllegalArgumentException if {@code x < 0} or {@code y < 0} or
148 * {@code units < 1}
149 */
150 protected Size2DSyntax(int x, int y, int units) {
151 if (x < 0) {
152 throw new IllegalArgumentException("x < 0");
153 }
154 if (y < 0) {
155 throw new IllegalArgumentException("y < 0");
156 }
157 if (units < 1) {
158 throw new IllegalArgumentException("units < 1");
159 }
160 this.x = x * units;
161 this.y = y * units;
162 }
163
164 /**
165 * Convert a value from micrometers to some other units. The result is
166 * returned as a floating-point number.
167 *
168 * @param x value (micrometers) to convert
169 * @param units unit conversion factor, e.g. {@link #INCH INCH} or
170 * {@link #MM MM}
171 * @return the value of {@code x} converted to the desired units
172 * @throws IllegalArgumentException if {@code units < 1}
173 */
174 private static float convertFromMicrometers(int x, int units) {
175 if (units < 1) {
176 throw new IllegalArgumentException("units is < 1");
177 }
178 return ((float)x) / ((float)units);
179 }
180
181 /**
182 * Get this two-dimensional size attribute's dimensions in the given units
183 * as floating-point values.
184 *
185 * @param units unit conversion factor, e.g. {@link #INCH INCH} or
186 * {@link #MM MM}
187 * @return a two-element array with the {@code X} dimension at index 0 and
188 * the {@code Y} dimension at index 1
189 * @throws IllegalArgumentException if {@code units < 1}
190 */
191 public float[] getSize(int units) {
192 return new float[] {getX(units), getY(units)};
193 }
194
195 /**
196 * Returns this two-dimensional size attribute's {@code X} dimension in the
197 * given units as a floating-point value.
198 *
199 * @param units unit conversion factor, e.g. {@link #INCH INCH} or
200 * {@link #MM MM}
201 * @return {@code X} dimension
202 * @throws IllegalArgumentException if {@code units < 1}
203 */
204 public float getX(int units) {
205 return convertFromMicrometers(x, units);
206 }
207
208 /**
209 * Returns this two-dimensional size attribute's {@code Y} dimension in the
210 * given units as a floating-point value.
211 *
212 * @param units unit conversion factor, e.g. {@link #INCH INCH} or
213 * {@link #MM MM}
214 * @return {@code Y} dimension
215 * @throws IllegalArgumentException if {@code units < 1}
216 */
217 public float getY(int units) {
218 return convertFromMicrometers(y, units);
219 }
220
221 /**
222 * Returns a string version of this two-dimensional size attribute in the
223 * given units. The string takes the form <code>"<i>X</i>x<i>Y</i>
224 * <i>U</i>"</code>, where <i>X</i> is the {@code X} dimension, <i>Y</i> is
225 * the {@code Y} dimension, and <i>U</i> is the units name. The values are
226 * displayed in floating point.
227 *
228 * @param units unit conversion factor, e.g. {@link #INCH INCH} or
229 * {@link #MM MM}
230 * @param unitsName units name string, e.g. {@code in} or {@code mm}. If
231 * {@code null}, no units name is appended to the result
232 * @return {@code String} version of this two-dimensional size attribute
233 * @throws IllegalArgumentException if {@code units < 1}
234 */
235 public String toString(int units, String unitsName) {
236 StringBuilder result = new StringBuilder();
237 result.append(getX (units));
238 result.append('x');
239 result.append(getY (units));
240 if (unitsName != null) {
241 result.append(' ');
242 result.append(unitsName);
243 }
244 return result.toString();
245 }
246
247 /**
248 * Returns whether this two-dimensional size attribute is equivalent to the
249 * passed in object. To be equivalent, all of the following conditions must
250 * be true:
251 * <ol type=1>
252 * <li>{@code object} is not {@code null}.
253 * <li>{@code object} is an instance of class {@code Size2DSyntax}
254 * <li>This attribute's {@code X} dimension is equal to {@code object}'s
255 * {@code X} dimension.
256 * <li>This attribute's {@code Y} dimension is equal to {@code object}'s
257 * {@code Y} dimension.
258 * </ol>
259 *
260 * @param object {@code Object} to compare to
261 * @return {@code true} if {@code object} is equivalent to this
262 * two-dimensional size attribute, {@code false} otherwise
263 */
264 public boolean equals(Object object) {
265 return(object != null &&
266 object instanceof Size2DSyntax &&
267 this.x == ((Size2DSyntax) object).x &&
268 this.y == ((Size2DSyntax) object).y);
269 }
270
271 /**
272 * Returns a hash code value for this two-dimensional size attribute.
273 */
274 public int hashCode() {
275 return (((x & 0x0000FFFF) ) |
276 ((y & 0x0000FFFF) << 16));
277 }
278
279 /**
280 * Returns a string version of this two-dimensional size attribute. The
281 * string takes the form <code>"<i>X</i>x<i>Y</i> um"</code>, where <i>X</i>
282 * is the {@code X} dimension and <i>Y</i> is the {@code Y} dimension. The
283 * values are reported in the internal units of micrometers.
284 */
285 public String toString() {
286 StringBuilder result = new StringBuilder();
287 result.append(x);
288 result.append('x');
289 result.append(y);
290 result.append(" um");
291 return result.toString();
292 }
293
294 /**
295 * Returns this two-dimensional size attribute's {@code X} dimension in
296 * units of micrometers (µm). (For use in a subclass.)
297 *
298 * @return {@code X} dimension (µm)
299 */
300 protected int getXMicrometers(){
301 return x;
302 }
303
304 /**
305 * Returns this two-dimensional size attribute's {@code Y} dimension in
306 * units of micrometers (µm). (For use in a subclass.)
307 *
308 * @return {@code Y} dimension (µm)
309 */
310 protected int getYMicrometers() {
311 return y;
312 }
313 }