001    /*
002     * Copyright 2015-2016 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2015-2016 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.
122       *
123       * @return A string representation of this value as it should appear in a
124       *          JSON object.
125       */
126      public abstract String toString();
127    
128    
129    
130      /**
131       * Appends a string representation of this value (as it should appear in a
132       * JSON object, including any necessary quoting, escaping, etc.) to the
133       * provided buffer.
134       *
135       * @param  buffer  The buffer to which the information should be appended.
136       */
137      public abstract void toString(final StringBuilder buffer);
138    
139    
140    
141      /**
142       * Retrieves a single-line string representation of this value as it should
143       * appear in a JSON object, including any necessary quoting, escaping, etc.
144       *
145       * @return  A string representation of this value as it should appear in a
146       *          JSON object.
147       */
148      public abstract String toSingleLineString();
149    
150    
151    
152      /**
153       * Appends a single-line string representation of this value (as it should
154       * appear in a JSON object, including any necessary quoting, escaping, etc.)
155       * to the provided buffer.
156       *
157       * @param  buffer  The buffer to which the information should be appended.
158       */
159      public abstract void toSingleLineString(final StringBuilder buffer);
160    
161    
162    
163      /**
164       * Retrieves a normalized string representation of this value.  All equivalent
165       * JSON values must have equivalent normalized representations, even if there
166       * are other legal representations for the value.
167       *
168       * @return  A normalized string representation of this value.
169       */
170      public abstract String toNormalizedString();
171    
172    
173    
174      /**
175       * Appends a normalized string representation of this value to the provided
176       * buffer.  All equivalent JSON values must have equivalent normalized
177       * representations, even if there are other legal representations for the
178       * value.
179       *
180       * @param  buffer  The buffer to which the information should be appended.
181       */
182      public abstract void toNormalizedString(final StringBuilder buffer);
183    
184    
185    
186      /**
187       * Appends this value to the provided JSON buffer.  This will not include a
188       * field name, so it should only be used for Boolean value elements in an
189       * array.
190       *
191       * @param  buffer  The JSON buffer to which this value should be appended.
192       */
193      public abstract void appendToJSONBuffer(final JSONBuffer buffer);
194    
195    
196    
197      /**
198       * Appends a field with the given name and this value to the provided JSON
199       * buffer.
200       *
201       * @param  fieldName  The name to use for the field.
202       * @param  buffer     The JSON buffer to which this value should be appended.
203       */
204      public abstract void appendToJSONBuffer(final String fieldName,
205                                              final JSONBuffer buffer);
206    }