faa.tg.units
Class AMeasure

java.lang.Object
  faa.tg.units.AMeasure

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<AMeasure>

Direct Known Subclasses:

Acceleration, Angle, AngularAcceleration, AngularRate, Area, Capacity, Density, Distance, Force, FuelFlowRate, IndicatedAirspeed, IndicatedAirspeedRate, Mach, MachRate, Mass, MassRate, OneOverTime, Pressure, Speed, Temperature, Time, TrueAirspeedRate, Volume, Weight

public class AMeasure
extends java.lang.Object
implements java.lang.Cloneable, java.lang.Comparable<AMeasure>, java.io.Serializable

 AMeasure is an abstract base class for all measures with associated units.
 Every class derived from AMeasure implements the following public methods.
 Note: SomeMeasure represents the name of the class derived from AMeasure
 and SomeUnits represents the name of a class derived from AUnits.

 SomeMeasure(double theValue, SomeUnits theUnits); // constructor
 void    set(double theValue, SomeUnits theUnits); // initializer

 double as(SomeUnits the Units); // returns a double in the units specified

 add(SomeMeasure itsMeasure); // implements += (uses AMeasure.add(AMeasure)
 sub(SomeMeasure itsMeasure); // implements -= (uses AMeasure.add(AMeasure)
 mul(double itsMultiplier);   // implements *= (derived from AMeasure)
 div(double itsDivisor);      // implements /= (derived from AMeasure)
 equals(SomeMeasure itsMeasure);// implements == 

 The following sample code illustrates how the classes Distance (derived
 from AMeasure) and DistanceUnits (derived from AUnits) could be used:

 // Defining units:

 static class units {
    // define canonical units
   static DistanceUnits meters("meters","m");

   // define derived units (ie. based on canonical units);
   static DistanceUnits km(1000.0,meters,"kilometers","km");
   static DistanceUnits cm(0.01, meters,"centimeters", "cm");
   static DistanceUnits in(2.54,cm,"inches", "in");
   static DistanceUnits ft(12,in,"feet","ft");
   static DistanceUnits nm(6076,ft,"nautical miles", "nm");
   static DistanceUnits mi(5280,ft,"statute miles","mi");
   static DistanceUnits ls(2.9999E8,meters,"light seconds","ls");
 }

 // Using Distance measures:
 ...
 Distance altitude = new Distance(10000.0, units.feet);
 Distance range    = new Distance(60,units.nm);
 Distance halfRange = range.clone(); halfRange.div(2);
 Distance climb    = new Distance(500,units.feet);

 altitude.add(climb); // altitude now equals 10500 feet
 double altitudeInKm = altitude.as(units.km);// 3.2004 km
 double altitudeInMi = altitude.as(units.mi);// 1.9886 mi
 

See section 5.6 of the Detailed Design Document for a discussion of design issues.

See the source: AMeasure.java

Version:

$Id: AMeasure.java,v 3.8 2008/11/24 22:13:10 lykensj Exp $

Author:

Robert G. Oliver, ACT-510

See Also:

AUnits, Distance, Mass, Time, Acceleration, Angle, Time, Volume, Serialized Form

Field Summary

