src/org/json/JSONWriter.java

   1 package org.json;
   2
   3 import java.io.IOException;
   4 import java.math.BigDecimal;
   5 import java.util.Collection;
   6 import java.util.Map;
   7
   8 /*
   9 Copyright (c) 2006 JSON.org
  10
  11 Permission is hereby granted, free of charge, to any person obtaining a copy
  12 of this software and associated documentation files (the "Software"), to deal
  13 in the Software without restriction, including without limitation the rights
  14 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  15 copies of the Software, and to permit persons to whom the Software is
  16 furnished to do so, subject to the following conditions:
  17
  18 The above copyright notice and this permission notice shall be included in all
  19 copies or substantial portions of the Software.
  20
  21 The Software shall be used for Good, not Evil.
  22
  23 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  24 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  25 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  26 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  27 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  28 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  29 SOFTWARE.
  30 */
  31
  32 /**
  33  * JSONWriter provides a quick and convenient way of producing JSON text.
  34  * The texts produced strictly conform to JSON syntax rules. No whitespace is
  35  * added, so the results are ready for transmission or storage. Each instance of
  36  * JSONWriter can produce one JSON text.
  37  * <p>
  38  * A JSONWriter instance provides a <code>value</code> method for appending
  39  * values to the
  40  * text, and a <code>key</code>
  41  * method for adding keys before values in objects. There are <code>array</code>
  42  * and <code>endArray</code> methods that make and bound array values, and
  43  * <code>object</code> and <code>endObject</code> methods which make and bound
  44  * object values. All of these methods return the JSONWriter instance,
  45  * permitting a cascade style. For example, <pre>
  46  * new JSONWriter(myWriter)
  47  *     .object()
  48  *         .key("JSON")
  49  *         .value("Hello, World!")
  50  *     .endObject();</pre> which writes <pre>
  51  * {"JSON":"Hello, World!"}</pre>
  52  * <p>
  53  * The first method called must be <code>array</code> or <code>object</code>.
  54  * There are no methods for adding commas or colons. JSONWriter adds them for
  55  * you. Objects and arrays can be nested up to 200 levels deep.
  56  * <p>
  57  * This can sometimes be easier than using a JSONObject to build a string.
  58  * @author JSON.org
  59  * @version 2016-08-08
  60  */
  61 public class JSONWriter {
  62     private static final int maxdepth = 200;
  63
  64     /**
  65      * The comma flag determines if a comma should be output before the next
  66      * value.
  67      */
  68     private boolean comma;
  69
  70     /**
  71      * The current mode. Values:
  72      * 'a' (array),
  73      * 'd' (done),
  74      * 'i' (initial),
  75      * 'k' (key),
  76      * 'o' (object).
  77      */
  78     protected char mode;
  79
  80     /**
  81      * The object/array stack.
  82      */
  83     private final JSONObject stack[];
  84
  85     /**
  86      * The stack top index. A value of 0 indicates that the stack is empty.
  87      */
  88     private int top;
  89
  90     /**
  91      * The writer that will receive the output.
  92      */
  93     protected Appendable writer;
  94
  95     /**
  96      * Make a fresh JSONWriter. It can be used to build one JSON text.
  97      */
  98     public JSONWriter(Appendable w) {
  99         this.comma = false;
 100         this.mode = 'i';
 101         this.stack = new JSONObject[maxdepth];
 102         this.top = 0;
 103         this.writer = w;
 104     }
 105
 106     /**
 107      * Append a value.
 108      * @param string A string value.
 109      * @return this
 110      * @throws JSONException If the value is out of sequence.
 111      */
 112     private JSONWriter append(String string) throws JSONException {
 113         if (string == null) {
 114             throw new JSONException("Null pointer");
 115         }
 116         if (this.mode == 'o' || this.mode == 'a') {
 117             try {
 118                 if (this.comma && this.mode == 'a') {
 119                     this.writer.append(',');
 120                 }
 121                 this.writer.append(string);
 122             } catch (IOException e) {
 123                 // Android as of API 25 does not support this exception constructor
 124                 // however we won't worry about it. If an exception is happening here
 125                 // it will just throw a "Method not found" exception instead.
 126                 throw new JSONException(e);
 127             }
 128             if (this.mode == 'o') {
 129                 this.mode = 'k';
 130             }
 131             this.comma = true;
 132             return this;
 133         }
 134         throw new JSONException("Value out of sequence.");
 135     }
 136
 137     /**
 138      * Begin appending a new array. All values until the balancing
 139      * <code>endArray</code> will be appended to this array. The
 140      * <code>endArray</code> method must be called to mark the array's end.
 141      * @return this
 142      * @throws JSONException If the nesting is too deep, or if the object is
 143      * started in the wrong place (for example as a key or after the end of the
 144      * outermost array or object).
 145      */
 146     public JSONWriter array() throws JSONException {
 147         if (this.mode == 'i' || this.mode == 'o' || this.mode == 'a') {
 148             this.push(null);
 149             this.append("[");
 150             this.comma = false;
 151             return this;
 152         }
 153         throw new JSONException("Misplaced array.");
 154     }
 155
 156     /**
 157      * End something.
 158      * @param m Mode
 159      * @param c Closing character
 160      * @return this
 161      * @throws JSONException If unbalanced.
 162      */
 163     private JSONWriter end(char m, char c) throws JSONException {
 164         if (this.mode != m) {
 165             throw new JSONException(m == 'a'
 166                 ? "Misplaced endArray."
 167                 : "Misplaced endObject.");
 168         }
 169         this.pop(m);
 170         try {
 171             this.writer.append(c);
 172         } catch (IOException e) {
 173                 // Android as of API 25 does not support this exception constructor
 174                 // however we won't worry about it. If an exception is happening here
 175                 // it will just throw a "Method not found" exception instead.
 176             throw new JSONException(e);
 177         }
 178         this.comma = true;
 179         return this;
 180     }
 181
 182     /**
 183      * End an array. This method most be called to balance calls to
 184      * <code>array</code>.
 185      * @return this
 186      * @throws JSONException If incorrectly nested.
 187      */
 188     public JSONWriter endArray() throws JSONException {
 189         return this.end('a', ']');
 190     }
 191
 192     /**
 193      * End an object. This method most be called to balance calls to
 194      * <code>object</code>.
 195      * @return this
 196      * @throws JSONException If incorrectly nested.
 197      */
 198     public JSONWriter endObject() throws JSONException {
 199         return this.end('k', '}');
 200     }
 201
 202     /**
 203      * Append a key. The key will be associated with the next value. In an
 204      * object, every value must be preceded by a key.
 205      * @param string A key string.
 206      * @return this
 207      * @throws JSONException If the key is out of place. For example, keys
 208      *  do not belong in arrays or if the key is null.
 209      */
 210     public JSONWriter key(String string) throws JSONException {
 211         if (string == null) {
 212             throw new JSONException("Null key.");
 213         }
 214         if (this.mode == 'k') {
 215             try {
 216                 JSONObject topObject = this.stack[this.top - 1];
 217                 // don't use the built in putOnce method to maintain Android support
 218                                 if(topObject.has(string)) {
 219                                         throw new JSONException("Duplicate key \"" + string + "\"");
 220                                 }
 221                 topObject.put(string, true);
 222                 if (this.comma) {
 223                     this.writer.append(',');
 224                 }
 225                 this.writer.append(JSONObject.quote(string));
 226                 this.writer.append(':');
 227                 this.comma = false;
 228                 this.mode = 'o';
 229                 return this;
 230             } catch (IOException e) {
 231                 // Android as of API 25 does not support this exception constructor
 232                 // however we won't worry about it. If an exception is happening here
 233                 // it will just throw a "Method not found" exception instead.
 234                 throw new JSONException(e);
 235             }
 236         }
 237         throw new JSONException("Misplaced key.");
 238     }
 239
 240
 241     /**
 242      * Begin appending a new object. All keys and values until the balancing
 243      * <code>endObject</code> will be appended to this object. The
 244      * <code>endObject</code> method must be called to mark the object's end.
 245      * @return this
 246      * @throws JSONException If the nesting is too deep, or if the object is
 247      * started in the wrong place (for example as a key or after the end of the
 248      * outermost array or object).
 249      */
 250     public JSONWriter object() throws JSONException {
 251         if (this.mode == 'i') {
 252             this.mode = 'o';
 253         }
 254         if (this.mode == 'o' || this.mode == 'a') {
 255             this.append("{");
 256             this.push(new JSONObject());
 257             this.comma = false;
 258             return this;
 259         }
 260         throw new JSONException("Misplaced object.");
 261
 262     }
 263
 264
 265     /**
 266      * Pop an array or object scope.
 267      * @param c The scope to close.
 268      * @throws JSONException If nesting is wrong.
 269      */
 270     private void pop(char c) throws JSONException {
 271         if (this.top <= 0) {
 272             throw new JSONException("Nesting error.");
 273         }
 274         char m = this.stack[this.top - 1] == null ? 'a' : 'k';
 275         if (m != c) {
 276             throw new JSONException("Nesting error.");
 277         }
 278         this.top -= 1;
 279         this.mode = this.top == 0
 280             ? 'd'
 281             : this.stack[this.top - 1] == null
 282             ? 'a'
 283             : 'k';
 284     }
 285
 286     /**
 287      * Push an array or object scope.
 288      * @param jo The scope to open.
 289      * @throws JSONException If nesting is too deep.
 290      */
 291     private void push(JSONObject jo) throws JSONException {
 292         if (this.top >= maxdepth) {
 293             throw new JSONException("Nesting too deep.");
 294         }
 295         this.stack[this.top] = jo;
 296         this.mode = jo == null ? 'a' : 'k';
 297         this.top += 1;
 298     }
 299
 300     /**
 301      * Make a JSON text of an Object value. If the object has an
 302      * value.toJSONString() method, then that method will be used to produce the
 303      * JSON text. The method is required to produce a strictly conforming text.
 304      * If the object does not contain a toJSONString method (which is the most
 305      * common case), then a text will be produced by other means. If the value
 306      * is an array or Collection, then a JSONArray will be made from it and its
 307      * toJSONString method will be called. If the value is a MAP, then a
 308      * JSONObject will be made from it and its toJSONString method will be
 309      * called. Otherwise, the value's toString method will be called, and the
 310      * result will be quoted.
 311      *
 312      * <p>
 313      * Warning: This method assumes that the data structure is acyclical.
 314      *
 315      * @param value
 316      *            The value to be serialized.
 317      * @return a printable, displayable, transmittable representation of the
 318      *         object, beginning with <code>{</code>&nbsp;<small>(left
 319      *         brace)</small> and ending with <code>}</code>&nbsp;<small>(right
 320      *         brace)</small>.
 321      * @throws JSONException
 322      *             If the value is or contains an invalid number.
 323      */
 324     public static String valueToString(Object value) throws JSONException {
 325         if (value == null || value.equals(null)) {
 326             return "null";
 327         }
 328         if (value instanceof JSONString) {
 329             Object object;
 330             try {
 331                 object = ((JSONString) value).toJSONString();
 332             } catch (Exception e) {
 333                 throw new JSONException(e);
 334             }
 335             if (object instanceof String) {
 336                 return (String) object;
 337             }
 338             throw new JSONException("Bad value from toJSONString: " + object);
 339         }
 340         if (value instanceof Number) {
 341             // not all Numbers may match actual JSON Numbers. i.e. Fractions or Complex
 342             final String numberAsString = JSONObject.numberToString((Number) value);
 343             try {
 344                 // Use the BigDecimal constructor for it's parser to validate the format.
 345                 @SuppressWarnings("unused")
 346                 BigDecimal unused = new BigDecimal(numberAsString);
 347                 // Close enough to a JSON number that we will return it unquoted
 348                 return numberAsString;
 349             } catch (NumberFormatException ex){
 350                 // The Number value is not a valid JSON number.
 351                 // Instead we will quote it as a string
 352                 return JSONObject.quote(numberAsString);
 353             }
 354         }
 355         if (value instanceof Boolean || value instanceof JSONObject
 356                 || value instanceof JSONArray) {
 357             return value.toString();
 358         }
 359         if (value instanceof Map) {
 360             Map<?, ?> map = (Map<?, ?>) value;
 361             return new JSONObject(map).toString();
 362         }
 363         if (value instanceof Collection) {
 364             Collection<?> coll = (Collection<?>) value;
 365             return new JSONArray(coll).toString();
 366         }
 367         if (value.getClass().isArray()) {
 368             return new JSONArray(value).toString();
 369         }
 370         if(value instanceof Enum<?>){
 371             return JSONObject.quote(((Enum<?>)value).name());
 372         }
 373         return JSONObject.quote(value.toString());
 374     }
 375
 376     /**
 377      * Append either the value <code>true</code> or the value
 378      * <code>false</code>.
 379      * @param b A boolean.
 380      * @return this
 381      * @throws JSONException
 382      */
 383     public JSONWriter value(boolean b) throws JSONException {
 384         return this.append(b ? "true" : "false");
 385     }
 386
 387     /**
 388      * Append a double value.
 389      * @param d A double.
 390      * @return this
 391      * @throws JSONException If the number is not finite.
 392      */
 393     public JSONWriter value(double d) throws JSONException {
 394         return this.value(Double.valueOf(d));
 395     }
 396
 397     /**
 398      * Append a long value.
 399      * @param l A long.
 400      * @return this
 401      * @throws JSONException
 402      */
 403     public JSONWriter value(long l) throws JSONException {
 404         return this.append(Long.toString(l));
 405     }
 406
 407
 408     /**
 409      * Append an object value.
 410      * @param object The object to append. It can be null, or a Boolean, Number,
 411      *   String, JSONObject, or JSONArray, or an object that implements JSONString.
 412      * @return this
 413      * @throws JSONException If the value is out of sequence.
 414      */
 415     public JSONWriter value(Object object) throws JSONException {
 416         return this.append(valueToString(object));
 417     }
 418 }