API Overview API Index Package Overview Direct link to this page
JDK 1.6
  javax.print.attribute. Size2DSyntax View Javadoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328

/*
 * @(#)Size2DSyntax.java	1.6 05/11/17
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */


package javax.print.attribute;

import java.io.Serializable;

/**
 * Class Size2DSyntax is an abstract base class providing the common 
 * implementation of all attributes denoting a size in two dimensions. 
 * <P>
 * A two-dimensional size attribute's value consists of two items, the X 
 * dimension and the Y dimension. A two-dimensional size attribute may be 
 * constructed by supplying the two values and indicating the units in which the 
 * values are measured. Methods are provided to return a two-dimensional size 
 * attribute's values, indicating the units in which the values are to be 
 * returned. The two most common size units are inches (in) and millimeters 
 * (mm), and exported constants {@link #INCH <CODE>INCH</CODE>} and {@link #MM 
 * <CODE>MM</CODE>} are provided for indicating those units. 
 * <P>
 * Once constructed, a two-dimensional size attribute's value is immutable. 
 * <P>
 * <B>Design</B>
 * <P>
 * A two-dimensional size attribute's X and Y dimension values are stored 
 * internally as integers in units of micrometers (&#181;m), where 1 micrometer 
 * = 10<SUP>-6</SUP> meter = 1/1000 millimeter = 1/25400 inch. This permits 
 * dimensions to be represented exactly to a precision of 1/1000 mm (= 1 
 * &#181;m) or 1/100 inch (= 254 &#181;m). If fractional inches are expressed in 
 * negative powers of two, this permits dimensions to be represented exactly to 
 * a precision of 1/8 inch (= 3175 &#181;m) but not 1/16 inch (because 1/16 inch 
 * does not equal an integral number of &#181;m). 
 * <P>
 * Storing the dimensions internally in common units of &#181;m lets two size 
 * attributes be compared without regard to the units in which they were 
 * created; for example, 8.5 in will compare equal to 215.9 mm, as they both are 
 * stored as 215900 &#181;m. For example, a lookup service can 
 * match resolution attributes based on equality of their serialized 
 * representations regardless of the units in which they were created. Using 
 * integers for internal storage allows precise equality comparisons to be done, 
 * which would not be guaranteed if an internal floating point representation 
 * were used. Note that if you're looking for U.S. letter sized media in metric 
 * units, you have to search for a media size of 215.9 x 279.4 mm; rounding off 
 * to an integral 216 x 279 mm will not match. 
 * <P>
 * The exported constant {@link #INCH <CODE>INCH</CODE>} is actually the 
 * conversion factor by which to multiply a value in inches to get the value in 
 * &#181;m. Likewise, the exported constant {@link #MM <CODE>MM</CODE>} is the 
 * conversion factor by which to multiply a value in mm to get the value in 
 * &#181;m. A client can specify a resolution value in units other than inches 
 * or mm by supplying its own conversion factor. However, since the internal 
 * units of &#181;m was chosen with supporting only the external units of inch 
 * and mm in mind, there is no guarantee that the conversion factor for the 
 * client's units will be an exact integer. If the conversion factor isn't an 
 * exact integer, resolution values in the client's units won't be stored 
 * precisely. 
 * <P>
 *
 * @author  Alan Kaminsky
 */
public abstract class Size2DSyntax implements Serializable, Cloneable {

    private static final long serialVersionUID = 5584439964938660530L;

    /**
     * X dimension in units of micrometers (&#181;m).
     * @serial
     */
    private int x;

    /**
     * Y dimension in units of micrometers (&#181;m).
     * @serial
     */
    private int y;

    /**
     * Value to indicate units of inches (in). It is actually the conversion 
     * factor by which to multiply inches to yield &#181;m (25400). 
     */
    public static final int INCH = 25400;

    /**
     * Value to indicate units of millimeters (mm). It is actually the 
     * conversion factor by which to multiply mm to yield &#181;m (1000). 
     */
    public static final int MM = 1000;


    /**
     * Construct a new two-dimensional size attribute from the given 
     * floating-point values. 
     *
     * @param  x  X dimension.
     * @param  y  Y dimension.
     * @param  units
     *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or 
     *     {@link #MM <CODE>MM</CODE>}. 
     *
     * @exception  IllegalArgumentException
     *     (Unchecked exception) Thrown if <CODE>x</CODE> < 0 or <CODE>y</CODE> 
     *     < 0 or <CODE>units</CODE> < 1. 
     */
    protected Size2DSyntax(float x, float y, int units) {
	if (x < 0.0f) {
	    throw new IllegalArgumentException("x < 0");
	}
	if (y < 0.0f) {
	    throw new IllegalArgumentException("y < 0");
	}
	if (units < 1) {
	    throw new IllegalArgumentException("units < 1");
	}
	this.x = (int) (x * units + 0.5f);
	this.y = (int) (y * units + 0.5f);
    }

    /**
     * Construct a new two-dimensional size attribute from the given integer 
     * values. 
     *
     * @param  x  X dimension.
     * @param  y  Y dimension.
     * @param  units
     *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or 
     *     {@link #MM <CODE>MM</CODE>}. 
     *
     * @exception  IllegalArgumentException
     *   (Unchecked exception) Thrown if <CODE>x</CODE> < 0 or <CODE>y</CODE> 
     *    < 0 or <CODE>units</CODE> < 1. 
     */
    protected Size2DSyntax(int x, int y, int units) {
	if (x < 0) {
	    throw new IllegalArgumentException("x < 0");
	}
	if (y < 0) {
	    throw new IllegalArgumentException("y < 0");
	}
	if (units < 1) {
	    throw new IllegalArgumentException("units < 1");
	}
	this.x = x * units;
	this.y = y * units;
    }

