001/*
002 * Copyright 2015-2019 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2015-2019 Ping Identity Corporation
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 */
021package com.unboundid.util.json;
022
023
024
025import java.io.Serializable;
026
027import com.unboundid.util.NotExtensible;
028import com.unboundid.util.ThreadSafety;
029import 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)
062public 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(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(JSONValue v, boolean ignoreFieldNameCase,
113                                 boolean ignoreValueCase,
114                                 boolean ignoreArrayOrder);
115
116
117
118  /**
119   * Retrieves a string representation of this value as it should appear in a
120   * JSON object, including any necessary quoting, escaping, etc.  If the object
121   * containing this value was decoded from a string, then this method will use
122   * the same string representation as in that original object.  Otherwise, the
123   * string representation will be constructed.
124   *
125   * @return  A string representation of this value as it should appear in a
126   *          JSON object.
127   */
128  public abstract String toString();
129
130
131
132  /**
133   * Appends a string representation of this value (as it should appear in a
134   * JSON object, including any necessary quoting, escaping, etc.) to the
135   * provided buffer.  If the object containing this value was decoded from a
136   * string, then this method will use the same string representation as in that
137   * original object.  Otherwise, the string representation will be constructed.
138   *
139   * @param  buffer  The buffer to which the information should be appended.
140   */
141  public abstract void toString(StringBuilder buffer);
142
143
144
145  /**
146   * Retrieves a single-line string representation of this value as it should
147   * appear in a JSON object, including any necessary quoting, escaping, etc.
148   *
149   * @return  A string representation of this value as it should appear in a
150   *          JSON object.
151   */
152  public abstract String toSingleLineString();
153
154
155
156  /**
157   * Appends a single-line string representation of this value (as it should
158   * appear in a JSON object, including any necessary quoting, escaping, etc.)
159   * to the provided buffer.
160   *
161   * @param  buffer  The buffer to which the information should be appended.
162   */
163  public abstract void toSingleLineString(StringBuilder buffer);
164
165
166
167  /**
168   * Retrieves a normalized string representation of this value.  All equivalent
169   * JSON values must have equivalent normalized representations, even if there
170   * are other legal representations for the value.
171   *
172   * @return  A normalized string representation of this value.
173   */
174  public abstract String toNormalizedString();
175
176
177
178  /**
179   * Appends a normalized string representation of this value to the provided
180   * buffer.  All equivalent JSON values must have equivalent normalized
181   * representations, even if there are other legal representations for the
182   * value.
183   *
184   * @param  buffer  The buffer to which the information should be appended.
185   */
186  public abstract void toNormalizedString(StringBuilder buffer);
187
188
189
190  /**
191   * Retrieves a normalized string representation of this value using the
192   * provided settings.
193   *
194   * @param  ignoreFieldNameCase  Indicates whether field names should be
195   *                              treated in a case-sensitive (if {@code false})
196   *                              or case-insensitive (if {@code true}) manner.
197   * @param  ignoreValueCase      Indicates whether string field values should
198   *                              be treated in a case-sensitive (if
199   *                              {@code false}) or case-insensitive (if
200   *                              {@code true}) manner.
201   * @param  ignoreArrayOrder     Indicates whether the order of elements in an
202   *                              array should be considered significant (if
203   *                              {@code false}) or insignificant (if
204   *                              {@code true}).
205   *
206   * @return  A normalized string representation of this value.
207   */
208  public abstract String toNormalizedString(boolean ignoreFieldNameCase,
209                                            boolean ignoreValueCase,
210                                            boolean ignoreArrayOrder);
211
212
213
214  /**
215   * Appends a normalized string representation of this value to the provided
216   * buffer using the provided settings.
217   *
218   * @param  buffer               The buffer to which the information should be
219   *                              appended.
220   * @param  ignoreFieldNameCase  Indicates whether field names should be
221   *                              treated in a case-sensitive (if {@code false})
222   *                              or case-insensitive (if {@code true}) manner.
223   * @param  ignoreValueCase      Indicates whether string field values should
224   *                              be treated in a case-sensitive (if
225   *                              {@code false}) or case-insensitive (if
226   *                              {@code true}) manner.
227   * @param  ignoreArrayOrder     Indicates whether the order of elements in an
228   *                              array should be considered significant (if
229   *                              {@code false}) or insignificant (if
230   *                              {@code true}).
231   */
232  public abstract void toNormalizedString(StringBuilder buffer,
233                                          boolean ignoreFieldNameCase,
234                                          boolean ignoreValueCase,
235                                          boolean ignoreArrayOrder);
236
237
238
239  /**
240   * Appends this value to the provided JSON buffer.  This will not include a
241   * field name, so it should only be used for Boolean value elements in an
242   * array.
243   *
244   * @param  buffer  The JSON buffer to which this value should be appended.
245   */
246  public abstract void appendToJSONBuffer(JSONBuffer buffer);
247
248
249
250  /**
251   * Appends a field with the given name and this value to the provided JSON
252   * buffer.
253   *
254   * @param  fieldName  The name to use for the field.
255   * @param  buffer     The JSON buffer to which this value should be appended.
256   */
257  public abstract void appendToJSONBuffer(String fieldName, JSONBuffer buffer);
258}