1 /*
2 * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package oracle.code.json;
27
28 /**
29 * The interface that represents a JSON value.
30 * <p>
31 * Instances of {@code JsonValue} are immutable and thread safe.
32 * <p>
33 * A {@code JsonValue} can be produced by {@link Json#parse(String)} or {@link
34 * Json#fromUntyped(Object)}. See {@link #toString()} for converting a {@code
35 * JsonValue} to its corresponding JSON String. For example,
36 * {@snippet lang=java:
37 * List<Object> values = Arrays.asList("foo", true, 25);
38 * JsonValue json = Json.fromUntyped(values);
39 * json.toString(); // returns "[\"foo\",true,25]"
40 * }
41 *
42 * A class implementing a non-sealed {@code JsonValue} sub-interface must adhere
43 * to the following:
44 * <ul>
45 * <li>The class's implementations of {@code equals}, {@code hashCode},
46 * and {@code toString} compute their results solely from the values
47 * of the class's instance fields (and the members of the objects they
48 * reference), not from the instance's identity.</li>
49 * <li>The class's methods treat instances as <em>freely substitutable</em>
50 * when equal, meaning that interchanging any two instances {@code x} and
51 * {@code y} that are equal according to {@code equals()} produces no
52 * visible change in the behavior of the class's methods.</li>
53 * <li>The class performs no synchronization using an instance's monitor.</li>
54 * <li>The class does not provide any instance creation mechanism that promises
55 * a unique identity on each method call—in particular, any factory
56 * method's contract must allow for the possibility that if two independently-produced
57 * instances are equal according to {@code equals()}, they may also be
58 * equal according to {@code ==}.</li>
59 * </ul>
60 * <p>
61 * Users of {@code JsonValue} instances should ensure the following:
62 * <ul>
63 * <li> When two instances of {@code JsonValue} are equal (according to {@code equals()}), users
64 * should not attempt to distinguish between their identities, whether directly via reference
65 * equality or indirectly via an appeal to synchronization, identity hashing,
66 * serialization, or any other identity-sensitive mechanism.</li>
67 * <li> Synchronization on instances of {@code JsonValue} is strongly discouraged,
68 * because the programmer cannot guarantee exclusive ownership of the
69 * associated monitor.</li>
70 * </ul>
71 *
72 * @since 99
73 */
74 public sealed interface JsonValue
75 permits JsonString, JsonNumber, JsonObject, JsonArray, JsonBoolean, JsonNull {
76
77 /**
78 * {@return the String representation of this {@code JsonValue} that conforms
79 * to the JSON syntax} If this {@code JsonValue} is created by parsing a
80 * JSON document, it preserves the text representation of the corresponding
81 * JSON element, except that the returned string does not contain any white
82 * spaces or newlines to produce a compact representation.
83 * For a String representation suitable for display, use
84 * {@link Json#toDisplayString(JsonValue)}.
85 *
86 * @see Json#toDisplayString(JsonValue)
87 */
88 String toString();
89 }