    /**
     * Convert a value from micrometers to some other units. The result is 
     * returned as a floating-point number. 
     *
     * @param  x
     *     Value (micrometers) to convert.
     * @param  units
     *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or 
     *     {@link #MM <CODE>MM</CODE>}. 
     *
     * @return  The value of <CODE>x</CODE> converted to the desired units.
     *
     * @exception  IllegalArgumentException
     *     (unchecked exception) Thrown if <CODE>units</CODE> < 1. 
     */
    private static float convertFromMicrometers(int x, int units) {
	if (units < 1) {
	    throw new IllegalArgumentException("units is < 1");
	}
	return ((float)x) / ((float)units);
    }

    /**
     * Get this two-dimensional size attribute's dimensions in the given units 
     * as floating-point values. 
     *
     * @param  units
     *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or 
     *     {@link #MM <CODE>MM</CODE>}. 
     *
     * @return  A two-element array with the X dimension at index 0 and the Y
     *          dimension at index 1. 
     *
     * @exception  IllegalArgumentException
     *     (unchecked exception) Thrown if <CODE>units</CODE> < 1. 
     */
    public float[] getSize(int units) {
	return new float[] {getX(units), getY(units)};
    }

    /**
     * Returns this two-dimensional size attribute's X dimension in the given 
     * units as a floating-point value. 
     *
     * @param  units
     *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or 
     *     {@link #MM <CODE>MM</CODE>}.
     *
     * @return  X dimension. 
     *
     * @exception  IllegalArgumentException
     *     (unchecked exception) Thrown if <CODE>units</CODE> < 1. 
     */
    public float getX(int units) {
	return convertFromMicrometers(x, units);
    }

    /**
     * Returns this two-dimensional size attribute's Y dimension in the given 
     * units as a floating-point value. 
     *
     * @param  units
     *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or 
     *     {@link #MM <CODE>MM</CODE>}. 
     *
     * @return  Y dimension. 
     *
     * @exception  IllegalArgumentException
     *     (unchecked exception) Thrown if <CODE>units</CODE> < 1. 
     */
    public float getY(int units) {
	return convertFromMicrometers(y, units);
    }

    /**
     * Returns a string version of this two-dimensional size attribute in the 
     * given units. The string takes the form <CODE>"<I>X</I>x<I>Y</I> 
     * <I>U</I>"</CODE>, where <I>X</I> is the X dimension, <I>Y</I> is the Y 
     * dimension, and <I>U</I> is the units name. The values are displayed in 
     * floating point. 
     *
     * @param  units
     *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or 
     *     {@link #MM <CODE>MM</CODE>}. 
     * @param  unitsName
     *     Units name string, e.g. <CODE>"in"</CODE> or <CODE>"mm"</CODE>. If 
     *     null, no units name is appended to the result. 
     *
     * @return  String version of this two-dimensional size attribute.
     *
     * @exception  IllegalArgumentException
     *     (unchecked exception) Thrown if <CODE>units</CODE> < 1. 
     */
    public String toString(int units, String unitsName) {
	StringBuffer result = new StringBuffer();
	result.append(getX (units));
	result.append('x');
	result.append(getY (units));
	if (unitsName != null) {
	    result.append(' ');
	    result.append(unitsName);
	}
	return result.toString();
    }

    /**
     * Returns whether this two-dimensional size attribute is equivalent to the 
     * passed in object. To be equivalent, all of the following conditions must 
     * be true: 
     * <OL TYPE=1>
     * <LI>
     * <CODE>object</CODE> is not null.
     * <LI>
     * <CODE>object</CODE> is an instance of class Size2DSyntax.
     * <LI>
     * This attribute's X dimension is equal to <CODE>object</CODE>'s X 
     * dimension. 
     * <LI>
     * This attribute's Y dimension is equal to <CODE>object</CODE>'s Y 
     * dimension. 
     * </OL>
     *
     * @param  object  Object to compare to.
     *
     * @return  True if <CODE>object</CODE> is equivalent to this
     *          two-dimensional size attribute, false otherwise. 
     */
    public boolean equals(Object object) {
	return(object != null &&
	       object instanceof Size2DSyntax &&
	       this.x == ((Size2DSyntax) object).x &&
	       this.y == ((Size2DSyntax) object).y);
    }

    /**
     * Returns a hash code value for this two-dimensional size attribute.
     */
    public int hashCode() {
	return (((x & 0x0000FFFF)      ) |
		((y & 0x0000FFFF) << 16));
    }

    /**
     * Returns a string version of this two-dimensional size attribute. The 
     * string takes the form <CODE>"<I>X</I>x<I>Y</I> um"</CODE>, where
     * <I>X</I> is the X dimension and <I>Y</I> is the Y dimension.
     * The values are reported in the internal units of micrometers. 
     */
    public String toString() {
	StringBuffer result = new StringBuffer();
	result.append(x);
	result.append('x');
	result.append(y);
	result.append(" um");
	return result.toString();
    }

    /**
     * Returns this two-dimensional size attribute's X dimension in units of 
     * micrometers (&#181;m). (For use in a subclass.)
     *
     * @return  X dimension (&#181;m).
     */
    protected int getXMicrometers(){
	return x;
    }
    
    /**
     * Returns this two-dimensional size attribute's Y dimension in units of 
     * micrometers (&#181;m). (For use in a subclass.)
     *
     * @return  Y dimension (&#181;m).
     */
    protected int getYMicrometers() {
	return y;
    }

}

Generated By: JavaOnTracks Doclet 0.1.4     ©Thibaut Colar