Package org.openjdk.jmc.common.unit

Class LinearKindOfQuantity

java.lang.Object

org.openjdk.jmc.common.unit.ContentType<IQuantity>

org.openjdk.jmc.common.unit.KindOfQuantity<LinearUnit>

org.openjdk.jmc.common.unit.LinearKindOfQuantity

All Implemented Interfaces:

IDescribable, IType<IQuantity>, IConstraint<IQuantity>, IPersister<IQuantity>

public class LinearKindOfQuantity
extends KindOfQuantity<LinearUnit>

The kind of a linear (scalar) physical quantity. Closely related to the dimension of a quantity, but we separate them further to be able to use units specific to certain kinds of quantities. In particular, Hertz for (clock) frequency. We are mainly interested in the commensurability of quantities, to display them in the same graph. So when the dimension suffices we do not need to introduce additional kinds of quantities. (Although we should strive to follow VIM.)

Each kind of quantity has a single "atom unit" which may be used with prefixes. Where applicable, this unit is the SI base unit with any prefix stripped (that is, "kg" is the base unit, but the atom unit is "g"). According to BIPM/VIM above, units that are not formed by a prefix and the atom unit may be permitted, but are treated as off-system units. This means that they cannot have prefixes. (Also, SI only permits a specified set of off-system units to be used with SI, in order to avoid ambiguity. For instance, since there's a unit "Pa", for Pascal, and prefixes "P" for Peta and "E" for Exa, no in-system unit may be designated by "a", and no off-system unit may be designated with "EPa".) To avoid future problems, where we might persist a unit without content type, we should stick to this.

Note that there's a relevant specification for representing units, SI as well as conventional, without ambiguity, in ASCII, with or without case sensitivity, see UCUM. We should strive for "limited conformance" with this specification. That is, it will hardly be worth the trouble of parsing every possible UCUM expression. (There's an Eclipse project for that, UOMo, but it has too much dependencies.) But what we produce when persisting quantities and units should be valid UCUM expressions. That will allow us to export data into a standardized format. And also to switch to a full UCUM implementation, should a suitable one become available.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	LinearKindOfQuantity.AutoFormatter
static class	LinearKindOfQuantity.DualUnitFormatter
static interface	LinearKindOfQuantity.LinearUnitSelector

Nested classes/interfaces inherited from class org.openjdk.jmc.common.unit.KindOfQuantity

KindOfQuantity.ExactFormatter<U extends TypedUnit<U>>, KindOfQuantity.VerboseFormatter<U extends TypedUnit<U>>

Field Summary

Fields

Modifier and Type	Field	Description
protected final Collection<LinearUnit>	allUnits
protected final LinearUnit	atomUnit
protected final String	atomUnitName
protected final Collection<LinearUnit>	commonUnits
protected final Map<String,LinearUnit>	interactiveSymbolToUnitMap
protected final Map<Object,LinearUnit>	unitCache
protected LinearKindOfQuantity.LinearUnitSelector	unitSelector

Fields inherited from class org.openjdk.jmc.common.unit.ContentType

m_identifier

Constructor Summary

Constructors

Constructor	Description
LinearKindOfQuantity(String id, String atomUnitId)	Create a new linear kind of quantity, with content type identifier id and sole unit identifier atomUnitId.
LinearKindOfQuantity(String id, String atomUnitId, P minPrefix, P maxPrefix)	Create a new linear kind of quantity, with content type identifier id and atom unit identifier atomUnitId, using prefixes in the range minPrefix to maxPrefix.

Method Summary

