001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.revetsec.json; 018 019import org.jspecify.annotations.NonNull; 020 021import javax.annotation.concurrent.Immutable; 022 023/** 024 * An immutable JSON value (RFC 8259): exactly one of {@link JsonObject}, {@link JsonArray}, {@link JsonString}, 025 * {@link JsonNumber}, {@link JsonBoolean} or {@link JsonNull}. 026 * <p> 027 * The permitted subtypes are frozen within a major version, so an exhaustive {@code instanceof} chain or, on newer 028 * Java releases, a pattern {@code switch} over them stays exhaustive. 029 * <p> 030 * <strong>Invariants.</strong> Every value is immutable and holds no {@code null}. Its strings and member names are 031 * well-formed UTF-16 (no unpaired surrogate). It nests at most 64 deep, where a scalar or an empty container has 032 * depth 1 and any other container is 1 deeper than its deepest child (member names add nothing). A number has at most 033 * 4,096 significant digits and an adjusted decimal exponent of magnitude at most 100,000. The factories reject a 034 * {@code null} with {@link NullPointerException} and anything else outside these invariants with 035 * {@link IllegalArgumentException}, so no content can make {@link #toJson()}, {@code equals} or {@code hashCode} 036 * throw, and none of them recurses more than 64 levels deep. 037 * <p> 038 * <strong>Cost.</strong> {@code hashCode} never walks nested values: containers compute theirs once, at construction. 039 * A value may hold the same instance in several places, and {@link #toJson()} and {@code equals} then visit it once 040 * per occurrence, so their work, and the length of the JSON text, follow the value's expanded tree, not the number of 041 * objects it holds. A value that nests one instance repeatedly can therefore be far larger than its objects: its 042 * {@link #toJson()} can run out of memory, and {@code equals} against a copy built separately can take exponential 043 * time. A value parsed from JSON text is always a tree, so its cost is proportional to that text. 044 * <p> 045 * <strong>Equality.</strong> Numbers compare by numeric value ({@code 1}, {@code 1.0} and {@code 1E0} are equal), 046 * objects compare their members by name regardless of order, arrays compare element by element in order, and strings 047 * and member names compare exactly, with no case folding or Unicode normalization. {@code hashCode} is consistent 048 * with {@code equals} but not resistant to collisions: strings use {@link String#hashCode()}, containers combine 049 * their contents' hashes, and no value type is {@link Comparable}. So a {@code HashMap} or {@code HashSet} keyed by 050 * values that someone else chooses can degrade to quadratic time. 051 * <p> 052 * <strong>Rendering.</strong> {@code toString()} never shows content: it renders {@code SimpleName{...=<redacted>}}, 053 * so a value that holds a secret or personal data is safe to log. {@link #toJson()} is the method that emits 054 * content. 055 * 056 * @author <a href="https://www.revetkn.com">Mark Allen</a> 057 * @since 1.0.0 058 */ 059@Immutable 060public sealed interface JsonValue permits JsonObject, JsonArray, JsonString, JsonNumber, JsonBoolean, JsonNull { 061 /** 062 * Serializes this value as compact JSON text: no insignificant whitespace, members in insertion order, and numbers 063 * in the canonical form of {@link java.math.BigDecimal#toString()} ({@code 1e2} becomes {@code 1E+2}). 064 * <p> 065 * Strings escape only what JSON requires: the quotation mark, the reverse solidus and the control characters 066 * U+0000 to U+001F, using the two-character escapes where they exist. Every other character, U+2028 and U+2029 067 * included, is written as itself. 068 * <p> 069 * Unlike {@code toString()}, the result contains every string and number this value holds. It is not the text a 070 * value was parsed from, so never verify a signature over it. 071 * 072 * @return the JSON text 073 * @since 1.0.0 074 */ 075 @NonNull String toJson(); 076}