 All Implemented Interfaces:
Serializable
,Cloneable
 Direct Known Subclasses:
MediaSize
public abstract class Size2DSyntax extends Object implements Serializable, Cloneable
Size2DSyntax
is an abstract base class providing the common
implementation of all attributes denoting a size in two dimensions.
A twodimensional size attribute's value consists of two items, the X
dimension and the Y
dimension. A twodimensional 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 twodimensional
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 INCH
and MM
are
provided for indicating those units.
Once constructed, a twodimensional size attribute's value is immutable.
Design
A twodimensional size attribute's X
and Y
dimension values
are stored internally as integers in units of micrometers (µm), where 1
micrometer = 10^{6} meter = 1/1000 millimeter = 1/25400 inch. This
permits dimensions to be represented exactly to a precision of 1/1000 mm (= 1
µm) or 1/100 inch (= 254 µ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 µm) but not 1/16 inch (because 1/16 inch
does not equal an integral number of µm).
Storing the dimensions internally in common units of µ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 µ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.
The exported constant INCH
is actually the conversion factor by
which to multiply a value in inches to get the value in µm. Likewise,
the exported constant MM
is the conversion factor by which to
multiply a value in mm to get the value in µ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 µ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.
 See Also:
 Serialized Form

Field Summary

Constructor Summary
Constructors Modifier Constructor Description protected
Size2DSyntax(float x, float y, int units)
Construct a new twodimensional size attribute from the given floatingpoint values.protected
Size2DSyntax(int x, int y, int units)
Construct a new twodimensional size attribute from the given integer values. 
Method Summary
Modifier and Type Method Description boolean
equals(Object object)
Returns whether this twodimensional size attribute is equivalent to the passed in object.float[]
getSize(int units)
Get this twodimensional size attribute's dimensions in the given units as floatingpoint values.float
getX(int units)
Returns this twodimensional size attribute'sX
dimension in the given units as a floatingpoint value.protected int
getXMicrometers()
Returns this twodimensional size attribute'sX
dimension in units of micrometers (µm).float
getY(int units)
Returns this twodimensional size attribute'sY
dimension in the given units as a floatingpoint value.protected int
getYMicrometers()
Returns this twodimensional size attribute'sY
dimension in units of micrometers (µm).int
hashCode()
Returns a hash code value for this twodimensional size attribute.String
toString()
Returns a string version of this twodimensional size attribute.String
toString(int units, String unitsName)
Returns a string version of this twodimensional size attribute in the given units.

Field Details

INCH
public static final int INCHValue to indicate units of inches (in). It is actually the conversion factor by which to multiply inches to yield µm (25400). See Also:
 Constant Field Values

MM
public static final int MMValue to indicate units of millimeters (mm). It is actually the conversion factor by which to multiply mm to yield µm (1000). See Also:
 Constant Field Values


Constructor Details

Size2DSyntax
protected Size2DSyntax(float x, float y, int units)Construct a new twodimensional size attribute from the given floatingpoint values. Parameters:
x
X
dimensiony
Y
dimensionunits
 unit conversion factor, e.g.INCH
orMM
 Throws:
IllegalArgumentException
 ifx < 0
ory < 0
orunits < 1

Size2DSyntax
protected Size2DSyntax(int x, int y, int units)Construct a new twodimensional size attribute from the given integer values. Parameters:
x
X
dimensiony
Y
dimensionunits
 unit conversion factor, e.g.INCH
orMM
 Throws:
IllegalArgumentException
 ifx < 0
ory < 0
orunits < 1


Method Details

getSize
public float[] getSize(int units)Get this twodimensional size attribute's dimensions in the given units as floatingpoint values. Parameters:
units
 unit conversion factor, e.g.INCH
orMM
 Returns:
 a twoelement array with the
X
dimension at index 0 and theY
dimension at index 1  Throws:
IllegalArgumentException
 ifunits < 1

getX
public float getX(int units)Returns this twodimensional size attribute'sX
dimension in the given units as a floatingpoint value. Parameters:
units
 unit conversion factor, e.g.INCH
orMM
 Returns:
X
dimension Throws:
IllegalArgumentException
 ifunits < 1

getY
public float getY(int units)Returns this twodimensional size attribute'sY
dimension in the given units as a floatingpoint value. Parameters:
units
 unit conversion factor, e.g.INCH
orMM
 Returns:
Y
dimension Throws:
IllegalArgumentException
 ifunits < 1

toString
Returns a string version of this twodimensional size attribute in the given units. The string takes the form"XxY U"
, where X is theX
dimension, Y is theY
dimension, and U is the units name. The values are displayed in floating point. Parameters:
units
 unit conversion factor, e.g.INCH
orMM
unitsName
 units name string, e.g.in
ormm
. Ifnull
, no units name is appended to the result Returns:
String
version of this twodimensional size attribute Throws:
IllegalArgumentException
 ifunits < 1

equals
Returns whether this twodimensional size attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:object
is notnull
.object
is an instance of classSize2DSyntax
 This attribute's
X
dimension is equal toobject
'sX
dimension.  This attribute's
Y
dimension is equal toobject
'sY
dimension.
 Overrides:
equals
in classObject
 Parameters:
object
Object
to compare to Returns:
true
ifobject
is equivalent to this twodimensional size attribute,false
otherwise See Also:
Object.hashCode()
,HashMap

hashCode
public int hashCode()Returns a hash code value for this twodimensional size attribute. Overrides:
hashCode
in classObject
 Returns:
 a hash code value for this object.
 See Also:
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)

toString
Returns a string version of this twodimensional size attribute. The string takes the form"XxY um"
, where X is theX
dimension and Y is theY
dimension. The values are reported in the internal units of micrometers. 
getXMicrometers
protected int getXMicrometers()Returns this twodimensional size attribute'sX
dimension in units of micrometers (µm). (For use in a subclass.) Returns:
X
dimension (µm)

getYMicrometers
protected int getYMicrometers()Returns this twodimensional size attribute'sY
dimension in units of micrometers (µm). (For use in a subclass.) Returns:
Y
dimension (µm)
