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 Collection<LinearUnit>`	`allUnits`
`protected LinearUnit`	`atomUnit`
`protected String`	`atomUnitName`
`protected Collection<LinearUnit>`	`commonUnits`
`protected Map<String,LinearUnit>`	`interactiveSymbolToUnitMap`
`protected 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

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.
`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 Detail
  - 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 Detail
  - 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 Detail
  - 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

Class LinearKindOfQuantity

Nested Class Summary

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

Field Summary

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

Constructor Summary

Method Summary

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

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

Methods inherited from class java.lang.Object

Field Detail

atomUnit

atomUnitName

commonUnits

allUnits

interactiveSymbolToUnitMap

unitSelector

unitCache

Constructor Detail

LinearKindOfQuantity

LinearKindOfQuantity

Method Detail

getNumberFormat

setDefaultSelector

getDeltaKind

getDefaultUnit

resolveLocalizedName

resolveLocalizedSymbol

getUnit

getUnit

getCachedUnit

getBestScaleFactorFor

makeUnit

makeUnit

makeCustomUnit

toString

getPreferredUnit

getLargestExactUnit

snapToBestBetweenHalfAndEqual

getFormatterResolving

parsePersisted

getAllUnits

getCommonUnits

addUnit

addUnit

parseInteractive

parseInteractive