Size2DSyntax


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