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 and 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

Modifier and Type	Method and 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 and other, if such a constraint would accept anything except null.
static <U extends TypedUnit<U>> String	format(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 most maxBuckets "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 of range, 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 using IConstraint.parsePersisted(String) (on this instance) yields a result that is equal to the given value.
boolean	validate(IQuantity value) Fundamentally, check that value 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

Methods inherited from class java.lang.Object

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

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 the unit argument.

Parameters:

number - numerical quantity value

unit - 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()

getUnit

public U getUnit(String id)

getPersister

public IPersister<IQuantity> getPersister()

Overrides:

getPersister in class ContentType<IQuantity>

combine

public IConstraint<IQuantity> combine(IConstraint<?> other)

Description copied from interface: IConstraint

Return a constraint that honors both this constraint and other, if such a constraint would accept anything except null. Otherwise, return null.

Specified by:

combine in interface IConstraint<IQuantity>

Returns:

a constraint or null

validate

public boolean validate(IQuantity value)

Description copied from interface: IConstraint

Fundamentally, check that value 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 interface IConstraint<IQuantity>

Specified by:

validate in interface IPersister<IQuantity>

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 using IConstraint.parsePersisted(String) (on this instance) yields a result that is equal to the given value. That is, the exact representation must be preserved.

Specified by:

persistableString in interface IConstraint<IQuantity>

Specified by:

persistableString in interface IPersister<IQuantity>

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 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>

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 using IConstraint.parseInteractive(String) (on this instance) yields a result that is equal to the given value. That is, the exact representation must be preserved.

Specified by:

interactiveFormat in interface IConstraint<IQuantity>

Specified by:

interactiveFormat in interface IPersister<IQuantity>

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 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>

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

Returns:

a unit or null

getFirstBucket

public final IRange<IQuantity> getFirstBucket(IQuantity start,
                                              IQuantity end,
                                              double maxBuckets)

Divide the given range into at most maxBuckets "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 between maxBuckets/2 and maxBuckets, but this should be better specified.

Note that start is included in the first bucket.

Parameters:

start - range start value

end - range end value

maxBuckets - 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. See IDisplayable.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 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.

getAttributes

public List<IAttribute<?>> getAttributes()

Specified by:

getAttributes in interface IType<IQuantity>

Overrides:

getAttributes in class ContentType<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 interface IType<IQuantity>

Overrides:

getAccessorKeys in class ContentType<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 with ICanonicalAccessorFactory.getAccessor(IType) call to pre-defined accessors.

Specified by:

getAccessor in interface IType<IQuantity>

Overrides:

getAccessor in class ContentType<IQuantity>

Type Parameters:

M - accessor value type

Parameters:

attribute - the identifier for the field

Returns:

a member accessor