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. {@code JsonValue} is the type returned
30  * by a {@link Json#parse(String)}. Valid subtypes are either {@code JsonString},
31  * {@code JsonNumber}, {@code JsonObject}, {@code JsonArray}, {@code JsonBoolean},
32  * or {@code JsonNull}.
33  * <p>
34  * See {@link Json#toUntyped(JsonValue)} and {@link Json#fromUntyped(Object)} for converting
35  * between a {@code JsonValue} and its corresponding data type. For example,
36  * {@snippet lang=java:
37  *     var values = Arrays.asList("foo", true, 25);
38  *     var json = Json.fromUntyped(values);
39  *     Json.toUntyped(json).equals(values); // returns true
40  * }
41  * See {@link #toString()} for converting a {@code JsonValue}
42  * to its corresponding JSON String. For example,
43  * {@snippet lang=java:
44  *     var values = Arrays.asList("foo", true, 25);
45  *     var json = Json.fromUntyped(values);
46  *     json.toString(); // returns "[\"foo\",true,25]"
47  * }
48  *
49  */
50 public sealed interface JsonValue
51         permits JsonString, JsonNumber, JsonObject, JsonArray, JsonBoolean, JsonNull {
52 
53     /**
54      * {@return the String representation of this {@code JsonValue} that conforms
55      * to the JSON syntax} The returned string do not contain any white spaces
56      * or newlines to produce a compact representation.
57      */
58     @Override
59     String toString();
60 
61     /**
62      * Indicates whether the given {@code obj} is "equal to" this {@code JsonValue}.
63      *
64      * @implSpec The comparison is based on the original document if it was produced by
65      * parsing a JSON document.
66      */
67     @Override
68     boolean equals(Object obj);
69 
70     // TBD: do we need this override?
71     /**
72      * {@return the hash code value of this {@code JsonValue}}
73      *
74      * @implSpec The returned hash code is based on the original document if it was
75      * produced by parsing a JSON document.
76      */
77     @Override
78     int hashCode();
79 }