Modifier and Type	Method	Description
protected void	addUnit(LinearUnit unit)	Add a common unit (displayed to the user when selecting a unit).
protected void	addUnit(LinearUnit unit, boolean common)	Add a unit so that it is available for parsing and content assist, optionally also for direct selection by users.
Collection<LinearUnit>	getAllUnits()
protected ScaleFactor	getBestScaleFactorFor(long value)
LinearUnit	getCachedUnit(Object key)
Collection<LinearUnit>	getCommonUnits()
LinearUnit	getDefaultUnit()
KindOfQuantity<LinearUnit>	getDeltaKind()
IFormatter<IQuantity>	getFormatterResolving(IRange<IQuantity> range)	Get a formatter with sufficient resolution to produce unique strings for both ends of range, and consecutive equally spaced quantities.
LinearUnit	getLargestExactUnit(IQuantity quantity)	Get the largest unit, if any, in which this quantity can be expressed exactly, typically with an integer.
static NumberFormat	getNumberFormat(boolean interactive)	Get a thread local configured NumberFormat suitable for display or interactive formatting, or interactive parsing.
LinearUnit	getPreferredUnit(IQuantity quantity, double minNumericalValue, double maxNumericalValue)
LinearUnit	getUnit(String id)
LinearUnit	getUnit(IPrefix<?> prefix)
LinearUnit	makeCustomUnit(ITypedQuantity<LinearUnit> quantity)	Create a custom unit.
LinearUnit	makeUnit(String id, ITypedQuantity<LinearUnit> quantity)	Create an off-system unit with no default localized name.
LinearUnit	makeUnit(String id, ITypedQuantity<LinearUnit> quantity, String localizedName)
ITypedQuantity<LinearUnit>	parseInteractive(String interactiveQuantity)	Parse an interactive string.
ITypedQuantity<LinearUnit>	parseInteractive(String interactiveQuantity, Map<String,? extends LinearUnit> symbolToUnitMap)
ITypedQuantity<LinearUnit>	parsePersisted(String persistedQuantity)	Parse a persisted string.
protected String	resolveLocalizedName(IPrefix<?> prefix)
protected String	resolveLocalizedSymbol(IPrefix<?> prefix)
protected void	setDefaultSelector(LinearKindOfQuantity.LinearUnitSelector unitSelector)
ITypedQuantity<LinearUnit>	snapToBestBetweenHalfAndEqual(ITypedQuantity<LinearUnit> upperLimit)
String	toString()

Methods inherited from class org.openjdk.jmc.common.unit.KindOfQuantity

combine, format, getAccessor, getAccessorKeys, getAttributes, getFirstBucket, getFirstBucket, getPersister, getRangeFormatter, interactiveFormat, persistableString, validate

Methods inherited from class org.openjdk.jmc.common.unit.ContentType

addFormatter, getDefaultFormatter, getDescription, getFormatter, getFormatters, getIdentifier, getName, hasAttribute, lookupNameFor

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

atomUnit

protected final LinearUnit atomUnit

atomUnitName

protected final String atomUnitName

commonUnits

protected final Collection<LinearUnit> commonUnits

allUnits

protected final Collection<LinearUnit> allUnits

interactiveSymbolToUnitMap

protected final Map<String,LinearUnit> interactiveSymbolToUnitMap

unitSelector

protected LinearKindOfQuantity.LinearUnitSelector unitSelector

unitCache

protected final Map<Object,LinearUnit> unitCache

Constructor Details

LinearKindOfQuantity

public LinearKindOfQuantity(String id,
 String atomUnitId)

Create a new linear kind of quantity, with content type identifier id and sole unit identifier atomUnitId.

LinearKindOfQuantity

public LinearKindOfQuantity(String id,
 String atomUnitId,
 P minPrefix,
 P maxPrefix)

Create a new linear kind of quantity, with content type identifier id and atom unit identifier atomUnitId, using prefixes in the range minPrefix to maxPrefix.

Method Details

getNumberFormat

public static NumberFormat getNumberFormat(boolean interactive)

Get a thread local configured NumberFormat suitable for display or interactive formatting, or interactive parsing. The returned formatter mustn't be modified except as by the NumberFormat.parse(String) and Format.format(Object) family of methods.

Parameters:

interactive - true to format/parse for interactive use, false otherwise

Returns:

a thread local configured NumberFormat

setDefaultSelector

protected void setDefaultSelector(LinearKindOfQuantity.LinearUnitSelector unitSelector)

getDeltaKind

public KindOfQuantity<LinearUnit> getDeltaKind()

Specified by:

getDeltaKind in class KindOfQuantity<LinearUnit>

getDefaultUnit

public LinearUnit getDefaultUnit()

Specified by:

getDefaultUnit in class KindOfQuantity<LinearUnit>

resolveLocalizedName

protected String resolveLocalizedName(IPrefix<?> prefix)

resolveLocalizedSymbol

protected String resolveLocalizedSymbol(IPrefix<?> prefix)

getUnit

public LinearUnit getUnit(IPrefix<?> prefix)

getUnit

public LinearUnit getUnit(String id)

Overrides:

getUnit in class KindOfQuantity<LinearUnit>

getCachedUnit

public LinearUnit getCachedUnit(Object key)

getBestScaleFactorFor

protected ScaleFactor getBestScaleFactorFor(long value)

makeUnit

public LinearUnit makeUnit(String id,
 ITypedQuantity<LinearUnit> quantity)

Create an off-system unit with no default localized name.

Parameters:

id - unit identifier which also is used as the unit symbol

makeUnit

public LinearUnit makeUnit(String id,
 ITypedQuantity<LinearUnit> quantity,
 String localizedName)

makeCustomUnit