static java.lang.String	CVS_VERSION_ID The CVS Version ID.
static java.text.DecimalFormat	DEC0 Format for a number with no decimal places: "0".
static java.text.DecimalFormat	DEC0_ Format for a number with no decimal places followed by a space: "0 "
static java.text.DecimalFormat	DEC00 Format numbers to: no decimal places and at least two digits.
static java.text.DecimalFormat	DEC000 Format numbers to: no decimal places and at least three digits.
static java.text.DecimalFormat	DEC1 Format for a number with 0 or 1 decimal place: "0.#".
static java.text.DecimalFormat	DEC1_ Format for a number with 0 or 1 decimal place & a final space: "0.# "
static java.text.DecimalFormat	DEC12 Number format for up to 12 decimal places: "0.0###########".
static java.text.DecimalFormat	DEC12_ Number format for up to 12 decimal places & space: "0.0########### ".
static java.text.DecimalFormat	DEC1L Format for a number with 1 decimal place: "0.0".
static java.text.DecimalFormat	DEC1L_ Format for a number with 1 decimal place and a final space: "0.0 ".
static java.text.DecimalFormat	DEC2 Number format for up to 2 decimal places: "0.0#".
static java.text.DecimalFormat	DEC2_ Number format for up to 2 decimal places and a final space: "0.0# "
static java.text.DecimalFormat	DEC3 Number format for up to 3 decimal places: "0.0##".
static java.text.DecimalFormat	DEC3_ Number format for up to 3 decimal places and a final space: "0.0## "
static java.text.DecimalFormat	DEC4 Number format for up to 4 decimal places: "0.0###".
static java.text.DecimalFormat	DEC4_ Number format for up to 4 decimal places and a final space: "0.0### "
static java.text.DecimalFormat	DEC5 Number format for up to 5 decimal places: "0.0####".
static java.text.DecimalFormat	DEC5_ Number format for up to 5 decimal places and a final space: "0.0#### "
static java.text.DecimalFormat	DEC6 Number format for up to 6 decimal places: "0.0#####".
static java.text.DecimalFormat	DEC6_ Number format for up to 6 decimal places and final space: "0.0##### "
static java.text.DecimalFormat	DEC7 Number format for up to 7 decimal places: "0.0######".
static java.text.DecimalFormat	DEC7_ Number format for up to 7 decimal places and final space: "0.0###### "
static java.text.DecimalFormat	DEC9 Number format for up to 9 decimal places: "0.0########".
static java.text.DecimalFormat	DEC9_ Number format for up to 9 decimal places & space: "0.0######## ".
private AUnits	initialUnit The AUnits unit this measure was created with.
protected double	itsValue The value of this measure as a double, in units of some fundamental type.
(package private) static long	serialVersionUID
static java.text.DecimalFormat	TIME_FRACTION Format for a zero-filled number with 2 digits before the decimal and 0-3 decimal places: "00.###" (i.e., seconds with possible millisecs).

Constructor Summary

protected

AMeasure(double theValue, AUnits theUnits) In order to construct any measure both the value and its units must be provided.

Method Summary

protected AMeasure	absoluteValue() This returns a measure to its absolute value.
protected AMeasure	add(AMeasure addend) Returns the sum of this value and the parameter's value.
protected double	as(AUnits theUnits) The as method extracts the value from a Measure in specified units.
double	as(java.lang.String unitName) This should NOT be used to extract the value from an AMeasure when the simulator is running since it can throw a RuntimeException.
AMeasure	clone() The method clones an object.
int	compareTo(AMeasure measure) This method (with an Object param) is needed to implement Comparable: see also eq()/gt()/lt()/ge()/le() methods.
java.lang.String	debug() Provides an easy value-to-text formatter that prints the AMeasure in the Units in which it was created.
AMeasure	div(double theDivisor) This division method divides by a scalar.
protected boolean	eq(AMeasure val) This method provides a test for equality.
boolean	equals(java.lang.Object measure) This overrides the Object equals() to match the compareTo() return value, as per the Comparable requirements; also provides checking to guarantee the unit types match.
protected boolean	ge(AMeasure val) This method provides a test for greater than / equal to.
static AUnits	getAUnit(java.lang.String unitName) This is used to get the AUnit that is specified by the unit string given.
AUnits	getCanonicalUnit() The canonical unit of measure for this AMeasure.
double	getCanonicalValue() The value of this measure in its canonical units.
AUnits	getInitialUnit() The unit this AMeasure was originally created with.
java.lang.Class<? extends AUnits>	getUnitClass() The unit class of this measure.
protected boolean	gt(AMeasure val) This method provides a test for greater than.
int	hashCode() Returns a hash code value for the AMeasure.
boolean	isBetween(AMeasure value1, AMeasure value2) Determines whether or not this value is between the two specified AMeasures (inclusive): the measures do not need to be in order.
protected boolean	le(AMeasure val) This method provides a test for less than / equal to.
protected boolean	lt(AMeasure val) This method provides a test for less than.
AMeasure	mul(double theMultiplier) The multiplication method multiplies by a scalar.
protected double	ratio(AMeasure theMeasure) This division method produces a dimensionless ratio of like measures.
protected AMeasure	sub(AMeasure subtrahend) Returns the difference of this value and the parameter's value.
static AMeasure	toAMeasure(org.w3c.dom.Element elem) Returns a new AMeasure extracted from the Element information.
java.lang.String	toString() Provides a default method of printing the AMeasure with its canonical unit, to seven digits of precision, and adds the unit abbreviation.
java.lang.String	toString(AUnits units) This provides a standardized print format for measurements that will allow a unit of measurement to be specified.
java.lang.String	toString(AUnits units, java.text.DecimalFormat precision) This provides a standardized print method for measurements that will allow a unit of measurement to be specified, where the numerical format to display can be modified for specific needs.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

