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>

  • Method Details

    • 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

      public Collection<? extends U> getAllUnits()
      Returns:
      all units, suitable for parsing, content assist and similar.
      See Also:

    • 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<U extends TypedUnit<U>>
      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<U extends TypedUnit<U>>
      Specified by:
      validate in interface IPersister<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 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<U extends TypedUnit<U>>
      Specified by:
      persistableString in interface IPersister<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 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<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 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<U extends TypedUnit<U>>
      Specified by:
      interactiveFormat in interface IPersister<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 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<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.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<U extends TypedUnit<U>>
      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<U extends TypedUnit<U>>
      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<U extends TypedUnit<U>>
      Overrides:
      getAccessor in class ContentType<IQuantity>
      Type Parameters:
      M - accessor value type
      Parameters:
      attribute - the identifier for the field
      Returns:
      a member accessor