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