static final long serialVersionUID

See Also:

Constant Field Values

CVS_VERSION_ID

public static final java.lang.String CVS_VERSION_ID

The CVS Version ID.

See Also:

Constant Field Values

TIME_FRACTION

public static final java.text.DecimalFormat TIME_FRACTION

Format for a zero-filled number with 2 digits before the decimal and 0-3 decimal places: "00.###" (i.e., seconds with possible millisecs).

DEC000

public static final java.text.DecimalFormat DEC000

Format numbers to: no decimal places and at least three digits.

DEC00

public static final java.text.DecimalFormat DEC00

Format numbers to: no decimal places and at least two digits.

DEC0

public static final java.text.DecimalFormat DEC0

Format for a number with no decimal places: "0".

DEC1

public static final java.text.DecimalFormat DEC1

Format for a number with 0 or 1 decimal place: "0.#".

DEC1L

public static final java.text.DecimalFormat DEC1L

Format for a number with 1 decimal place: "0.0".

DEC2

public static final java.text.DecimalFormat DEC2

Number format for up to 2 decimal places: "0.0#".

DEC3

public static final java.text.DecimalFormat DEC3

Number format for up to 3 decimal places: "0.0##".

DEC4

public static final java.text.DecimalFormat DEC4

Number format for up to 4 decimal places: "0.0###".

DEC5

public static final java.text.DecimalFormat DEC5

Number format for up to 5 decimal places: "0.0####".

DEC6

public static final java.text.DecimalFormat DEC6

Number format for up to 6 decimal places: "0.0#####".

DEC7

public static final java.text.DecimalFormat DEC7

Number format for up to 7 decimal places: "0.0######".

DEC9

public static final java.text.DecimalFormat DEC9

Number format for up to 9 decimal places: "0.0########".

DEC12

public static final java.text.DecimalFormat DEC12

Number format for up to 12 decimal places: "0.0###########".

DEC0_

public static final java.text.DecimalFormat DEC0_

Format for a number with no decimal places followed by a space: "0 "

DEC1_

public static final java.text.DecimalFormat DEC1_

Format for a number with 0 or 1 decimal place & a final space: "0.# "

DEC1L_

public static final java.text.DecimalFormat DEC1L_

Format for a number with 1 decimal place and a final space: "0.0 ".

DEC2_

public static final java.text.DecimalFormat DEC2_

Number format for up to 2 decimal places and a final space: "0.0# "

DEC3_

public static final java.text.DecimalFormat DEC3_

Number format for up to 3 decimal places and a final space: "0.0## "

DEC4_

public static final java.text.DecimalFormat DEC4_

Number format for up to 4 decimal places and a final space: "0.0### "

DEC5_

public static final java.text.DecimalFormat DEC5_

Number format for up to 5 decimal places and a final space: "0.0#### "

DEC6_

public static final java.text.DecimalFormat DEC6_

Number format for up to 6 decimal places and final space: "0.0##### "

DEC7_

public static final java.text.DecimalFormat DEC7_

Number format for up to 7 decimal places and final space: "0.0###### "

DEC9_

public static final java.text.DecimalFormat DEC9_

Number format for up to 9 decimal places & space: "0.0######## ".

DEC12_

public static final java.text.DecimalFormat DEC12_

Number format for up to 12 decimal places & space: "0.0########### ".

itsValue

protected double itsValue

The value of this measure as a double, in units of some fundamental type. For example: the fundamental unit of Distance is a meter. DON'T CHANGE THIS IF YOU ARE UNSURE

initialUnit

private AUnits initialUnit

The AUnits unit this measure was created with. If the unit AMeasures are created with is not standardized, this could result in output where the units switch back and forth.

Constructor Detail

AMeasure

protected AMeasure(double theValue,
                   AUnits theUnits)

In order to construct any measure both the value and its units must be provided. Units converts the internal representation to canonical units.

Parameters:

theValue - represents a quantity in some specified units

theUnits - describes the units of the value

Method Detail

toAMeasure

public static AMeasure toAMeasure(org.w3c.dom.Element elem)
                           throws java.lang.IllegalArgumentException,
                                  org.w3c.dom.DOMException

Returns a new AMeasure extracted from the Element information.

