Package org.openjdk.jmc.common.unit
Class KindOfQuantity<U extends TypedUnit<U>>
- java.lang.Object
-
- org.openjdk.jmc.common.unit.ContentType<IQuantity>
-
- org.openjdk.jmc.common.unit.KindOfQuantity<U>
-
- All Implemented Interfaces:
IDescribable
,IType<IQuantity>
,IConstraint<IQuantity>
,IPersister<IQuantity>
- Direct Known Subclasses:
LinearKindOfQuantity
public abstract class KindOfQuantity<U extends TypedUnit<U>> extends ContentType<IQuantity> implements IPersister<IQuantity>
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
KindOfQuantity.ExactFormatter<U extends TypedUnit<U>>
static class
KindOfQuantity.VerboseFormatter<U extends TypedUnit<U>>
-
Field Summary
-
Fields inherited from class org.openjdk.jmc.common.unit.ContentType
m_identifier
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description protected void
addUnit(U unit)
Add a common unit (displayed to the user when selecting a unit).IConstraint<IQuantity>
combine(IConstraint<?> other)
Return a constraint that honors both this constraint andother
, if such a constraint would accept anything exceptnull
.static <U extends TypedUnit<U>>
Stringformat(Number number, IUnit unit)
Convenience method (possibly temporary) until type parameters has settled.<M> IMemberAccessor<M,IQuantity>
getAccessor(IAccessorKey<M> attribute)
Internal low-level mechanism for retrieving a member accessor for a type, or null if not available.Map<IAccessorKey<?>,? extends IDescribable>
getAccessorKeys()
Get keys for the accessors that this type knows of.Collection<? extends U>
getAllUnits()
List<IAttribute<?>>
getAttributes()
Collection<? extends U>
getCommonUnits()
abstract U
getDefaultUnit()
abstract KindOfQuantity<LinearUnit>
getDeltaKind()
IRange<IQuantity>
getFirstBucket(IQuantity start, IQuantity end, double maxBuckets)
Divide the given range into at mostmaxBuckets
"naturally" aligned buckets, and return the first one.protected IRange<IQuantity>
getFirstBucket(ITypedQuantity<U> start, ITypedQuantity<U> end, double maxBuckets)
abstract 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.abstract U
getLargestExactUnit(IQuantity quantity)
Get the largest unit, if any, in which this quantity can be expressed exactly, typically with an integer.IPersister<IQuantity>
getPersister()
abstract U
getPreferredUnit(IQuantity quantity, double minNumericalValue, double maxNumericalValue)
IFormatter<IRange<IQuantity>>
getRangeFormatter(String formatHint)
Temporary helper to format quantity ranges.U
getUnit(String id)
String
interactiveFormat(IQuantity value)
An exact string representation taking locale and internationalization into account.abstract ITypedQuantity<U>
parseInteractive(String interactiveQuantity)
Parse an interactive string.abstract ITypedQuantity<U>
parsePersisted(String persistedQuantity)
Parse a persisted string.String
persistableString(IQuantity value)
A string representation independent of locale or internationalization, that when parsed usingIConstraint.parsePersisted(String)
(on this instance) yields a result that isequal
to the givenvalue
.boolean
validate(IQuantity value)
Fundamentally, check thatvalue
satisfies this constraint and throw an exception otherwise.-
Methods inherited from class org.openjdk.jmc.common.unit.ContentType
addFormatter, getDefaultFormatter, getDescription, getFormatter, getFormatters, getIdentifier, getName, hasAttribute, lookupNameFor, toString
-
-
-
-
Method Detail
-
format
public static <U extends TypedUnit<U>> String format(Number number, IUnit unit)
Convenience method (possibly temporary) until type parameters has settled.- Type Parameters:
U
- Unit type. Inferred from theunit
argument.- Parameters:
number
- numerical quantity valueunit
- quantity unit- Returns:
- a string representing a formatted version of the number with unit
-
getDeltaKind
public abstract KindOfQuantity<LinearUnit> getDeltaKind()
-
getDefaultUnit
public abstract U getDefaultUnit()
-
addUnit
protected void addUnit(U unit)
Add a common unit (displayed to the user when selecting a unit).
-
getCommonUnits
public Collection<? extends U> getCommonUnits()
- Returns:
- the most common units, suitable to display a unit selection to the user.
- See Also:
getAllUnits()
-
getAllUnits
public Collection<? extends U> getAllUnits()
- Returns:
- all units, suitable for parsing, content assist and similar.
- See Also:
getCommonUnits()
-
getPersister
public IPersister<IQuantity> getPersister()
- Overrides:
getPersister
in classContentType<IQuantity>
-
combine
public IConstraint<IQuantity> combine(IConstraint<?> other)
Description copied from interface:IConstraint
Return a constraint that honors both this constraint andother
, if such a constraint would accept anything exceptnull
. Otherwise, returnnull
.- Specified by:
combine
in interfaceIConstraint<U extends TypedUnit<U>>
- Returns:
- a constraint or
null
-
validate
public boolean validate(IQuantity value)
Description copied from interface:IConstraint
Fundamentally, check thatvalue
satisfies this constraint and throw an exception otherwise. As long as the method returns normally,value
is a valid value, regardless of the return value. However, when wrapping a persister in a constraint, it is possible that the persister treats some magic values differently. If the constraint isn't aware of these magical values it should typically not try to validate them. This is signaled by the persister by returning true from this method.- Specified by:
validate
in interfaceIConstraint<U extends TypedUnit<U>>
- Specified by:
validate
in interfaceIPersister<U extends TypedUnit<U>>
- Returns:
- true if this value is considered magical and further validation should be skipped,
false otherwise. Any return value mean that the
value
is valid.
-
persistableString
public String persistableString(IQuantity value)
Description copied from interface:IPersister
A string representation independent of locale or internationalization, that when parsed usingIConstraint.parsePersisted(String)
(on this instance) yields a result that isequal
to the givenvalue
. That is, the exact representation must be preserved.- Specified by:
persistableString
in interfaceIConstraint<U extends TypedUnit<U>>
- Specified by:
persistableString
in interfaceIPersister<U extends TypedUnit<U>>
- Returns:
- a string representation independent of locale or internationalization.
-
parsePersisted
public abstract ITypedQuantity<U> parsePersisted(String persistedQuantity) throws QuantityConversionException
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<U extends TypedUnit<U>>
- Parameters:
persistedQuantity
- persisted string to parse- Returns:
- a valid quantity for this kind of quantity
- Throws:
QuantityConversionException
- if parsing failed
-
interactiveFormat
public String interactiveFormat(IQuantity value)
Description copied from interface:IPersister
An exact string representation taking locale and internationalization into account. When parsed usingIConstraint.parseInteractive(String)
(on this instance) yields a result that isequal
to the givenvalue
. That is, the exact representation must be preserved.- Specified by:
interactiveFormat
in interfaceIConstraint<U extends TypedUnit<U>>
- Specified by:
interactiveFormat
in interfaceIPersister<U extends TypedUnit<U>>
- Returns:
- a string representation taking locale and internationalization into account.
-
parseInteractive
public abstract ITypedQuantity<U> parseInteractive(String interactiveQuantity) throws QuantityConversionException
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<U extends TypedUnit<U>>
- Parameters:
interactiveQuantity
- interactive string to parse- Returns:
- a valid quantity for this kind of quantity
- Throws:
QuantityConversionException
- if parsing failed
-
getPreferredUnit
public abstract U getPreferredUnit(IQuantity quantity, double minNumericalValue, double maxNumericalValue)
-
getLargestExactUnit
public abstract U getLargestExactUnit(IQuantity quantity)
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.
- Returns:
- a unit or
null
-
getFirstBucket
public final IRange<IQuantity> getFirstBucket(IQuantity start, IQuantity end, double maxBuckets)
Divide the given range into at mostmaxBuckets
"naturally" aligned buckets, and return the first one. This can be used to create tick marks in charts or buckets for histograms. The number of buckets will typically be betweenmaxBuckets/2
andmaxBuckets
, but this should be better specified.Note that
start
is included in the first bucket.- Parameters:
start
- range start valueend
- range end valuemaxBuckets
- maximum number of buckets to divide range into- Returns:
- the first bucket, as described above
-
getFirstBucket
protected IRange<IQuantity> getFirstBucket(ITypedQuantity<U> start, ITypedQuantity<U> end, double maxBuckets)
-
getRangeFormatter
public IFormatter<IRange<IQuantity>> getRangeFormatter(String formatHint)
Temporary helper to format quantity ranges.- Parameters:
formatHint
- A format hint. SeeIDisplayable.displayUsing(String)
.- Returns:
- a quantity range formatter
-
getFormatterResolving
public abstract 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. The returned formatter might implementIIncrementalFormatter
, in which case its method can be used to reduce redundant information between adjacent quantities.
-
getAttributes
public List<IAttribute<?>> getAttributes()
- Specified by:
getAttributes
in interfaceIType<U extends TypedUnit<U>>
- Overrides:
getAttributes
in classContentType<IQuantity>
-
getAccessorKeys
public Map<IAccessorKey<?>,? extends IDescribable> getAccessorKeys()
Description copied from interface:IType
Get keys for the accessors that this type knows of. Note that the returned accessors does not necessarily cover all possible data from the items of this type, and that it is always possible to define additional accessors that get or calculate values from the items in non-standard ways.Should only be used for low level type inspection. Iterators etc. should use a collection of predefined
attributes
.- Specified by:
getAccessorKeys
in interfaceIType<U extends TypedUnit<U>>
- Overrides:
getAccessorKeys
in classContentType<IQuantity>
- Returns:
- keys for the accessors defined for this type
-
getAccessor
public <M> IMemberAccessor<M,IQuantity> getAccessor(IAccessorKey<M> attribute)
Description copied from interface:IType
Internal low-level mechanism for retrieving a member accessor for a type, or null if not available.This is only intended to be used by implementors of
IAccessorFactory
. All other usage should be replaced withICanonicalAccessorFactory.getAccessor(IType)
call to pre-defined accessors.- Specified by:
getAccessor
in interfaceIType<U extends TypedUnit<U>>
- Overrides:
getAccessor
in classContentType<IQuantity>
- Type Parameters:
M
- accessor value type- Parameters:
attribute
- the identifier for the field- Returns:
- a member accessor
-
-