Package foundation.omni

Class OmniValue

java.lang.Object
java.lang.Number
javax.money.NumberValue
foundation.omni.OmniValue
All Implemented Interfaces:
Serializable, Comparable<javax.money.NumberValue>
Direct Known Subclasses:
OmniDivisibleValue, OmniIndivisibleValue
public abstract class OmniValue extends javax.money.NumberValue

Numeric value for a quantity of Omni tokens - base class for OmniDivisible and OmniIndivisible subclasses. Known as "Number of Coins" in the Omni Protocol Specification.

The internal representation is a long which corresponds to what we call a "willett" in honour of J.R. Willett in the same fashion as the smallest Bitcoin unit is called a "satoshi".

The constructors are protected and instances should be created with the of() static methods which can take either BigDecimal or long values as parameters.

The various *value() methods of Number and NumberValue will return values as used in the Omni Protocol Specification, which means that for divisible tokens the values will be treated a decimal values and methods returning integer types will be throw exceptions if their is a fractional component that would be truncated.

TODO: Consider refactoring to extend java.lang.Number to remove dependency on javax.money in omnij-core

TODO: provide examples of *value() methods and what they return

TODO: Implement unsupported methods

TODO: Should we allow negative values?

See Also:

  • Field Details

    • willettsPerDivisible

      public static final long willettsPerDivisible

    • willetts

      protected final long willetts

    • MIN_WILLETTS

      public static final long MIN_WILLETTS
      See Also:

    • MAX_WILLETTS

      public static final long MAX_WILLETTS
      See Also:

  • Constructor Details

    • OmniValue

      protected OmniValue(long willetts)
      Default Constructor Used only by subclasses using internal (willetts) format
      Parameters:
      willetts - Willetts (internal/wire format)

  • Method Details

    • of

      public static OmniValue of(BigDecimal amount, PropertyType type)
      Parameters:
      amount - amount
      type - property type
      Returns:
      OmniDivisibleValue or OmniIndivisibleValue as appropriate

    • of

      public static OmniValue of(long amount, PropertyType type)
      Parameters:
      amount - amount
      type - property type
      Returns:
      OmniDivisibleValue or OmniIndivisibleValue as appropriate

    • of

      public static OmniValue of(BigDecimal amount, boolean divisible)
      Parameters:
      amount - amount
      divisible - true if divisible
      Returns:
      OmniDivisibleValue or OmniIndivisibleValue as appropriate

    • of

      public static OmniValue of(long amount, boolean divisible)
      Parameters:
      amount - amount
      divisible - true if divisible
      Returns:
      OmniDivisibleValue or OmniIndivisibleValue as appropriate

    • of

      public static OmniValue of(String omniValueJsonFormattedString)
      Parse a String (which should be in OmniValue JSON format) to get an OmniValue

      WARNING: This method requires that all amounts for OmniDivisibleValue must contain a decimal point to be properly parsed into an OmniDivisibleValue representation. See toJsonFormattedString() for details.

      Parameters:
      omniValueJsonFormattedString - A string representation of an OmniValue in OmniValue JSON format
      Returns:
      An OmniDivisibleValue if the string contains a '.', otherwise an OmniIndivisibleValue
      Throws:
      NumberFormatException - if the string is not parseable.

    • of

      public static OmniValue of(String string, boolean divisible)
      Parse a numeric String to get an OmniValue
      Parameters:
      string - A string that should be parseable to a BigDecimal
      divisible - whether this string represents a divisible value, false otherwise
      Returns:
      An OmniDivisibleValue or OmniIndivisibleValue depending upon the divisible parameter
      Throws:
      NumberFormatException - if the string is not parseable.

    • ofWilletts

      public static OmniValue ofWilletts(long amount, PropertyType type)
      Parameters:
      amount - amount
      type - property type
      Returns:
      OmniDivisibleValue or OmniIndivisibleValue as appropriate

    • ofWilletts

      public static OmniValue ofWilletts(long amount, boolean divisible)
      Parameters:
      amount - amount
      divisible - true if divisible
      Returns:
      OmniDivisibleValue or OmniIndivisibleValue as appropriate

    • getWilletts

      public long getWilletts()
      Returns:
      value in willetts

    • getPropertyType

      public abstract PropertyType getPropertyType()
      Returns:
      property type

    • checkWillettValue

      public static void checkWillettValue(BigInteger willetts) throws ArithmeticException

      Make sure a BigInteger value is a valid Omni "number of coins" (willetts) value

      Parameters:
      willetts - "number of coins" (willetts) value to check
      Throws:
      ArithmeticException - if less than minimum or greater than maximum allowed value

    • checkWillettValue

      public static void checkWillettValue(long willetts) throws ArithmeticException

      Make sure a long value is a valid Omni "number of coins" value

      Note: Since any positive long is valid, we just need to check that it's not less than MIN_VALUE

      Parameters:
      willetts - value to check.
      Throws:
      ArithmeticException - if less than minimum allowed value

    • getNumberType

      public abstract Class<? extends Number> getNumberType()
      Specified by:
      getNumberType in class javax.money.NumberValue

    • numberValue

      public abstract Number numberValue()
      Return value in preferred number type
      Returns:
      value as represented in best/preferred number type

    • getPrecision

      public int getPrecision()
      Specified by:
      getPrecision in class javax.money.NumberValue

    • getScale

      public int getScale()
      Specified by:
      getScale in class javax.money.NumberValue

    • intValueExact

      public int intValueExact()
      Specified by:
      intValueExact in class javax.money.NumberValue

    • longValueExact

      public long longValueExact()
      Specified by:
      longValueExact in class javax.money.NumberValue

    • doubleValueExact

      public abstract double doubleValueExact()
      Specified by:
      doubleValueExact in class javax.money.NumberValue

    • numberValue

      public <T extends Number> T numberValue(Class<T> numberType)
      Specified by:
      numberValue in class javax.money.NumberValue

    • numberValueExact

      public <T extends Number> T numberValueExact(Class<T> numberType)
      Specified by:
      numberValueExact in class javax.money.NumberValue

    • getAmountFractionNumerator

      public long getAmountFractionNumerator()
      Specified by:
      getAmountFractionNumerator in class javax.money.NumberValue

    • getAmountFractionDenominator

      public long getAmountFractionDenominator()
      Specified by:
      getAmountFractionDenominator in class javax.money.NumberValue

    • byteValue

      public byte byteValue()
      Overrides:
      byteValue in class Number

    • shortValue

      public short shortValue()
      Overrides:
      shortValue in class Number

    • intValue

      public int intValue()
      Specified by:
      intValue in class Number

    • longValue

      public long longValue()
      Specified by:
      longValue in class Number

    • floatValue

      public float floatValue()
      Specified by:
      floatValue in class Number

    • doubleValue

      public abstract double doubleValue()
      Return a double value. Warning: this will result in rounding errors. Only use this for applications like plotting data, never for anything that counts currency.
      Specified by:
      doubleValue in class Number
      Returns:
      The value rounded to the nearest double.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public abstract boolean equals(Object obj)
      Overrides:
      equals in class Object

    • compareTo

      public int compareTo(javax.money.NumberValue o)
      Specified by:
      compareTo in interface Comparable<javax.money.NumberValue>
      Overrides:
      compareTo in class javax.money.NumberValue

    • toString

      public abstract String toString()
      Convert to String. Uses standard JVM toString() formats. For OmniDivisibleValue it is the same format as BigDecimal (this means"0E-8" for OmniDivisibleValue.ZERO.) For OmniIndivisibleValue it is the same format as Long.
      Overrides:
      toString in class Object
      Returns:
      Number as a string

    • toPlainString

      public abstract String toPlainString()
      Convert to String. For OmniDivisibleValue the same format as BigDecimal.toPlainString(). For OmniIndivisibleValue it is the same as OmniIndivisibleValue.toString().
      Returns:
      Number as a string

    • toJsonFormattedString

      public abstract String toJsonFormattedString()
      Convert to String. The required format for OmniValues in JSON. For OmniDivisibleValue there is always at least one place after the decimal point (e.g. "0.0"). This allows humans and parsers to easily tell OmniDivisibleValues from OmniIndivisibleValues. Note: The '.' separator is always used regardless of the current Locale.
      Returns:
      Number as a string

    • toFormattedString

      public abstract String toFormattedString()
      Convert to String. A human-readable format using locale-specific place-separators.
      Returns:
      Number as a string

    • bigDecimalValue

      public abstract BigDecimal bigDecimalValue()
      Convert to a BigDecimal value. This will be lossless. For OmniIndivisibleValue the BigDecimal value will be an integer, of course.
      Returns:
      the value

    • plus

      public OmniValue plus(OmniValue right)
      Create a new OmniValue by adding this value and another value.

      The method-name plus supports Groovy operator overloading

      Parameters:
      right - value to add
      Returns:
      a new value with the result

    • minus

      public OmniValue minus(OmniValue right)
      Create a new OmniValue by subtracting another value from this value.

      The method-name minus supports Groovy operator overloading

      Parameters:
      right - value to subtract
      Returns:
      a new value with the result

    • multiply

      public OmniValue multiply(long right)
      Create a new OmniValue by multiplying this value and another value.

      The method-name multiply supports Groovy operator overloading

      Parameters:
      right - value to add
      Returns:
      a new value with the result