 java.lang.Object

 javax.print.attribute.Size2DSyntax

 All Implemented Interfaces:
Serializable
,Cloneable
 Direct Known Subclasses:
MediaSize
public abstract class Size2DSyntax extends Object implements Serializable, Cloneable
Class 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
andMM
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 constantMM
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


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
All Methods Instance Methods Concrete Methods 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's X dimension in the given units as a floatingpoint value.protected int
getXMicrometers()
Returns this twodimensional size attribute's X dimension in units of micrometers (µm).float
getY(int units)
Returns this twodimensional size attribute's Y dimension in the given units as a floatingpoint value.protected int
getYMicrometers()
Returns this twodimensional size attribute's Y 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 Detail

INCH
public static final int INCH
Value 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 MM
Value 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 Detail

Size2DSyntax
protected Size2DSyntax(float x, float y, int units)
Construct a new twodimensional size attribute from the given floatingpoint values. Parameters:
x
 X dimension.y
 Y dimension.units
 Unit conversion factor, e.g.INCH
orMM
. Throws:
IllegalArgumentException
 (Unchecked exception) Thrown 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 dimension.y
 Y dimension.units
 Unit conversion factor, e.g.INCH
orMM
. Throws:
IllegalArgumentException
 (Unchecked exception) Thrown ifx < 0
ory < 0
orunits < 1
.


Method Detail

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 the Y dimension at index 1.
 Throws:
IllegalArgumentException
 (unchecked exception) Thrown ifunits < 1
.

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

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

toString
public String toString(int units, String unitsName)
Returns a string version of this twodimensional size attribute in the given units. The string takes the form"XxY U"
, where X is the X dimension, Y is the Y 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
. If null, no units name is appended to the result. Returns:
 String version of this twodimensional size attribute.
 Throws:
IllegalArgumentException
 (unchecked exception) Thrown ifunits < 1
.

equals
public boolean equals(Object object)
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 not null. 
object
is an instance of class Size2DSyntax. 
This attribute's X dimension is equal to
object
's X dimension. 
This attribute's Y dimension is equal to
object
's Y dimension.
 Overrides:
equals
in classObject
 Parameters:
object
 Object to compare to. Returns:
 True if
object
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
public String toString()
Returns a string version of this twodimensional size attribute. The string takes the form"XxY um"
, where X is the X dimension and Y is the Y dimension. The values are reported in the internal units of micrometers.

getXMicrometers
protected int getXMicrometers()
Returns this twodimensional size attribute's X dimension in units of micrometers (µm). (For use in a subclass.) Returns:
 X dimension (µm).

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

