Module tools.jackson.databind
Package tools.jackson.databind.node

Class NumericNode

java.lang.Object
tools.jackson.databind.JacksonSerializable.Base
tools.jackson.databind.JsonNode
tools.jackson.databind.node.BaseJsonNode
tools.jackson.databind.node.ValueNode
tools.jackson.databind.node.NumericNode
All Implemented Interfaces:
Serializable, Iterable<JsonNode>, TreeNode, JacksonSerializable
Direct Known Subclasses:
NumericFPNode, NumericIntNode
public abstract class NumericNode extends ValueNode
Intermediate value node used for numeric nodes.
See Also:

  • Constructor Details

    • NumericNode

      protected NumericNode()

  • Method Details

    • getNodeType

      public final JsonNodeType getNodeType()
      Description copied from class: JsonNode
      Return the type of this node
      Specified by:
      getNodeType in class JsonNode
      Returns:
      the node type as a JsonNodeType enum value

    • deepCopy

      public NumericNode deepCopy()
      Description copied from class: ValueNode
      All current value nodes are immutable, so we can just return them as is.
      Overrides:
      deepCopy in class ValueNode
      Returns:
      Node that is either a copy of this node (and all non-leaf children); or, for immutable leaf nodes, node itself.

    • _valueDesc

      protected final String _valueDesc()
      Description copied from class: BaseJsonNode
      Method for implementation classes to return a short description of contained value, to be used in error messages.
      Specified by:
      _valueDesc in class BaseJsonNode

    • numberType

      public abstract JsonParser.NumberType numberType()
      Description copied from class: BaseJsonNode
      Returns code that identifies type of underlying numeric value, if (and only if) node is a number node.
      Specified by:
      numberType in interface TreeNode
      Overrides:
      numberType in class BaseJsonNode

    • numberValue

      public abstract Number numberValue()
      Description copied from class: JsonNode
      Method that will try to access value of this node as Number that accurately represents its value, if (and only if) this is a number node (returns true for JsonNode.isNumber()). If this node is NOT a number node, a JsonNodeException will be thrown.
      Overrides:
      numberValue in class BaseJsonNode
      Returns:
      Number value this node contains, if numeric node

    • shortValue

      public abstract short shortValue()
      Description copied from class: JsonNode
      Method that will try to access value of this node as 16-bit signed integer value (Java short): but if node value cannot be expressed exactly as a short, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Integer values that fit in Java 16-bit signed short range
      • JSON Floating-point values that fit in Java 16-bit signed short range AND do not have fractional part.

      Overrides:
      shortValue in class BaseJsonNode
      Returns:
      Short value this node represents, if possible to accurately represent

    • shortValue

      public abstract short shortValue(short defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.shortValue(), but that will return specified defaultValue if this node cannot be converted to Java short.
      Overrides:
      shortValue in class BaseJsonNode
      Parameters:
      defaultValue - Value to return if this node cannot be converted to Java short
      Returns:
      Java short value this node represents, if possible to accurately represent; defaultValue otherwise

    • shortValueOpt

      public abstract Optional<Short> shortValueOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.shortValue(), but that will return empty Optional<Short> (Optional.empty()) if this node cannot be converted to Java short.
      Overrides:
      shortValueOpt in class BaseJsonNode
      Returns:
      Java short value this node represents, as Optional<Short>, if possible to accurately represent; Optional.empty() otherwise

    • asShort

      public abstract short asShort()
      Description copied from class: JsonNode
      Method similar to JsonNode.shortValue() but in addition to coercing Number values (same as JsonNode.shortValue()), will also try to coerce a couple of additional types (or cases):
      • JSON Floating-point numbers with fractions (ones without fractions are ok for JsonNode.shortValue()) will be truncated to short (if (and only if) they fit in short range).
      • JSON Strings that represent JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0))
      • POJO nodes that contain Number values
      Overrides:
      asShort in class BaseJsonNode
      Returns:
      short value this node represents, if possible to accurately represent

    • asShort

      public abstract short asShort(short defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.shortValue(), but that will return specified defaultValue if this node cannot be converted to short.
      Overrides:
      asShort in class BaseJsonNode
      Parameters:
      defaultValue - Value to return if this node cannot be converted to short
      Returns:
      short value this node represents, if possible to accurately represent; defaultValue otherwise

    • asShortOpt

      public abstract Optional<Short> asShortOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.asShort(), but that will return (Optional.empty()) if this node cannot be coerced to short.
      Overrides:
      asShortOpt in class BaseJsonNode
      Returns:
      Optional<Short> value this node represents, if possible to accurately represent; Optional.empty() otherwise

    • intValue

      public abstract int intValue()
      Description copied from class: JsonNode
      Method that will try to access value of this node as a Java int: but if node value cannot be expressed exactly as an int, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Integer values that fit in Java 32-bit signed int range
      • JSON Floating-point values that fit in Java 32-bit signed int range AND do not have fractional part.

      NOTE: for more lenient conversions, use JsonNode.asInt()

      Overrides:
      intValue in class BaseJsonNode
      Returns:
      Int value this node represents, if possible to accurately represent

    • intValue

      public abstract int intValue(int defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.intValue(), but that will return specified defaultValue if this node cannot be converted to Java int.
      Overrides:
      intValue in class BaseJsonNode
      Parameters:
      defaultValue - Value to return if this node cannot be converted to Java int
      Returns:
      Java int value this node represents, if possible to accurately represent; defaultValue otherwise

    • intValueOpt

      public abstract OptionalInt intValueOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.intValue(), but that will return empty OptionalInt (OptionalInt.empty()) if this node cannot be converted to Java int.
      Overrides:
      intValueOpt in class BaseJsonNode
      Returns:
      Java int value this node represents, as OptionalInt, if possible to accurately represent; OptionalInt.empty() otherwise

    • asInt

      public abstract int asInt()
      Description copied from class: JsonNode
      Method similar to JsonNode.intValue() but in addition to coercing Number values (same as JsonNode.intValue()), will also try to coerce a couple of additional types (or cases):
      • JSON Floating-point numbers with fractions (ones without fractions are ok for JsonNode.intValue()) will be truncated to int (if (and only if) they fit in int range).
      • JSON Strings that represent JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0))
      • POJO nodes that contain Number values
      Overrides:
      asInt in class BaseJsonNode
      Returns:
      int value this node represents, if possible to accurately represent

    • asInt

      public abstract int asInt(int defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.intValue(), but that will return specified defaultValue if this node cannot be converted to int.
      Overrides:
      asInt in class BaseJsonNode
      Parameters:
      defaultValue - Value to return if this node cannot be converted to int
      Returns:
      int value this node represents, if possible to accurately represent; defaultValue otherwise

    • asIntOpt

      public abstract OptionalInt asIntOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.asInt(), but that will return (OptionalInt.empty()) if this node cannot be coerced to int.
      Overrides:
      asIntOpt in class BaseJsonNode
      Returns:
      OptionalInt value this node represents, if possible to accurately represent; OptionalInt.empty() otherwise

    • longValue

      public abstract long longValue()
      Description copied from class: JsonNode
      Method that will try to access value of this node as a Java long: but if node value cannot be expressed exactly as a long, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Integer values that fit in Java 64-bit signed long range
      • JSON Floating-point values that fit in Java 64-bit signed long range AND do not have fractional part.

      NOTE: for more lenient conversions, use JsonNode.asLong()

      Overrides:
      longValue in class BaseJsonNode
      Returns:
      Long value this node represents, if possible to accurately represent

    • longValue

      public abstract long longValue(long defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.longValue(), but that will return specified defaultValue if this node cannot be converted to long.
      Overrides:
      longValue in class BaseJsonNode
      Parameters:
      defaultValue - Value to return if this node cannot be converted to long
      Returns:
      long value this node represents, if possible to accurately represent; defaultValue otherwise

    • longValueOpt

      public abstract OptionalLong longValueOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.longValue(), but that will return empty OptionalLong (OptionalLong.empty()) if this node cannot be converted to Java long.
      Overrides:
      longValueOpt in class BaseJsonNode
      Returns:
      Java long value this node represents, as OptionalLong, if possible to accurately represent; OptionalLong.empty() otherwise

    • asLong

      public abstract long asLong()
      Description copied from class: JsonNode
      Method similar to JsonNode.longValue() but in addition to coercing Number values (same as JsonNode.longValue()), will also try to coerce a couple of additional types (or cases):
      • JSON Floating-point numbers with fractions (ones without fractions are ok for JsonNode.longValue()) will be truncated to long (if (and only if) they fit in long range).
      • JSON Strings that represent JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0))
      • POJO nodes that contain Number values
      Overrides:
      asLong in class BaseJsonNode
      Returns:
      long value this node represents, if possible to accurately represent

    • asLong

      public abstract long asLong(long defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.asLong(), but that will return specified defaultValue if this node cannot be coerced to long (instead of throwing an exception).
      Overrides:
      asLong in class BaseJsonNode
      Parameters:
      defaultValue - Value to return if this node cannot be coerced to long
      Returns:
      long value this node represents, if possible to accurately represent; defaultValue otherwise

    • asLongOpt

      public abstract OptionalLong asLongOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.asLong(), but that will return (OptionalLong.empty()) if this node cannot be coerced to long.
      Overrides:
      asLongOpt in class BaseJsonNode
      Returns:
      OptionalLong value this node represents (or can be coerced to), OptionalLong.empty() otherwise

    • bigIntegerValue

      public abstract BigInteger bigIntegerValue()
      Description copied from class: JsonNode
      Method that will try to access value of this node as a BigInteger, but if node value cannot be expressed exactly as a BigInteger, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Integer values
      • JSON Floating-point values that do not have fractional part.

      Overrides:
      bigIntegerValue in class BaseJsonNode
      Returns:
      BigInteger value this node represents, if possible to accurately represent

    • bigIntegerValue

      public abstract BigInteger bigIntegerValue(BigInteger defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.bigIntegerValue(), but that will return specified defaultValue if this node cannot be converted to Java BigInteger.
      Overrides:
      bigIntegerValue in class BaseJsonNode
      Parameters:
      defaultValue - Value to return if this node cannot be converted to Java BigInteger
      Returns:
      Java BigInteger value this node represents, if possible to accurately represent; defaultValue otherwise

    • bigIntegerValueOpt

      public abstract Optional<BigInteger> bigIntegerValueOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.bigIntegerValue(), but that will return empty (Optional.empty()) if this node cannot be converted to Java BigInteger.
      Overrides:
      bigIntegerValueOpt in class BaseJsonNode
      Returns:
      Java BigInteger value this node represents, as Optional<BigInteger>, if possible to accurately represent; Optional.empty() otherwise

    • asBigInteger

      public abstract BigInteger asBigInteger()
      Description copied from class: JsonNode
      Method similar to JsonNode.bigIntegerValue() but in addition to coercing Number values (same as JsonNode.bigIntegerValue()), will also try to coerce a couple of additional types (or cases):
      • JSON Floating-point numbers with fractions (ones without fractions are ok for JsonNode.bigIntegerValue()) will be truncated to integer value (like with BigDecimal.toBigInteger()))
      • JSON Strings that represent JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0))
      • POJO nodes that contain Number values
      Overrides:
      asBigInteger in class BaseJsonNode
      Returns:
      BigInteger value this node represents, if possible to accurately convert; defaultValue otherwise

    • asBigInteger

      public abstract BigInteger asBigInteger(BigInteger defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.asBigInteger(), but that will return specified defaultValue if this node cannot be converted to BigInteger.
      Overrides:
      asBigInteger in class BaseJsonNode
      Parameters:
      defaultValue - Value to return if this node cannot be converted to BigInteger
      Returns:
      BigInteger value this node represents, if possible to accurately convert; defaultValue otherwise

    • asBigIntegerOpt

      public abstract Optional<BigInteger> asBigIntegerOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.bigIntegerValue(), but that will return empty (Optional.empty()) if this node cannot be converted to Java BigInteger.
      Overrides:
      asBigIntegerOpt in class BaseJsonNode
      Returns:
      BigInteger value this node represents, as Optional<BigInteger>, if possible to accurately represent; Optional.empty() otherwise.

    • floatValue

      public abstract float floatValue()
      Description copied from class: JsonNode
      Method that will try to access value of this node as a Java float: but if node value cannot be expressed exactly as a float, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Floating-point values that fit in Java 32-bit double range
      • JSON Integer values that fit in Java 32-bit double range

      Overrides:
      floatValue in class BaseJsonNode
      Returns:
      Float value this node represents, if possible to accurately represent

    • floatValue

      public abstract float floatValue(float defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.floatValue(), but that will return specified defaultValue if this node cannot be converted to float.
      Overrides:
      floatValue in class BaseJsonNode
      Parameters:
      defaultValue - Value to return if this node cannot be converted to float
      Returns:
      float value this node represents, if possible to accurately represent; defaultValue otherwise

    • floatValueOpt

      public abstract Optional<Float> floatValueOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.floatValue(), but that will return empty Optional<Float> (Optional.empty()) if this node cannot be converted to Java float.
      Overrides:
      floatValueOpt in class BaseJsonNode
      Returns:
      Java float value this node represents, as Optional<Float>, if possible to accurately represent; Optional.empty() otherwise

    • asFloat

      public abstract float asFloat()
      Description copied from class: JsonNode
      Method similar to JsonNode.floatValue() but in addition to coercing Number values will also try coerce couple of additional types:
      • JSON String that represents JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0.0f)
      • POJO nodes that contain Number values

      Overrides:
      asFloat in class BaseJsonNode
      Returns:
      float value this node represents, if possible to accurately represent

    • asFloat

      public abstract float asFloat(float defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.asFloat(), but that will return defaultValue if this node cannot be coerced to float.
      Overrides:
      asFloat in class BaseJsonNode
      Returns:
      float value this node represents, if possible to accurately represent; defaultValue otherwise

    • asFloatOpt

      public abstract Optional<Float> asFloatOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.asFloat(), but that will return (Optional.empty()) if this node cannot be coerced to float.
      Overrides:
      asFloatOpt in class BaseJsonNode
      Returns:
      Optional<Float> value this node represents, if possible to accurately represent; Optional.empty() otherwise

    • doubleValue

      public abstract double doubleValue()
      Description copied from class: JsonNode
      Method that will try to access value of this node as a double: but if node value cannot be expressed exactly as a double, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Floating-point values that fit in Java 64-bit double range
      • JSON Integer values that fit in Java 64-bit double range

      NOTE: for more lenient conversions, use JsonNode.asDouble()

      Overrides:
      doubleValue in class BaseJsonNode
      Returns:
      Double value this node represents, if possible to accurately represent

    • doubleValue

      public abstract double doubleValue(double defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.doubleValue(), but that will return specified defaultValue if this node cannot be converted to double.
      Overrides:
      doubleValue in class BaseJsonNode
      Parameters:
      defaultValue - Value to return if this node cannot be converted to double
      Returns:
      double value this node represents, if possible to accurately represent; defaultValue otherwise

    • doubleValueOpt

      public abstract OptionalDouble doubleValueOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.doubleValue(), but that will return empty OptionalLong (OptionalDouble.empty()) if this node cannot be converted to Java double.
      Overrides:
      doubleValueOpt in class BaseJsonNode
      Returns:
      Java double value this node represents, as OptionalDouble, if possible to accurately represent; OptionalDouble.empty() otherwise

    • asDouble

      public abstract double asDouble()
      Description copied from class: JsonNode
      Method similar to JsonNode.doubleValue() but in addition to coercing Number values will also try coerce couple of additional types:
      • JSON String that represents JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0.0d)
      • POJO nodes that contain Number values

      Overrides:
      asDouble in class BaseJsonNode
      Returns:
      double value this node represents, if possible to accurately represent

    • asDouble

      public abstract double asDouble(double defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.asDouble(), but that will return defaultValue if this node cannot be coerced to double.
      Overrides:
      asDouble in class BaseJsonNode
      Returns:
      double value this node represents, if possible to accurately represent; defaultValue otherwise

    • asDoubleOpt

      public abstract OptionalDouble asDoubleOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.asDouble(), but that will return (OptionalDouble.empty()) if this node cannot be coerced to double.
      Overrides:
      asDoubleOpt in class BaseJsonNode
      Returns:
      OptionalDouble value this node represents, if possible to accurately represent; OptionalDouble.empty() otherwise

    • decimalValue

      public abstract BigDecimal decimalValue()
      Description copied from class: JsonNode
      Method that will try to access value of this node as a Java BigDecimal: but if node value cannot be expressed exactly as a BigDecimal, a JsonNodeException will be thrown. Access works for following cases:
      • All JSON Number values

      NOTE: for more lenient conversions, use JsonNode.asDecimal()

      Overrides:
      decimalValue in class BaseJsonNode
      Returns:
      BigDecimal value this node represents, if possible to accurately represent

    • decimalValue

      public abstract BigDecimal decimalValue(BigDecimal defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.decimalValue(), but that will return defaultValue if this node cannot be coerced to Java BigDecimal.
      Overrides:
      decimalValue in class BaseJsonNode
      Returns:
      BigDecimal value this node represents, if possible to accurately represent; defaultValue otherwise

    • decimalValueOpt

      public abstract Optional<BigDecimal> decimalValueOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.decimalValue(), but that will return empty Optional (Optional.empty()) if this node cannot be coerced to BigDecimal.
      Overrides:
      decimalValueOpt in class BaseJsonNode
      Returns:
      Java BigDecimal value this node represents, as Optional<BigDecimal>, if possible to accurately represent; Optional.empty() otherwise

    • asDecimal

      public abstract BigDecimal asDecimal()
      Description copied from class: JsonNode
      Method that will try to access value of this node as a BigDecimal: but if node value cannot be expressed exactly as a BigDecimal, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Floating-point values (but not "NaN" or "Infinity")
      • JSON Integer values
      • JSON String that represents JSON Numbers ("stringified" numbers)
      • JSON Null (converted to BigDecimal.ZERO))
      • POJO nodes that contain Number values

      Overrides:
      asDecimal in class BaseJsonNode
      Returns:
      BigDecimal value this node represents, if possible to accurately represent

    • asDecimal

      public abstract BigDecimal asDecimal(BigDecimal defaultValue)
      Description copied from class: JsonNode
      Method similar to JsonNode.asDecimal(), but that will return defaultValue if this node cannot be coerced to Java BigDecimal.
      Overrides:
      asDecimal in class BaseJsonNode
      Returns:
      BigDecimal value this node represents, if possible to accurately represent; defaultValue otherwise

    • asDecimalOpt

      public abstract Optional<BigDecimal> asDecimalOpt()
      Description copied from class: JsonNode
      Method similar to JsonNode.asDecimal(), but that will return empty Optional (Optional.empty()) if this node cannot be coerced to BigDecimal.
      Overrides:
      asDecimalOpt in class BaseJsonNode
      Returns:
      Java BigDecimal value this node represents, as Optional<BigDecimal>, if possible to accurately represent; Optional.empty() otherwise

    • canConvertToShort

      public abstract boolean canConvertToShort()
      Description copied from class: JsonNode
      Method that can be used to check whether this node is a numeric node (JsonNode.isNumber() would return true) AND can be converted without loss to short (that is, its value fits in Java's 16-bit signed integer type, short and if it is a floating-point number, it does not have fractional part).

      NOTE: this method does not consider possible value type conversion from non-number types like JSON String into Number; so even if this method returns false, it is possible that JsonNode.asShort() could still succeed.

      Overrides:
      canConvertToShort in class JsonNode

    • canConvertToInt

      public abstract boolean canConvertToInt()
      Description copied from class: JsonNode
      Method that can be used to check whether this node is a numeric node (JsonNode.isNumber() would return true) AND can be converted without loss to int (that is, its value fits in Java's 32-bit signed integer type, int and if it is a floating-point number, it does not have fractional part).

      NOTE: this method does not consider possible value type conversion from non-number types like JSON String into Number; so even if this method returns false, it is possible that JsonNode.asInt() could still succeed.

      Overrides:
      canConvertToInt in class JsonNode

    • canConvertToLong

      public abstract boolean canConvertToLong()
      Description copied from class: JsonNode
      Method that can be used to check whether this node is a numeric node (JsonNode.isNumber() would return true) AND can be converted without loss to long (that is, its value fits in Java's 64-bit signed integer type, long and if it is a floating-point number, it does not have fractional part).

      NOTE: this method does not consider possible value type conversion from non-number types like JSON String into Number; so even if this method returns false, it is possible that JsonNode.asLong() could still succeed.

      Overrides:
      canConvertToLong in class JsonNode

    • _asString

      protected abstract String _asString()
      Description copied from class: BaseJsonNode
      Method sub-classes should override if they can produce String values via BaseJsonNode.asString() -- if not, return null (in which case appropriate error will be thrown or default value returned).
      Overrides:
      _asString in class BaseJsonNode
      Returns:
      Coerced value if possible; otherwise null to indicate this node cannot be coerced.

    • hasFractionalPart

      public abstract boolean hasFractionalPart()
      Convenience method for checking whether this node is a NumericFPNode that contains non-zero fractional part (as opposed to only integer part). Always returns false for integral NumericNodes (that is, s).

    • inShortRange

      public abstract boolean inShortRange()
      Method that can be used to determine whether this numeric value's in part fits within Java 16-bit short type.

    • inIntRange

      public abstract boolean inIntRange()
      Method that can be used to determine whether this numeric value's in part fits within Java 32-bitint type.

    • inLongRange

      public abstract boolean inLongRange()
      Method that can be used to determine whether this numeric value's in part fits within Java 64-bit long type.

    • isNaN

      public abstract boolean isNaN()
      Convenience method for checking whether this node is a FloatNode or DoubleNode that contains "not-a-number" (NaN) value.

    • _asShortValueUnchecked

      public abstract short _asShortValueUnchecked()
      Method for sub-classes to implement; returns the underlying value as a short without any checks (wrt NaN or value range), so caller must ensure validity prior to calling

    • _asIntValueUnchecked

      public abstract int _asIntValueUnchecked()
      Method for sub-classes to implement; returns the underlying value as a int without any checks (wrt NaN or value range), so caller must ensure validity prior to calling

    • _asLongValueUnchecked

      public abstract long _asLongValueUnchecked()
      Method for sub-classes to implement; returns the underlying value as a long without any checks (wrt NaN or value range), so caller must ensure validity prior to calling