Interface JsonValue
- All Known Implementing Classes:
JsonArray, JsonBoolean, JsonNull, JsonNumber, JsonObject, JsonString
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 TypeMethodDescriptiontoJson()Serializes this value as compact JSON text: no insignificant whitespace, members in insertion order, and numbers in the canonical form ofBigDecimal.toString()(1e2becomes1E+2).
-
Method Details
-
toJson
Serializes this value as compact JSON text: no insignificant whitespace, members in insertion order, and numbers in the canonical form ofBigDecimal.toString()(1e2becomes1E+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
-