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. The
  34  * texts produced strictly conform to JSON syntax rules. No whitespace is added,
  35  * 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 text, and a <code>key</code> method for adding keys before
  40  * values in objects. There are <code>array</code> and <code>endArray</code>
  41  * methods that make and bound array values, and <code>object</code> and
  42  * <code>endObject</code> methods which make and bound object values. All of
  43  * these methods return the JSONWriter instance, permitting a cascade style. For
  44  * example,
  45  *
  46  * <pre>
  47  * new JSONWriter(myWriter).object().key("JSON").value("Hello, World!")
  48  *         .endObject();
  49  * </pre>
  50  *
  51  * which writes
  52  *
  53  * <pre>
  54  * {"JSON":"Hello, World!"}
  55  * </pre>
  56  * <p>
  57  * The first method called must be <code>array</code> or <code>object</code>.
  58  * There are no methods for adding commas or colons. JSONWriter adds them for
  59  * you. Objects and arrays can be nested up to 200 levels deep.
  60  * <p>
  61  * This can sometimes be easier than using a JSONObject to build a string.
  62  *
  63  * @author JSON.org
  64  * @version 2016-08-08
  65  */
  66 public class JSONWriter
  67 {
  68   private static final int maxdepth = 200;
  69
  70   /**
  71    * The comma flag determines if a comma should be output before the next
  72    * value.
  73    */
  74   private boolean comma;
  75
  76   /**
  77    * The current mode. Values: 'a' (array), 'd' (done), 'i' (initial), 'k'
  78    * (key), 'o' (object).
  79    */
  80   protected char mode;
  81
  82   /**
  83    * The object/array stack.
  84    */
  85   private final JSONObject stack[];
  86
  87   /**
  88    * The stack top index. A value of 0 indicates that the stack is empty.
  89    */
  90   private int top;
  91
  92   /**
  93    * The writer that will receive the output.
  94    */
  95   protected Appendable writer;
  96
  97   /**
  98    * Make a fresh JSONWriter. It can be used to build one JSON text.
  99    */
 100   public JSONWriter(Appendable w)
 101   {
 102     this.comma = false;
 103     this.mode = 'i';
 104     this.stack = new JSONObject[maxdepth];
 105     this.top = 0;
 106     this.writer = w;
 107   }
 108
 109   /**
 110    * Append a value.
 111    *
 112    * @param string
 113    *          A string value.
 114    * @return this
 115    * @throws JSONException
 116    *           If the value is out of sequence.
 117    */
 118   private JSONWriter append(String string) throws JSONException
 119   {
 120     if (string == null)
 121     {
 122       throw new JSONException("Null pointer");
 123     }
 124     if (this.mode == 'o' || this.mode == 'a')
 125     {
 126       try
 127       {
 128         if (this.comma && this.mode == 'a')
 129         {
 130           this.writer.append(',');
 131         }
 132         this.writer.append(string);
 133       } catch (IOException e)
 134       {
 135         // Android as of API 25 does not support this exception constructor
 136         // however we won't worry about it. If an exception is happening here
 137         // it will just throw a "Method not found" exception instead.
 138         throw new JSONException(e);
 139       }
 140       if (this.mode == 'o')
 141       {
 142         this.mode = 'k';
 143       }
 144       this.comma = true;
 145       return this;
 146     }
 147     throw new JSONException("Value out of sequence.");
 148   }
 149
 150   /**
 151    * Begin appending a new array. All values until the balancing
 152    * <code>endArray</code> will be appended to this array. The
 153    * <code>endArray</code> method must be called to mark the array's end.
 154    *
 155    * @return this
 156    * @throws JSONException
 157    *           If the nesting is too deep, or if the object is started in the
 158    *           wrong place (for example as a key or after the end of the
 159    *           outermost array or object).
 160    */
 161   public JSONWriter array() throws JSONException
 162   {
 163     if (this.mode == 'i' || this.mode == 'o' || this.mode == 'a')
 164     {
 165       this.push(null);
 166       this.append("[");
 167       this.comma = false;
 168       return this;
 169     }
 170     throw new JSONException("Misplaced array.");
 171   }
 172
 173   /**
 174    * End something.
 175    *
 176    * @param m
 177    *          Mode
 178    * @param c
 179    *          Closing character
 180    * @return this
 181    * @throws JSONException
 182    *           If unbalanced.
 183    */
 184   private JSONWriter end(char m, char c) throws JSONException
 185   {
 186     if (this.mode != m)
 187     {
 188       throw new JSONException(
 189               m == 'a' ? "Misplaced endArray." : "Misplaced endObject.");
 190     }
 191     this.pop(m);
 192     try
 193     {
 194       this.writer.append(c);
 195     } catch (IOException e)
 196     {
 197       // Android as of API 25 does not support this exception constructor
 198       // however we won't worry about it. If an exception is happening here
 199       // it will just throw a "Method not found" exception instead.
 200       throw new JSONException(e);
 201     }
 202     this.comma = true;
 203     return this;
 204   }
 205
 206   /**
 207    * End an array. This method most be called to balance calls to
 208    * <code>array</code>.
 209    *
 210    * @return this
 211    * @throws JSONException
 212    *           If incorrectly nested.
 213    */
 214   public JSONWriter endArray() throws JSONException
 215   {
 216     return this.end('a', ']');
 217   }
 218
 219   /**
 220    * End an object. This method most be called to balance calls to
 221    * <code>object</code>.
 222    *
 223    * @return this
 224    * @throws JSONException
 225    *           If incorrectly nested.
 226    */
 227   public JSONWriter endObject() throws JSONException
 228   {
 229     return this.end('k', '}');
 230   }
 231
 232   /**
 233    * Append a key. The key will be associated with the next value. In an object,
 234    * every value must be preceded by a key.
 235    *
 236    * @param string
 237    *          A key string.
 238    * @return this
 239    * @throws JSONException
 240    *           If the key is out of place. For example, keys do not belong in
 241    *           arrays or if the key is null.
 242    */
 243   public JSONWriter key(String string) throws JSONException
 244   {
 245     if (string == null)
 246     {
 247       throw new JSONException("Null key.");
 248     }
 249     if (this.mode == 'k')
 250     {
 251       try
 252       {
 253         JSONObject topObject = this.stack[this.top - 1];
 254         // don't use the built in putOnce method to maintain Android support
 255         if (topObject.has(string))
 256         {
 257           throw new JSONException("Duplicate key \"" + string + "\"");
 258         }
 259         topObject.put(string, true);
 260         if (this.comma)
 261         {
 262           this.writer.append(',');
 263         }
 264         this.writer.append(JSONObject.quote(string));
 265         this.writer.append(':');
 266         this.comma = false;
 267         this.mode = 'o';
 268         return this;
 269       } catch (IOException e)
 270       {
 271         // Android as of API 25 does not support this exception constructor
 272         // however we won't worry about it. If an exception is happening here
 273         // it will just throw a "Method not found" exception instead.
 274         throw new JSONException(e);
 275       }
 276     }
 277     throw new JSONException("Misplaced key.");
 278   }
 279
 280   /**
 281    * Begin appending a new object. All keys and values until the balancing
 282    * <code>endObject</code> will be appended to this object. The
 283    * <code>endObject</code> method must be called to mark the object's end.
 284    *
 285    * @return this
 286    * @throws JSONException
 287    *           If the nesting is too deep, or if the object is started in the
 288    *           wrong place (for example as a key or after the end of the
 289    *           outermost array or object).
 290    */
 291   public JSONWriter object() throws JSONException
 292   {
 293     if (this.mode == 'i')
 294     {
 295       this.mode = 'o';
 296     }
 297     if (this.mode == 'o' || this.mode == 'a')
 298     {
 299       this.append("{");
 300       this.push(new JSONObject());
 301       this.comma = false;
 302       return this;
 303     }
 304     throw new JSONException("Misplaced object.");
 305
 306   }
 307
 308   /**
 309    * Pop an array or object scope.
 310    *
 311    * @param c
 312    *          The scope to close.
 313    * @throws JSONException
 314    *           If nesting is wrong.
 315    */
 316   private void pop(char c) throws JSONException
 317   {
 318     if (this.top <= 0)
 319     {
 320       throw new JSONException("Nesting error.");
 321     }
 322     char m = this.stack[this.top - 1] == null ? 'a' : 'k';
 323     if (m != c)
 324     {
 325       throw new JSONException("Nesting error.");
 326     }
 327     this.top -= 1;
 328     this.mode = this.top == 0 ? 'd'
 329             : this.stack[this.top - 1] == null ? 'a' : 'k';
 330   }
 331
 332   /**
 333    * Push an array or object scope.
 334    *
 335    * @param jo
 336    *          The scope to open.
 337    * @throws JSONException
 338    *           If nesting is too deep.
 339    */
 340   private void push(JSONObject jo) throws JSONException
 341   {
 342     if (this.top >= maxdepth)
 343     {
 344       throw new JSONException("Nesting too deep.");
 345     }
 346     this.stack[this.top] = jo;
 347     this.mode = jo == null ? 'a' : 'k';
 348     this.top += 1;
 349   }
 350
 351   /**
 352    * Make a JSON text of an Object value. If the object has an
 353    * value.toJSONString() method, then that method will be used to produce the
 354    * JSON text. The method is required to produce a strictly conforming text. If
 355    * the object does not contain a toJSONString method (which is the most common
 356    * case), then a text will be produced by other means. If the value is an
 357    * array or Collection, then a JSONArray will be made from it and its
 358    * toJSONString method will be called. If the value is a MAP, then a
 359    * JSONObject will be made from it and its toJSONString method will be called.
 360    * Otherwise, the value's toString method will be called, and the result will
 361    * be quoted.
 362    *
 363    * <p>
 364    * Warning: This method assumes that the data structure is acyclical.
 365    *
 366    * @param value
 367    *          The value to be serialized.
 368    * @return a printable, displayable, transmittable representation of the
 369    *         object, beginning with <code>{</code>&nbsp;<small>(left
 370    *         brace)</small> and ending with <code>}</code>&nbsp;<small>(right
 371    *         brace)</small>.
 372    * @throws JSONException
 373    *           If the value is or contains an invalid number.
 374    */
 375   public static String valueToString(Object value) throws JSONException
 376   {
 377     if (value == null || value.equals(null))
 378     {
 379       return "null";
 380     }
 381     if (value instanceof JSONString)
 382     {
 383       Object object;
 384       try
 385       {
 386         object = ((JSONString) value).toJSONString();
 387       } catch (Exception e)
 388       {
 389         throw new JSONException(e);
 390       }
 391       if (object instanceof String)
 392       {
 393         return (String) object;
 394       }
 395       throw new JSONException("Bad value from toJSONString: " + object);
 396     }
 397     if (value instanceof Number)
 398     {
 399       // not all Numbers may match actual JSON Numbers. i.e. Fractions or
 400       // Complex
 401       final String numberAsString = JSONObject
 402               .numberToString((Number) value);
 403       try
 404       {
 405         // Use the BigDecimal constructor for it's parser to validate the
 406         // format.
 407         @SuppressWarnings("unused")
 408         BigDecimal unused = new BigDecimal(numberAsString);
 409         // Close enough to a JSON number that we will return it unquoted
 410         return numberAsString;
 411       } catch (NumberFormatException ex)
 412       {
 413         // The Number value is not a valid JSON number.
 414         // Instead we will quote it as a string
 415         return JSONObject.quote(numberAsString);
 416       }
 417     }
 418     if (value instanceof Boolean || value instanceof JSONObject
 419             || value instanceof JSONArray)
 420     {
 421       return value.toString();
 422     }
 423     if (value instanceof Map)
 424     {
 425       Map<?, ?> map = (Map<?, ?>) value;
 426       return new JSONObject(map).toString();
 427     }
 428     if (value instanceof Collection)
 429     {
 430       Collection<?> coll = (Collection<?>) value;
 431       return new JSONArray(coll).toString();
 432     }
 433     if (value.getClass().isArray())
 434     {
 435       return new JSONArray(value).toString();
 436     }
 437     if (value instanceof Enum<?>)
 438     {
 439       return JSONObject.quote(((Enum<?>) value).name());
 440     }
 441     return JSONObject.quote(value.toString());
 442   }
 443
 444   /**
 445    * Append either the value <code>true</code> or the value <code>false</code>.
 446    *
 447    * @param b
 448    *          A boolean.
 449    * @return this
 450    * @throws JSONException
 451    */
 452   public JSONWriter value(boolean b) throws JSONException
 453   {
 454     return this.append(b ? "true" : "false");
 455   }
 456
 457   /**
 458    * Append a double value.
 459    *
 460    * @param d
 461    *          A double.
 462    * @return this
 463    * @throws JSONException
 464    *           If the number is not finite.
 465    */
 466   public JSONWriter value(double d) throws JSONException
 467   {
 468     return this.value(Double.valueOf(d));
 469   }
 470
 471   /**
 472    * Append a long value.
 473    *
 474    * @param l
 475    *          A long.
 476    * @return this
 477    * @throws JSONException
 478    */
 479   public JSONWriter value(long l) throws JSONException
 480   {
 481     return this.append(Long.toString(l));
 482   }
 483
 484   /**
 485    * Append an object value.
 486    *
 487    * @param object
 488    *          The object to append. It can be null, or a Boolean, Number,
 489    *          String, JSONObject, or JSONArray, or an object that implements
 490    *          JSONString.
 491    * @return this
 492    * @throws JSONException
 493    *           If the value is out of sequence.
 494    */
 495   public JSONWriter value(Object object) throws JSONException
 496   {
 497     return this.append(valueToString(object));
 498   }
 499 }