Interface JsonValue

All Known Implementing Classes:
JsonArray, JsonBoolean, JsonNull, JsonNumber, JsonObject, JsonString

An immutable JSON value (RFC 8259): exactly one of JsonObject, JsonArray, JsonString, JsonNumber, JsonBoolean or JsonNull.

The permitted subtypes are frozen within a major version, so an exhaustive instanceof chain or, on newer Java releases, a pattern switch over them stays exhaustive.

Invariants. Every value is immutable and holds no null. Its strings and member names are well-formed UTF-16 (no unpaired surrogate). It nests at most 64 deep, where a scalar or an empty container has depth 1 and any other container is 1 deeper than its deepest child (member names add nothing). A number has at most 4,096 significant digits and an adjusted decimal exponent of magnitude at most 100,000. The factories reject a null with NullPointerException and anything else outside these invariants with IllegalArgumentException, so no content can make toJson(), equals or hashCode throw, and none of them recurses more than 64 levels deep.

Cost. hashCode never walks nested values: containers compute theirs once, at construction. A value may hold the same instance in several places, and toJson() and equals then visit it once per occurrence, so their work, and the length of the JSON text, follow the value's expanded tree, not the number of objects it holds. A value that nests one instance repeatedly can therefore be far larger than its objects: its toJson() can run out of memory, and equals against a copy built separately can take exponential time. A value parsed from JSON text is always a tree, so its cost is proportional to that text.

Equality. Numbers compare by numeric value (1, 1.0 and 1E0 are equal), objects compare their members by name regardless of order, arrays compare element by element in order, and strings and member names compare exactly, with no case folding or Unicode normalization. hashCode is consistent with equals but not resistant to collisions: strings use String.hashCode(), containers combine their contents' hashes, and no value type is Comparable. So a HashMap or HashSet keyed by values that someone else chooses can degrade to quadratic time.

Rendering. toString() never shows content: it renders SimpleName{...=<redacted>}, so a value that holds a secret or personal data is safe to log. toJson() is the method that emits content.

Since:
1.0.0
Author:
Mark Allen
  • Method Summary

    Modifier and Type
    Method
    Description
    Serializes this value as compact JSON text: no insignificant whitespace, members in insertion order, and numbers in the canonical form of BigDecimal.toString() (1e2 becomes 1E+2).
  • Method Details

    • toJson

      Serializes this value as compact JSON text: no insignificant whitespace, members in insertion order, and numbers in the canonical form of BigDecimal.toString() (1e2 becomes 1E+2).

      Strings escape only what JSON requires: the quotation mark, the reverse solidus and the control characters U+0000 to U+001F, using the two-character escapes where they exist. Every other character, U+2028 and U+2029 included, is written as itself.

      Unlike toString(), the result contains every string and number this value holds. It is not the text a value was parsed from, so never verify a signature over it.

      Returns:
      the JSON text
      Since:
      1.0.0