Parameters:

elem - AMeasure Element with unit & class attribute and a value.

Returns:

Returns a new AMeasure extracted from the Element information.

Throws:

org.w3c.dom.DOMException - XML construction error.

java.lang.IllegalArgumentException - XML did not correctly specify AMeasure.

compareTo

public int compareTo(AMeasure measure)
              throws java.lang.ClassCastException

This method (with an Object param) is needed to implement Comparable: see also eq()/gt()/lt()/ge()/le() methods. Compares this measure to the given measure. If this measure is lower, returns -1; if equal, returns 0; if this measure is greater, returns 1. This class is not recommended to be used. The eq/gt/lt/ge/le operations are much easier, as well as significantly faster. This method is only included so that AMeasures implement the comparable interface.

Specified by:

compareTo in interface java.lang.Comparable<AMeasure>

Parameters:

measure - The given measure.

Returns:

Returns -1 if <, 0 if =, or 1 if >, the given measure.

Throws:

UnitsMismatchException - If units are not comparable.

java.lang.ClassCastException - If the object is not an AMeasure.

See Also:

isBetween(AMeasure, AMeasure)

equals

public boolean equals(java.lang.Object measure)
               throws java.lang.ClassCastException

This overrides the Object equals() to match the compareTo() return value, as per the Comparable requirements; also provides checking to guarantee the unit types match. Returns whether the measures are equal.

This class is not recommended to be used. The eq/gt/lt/ge/le operations are much easier, as well as significantly faster. This method is only included so that AMeasures implement the comparable interface.

Overrides:

equals in class java.lang.Object

Parameters:

measure - The given measure.

Returns:

Returns boolean indicating whether the measures are equal.

Throws:

UnitsMismatchException - If units are not comparable.

java.lang.ClassCastException - If the object is not an AMeasure.

See Also:

Comparable.compareTo(Object)

hashCode

public int hashCode()

Returns a hash code value for the AMeasure. This method is supported so that AMeasures may be used as keys in hashtables.

Overrides:

hashCode in class java.lang.Object

Returns:

Returns a hash code value for this object.

See Also:

Object.hashCode(), Hashtable

eq

protected boolean eq(AMeasure val)

This method provides a test for equality. It is to be extended by subclasses to test like measures.

Returns:

Returns boolean indicating whether values are equal.

lt

protected boolean lt(AMeasure val)

This method provides a test for less than. It is to be extended by subclasses to test like measures.

Returns:

Returns whether this value is less than the given value.

gt

protected boolean gt(AMeasure val)

This method provides a test for greater than. It is to be extended by subclasses to test like measures.

Returns:

Returns whether this value is greater than the given value.

le

protected boolean le(AMeasure val)

This method provides a test for less than / equal to. It is to be extended by subclasses to test like measures.

Returns:

Returns result of test for less than or equal to.

ge

protected boolean ge(AMeasure val)

This method provides a test for greater than / equal to. It is to be extended by subclasses to test like measures.

Returns:

Returns result of test for greater than or equal to.

absoluteValue

protected AMeasure absoluteValue()

This returns a measure to its absolute value. This is also significantly slower than using the Math.abs() method call after converting a unit to a double via it's .as() method, but sometimes we'll want a new object returned. (Testing revealed this to be up to five times slower.)

Returns:

An AMeasure with a value equal to the absolute value of this.

ratio

protected double ratio(AMeasure theMeasure)

This division method produces a dimensionless ratio of like measures.

Parameters:

theMeasure - The measure to divide by.

Returns:

The (dimensionless) ratio of the two measures.

add

protected AMeasure add(AMeasure addend)

Returns the sum of this value and the parameter's value.

Parameters:

addend - The unit of measure to add to this measure.

Returns:

A new AMeasure equal to this value plus the parameter value.

sub

protected AMeasure sub(AMeasure subtrahend)

Returns the difference of this value and the parameter's value. This subtraction method subtracts a value with like units. This method is to be extended by subclasses to sub like measures.

Parameters:

subtrahend - The unit of measure to subtract from this measure.

Returns:

A new AMeasure equal to this value minus the parameter value.

isBetween

public boolean isBetween(AMeasure value1,
                         AMeasure value2)

Determines whether or not this value is between the two specified AMeasures (inclusive): the measures do not need to be in order. This method is overridden for Angles.

Parameters:

value1 - One of the two boundary measures.

value2 - The other of the two boundary measures.

