Package org.openjdk.jmc.common.unit

Interface IConstraint<T>

Type Parameters:
T - the type of values that the constraint operates on
All Known Subinterfaces:
IPersister<T>
All Known Implementing Classes:
ComparableConstraint, KindOfQuantity, LinearKindOfQuantity, WrappingPersister
public interface IConstraint<T>
A constraint on allowed instances of an existing type T, including constrained conversions to and from persistable and interactive strings.

  • Method Summary

    Modifier and Type
    Method
    Description
    IConstraint<T>
    combine(IConstraint<?> other)
    Return a constraint that honors both this constraint and other, if such a constraint would accept anything except null.
    String
    interactiveFormat(T value)
    An exact string representation taking locale and internationalization into account.
    T
    parseInteractive(String interactiveValue)
    Parse an interactive string.
    T
    parsePersisted(String persistedValue)
    Parse a persisted string.
    String
    persistableString(T value)
    A string representation independent of locale or internationalization, that when parsed using parsePersisted(String) (on this instance) yields a result that is equal to the given value.
    boolean
    validate(T value)
    Fundamentally, check that value satisfies this constraint and throw an exception otherwise.

  • Method Details

    • combine

      IConstraint<T> combine(IConstraint<?> other)
      Return a constraint that honors both this constraint and other, if such a constraint would accept anything except null. Otherwise, return null.
      Returns:
      a constraint or null

    • validate

      boolean validate(T value) throws QuantityConversionException
      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.
      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.
      Throws:
      NullPointerException - if value is null and this constraint doesn't allow it
      IllegalArgumentException - if some type aspect of value prevents it from being valid
      QuantityConversionException - if the constraint isn't satisfied in some other way

    • persistableString

      String persistableString(T value) throws QuantityConversionException
      A string representation independent of locale or internationalization, that when parsed using parsePersisted(String) (on this instance) yields a result that is equal to the given value. That is, the exact representation must be preserved.
      Returns:
      a string representation independent of locale or internationalization.
      Throws:
      NullPointerException - if value is null and this constraint doesn't allow it
      IllegalArgumentException - if some type aspect of value prevents it from being valid
      QuantityConversionException - if the constraint isn't satisfied in some other way

    • parsePersisted

      T parsePersisted(String persistedValue) throws QuantityConversionException
      Parse a persisted string. Only guaranteed to be able to parse strings produced by persistableString(Object) on this instance. Only use this on persisted strings, never for interactive input.
      Returns:
      a valid value for this instance
      Throws:
      NullPointerException - if persistedValue is null
      QuantityConversionException - if persistedValue couldn't be parsed or didn't satisfy the constraint

    • interactiveFormat

      String interactiveFormat(T value) throws QuantityConversionException
      An exact string representation taking locale and internationalization into account. When parsed using parseInteractive(String) (on this instance) yields a result that is equal to the given value. That is, the exact representation must be preserved.
      Returns:
      a string representation taking locale and internationalization into account.
      Throws:
      NullPointerException - if value is null and this constraint doesn't allow it
      IllegalArgumentException - if some type aspect of value prevents it from being valid
      QuantityConversionException - if value doesn't satisfy the constraint

    • parseInteractive

      T parseInteractive(String interactiveValue) throws QuantityConversionException
      Parse an interactive string. Only guaranteed to be able to parse strings produced by interactiveFormat(Object) on this instance and in the same locale. Only use this for interactive input, never for persisted strings.
      Returns:
      a valid value for this instance
      Throws:
      NullPointerException - if interactiveValue is null
      QuantityConversionException - if interactiveValue couldn't be parsed or didn't satisfy the constraint