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