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 java.util.Collection<LinearUnit>
allUnits
protected LinearUnit
atomUnit
protected java.lang.String
atomUnitName
protected java.util.Collection<LinearUnit>
commonUnits
protected java.util.Map<java.lang.String,LinearUnit>
interactiveSymbolToUnitMap
private static FormatThreadLocal<java.text.NumberFormat>
NUMBER_FORMAT_DISPLAY_HOLDER
private static FormatThreadLocal<java.text.NumberFormat>
NUMBER_FORMAT_INTERACTIVE_HOLDER
private static java.util.regex.Pattern
NUMBER_UNIT_PATTERN
protected java.util.Map<java.lang.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(java.lang.String id, java.lang.String atomUnitId)
Create a new linear kind of quantity, with content type identifierid
and sole unit identifieratomUnitId
.LinearKindOfQuantity(java.lang.String id, java.lang.String atomUnitId, java.util.Collection<P> prefixes)
Create a new linear kind of quantity, with content type identifierid
and atom unit identifieratomUnitId
, using the prefixes inprefixes
.LinearKindOfQuantity(java.lang.String id, java.lang.String atomUnitId, java.util.Collection<P> commonPrefixes, java.util.Collection<P> allPrefixes)
Create a new linear kind of quantity, with content type identifierid
and atom unit identifieratomUnitId
, using the prefixes inallPrefixes
but only designating those incommonPrefixes
as common.LinearKindOfQuantity(java.lang.String id, java.lang.String atomUnitId, P minPrefix, P maxPrefix)
Create a new linear kind of quantity, with content type identifierid
and atom unit identifieratomUnitId
, using prefixes in the rangeminPrefix
tomaxPrefix
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods 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.java.util.Collection<LinearUnit>
getAllUnits()
protected ScaleFactor
getBestScaleFactorFor(long value)
LinearUnit
getCachedUnit(java.lang.Object key)
java.util.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 ofrange
, and consecutive equally spaced quantities.private static java.lang.String
getHexNumberString(java.lang.String interactiveQuantity)
LinearUnit
getLargestExactUnit(IQuantity quantity)
Get the largest unit, if any, in which this quantity can be expressed exactly, typically with an integer.static java.text.NumberFormat
getNumberFormat(boolean interactive)
Get a thread local configuredNumberFormat
suitable for display or interactive formatting, or interactive parsing.LinearUnit
getPreferredUnit(IQuantity quantity, double minNumericalValue, double maxNumericalValue)
LinearUnit
getUnit(java.lang.String id)
LinearUnit
getUnit(IPrefix<?> prefix)
private static boolean
isHexDigit(char character)
private boolean
isHexString(java.lang.String interactiveQuantity)
LinearUnit
makeCustomUnit(ITypedQuantity<LinearUnit> quantity)
Create a custom unit.private LinearUnit
makeUnit(java.lang.String id, java.lang.String localizedSymbol, ITypedQuantity<LinearUnit> quantity, java.lang.String localizedName, boolean custom)
Create an off-system unit.LinearUnit
makeUnit(java.lang.String id, ITypedQuantity<LinearUnit> quantity)
Create an off-system unit with no default localized name.LinearUnit
makeUnit(java.lang.String id, ITypedQuantity<LinearUnit> quantity, java.lang.String localizedName)
private java.lang.Number
parseHexNumberString(java.lang.String numberString)
ITypedQuantity<LinearUnit>
parseInteractive(java.lang.String interactiveQuantity)
Parse an interactive string.ITypedQuantity<LinearUnit>
parseInteractive(java.lang.String interactiveQuantity, java.util.Map<java.lang.String,? extends LinearUnit> symbolToUnitMap)
ITypedQuantity<LinearUnit>
parsePersisted(java.lang.String persistedQuantity)
Parse a persisted string.protected java.lang.String
resolveLocalizedName(IPrefix<?> prefix)
protected java.lang.String
resolveLocalizedSymbol(IPrefix<?> prefix)
protected void
setDefaultSelector(LinearKindOfQuantity.LinearUnitSelector unitSelector)
ITypedQuantity<LinearUnit>
snapToBestBetweenHalfAndEqual(ITypedQuantity<LinearUnit> upperLimit)
java.lang.String
toString()
-
Methods inherited from class org.openjdk.jmc.common.unit.KindOfQuantity
combine, format, getAccessor, getAccessorKeys, getAttributes, getFirstBucket, getFirstBucket, getPersister, getRangeFormatter, interactiveFormat, persistableString, resolveLocalizedName, resolveLocalizedSymbol, validate
-
Methods inherited from class org.openjdk.jmc.common.unit.ContentType
addFormatter, getDefaultFormatter, getDescription, getFormatter, getFormatters, getIdentifier, getName, hasAttribute, lookupNameFor
-
-
-
-
Field Detail
-
NUMBER_FORMAT_INTERACTIVE_HOLDER
private static final FormatThreadLocal<java.text.NumberFormat> NUMBER_FORMAT_INTERACTIVE_HOLDER
-
NUMBER_FORMAT_DISPLAY_HOLDER
private static final FormatThreadLocal<java.text.NumberFormat> NUMBER_FORMAT_DISPLAY_HOLDER
-
atomUnit
protected final LinearUnit atomUnit
-
atomUnitName
protected final java.lang.String atomUnitName
-
commonUnits
protected final java.util.Collection<LinearUnit> commonUnits
-
allUnits
protected final java.util.Collection<LinearUnit> allUnits
-
interactiveSymbolToUnitMap
protected final java.util.Map<java.lang.String,LinearUnit> interactiveSymbolToUnitMap
-
unitSelector
protected LinearKindOfQuantity.LinearUnitSelector unitSelector
-
unitCache
protected final java.util.Map<java.lang.Object,LinearUnit> unitCache
-
NUMBER_UNIT_PATTERN
private static final java.util.regex.Pattern NUMBER_UNIT_PATTERN
-
-
Constructor Detail
-
LinearKindOfQuantity
public LinearKindOfQuantity(java.lang.String id, java.lang.String atomUnitId)
Create a new linear kind of quantity, with content type identifierid
and sole unit identifieratomUnitId
.
-
LinearKindOfQuantity
public LinearKindOfQuantity(java.lang.String id, java.lang.String atomUnitId, P minPrefix, P maxPrefix)
Create a new linear kind of quantity, with content type identifierid
and atom unit identifieratomUnitId
, using prefixes in the rangeminPrefix
tomaxPrefix
.
-
LinearKindOfQuantity
LinearKindOfQuantity(java.lang.String id, java.lang.String atomUnitId, java.util.Collection<P> prefixes)
Create a new linear kind of quantity, with content type identifierid
and atom unit identifieratomUnitId
, using the prefixes inprefixes
.
-
LinearKindOfQuantity
LinearKindOfQuantity(java.lang.String id, java.lang.String atomUnitId, java.util.Collection<P> commonPrefixes, java.util.Collection<P> allPrefixes)
Create a new linear kind of quantity, with content type identifierid
and atom unit identifieratomUnitId
, using the prefixes inallPrefixes
but only designating those incommonPrefixes
as common.
-
-
Method Detail
-
getNumberFormat
public static java.text.NumberFormat getNumberFormat(boolean interactive)
Get a thread local configuredNumberFormat
suitable for display or interactive formatting, or interactive parsing. The returned formatter mustn't be modified except as by theNumberFormat.parse(String)
andFormat.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 classKindOfQuantity<LinearUnit>
-
getDefaultUnit
public LinearUnit getDefaultUnit()
- Specified by:
getDefaultUnit
in classKindOfQuantity<LinearUnit>
-
resolveLocalizedName
protected java.lang.String resolveLocalizedName(IPrefix<?> prefix)
-
resolveLocalizedSymbol
protected java.lang.String resolveLocalizedSymbol(IPrefix<?> prefix)
-
getUnit
public LinearUnit getUnit(IPrefix<?> prefix)
-
getUnit
public LinearUnit getUnit(java.lang.String id)
- Overrides:
getUnit
in classKindOfQuantity<LinearUnit>
-
getCachedUnit
public LinearUnit getCachedUnit(java.lang.Object key)
-
getBestScaleFactorFor
protected ScaleFactor getBestScaleFactorFor(long value)
-
makeUnit
public LinearUnit makeUnit(java.lang.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(java.lang.String id, ITypedQuantity<LinearUnit> quantity, java.lang.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).
-
makeUnit
private LinearUnit makeUnit(java.lang.String id, java.lang.String localizedSymbol, ITypedQuantity<LinearUnit> quantity, java.lang.String localizedName, boolean custom)
Create an off-system unit.- Parameters:
localizedSymbol
- Default unit symbol. May be an empty string and may be overridden by translation.localizedName
- Default unit name. May benull
and may be overridden by translation.
-
toString
public java.lang.String toString()
- Overrides:
toString
in classContentType<IQuantity>
-
getPreferredUnit
public LinearUnit getPreferredUnit(IQuantity quantity, double minNumericalValue, double maxNumericalValue)
- Specified by:
getPreferredUnit
in classKindOfQuantity<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.0quantity.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 classKindOfQuantity<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 ofrange
, and consecutive equally spaced quantities. The returned formatter might implementIIncrementalFormatter
, in which case its method can be used to reduce redundant information between adjacent quantities.- Specified by:
getFormatterResolving
in classKindOfQuantity<LinearUnit>
-
parsePersisted
public ITypedQuantity<LinearUnit> parsePersisted(java.lang.String persistedQuantity) throws QuantityConversionException
Description copied from class:KindOfQuantity
Parse a persisted string. Only guaranteed to be able to parse strings produced byIQuantity.persistableString()
for quantities of this kind of quantity. Only use this on persisted strings, never for interactive input.- Specified by:
parsePersisted
in interfaceIConstraint<IQuantity>
- Specified by:
parsePersisted
in classKindOfQuantity<LinearUnit>
- Parameters:
persistedQuantity
- persisted string to parse- Returns:
- a valid quantity for this kind of quantity
- Throws:
QuantityConversionException
- if parsing failed
-
getAllUnits
public java.util.Collection<LinearUnit> getAllUnits()
- Overrides:
getAllUnits
in classKindOfQuantity<LinearUnit>
- Returns:
- all units, suitable for parsing, content assist and similar.
- See Also:
KindOfQuantity.getCommonUnits()
-
getCommonUnits
public java.util.Collection<LinearUnit> getCommonUnits()
- Overrides:
getCommonUnits
in classKindOfQuantity<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 classKindOfQuantity<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(java.lang.String interactiveQuantity) throws QuantityConversionException
Description copied from class:KindOfQuantity
Parse an interactive string. Only guaranteed to be able to parse strings produced byIQuantity.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 interfaceIConstraint<IQuantity>
- Specified by:
parseInteractive
in classKindOfQuantity<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(java.lang.String interactiveQuantity, java.util.Map<java.lang.String,? extends LinearUnit> symbolToUnitMap) throws QuantityConversionException
- Parameters:
interactiveQuantity
- string to parse, interactive stylesymbolToUnitMap
- map of additional symbols to parse into units, or null- Returns:
- the parsed quantity
- Throws:
QuantityConversionException
- containing detailed structured information, if parsing failed
-
isHexString
private boolean isHexString(java.lang.String interactiveQuantity)
-
parseHexNumberString
private java.lang.Number parseHexNumberString(java.lang.String numberString) throws QuantityConversionException
- Throws:
QuantityConversionException
-
getHexNumberString
private static java.lang.String getHexNumberString(java.lang.String interactiveQuantity)
-
isHexDigit
private static boolean isHexDigit(char character)
-
-