001 /*
002 * Copyright 2015-2017 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2015-2017 UnboundID Corp.
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021 package com.unboundid.util.json;
022
023
024
025 import java.io.Serializable;
026
027 import com.unboundid.util.NotExtensible;
028 import com.unboundid.util.ThreadSafety;
029 import com.unboundid.util.ThreadSafetyLevel;
030
031
032
033 /**
034 * This class provides the base class for data types that can be used as values
035 * in JSON objects and as elements in JSON arrays. The types of values defined
036 * in the ECMA-404 specification are:
037 * <UL>
038 * <LI>
039 * The {@code null} value, as implemented in the {@link JSONNull} class.
040 * </LI>
041 * <LI>
042 * The Boolean {@code true} and {@code false} values, as implemented in the
043 * {@link JSONBoolean} class.
044 * </LI>
045 * <LI>
046 * Numeric values, as implemented in the {@link JSONNumber} class.
047 * </LI>
048 * <LI>
049 * String values, as implemented in the {@link JSONString} class.
050 * </LI>
051 * <LI>
052 * Object values (consisting of zero or more name-value pairs), as
053 * implemented in the {@link JSONObject} class.
054 * </LI>
055 * <LI>
056 * Arrays of JSON values, as implemented in the {@link JSONArray} class.
057 * </LI>
058 * </UL>
059 */
060 @NotExtensible()
061 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
062 public abstract class JSONValue
063 implements Serializable
064 {
065 /**
066 * A serial version UID for this serializable class.
067 */
068 private static final long serialVersionUID = -4446120225858980451L;
069
070
071
072 /**
073 * Retrieves a hash code for this JSON value.
074 *
075 * @return The hash code for this JSON value.
076 */
077 public abstract int hashCode();
078
079
080
081 /**
082 * Indicates whether the provided object is equal to this JSON value.
083 *
084 * @param o The object to compare against this JSON value.
085 *
086 * @return {@code true} if the provided object is considered equal to this
087 * JSON value, or {@code false} if not.
088 */
089 public abstract boolean equals(final Object o);
090
091
092
093 /**
094 * Indicates whether this JSON value is considered equal to the provided JSON
095 * value, subject to the specified constraints. Note that not all constraints
096 * will apply to all data types.
097 *
098 * @param v The JSON value for which to make the
099 * determination. It must not be {@code null}.
100 * @param ignoreFieldNameCase Indicates whether to ignore differences in the
101 * capitalization of JSON field names.
102 * @param ignoreValueCase Indicates whether to ignore differences in
103 * the capitalization of JSON values that
104 * represent strings.
105 * @param ignoreArrayOrder Indicates whether to ignore differences in the
106 * order of elements in JSON arrays.
107 *
108 * @return {@code true} if this JSON value is considered equal to the
109 * provided JSON value (subject to the specified constraints), or
110 * {@code false} if not.
111 */
112 public abstract boolean equals(final JSONValue v,
113 final boolean ignoreFieldNameCase,
114 final boolean ignoreValueCase,
115 final boolean ignoreArrayOrder);
116
117
118
119 /**
120 * Retrieves a string representation of this value as it should appear in a
121 * JSON object, including any necessary quoting, escaping, etc. If the object
122 * containing this value was decoded from a string, then this method will use
123 * the same string representation as in that original object. Otherwise, the
124 * string representation will be constructed.
125 *
126 * @return A string representation of this value as it should appear in a
127 * JSON object.
128 */
129 public abstract String toString();
130
131
132
133 /**
134 * Appends a string representation of this value (as it should appear in a
135 * JSON object, including any necessary quoting, escaping, etc.) to the
136 * provided buffer. If the object containing this value was decoded from a
137 * string, then this method will use the same string representation as in that
138 * original object. Otherwise, the string representation will be constructed.
139 *
140 * @param buffer The buffer to which the information should be appended.
141 */
142 public abstract void toString(final StringBuilder buffer);
143
144
145
146 /**
147 * Retrieves a single-line string representation of this value as it should
148 * appear in a JSON object, including any necessary quoting, escaping, etc.
149 *
150 * @return A string representation of this value as it should appear in a
151 * JSON object.
152 */
153 public abstract String toSingleLineString();
154
155
156
157 /**
158 * Appends a single-line string representation of this value (as it should
159 * appear in a JSON object, including any necessary quoting, escaping, etc.)
160 * to the provided buffer.
161 *
162 * @param buffer The buffer to which the information should be appended.
163 */
164 public abstract void toSingleLineString(final StringBuilder buffer);
165
166
167
168 /**
169 * Retrieves a normalized string representation of this value. All equivalent
170 * JSON values must have equivalent normalized representations, even if there
171 * are other legal representations for the value.
172 *
173 * @return A normalized string representation of this value.
174 */
175 public abstract String toNormalizedString();
176
177
178
179 /**
180 * Appends a normalized string representation of this value to the provided
181 * buffer. All equivalent JSON values must have equivalent normalized
182 * representations, even if there are other legal representations for the
183 * value.
184 *
185 * @param buffer The buffer to which the information should be appended.
186 */
187 public abstract void toNormalizedString(final StringBuilder buffer);
188
189
190
191 /**
192 * Appends this value to the provided JSON buffer. This will not include a
193 * field name, so it should only be used for Boolean value elements in an
194 * array.
195 *
196 * @param buffer The JSON buffer to which this value should be appended.
197 */
198 public abstract void appendToJSONBuffer(final JSONBuffer buffer);
199
200
201
202 /**
203 * Appends a field with the given name and this value to the provided JSON
204 * buffer.
205 *
206 * @param fieldName The name to use for the field.
207 * @param buffer The JSON buffer to which this value should be appended.
208 */
209 public abstract void appendToJSONBuffer(final String fieldName,
210 final JSONBuffer buffer);
211 }