javax.print.attribute: abstract public class: Size2DSyntax

javax.print.attribute
abstract public class: Size2DSyntax [javadoc | source]

java.lang.Object
   javax.print.attribute.Size2DSyntax

All Implemented Interfaces:
Cloneable, Serializable

Direct Known Subclasses:
MediaSize

Class Size2DSyntax is an abstract base class providing the common implementation of all attributes denoting a size in two dimensions.

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 INCH and MM are provided for indicating those units.

Once constructed, a two-dimensional size attribute's value is immutable.

Design

A two-dimensional 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.

author: Alan - Kaminsky

Field Summary
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).
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).

Constructor:

Constructor:
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 floating-point values. Parameters: `x` - X dimension. `y` - Y dimension. `units` - Unit conversion factor, e.g. `INCH` or `MM` . Throws: `IllegalArgumentException` - (Unchecked exception) Thrown if `x` < 0 or `y` < 0 or `units` < 1. exception: `IllegalArgumentException` - (Unchecked exception) Thrown if `x` < 0 or `y` < 0 or `units` < 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; } Construct a new two-dimensional size attribute from the given integer values. Parameters: `x` - X dimension. `y` - Y dimension. `units` - Unit conversion factor, e.g. `INCH` or `MM` . Throws: `IllegalArgumentException` - (Unchecked exception) Thrown if `x` < 0 or `y` < 0 or `units` < 1. exception: `IllegalArgumentException` - (Unchecked exception) Thrown if `x` < 0 or `y` < 0 or `units` < 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 floating-point values.

Parameters:

x - X dimension.

y - Y dimension.

units - Unit conversion factor, e.g. INCH or MM .

Throws:

IllegalArgumentException - (Unchecked exception) Thrown if x < 0 or y < 0 or units < 1.

exception: IllegalArgumentException - (Unchecked exception) Thrown if x < 0 or y < 0 or units < 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;
}

Construct a new two-dimensional size attribute from the given integer values.

Parameters:

x - X dimension.

y - Y dimension.

units - Unit conversion factor, e.g. INCH or MM .

Throws:

IllegalArgumentException - (Unchecked exception) Thrown if x < 0 or y < 0 or units < 1.

exception: IllegalArgumentException - (Unchecked exception) Thrown if x < 0 or y < 0 or units < 1.

Method from javax.print.attribute.Size2DSyntax Summary:
equals, getSize, getX, getXMicrometers, getY, getYMicrometers, hashCode, toString, toString

Methods from java.lang.Object:
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from javax.print.attribute.Size2DSyntax Detail:
public boolean equals(Object object) { return(object != null && object instanceof Size2DSyntax && this.x == ((Size2DSyntax) object).x && this.y == ((Size2DSyntax) object).y); } 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: `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.
public float[] getSize(int units) { return new float[] {getX(units), getY(units)}; } Get this two-dimensional size attribute's dimensions in the given units as floating-point values.
public float getX(int units) { return convertFromMicrometers(x, units); } Returns this two-dimensional size attribute's X dimension in the given units as a floating-point value.
protected int getXMicrometers() { return x; } Returns this two-dimensional size attribute's X dimension in units of micrometers (µm). (For use in a subclass.)
public float getY(int units) { return convertFromMicrometers(y, units); } Returns this two-dimensional size attribute's Y dimension in the given units as a floating-point value.
protected int getYMicrometers() { return y; } Returns this two-dimensional size attribute's Y dimension in units of micrometers (µm). (For use in a subclass.)
public int hashCode() { return (((x & 0x0000FFFF) ) \| ((y & 0x0000FFFF) < < 16)); } Returns a hash code value for this two-dimensional size attribute.
public String toString() { StringBuffer result = new StringBuffer(); result.append(x); result.append('x"); result.append(y); result.append(" um"); return result.toString(); } Returns a string version of this two-dimensional 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.
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 a string version of this two-dimensional 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.

Method from javax.print.attribute.Size2DSyntax Detail:

 public boolean equals(Object object) {
        return(object != null &&
               object instanceof Size2DSyntax &&
               this.x == ((Size2DSyntax) object).x &&
               this.y == ((Size2DSyntax) object).y);
}

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.

 public float[] getSize(int units) {
        return new float[] {getX(units), getY(units)};
}

Get this two-dimensional size attribute's dimensions in the given units as floating-point values.

 public float getX(int units) {
        return convertFromMicrometers(x, units);
}

Returns this two-dimensional size attribute's X dimension in the given units as a floating-point value.

 protected int getXMicrometers() {
        return x;
}

Returns this two-dimensional size attribute's X dimension in units of micrometers (µm). (For use in a subclass.)

 public float getY(int units) {
        return convertFromMicrometers(y, units);
}

Returns this two-dimensional size attribute's Y dimension in the given units as a floating-point value.

 protected int getYMicrometers() {
        return y;
}

Returns this two-dimensional size attribute's Y dimension in units of micrometers (µm). (For use in a subclass.)

 public int hashCode() {
        return (((x & 0x0000FFFF)      ) |
                ((y & 0x0000FFFF) < <  16));
}

Returns a hash code value for this two-dimensional size attribute.

 public String toString() {
        StringBuffer result = new StringBuffer();
        result.append(x);
        result.append('x");
        result.append(y);
        result.append(" um");
        return result.toString();
}

"XxY um"

 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();
}

"XxY
U"