Returns:

True if this value is between the other two, false otherwise.

Throws:

UnitsMismatchException - If units are not comparable.

getCanonicalValue

public double getCanonicalValue()

The value of this measure in its canonical units.

Returns:

The value of this measure in its canonical units.

getCanonicalUnit

public AUnits getCanonicalUnit()

The canonical unit of measure for this AMeasure.

Returns:

The canonical unit for this AMeasure.

getInitialUnit

public AUnits getInitialUnit()

The unit this AMeasure was originally created with.

Returns:

The unit of measure this AMeasure was initially created with.

getUnitClass

public java.lang.Class<? extends AUnits> getUnitClass()

The unit class of this measure. For example: if you called d.getUnitClass where d is an object of type Distance you would get the DistanceUnits Class, since Distance objects are measured in DistanceUnits.

Returns:

The measure's unit Class.

mul

public AMeasure mul(double theMultiplier)

The multiplication method multiplies by a scalar. Need not be overridden! This will return an AMeasure that should be cast as needed.

Parameters:

theMultiplier - The value to multiply the AMeasure by.

Returns:

A new AMeasure with a value that is multiplied by the parameter.

div

public AMeasure div(double theDivisor)

This division method divides by a scalar. Need not be overridden! This will return an AMeasure that should be cast as needed.

Parameters:

theDivisor - The value to divide the AMeasure by.

Returns:

A new AMeasure with a value that is divided by the parameter.

as

protected double as(AUnits theUnits)

The as method extracts the value from a Measure in specified units. Override for type safety!

Parameters:

theUnits - the units of the value that will be returned (ex: km)

Returns:

the value of the measure in specified units

as

public double as(java.lang.String unitName)
          throws java.lang.IllegalArgumentException

This should NOT be used to extract the value from an AMeasure when the simulator is running since it can throw a RuntimeException. Returns the value of the measure in units specified, using the String parameter as the name of the field in the Units class to extract the AUnits type.

Parameters:

unitName - The name of the units to return the value as (ex: "km").

Returns:

the value of the measure in specified units

Throws:

java.lang.IllegalArgumentException - If unit string was invalid.

getAUnit

public static AUnits getAUnit(java.lang.String unitName)
                       throws java.lang.IllegalArgumentException

This is used to get the AUnit that is specified by the unit string given.

Parameters:

unitName - String name of the unit desired.

Returns:

aUnit Returns the AUnits that corresponds to the string given.

Throws:

java.lang.IllegalArgumentException - If is no unitName field in Units.class.

clone

public AMeasure clone()

The method clones an object.

Overrides:

clone in class java.lang.Object

Returns:

the cloned object

debug

public java.lang.String debug()

Provides an easy value-to-text formatter that prints the AMeasure in the Units in which it was created. The output has 3 decimal digits of precision, and adds the unit abbreviation.

Returns:

A String representing the measure in the unit created with.

toString

public java.lang.String toString()

Provides a default method of printing the AMeasure with its canonical unit, to seven digits of precision, and adds the unit abbreviation.

Overrides:

toString in class java.lang.Object

Returns:

A String representing the measure in the canonical unit.

toString

public java.lang.String toString(AUnits units)

This provides a standardized print format for measurements that will allow a unit of measurement to be specified.

Returns the String representation of this object as the specified unit in the format "value unitAbbr"; for example: "233.31 ft". For a number format other than 2 decimal places, use toString(AUnits, DecimalFormat).

The unit definitions can be found in Units.java.

If the as() method was properly overridden, the method will throw a UnitsMismatchException for units that do not match this measurement.

See Also:

Units, toString(AUnits, DecimalFormat)

toString

public java.lang.String toString(AUnits units,
                                 java.text.DecimalFormat precision)

This provides a standardized print method for measurements that will allow a unit of measurement to be specified, where the numerical format to display can be modified for specific needs.

Returns the String representation of this object as the specified unit in the format "value unitAbbr" using the DecimalFormat given; for example: "233.333 ft". No space is put between the value and the unit unless the DecimalFormat contains one.

The unit definitions can be found in Units.java.

The method will throw a UnitsMismatchException for units that do not match the units for this measurement.

See Also:

Units, DEC0, DEC1, DEC2, DEC3, DEC4, DEC5, DEC6, DEC7, DEC0_, DEC1_, DEC2_, DEC3_, DEC4_, DEC5_, DEC6_, DEC7_