public LinearUnit makeCustomUnit(ITypedQuantity<LinearUnit> quantity)

Create a custom unit. That is, one that normally isn't available for parsing (persisted or interactive).

toString

public String toString()

Overrides:

toString in class ContentType<IQuantity>

getPreferredUnit

public LinearUnit getPreferredUnit(IQuantity quantity,
 double minNumericalValue,
 double maxNumericalValue)

Specified by:

getPreferredUnit in class KindOfQuantity<LinearUnit>

getLargestExactUnit

public LinearUnit getLargestExactUnit(IQuantity quantity)

Description copied from class: KindOfQuantity

Get the largest unit, if any, in which this quantity can be expressed exactly, typically with an integer. If the quantity has zero magnitude (quantity.doubleValue() == 0.0), quantity.getUnit() will be returned. Thus, if you want to find out a maximum common unit for a set of quantities (not recommended), only use the non-zero quantities.

Note that this may be a fairly expensive operation, and isn't intended to be used excessively. The only valid use case is for guessing the original unit in which a quantity was expressed, after it has been stored or transmitted using a legacy mechanism with a fixed unit.

Specified by:

getLargestExactUnit in class KindOfQuantity<LinearUnit>

Returns:

a unit or null

snapToBestBetweenHalfAndEqual

public ITypedQuantity<LinearUnit> snapToBestBetweenHalfAndEqual(ITypedQuantity<LinearUnit> upperLimit)

getFormatterResolving

public IFormatter<IQuantity> getFormatterResolving(IRange<IQuantity> range)

Description copied from class: KindOfQuantity

Get a formatter with sufficient resolution to produce unique strings for both ends of range, and consecutive equally spaced quantities. The returned formatter might implement IIncrementalFormatter, in which case its method can be used to reduce redundant information between adjacent quantities.

Specified by:

getFormatterResolving in class KindOfQuantity<LinearUnit>

parsePersisted

public ITypedQuantity<LinearUnit> parsePersisted(String persistedQuantity)
                                          throws QuantityConversionException

Description copied from class: KindOfQuantity

Parse a persisted string. Only guaranteed to be able to parse strings produced by IQuantity.persistableString() for quantities of this kind of quantity. Only use this on persisted strings, never for interactive input.

Specified by:

parsePersisted in interface IConstraint<IQuantity>

Specified by:

parsePersisted in class KindOfQuantity<LinearUnit>

Parameters:

persistedQuantity - persisted string to parse

Returns:

a valid quantity for this kind of quantity

Throws:

QuantityConversionException - if parsing failed

getAllUnits

public Collection<LinearUnit> getAllUnits()

Overrides:

getAllUnits in class KindOfQuantity<LinearUnit>

Returns:

all units, suitable for parsing, content assist and similar.

See Also:

• KindOfQuantity.getCommonUnits()

getCommonUnits

public Collection<LinearUnit> getCommonUnits()

Overrides:

getCommonUnits in class KindOfQuantity<LinearUnit>

Returns:

the most common units, suitable to display a unit selection to the user.

See Also:

• KindOfQuantity.getAllUnits()

addUnit

protected void addUnit(LinearUnit unit)

Description copied from class: KindOfQuantity

Add a common unit (displayed to the user when selecting a unit).

Overrides:

addUnit in class KindOfQuantity<LinearUnit>

addUnit

protected void addUnit(LinearUnit unit,
 boolean common)

Add a unit so that it is available for parsing and content assist, optionally also for direct selection by users.

Parameters:

common - whether to include when showing most common units to users

parseInteractive

public ITypedQuantity<LinearUnit> parseInteractive(String interactiveQuantity)
                                            throws QuantityConversionException

Description copied from class: KindOfQuantity

Parse an interactive string. Only guaranteed to be able to parse strings produced by IQuantity.interactiveFormat() for quantities of this kind of quantity and in the same locale. Only use this for interactive input, never for persisted strings.

Specified by:

parseInteractive in interface IConstraint<IQuantity>

Specified by:

parseInteractive in class KindOfQuantity<LinearUnit>

Parameters:

interactiveQuantity - interactive string to parse

Returns:

a valid quantity for this kind of quantity

Throws:

QuantityConversionException - if parsing failed

parseInteractive

public ITypedQuantity<LinearUnit> parseInteractive(String interactiveQuantity,
 Map<String,? extends LinearUnit> symbolToUnitMap)
                                            throws QuantityConversionException

Parameters:

interactiveQuantity - string to parse, interactive style

symbolToUnitMap - map of additional symbols to parse into units, or null

Returns:

the parsed quantity

Throws:

QuantityConversionException - containing detailed structured information, if parsing failed