Update README

Fixes XML Unescaping

CDL.java

@@ -22,7 +22,7 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-*/
+ */
 
 /**
  * This provides static methods to convert comma delimited text into a
@@ -41,7 +41,7 @@ SOFTWARE.
  * The names for the elements in the JSONObjects can be taken from the names
  * in the first row.
  * @author JSON.org
- * @version 2015-05-01
+ * @version 2016-05-01
  */
 public class CDL {
 
@@ -69,8 +69,16 @@ public class CDL {
             for (;;) {
                 c = x.next();
                 if (c == q) {
+                    //Handle escaped double-quote
+                    char nextC = x.next();
+                    if(nextC != '\"') {
+                        // if our quote was the end of the file, don't step
+                        if(nextC > 0) {
+                            x.back();
+                        }
                         break;
                     }
+                }
                 if (c == 0 || c == '\n' || c == '\r') {
                     throw x.syntaxError("Missing close quote '" + q + "'.");
                 }

Cookie.java

@@ -28,7 +28,7 @@ SOFTWARE.
  * Convert a web browser cookie specification to a JSONObject and back.
  * JSON and Cookies are both notations for name/value pairs.
  * @author JSON.org
- * @version 2014-05-03
+ * @version 2015-12-09
  */
 public class Cookie {
 

CookieList.java

@@ -1,5 +1,7 @@
 package org.json;
 
+import java.util.Map.Entry;
+
 /*
 Copyright (c) 2002 JSON.org
 
@@ -24,12 +26,10 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
-import java.util.Iterator;
-
 /**
  * Convert a web browser cookie list string to a JSONObject and back.
  * @author JSON.org
- * @version 2014-05-03
+ * @version 2015-12-09
  */
 public class CookieList {
 
@@ -39,7 +39,7 @@ public class CookieList {
      * The pairs are separated by ';'. The names and the values
      * will be unescaped, possibly converting '+' and '%' sequences.
      *
-     * To add a cookie to a cooklist,
+     * To add a cookie to a cookie list,
      * cookielistJSONObject.put(cookieJSONObject.getString("name"),
      *     cookieJSONObject.getString("value"));
      * @param string  A cookie list string
@@ -69,18 +69,17 @@ public class CookieList {
      */
     public static String toString(JSONObject jo) throws JSONException {
         boolean             b = false;
-        Iterator<String>    keys = jo.keys();
-        String              string;
         StringBuilder sb = new StringBuilder();
-        while (keys.hasNext()) {
+        for (final Entry<String,?> entry : jo.entrySet()) {
-            string = keys.next();
+        	final String key = entry.getKey();
-            if (!jo.isNull(string)) {
+        	final Object value = entry.getValue();
+            if (!JSONObject.NULL.equals(value)) {
                 if (b) {
                     sb.append(';');
                 }
-                sb.append(Cookie.escape(string));
+                sb.append(Cookie.escape(key));
                 sb.append("=");
-                sb.append(Cookie.escape(jo.getString(string)));
+				sb.append(Cookie.escape(value.toString()));
                 b = true;
             }
         }

HTTP.java

@@ -24,12 +24,13 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
-import java.util.Iterator;
+import java.util.Locale;
+import java.util.Map.Entry;
 
 /**
  * Convert an HTTP header to a JSONObject and back.
  * @author JSON.org
- * @version 2014-05-03
+ * @version 2015-12-09
  */
 public class HTTP {
 
@@ -74,7 +75,7 @@ public class HTTP {
         String         token;
 
         token = x.nextToken();
-        if (token.toUpperCase().startsWith("HTTP")) {
+        if (token.toUpperCase(Locale.ROOT).startsWith("HTTP")) {
 
 // Response
 
@@ -125,8 +126,6 @@ public class HTTP {
      *  information.
      */
     public static String toString(JSONObject jo) throws JSONException {
-        Iterator<String>    keys = jo.keys();
-        String              string;
         StringBuilder       sb = new StringBuilder();
         if (jo.has("Status-Code") && jo.has("Reason-Phrase")) {
             sb.append(jo.getString("HTTP-Version"));
@@ -146,14 +145,14 @@ public class HTTP {
             throw new JSONException("Not enough material for an HTTP header.");
         }
         sb.append(CRLF);
-        while (keys.hasNext()) {
+        for (final Entry<String,?> entry : jo.entrySet()) {
-            string = keys.next();
+        	final String key = entry.getKey();
-            if (!"HTTP-Version".equals(string)      && !"Status-Code".equals(string) &&
+            if (!"HTTP-Version".equals(key)      && !"Status-Code".equals(key) &&
-                    !"Reason-Phrase".equals(string) && !"Method".equals(string) &&
+                    !"Reason-Phrase".equals(key) && !"Method".equals(key) &&
-                    !"Request-URI".equals(string)   && !jo.isNull(string)) {
+                    !"Request-URI".equals(key)   && !JSONObject.NULL.equals(entry.getValue())) {
-                sb.append(string);
+                sb.append(key);
                 sb.append(": ");
-                sb.append(jo.getString(string));
+                sb.append(jo.optString(key));
                 sb.append(CRLF);
             }
         }

HTTPTokener.java

@@ -28,7 +28,7 @@ SOFTWARE.
  * The HTTPTokener extends the JSONTokener to provide additional methods
  * for the parsing of HTTP headers.
  * @author JSON.org
- * @version 2014-05-03
+ * @version 2015-12-09
  */
 public class HTTPTokener extends JSONTokener {
 

JSONArray.java

@@ -28,10 +28,12 @@ import java.io.IOException;
 import java.io.StringWriter;
 import java.io.Writer;
 import java.lang.reflect.Array;
-import java.math.*;
+import java.math.BigDecimal;
+import java.math.BigInteger;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Iterator;
+import java.util.List;
 import java.util.Map;
 
 /**
@@ -76,7 +78,7 @@ import java.util.Map;
  * </ul>
  *
  * @author JSON.org
- * @version 2015-10-29
+ * @version 2016-08/15
  */
 public class JSONArray implements Iterable<Object> {
 
@@ -152,8 +154,10 @@ public class JSONArray implements Iterable<Object> {
      *            A Collection.
      */
     public JSONArray(Collection<?> collection) {
+        if (collection == null) {
             this.myArrayList = new ArrayList<Object>();
-        if (collection != null) {
+        } else {
+            this.myArrayList = new ArrayList<Object>(collection.size());
         	for (Object o: collection){
         		this.myArrayList.add(JSONObject.wrap(o));
         	}
@@ -170,6 +174,7 @@ public class JSONArray implements Iterable<Object> {
         this();
         if (array.getClass().isArray()) {
             int length = Array.getLength(array);
+            this.myArrayList.ensureCapacity(length);
             for (int i = 0; i < length; i += 1) {
                 this.put(JSONObject.wrap(Array.get(array, i)));
             }
@@ -181,7 +186,7 @@ public class JSONArray implements Iterable<Object> {
 
     @Override
     public Iterator<Object> iterator() {
-        return myArrayList.iterator();
+        return this.myArrayList.iterator();
     }
 
     /**
@@ -242,7 +247,50 @@ public class JSONArray implements Iterable<Object> {
             return object instanceof Number ? ((Number) object).doubleValue()
                     : Double.parseDouble((String) object);
         } catch (Exception e) {
-            throw new JSONException("JSONArray[" + index + "] is not a number.");
+            throw new JSONException("JSONArray[" + index + "] is not a number.", e);
+        }
+    }
+
+    /**
+     * Get the float value associated with a key.
+     *
+     * @param index
+     *            The index must be between 0 and length() - 1.
+     * @return The numeric value.
+     * @throws JSONException
+     *             if the key is not found or if the value is not a Number
+     *             object and cannot be converted to a number.
+     */
+    public float getFloat(int index) throws JSONException {
+        Object object = this.get(index);
+        try {
+            return object instanceof Number ? ((Number) object).floatValue()
+                    : Float.parseFloat(object.toString());
+        } catch (Exception e) {
+            throw new JSONException("JSONArray[" + index
+                    + "] is not a number.", e);
+        }
+    }
+
+    /**
+     * Get the Number value associated with a key.
+     *
+     * @param index
+     *            The index must be between 0 and length() - 1.
+     * @return The numeric value.
+     * @throws JSONException
+     *             if the key is not found or if the value is not a Number
+     *             object and cannot be converted to a number.
+     */
+    public Number getNumber(int index) throws JSONException {
+        Object object = this.get(index);
+        try {
+            if (object instanceof Number) {
+                return (Number)object;
+            }
+            return JSONObject.stringToNumber(object.toString());
+        } catch (Exception e) {
+            throw new JSONException("JSONArray[" + index + "] is not a number.", e);
         }
     }
 
@@ -264,9 +312,8 @@ public class JSONArray implements Iterable<Object> {
             // JSONException should really take a throwable argument.
             // If it did, I would re-implement this with the Enum.valueOf
             // method and place any thrown exception in the JSONException
-            throw new JSONException("JSONObject[" + JSONObject.quote(Integer.toString(index))
+            throw new JSONException("JSONArray[" + index + "] is not an enum of type "
-                    + "] is not an enum of type " + JSONObject.quote(clazz.getSimpleName())
+                    + JSONObject.quote(clazz.getSimpleName()) + ".");
-                    + ".");
         }
         return val;
     }
@@ -287,7 +334,7 @@ public class JSONArray implements Iterable<Object> {
             return new BigDecimal(object.toString());
         } catch (Exception e) {
             throw new JSONException("JSONArray[" + index +
-                    "] could not convert to BigDecimal.");
+                    "] could not convert to BigDecimal.", e);
         }
     }
 
@@ -307,7 +354,7 @@ public class JSONArray implements Iterable<Object> {
             return new BigInteger(object.toString());
         } catch (Exception e) {
             throw new JSONException("JSONArray[" + index +
-                    "] could not convert to BigInteger.");
+                    "] could not convert to BigInteger.", e);
         }
     }
 
@@ -326,7 +373,7 @@ public class JSONArray implements Iterable<Object> {
             return object instanceof Number ? ((Number) object).intValue()
                     : Integer.parseInt((String) object);
         } catch (Exception e) {
-            throw new JSONException("JSONArray[" + index + "] is not a number.");
+            throw new JSONException("JSONArray[" + index + "] is not a number.", e);
         }
     }
 
@@ -382,7 +429,7 @@ public class JSONArray implements Iterable<Object> {
             return object instanceof Number ? ((Number) object).longValue()
                     : Long.parseLong((String) object);
         } catch (Exception e) {
-            throw new JSONException("JSONArray[" + index + "] is not a number.");
+            throw new JSONException("JSONArray[" + index + "] is not a number.", e);
         }
     }
 
@@ -451,7 +498,7 @@ public class JSONArray implements Iterable<Object> {
      * Get the optional object value associated with an index.
      *
      * @param index
-     *            The index must be between 0 and length() - 1.
+     *            The index must be between 0 and length() - 1. If not, null is returned.
      * @return An object value, or null if there is no object at that index.
      */
     public Object opt(int index) {
@@ -516,12 +563,64 @@ public class JSONArray implements Iterable<Object> {
      * @return The value.
      */
     public double optDouble(int index, double defaultValue) {
+        Object val = this.opt(index);
+        if (JSONObject.NULL.equals(val)) {
+            return defaultValue;
+        }
+        if (val instanceof Number){
+            return ((Number) val).doubleValue();
+        }
+        if (val instanceof String) {
             try {
-            return this.getDouble(index);
+                return Double.parseDouble((String) val);
             } catch (Exception e) {
                 return defaultValue;
             }
         }
+        return defaultValue;
+    }
+
+    /**
+     * Get the optional float value associated with an index. NaN is returned
+     * if there is no value for the index, or if the value is not a number and
+     * cannot be converted to a number.
+     *
+     * @param index
+     *            The index must be between 0 and length() - 1.
+     * @return The value.
+     */
+    public float optFloat(int index) {
+        return this.optFloat(index, Float.NaN);
+    }
+
+    /**
+     * Get the optional float value associated with an index. The defaultValue
+     * is returned if there is no value for the index, or if the value is not a
+     * number and cannot be converted to a number.
+     *
+     * @param index
+     *            subscript
+     * @param defaultValue
+     *            The default value.
+     * @return The value.
+     */
+    public float optFloat(int index, float defaultValue) {
+        Object val = this.opt(index);
+        if (JSONObject.NULL.equals(val)) {
+            return defaultValue;
+        }
+        if (val instanceof Number){
+            return ((Number) val).floatValue();
+        }
+        if (val instanceof String) {
+            try {
+                return Float.parseFloat((String) val);
+            } catch (Exception e) {
+                return defaultValue;
+            }
+        }
+        return defaultValue;
+    }
 
     /**
      * Get the optional int value associated with an index. Zero is returned if
@@ -548,12 +647,23 @@ public class JSONArray implements Iterable<Object> {
      * @return The value.
      */
     public int optInt(int index, int defaultValue) {
+        Object val = this.opt(index);
+        if (JSONObject.NULL.equals(val)) {
+            return defaultValue;
+        }
+        if (val instanceof Number){
+            return ((Number) val).intValue();
+        }
+        
+        if (val instanceof String) {
             try {
-            return this.getInt(index);
+                return new BigDecimal(val.toString()).intValue();
             } catch (Exception e) {
                 return defaultValue;
             }
         }
+        return defaultValue;
+    }
 
     /**
      * Get the enum value associated with a key.
@@ -593,7 +703,9 @@ public class JSONArray implements Iterable<Object> {
                 return myE;
             }
             return Enum.valueOf(clazz, val.toString());
-        } catch (IllegalArgumentException | NullPointerException e) {
+        } catch (IllegalArgumentException e) {
+            return defaultValue;
+        } catch (NullPointerException e) {
             return defaultValue;
         }
     }
@@ -611,8 +723,29 @@ public class JSONArray implements Iterable<Object> {
      * @return The value.
      */
     public BigInteger optBigInteger(int index, BigInteger defaultValue) {
+        Object val = this.opt(index);
+        if (JSONObject.NULL.equals(val)) {
+            return defaultValue;
+        }
+        if (val instanceof BigInteger){
+            return (BigInteger) val;
+        }
+        if (val instanceof BigDecimal){
+            return ((BigDecimal) val).toBigInteger();
+        }
+        if (val instanceof Double || val instanceof Float){
+            return new BigDecimal(((Number) val).doubleValue()).toBigInteger();
+        }
+        if (val instanceof Long || val instanceof Integer
+                || val instanceof Short || val instanceof Byte){
+            return BigInteger.valueOf(((Number) val).longValue());
+        }
         try {
-            return this.getBigInteger(index);
+            final String valStr = val.toString();
+            if(JSONObject.isDecimalNotation(valStr)) {
+                return new BigDecimal(valStr).toBigInteger();
+            }
+            return new BigInteger(valStr);
         } catch (Exception e) {
             return defaultValue;
         }
@@ -630,8 +763,25 @@ public class JSONArray implements Iterable<Object> {
      * @return The value.
      */
     public BigDecimal optBigDecimal(int index, BigDecimal defaultValue) {
+        Object val = this.opt(index);
+        if (JSONObject.NULL.equals(val)) {
+            return defaultValue;
+        }
+        if (val instanceof BigDecimal){
+            return (BigDecimal) val;
+        }
+        if (val instanceof BigInteger){
+            return new BigDecimal((BigInteger) val);
+        }
+        if (val instanceof Double || val instanceof Float){
+            return new BigDecimal(((Number) val).doubleValue());
+        }
+        if (val instanceof Long || val instanceof Integer
+                || val instanceof Short || val instanceof Byte){
+            return new BigDecimal(((Number) val).longValue());
+        }
         try {
-            return this.getBigDecimal(index);
+            return new BigDecimal(val.toString());
         } catch (Exception e) {
             return defaultValue;
         }
@@ -689,17 +839,73 @@ public class JSONArray implements Iterable<Object> {
      * @return The value.
      */
     public long optLong(int index, long defaultValue) {
+        Object val = this.opt(index);
+        if (JSONObject.NULL.equals(val)) {
+            return defaultValue;
+        }
+        if (val instanceof Number){
+            return ((Number) val).longValue();
+        }
+        
+        if (val instanceof String) {
             try {
-            return this.getLong(index);
+                return new BigDecimal(val.toString()).longValue();
             } catch (Exception e) {
                 return defaultValue;
             }
         }
+        return defaultValue;
+    }
+
+    /**
+     * Get an optional {@link Number} value associated with a key, or <code>null</code>
+     * if there is no such key or if the value is not a number. If the value is a string,
+     * an attempt will be made to evaluate it as a number ({@link BigDecimal}). This method
+     * would be used in cases where type coercion of the number value is unwanted.
+     *
+     * @param index
+     *            The index must be between 0 and length() - 1.
+     * @return An object which is the value.
+     */
+    public Number optNumber(int index) {
+        return this.optNumber(index, null);
+    }
+
+    /**
+     * Get an optional {@link Number} value associated with a key, or the default if there
+     * is no such key or if the value is not a number. If the value is a string,
+     * an attempt will be made to evaluate it as a number ({@link BigDecimal}). This method
+     * would be used in cases where type coercion of the number value is unwanted.
+     *
+     * @param index
+     *            The index must be between 0 and length() - 1.
+     * @param defaultValue
+     *            The default.
+     * @return An object which is the value.
+     */
+    public Number optNumber(int index, Number defaultValue) {
+        Object val = this.opt(index);
+        if (JSONObject.NULL.equals(val)) {
+            return defaultValue;
+        }
+        if (val instanceof Number){
+            return (Number) val;
+        }
+        
+        if (val instanceof String) {
+            try {
+                return JSONObject.stringToNumber((String) val);
+            } catch (Exception e) {
+                return defaultValue;
+            }
+        }
+        return defaultValue;
+    }
 
     /**
      * Get the optional string value associated with an index. It returns an
      * empty string if there is no value at that index. If the value is not a
-     * string and is not null, then it is coverted to a string.
+     * string and is not null, then it is converted to a string.
      *
      * @param index
      *            The index must be between 0 and length() - 1.
@@ -947,7 +1153,13 @@ public class JSONArray implements Iterable<Object> {
         }
         if (index < this.length()) {
             this.myArrayList.set(index, value);
+        } else if(index == this.length()){
+            // simple append
+            this.put(value);
         } else {
+            // if we are inserting past the length, we want to grow the array all at once
+            // instead of incrementally.
+            this.myArrayList.ensureCapacity(index + 1);
             while (index != this.length()) {
                 this.put(JSONObject.NULL);
             }
@@ -956,6 +1168,80 @@ public class JSONArray implements Iterable<Object> {
         return this;
     }
     
+    /**
+     * Creates a JSONPointer using an initialization string and tries to 
+     * match it to an item within this JSONArray. For example, given a
+     * JSONArray initialized with this document:
+     * <pre>
+     * [
+     *     {"b":"c"}
+     * ]
+     * </pre>
+     * and this JSONPointer string: 
+     * <pre>
+     * "/0/b"
+     * </pre>
+     * Then this method will return the String "c"
+     * A JSONPointerException may be thrown from code called by this method.
+     *
+     * @param jsonPointer string that can be used to create a JSONPointer
+     * @return the item matched by the JSONPointer, otherwise null
+     */
+    public Object query(String jsonPointer) {
+        return query(new JSONPointer(jsonPointer));
+    }
+    
+    /**
+     * Uses a uaer initialized JSONPointer  and tries to 
+     * match it to an item whithin this JSONArray. For example, given a
+     * JSONArray initialized with this document:
+     * <pre>
+     * [
+     *     {"b":"c"}
+     * ]
+     * </pre>
+     * and this JSONPointer: 
+     * <pre>
+     * "/0/b"
+     * </pre>
+     * Then this method will return the String "c"
+     * A JSONPointerException may be thrown from code called by this method.
+     *
+     * @param jsonPointer string that can be used to create a JSONPointer
+     * @return the item matched by the JSONPointer, otherwise null
+     */
+    public Object query(JSONPointer jsonPointer) {
+        return jsonPointer.queryFrom(this);
+    }
+    
+    /**
+     * Queries and returns a value from this object using {@code jsonPointer}, or
+     * returns null if the query fails due to a missing key.
+     * 
+     * @param jsonPointer the string representation of the JSON pointer
+     * @return the queried value or {@code null}
+     * @throws IllegalArgumentException if {@code jsonPointer} has invalid syntax
+     */
+    public Object optQuery(String jsonPointer) {
+    	return optQuery(new JSONPointer(jsonPointer));
+    }
+    
+    /**
+     * Queries and returns a value from this object using {@code jsonPointer}, or
+     * returns null if the query fails due to a missing key.
+     * 
+     * @param jsonPointer The JSON pointer
+     * @return the queried value or {@code null}
+     * @throws IllegalArgumentException if {@code jsonPointer} has invalid syntax
+     */
+    public Object optQuery(JSONPointer jsonPointer) {
+        try {
+            return jsonPointer.queryFrom(this);
+        } catch (JSONPointerException e) {
+            return null;
+        }
+    }
+
     /**
      * Remove an index and close the hole.
      *
@@ -986,8 +1272,14 @@ public class JSONArray implements Iterable<Object> {
             return false;
         }
         for (int i = 0; i < len; i += 1) {
-            Object valueThis = this.get(i);
+            Object valueThis = this.myArrayList.get(i);
-            Object valueOther = ((JSONArray)other).get(i);
+            Object valueOther = ((JSONArray)other).myArrayList.get(i);
+            if(valueThis == valueOther) {
+            	return true;
+            }
+            if(valueThis == null) {
+            	return false;
+            }
             if (valueThis instanceof JSONObject) {
                 if (!((JSONObject)valueThis).similar(valueOther)) {
                     return false;
@@ -1019,7 +1311,7 @@ public class JSONArray implements Iterable<Object> {
         if (names == null || names.length() == 0 || this.length() == 0) {
             return null;
         }
-        JSONObject jo = new JSONObject();
+        JSONObject jo = new JSONObject(names.length());
         for (int i = 0; i < names.length(); i += 1) {
             jo.put(names.getString(i), this.opt(i));
         }
@@ -1031,12 +1323,14 @@ public class JSONArray implements Iterable<Object> {
      * whitespace is added. If it is not possible to produce a syntactically
      * correct JSON text then null will be returned instead. This could occur if
      * the array contains an invalid number.
-     * <p>
+     * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
+     * </b>
      *
      * @return a printable, displayable, transmittable representation of the
      *         array.
      */
+    @Override
     public String toString() {
         try {
             return this.toString(0);
@@ -1046,8 +1340,23 @@ public class JSONArray implements Iterable<Object> {
     }
 
     /**
-     * Make a prettyprinted JSON text of this JSONArray. Warning: This method
+     * Make a pretty-printed JSON text of this JSONArray.
-     * assumes that the data structure is acyclical.
+     * 
+     * <p>If <code>indentFactor > 0</code> and the {@link JSONArray} has only
+     * one element, then the array will be output on a single line:
+     * <pre>{@code [1]}</pre>
+     * 
+     * <p>If an array has 2 or more elements, then it will be output across
+     * multiple lines: <pre>{@code
+     * [
+     * 1,
+     * "value 2",
+     * 3
+     * ]
+     * }</pre>
+     * <p><b>
+     * Warning: This method assumes that the data structure is acyclical.
+     * </b>
      * 
      * @param indentFactor
      *            The number of spaces to add to each level of indentation.
@@ -1067,8 +1376,9 @@ public class JSONArray implements Iterable<Object> {
     /**
      * Write the contents of the JSONArray as JSON text to a writer. For
      * compactness, no whitespace is added.
-     * <p>
+     * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
+     *</b>
      *
      * @return The writer.
      * @throws JSONException
@@ -1078,19 +1388,34 @@ public class JSONArray implements Iterable<Object> {
     }
 
     /**
-     * Write the contents of the JSONArray as JSON text to a writer. For
+     * Write the contents of the JSONArray as JSON text to a writer.
-     * compactness, no whitespace is added.
-     * <p>
-     * Warning: This method assumes that the data structure is acyclical.
      * 
+     * <p>If <code>indentFactor > 0</code> and the {@link JSONArray} has only
+     * one element, then the array will be output on a single line:
+     * <pre>{@code [1]}</pre>
+     * 
+     * <p>If an array has 2 or more elements, then it will be output across
+     * multiple lines: <pre>{@code
+     * [
+     * 1,
+     * "value 2",
+     * 3
+     * ]
+     * }</pre>
+     * <p><b>
+     * Warning: This method assumes that the data structure is acyclical.
+     * </b>
+     *
+     * @param writer
+     *            Writes the serialized JSON
      * @param indentFactor
      *            The number of spaces to add to each level of indentation.
      * @param indent
-     *            The indention of the top level.
+     *            The indentation of the top level.
      * @return The writer.
      * @throws JSONException
      */
-    Writer write(Writer writer, int indentFactor, int indent)
+    public Writer write(Writer writer, int indentFactor, int indent)
             throws JSONException {
         try {
             boolean commanate = false;
@@ -1098,8 +1423,12 @@ public class JSONArray implements Iterable<Object> {
             writer.write('[');
 
             if (length == 1) {
+                try {
                     JSONObject.writeValue(writer, this.myArrayList.get(0),
                             indentFactor, indent);
+                } catch (Exception e) {
+                    throw new JSONException("Unable to write JSONArray value at index: 0", e);
+                }
             } else if (length != 0) {
                 final int newindent = indent + indentFactor;
 
@@ -1111,8 +1440,12 @@ public class JSONArray implements Iterable<Object> {
                         writer.write('\n');
                     }
                     JSONObject.indent(writer, newindent);
+                    try {
                         JSONObject.writeValue(writer, this.myArrayList.get(i),
                                 indentFactor, newindent);
+                    } catch (Exception e) {
+                        throw new JSONException("Unable to write JSONArray value at index: " + i, e);
+                    }
                     commanate = true;
                 }
                 if (indentFactor > 0) {
@@ -1126,4 +1459,29 @@ public class JSONArray implements Iterable<Object> {
             throw new JSONException(e);
         }
     }
+
+    /**
+     * Returns a java.util.List containing all of the elements in this array.
+     * If an element in the array is a JSONArray or JSONObject it will also
+     * be converted.
+     * <p>
+     * Warning: This method assumes that the data structure is acyclical.
+     *
+     * @return a java.util.List containing the elements of this array
+     */
+    public List<Object> toList() {
+        List<Object> results = new ArrayList<Object>(this.myArrayList.size());
+        for (Object element : this.myArrayList) {
+            if (element == null || JSONObject.NULL.equals(element)) {
+                results.add(null);
+            } else if (element instanceof JSONArray) {
+                results.add(((JSONArray) element).toList());
+            } else if (element instanceof JSONObject) {
+                results.add(((JSONObject) element).toMap());
+            } else {
+                results.add(element);
+            }
+        }
+        return results;
+    }
 }

JSONException.java

@@ -4,7 +4,7 @@ package org.json;
  * The JSONException is thrown by the JSON.org classes when things are amiss.
  *
  * @author JSON.org
- * @version 2015-10-18
+ * @version 2015-12-09
  */
 public class JSONException extends RuntimeException {
     /** Serialization ID */

JSONML.java

@@ -1,5 +1,7 @@
 package org.json;
 
+import java.util.Map.Entry;
+
 /*
 Copyright (c) 2008 JSON.org
 
@@ -24,32 +26,30 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
-import java.util.Iterator;
-
-
 /**
  * This provides static methods to convert an XML text into a JSONArray or
  * JSONObject, and to covert a JSONArray or JSONObject into an XML text using
  * the JsonML transform.
  *
  * @author JSON.org
- * @version 2014-05-03
+ * @version 2016-01-30
  */
 public class JSONML {
-
     /**
      * Parse XML values and store them in a JSONArray.
      * @param x       The XMLTokener containing the source string.
      * @param arrayForm true if array form, false if object form.
      * @param ja      The JSONArray that is containing the current tag or null
      *     if we are at the outermost level.
+     * @param keepStrings	Don't type-convert text nodes and attribute values
      * @return A JSONArray if the value is the outermost tag, otherwise null.
      * @throws JSONException
      */
     private static Object parse(
         XMLTokener x,
         boolean    arrayForm,
-        JSONArray  ja
+        JSONArray  ja,
+        boolean keepStrings
     ) throws JSONException {
         String     attribute;
         char       c;
@@ -174,7 +174,7 @@ public class JSONML {
                             if (!(token instanceof String)) {
                                 throw x.syntaxError("Missing value");
                             }
-                            newjo.accumulate(attribute, XML.stringToValue((String)token));
+                            newjo.accumulate(attribute, keepStrings ? ((String)token) :XML.stringToValue((String)token));
                             token = null;
                         } else {
                             newjo.accumulate(attribute, "");
@@ -193,9 +193,8 @@ public class JSONML {
                         if (ja == null) {
                             if (arrayForm) {
                                 return newja;
-                            } else {
-                                return newjo;
                             }
+                            return newjo;
                         }
 
 // Content, between <...> and </...>
@@ -204,7 +203,7 @@ public class JSONML {
                         if (token != XML.GT) {
                             throw x.syntaxError("Misshaped tag");
                         }
-                        closeTag = (String)parse(x, arrayForm, newja);
+                        closeTag = (String)parse(x, arrayForm, newja, keepStrings);
                         if (closeTag != null) {
                             if (!closeTag.equals(tagName)) {
                                 throw x.syntaxError("Mismatched '" + tagName +
@@ -217,9 +216,8 @@ public class JSONML {
                             if (ja == null) {
                                 if (arrayForm) {
                                     return newja;
-                                } else {
-                                    return newjo;
                                 }
+                                return newjo;
                             }
                         }
                     }
@@ -227,7 +225,7 @@ public class JSONML {
             } else {
                 if (ja != null) {
                     ja.put(token instanceof String
-                        ? XML.stringToValue((String)token)
+                        ? keepStrings ? XML.unescape((String)token) :XML.stringToValue((String)token)
                         : token);
                 }
             }
@@ -245,10 +243,54 @@ public class JSONML {
      * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
      * @param string The source string.
      * @return A JSONArray containing the structured data from the XML string.
-     * @throws JSONException
+     * @throws JSONException Thrown on error converting to a JSONArray
      */
     public static JSONArray toJSONArray(String string) throws JSONException {
-        return toJSONArray(new XMLTokener(string));
+        return (JSONArray)parse(new XMLTokener(string), true, null, false);
+    }
+
+
+    /**
+     * Convert a well-formed (but not necessarily valid) XML string into a
+     * JSONArray using the JsonML transform. Each XML tag is represented as
+     * a JSONArray in which the first element is the tag name. If the tag has
+     * attributes, then the second element will be JSONObject containing the
+     * name/value pairs. If the tag contains children, then strings and
+     * JSONArrays will represent the child tags.
+     * As opposed to toJSONArray this method does not attempt to convert 
+     * any text node or attribute value to any type 
+     * but just leaves it as a string.
+     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * @param string The source string.
+     * @param keepStrings If true, then values will not be coerced into boolean
+     *  or numeric values and will instead be left as strings
+     * @return A JSONArray containing the structured data from the XML string.
+     * @throws JSONException Thrown on error converting to a JSONArray
+     */
+    public static JSONArray toJSONArray(String string, boolean keepStrings) throws JSONException {
+        return (JSONArray)parse(new XMLTokener(string), true, null, keepStrings);
+    }
+
+
+    /**
+     * Convert a well-formed (but not necessarily valid) XML string into a
+     * JSONArray using the JsonML transform. Each XML tag is represented as
+     * a JSONArray in which the first element is the tag name. If the tag has
+     * attributes, then the second element will be JSONObject containing the
+     * name/value pairs. If the tag contains children, then strings and
+     * JSONArrays will represent the child content and tags.
+     * As opposed to toJSONArray this method does not attempt to convert 
+     * any text node or attribute value to any type 
+     * but just leaves it as a string.
+     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * @param x An XMLTokener.
+     * @param keepStrings If true, then values will not be coerced into boolean
+     *  or numeric values and will instead be left as strings
+     * @return A JSONArray containing the structured data from the XML string.
+     * @throws JSONException Thrown on error converting to a JSONArray
+     */
+    public static JSONArray toJSONArray(XMLTokener x, boolean keepStrings) throws JSONException {
+        return (JSONArray)parse(x, true, null, keepStrings);
     }
 
 
@@ -262,28 +304,10 @@ public class JSONML {
      * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
      * @param x An XMLTokener.
      * @return A JSONArray containing the structured data from the XML string.
-     * @throws JSONException
+     * @throws JSONException Thrown on error converting to a JSONArray
      */
     public static JSONArray toJSONArray(XMLTokener x) throws JSONException {
-        return (JSONArray)parse(x, true, null);
+        return (JSONArray)parse(x, true, null, false);
-    }
-
-
-    /**
-     * Convert a well-formed (but not necessarily valid) XML string into a
-     * JSONObject using the JsonML transform. Each XML tag is represented as
-     * a JSONObject with a "tagName" property. If the tag has attributes, then
-     * the attributes will be in the JSONObject as properties. If the tag
-     * contains children, the object will have a "childNodes" property which
-     * will be an array of strings and JsonML JSONObjects.
-
-     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
-     * @param x An XMLTokener of the XML source text.
-     * @return A JSONObject containing the structured data from the XML string.
-     * @throws JSONException
-     */
-    public static JSONObject toJSONObject(XMLTokener x) throws JSONException {
-           return (JSONObject)parse(x, false, null);
     }
 
 
@@ -298,10 +322,68 @@ public class JSONML {
      * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
      * @param string The XML source text.
      * @return A JSONObject containing the structured data from the XML string.
-     * @throws JSONException
+     * @throws JSONException Thrown on error converting to a JSONObject
      */
     public static JSONObject toJSONObject(String string) throws JSONException {
-        return toJSONObject(new XMLTokener(string));
+        return (JSONObject)parse(new XMLTokener(string), false, null, false);
+    }
+    
+    
+    /**
+     * Convert a well-formed (but not necessarily valid) XML string into a
+     * JSONObject using the JsonML transform. Each XML tag is represented as
+     * a JSONObject with a "tagName" property. If the tag has attributes, then
+     * the attributes will be in the JSONObject as properties. If the tag
+     * contains children, the object will have a "childNodes" property which
+     * will be an array of strings and JsonML JSONObjects.
+
+     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * @param string The XML source text.
+     * @param keepStrings If true, then values will not be coerced into boolean
+     *  or numeric values and will instead be left as strings
+     * @return A JSONObject containing the structured data from the XML string.
+     * @throws JSONException Thrown on error converting to a JSONObject
+     */
+    public static JSONObject toJSONObject(String string, boolean keepStrings) throws JSONException {
+        return (JSONObject)parse(new XMLTokener(string), false, null, keepStrings);
+    }
+
+    
+    /**
+     * Convert a well-formed (but not necessarily valid) XML string into a
+     * JSONObject using the JsonML transform. Each XML tag is represented as
+     * a JSONObject with a "tagName" property. If the tag has attributes, then
+     * the attributes will be in the JSONObject as properties. If the tag
+     * contains children, the object will have a "childNodes" property which
+     * will be an array of strings and JsonML JSONObjects.
+
+     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * @param x An XMLTokener of the XML source text.
+     * @return A JSONObject containing the structured data from the XML string.
+     * @throws JSONException Thrown on error converting to a JSONObject
+     */
+    public static JSONObject toJSONObject(XMLTokener x) throws JSONException {
+           return (JSONObject)parse(x, false, null, false);
+    }
+
+
+    /**
+     * Convert a well-formed (but not necessarily valid) XML string into a
+     * JSONObject using the JsonML transform. Each XML tag is represented as
+     * a JSONObject with a "tagName" property. If the tag has attributes, then
+     * the attributes will be in the JSONObject as properties. If the tag
+     * contains children, the object will have a "childNodes" property which
+     * will be an array of strings and JsonML JSONObjects.
+
+     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * @param x An XMLTokener of the XML source text.
+     * @param keepStrings If true, then values will not be coerced into boolean
+     *  or numeric values and will instead be left as strings
+     * @return A JSONObject containing the structured data from the XML string.
+     * @throws JSONException Thrown on error converting to a JSONObject
+     */
+    public static JSONObject toJSONObject(XMLTokener x, boolean keepStrings) throws JSONException {
+           return (JSONObject)parse(x, false, null, keepStrings);
     }
 
 
@@ -309,18 +391,15 @@ public class JSONML {
      * Reverse the JSONML transformation, making an XML text from a JSONArray.
      * @param ja A JSONArray.
      * @return An XML string.
-     * @throws JSONException
+     * @throws JSONException Thrown on error converting to a string
      */
     public static String toString(JSONArray ja) throws JSONException {
         int                 i;
         JSONObject          jo;
-        String              key;
-        Iterator<String>    keys;
         int                 length;
         Object              object;
         StringBuilder        sb = new StringBuilder();
         String              tagName;
-        String               value;
 
 // Emit <tagName
 
@@ -337,17 +416,16 @@ public class JSONML {
 
 // Emit the attributes
 
-            keys = jo.keys();
+            for (final Entry<String, ?> entry : jo.entrySet()) {
-            while (keys.hasNext()) {
+            	final String key = entry.getKey();
-                key = keys.next();
                 XML.noSpace(key);
-                value = jo.optString(key);
+                final Object value = entry.getValue();
                 if (value != null) {
                     sb.append(' ');
                     sb.append(XML.escape(key));
                     sb.append('=');
                     sb.append('"');
-                    sb.append(XML.escape(value));
+                    sb.append(XML.escape(value.toString()));
                     sb.append('"');
                 }
             }
@@ -393,18 +471,16 @@ public class JSONML {
      * The other properties are attributes with string values.
      * @param jo A JSONObject.
      * @return An XML string.
-     * @throws JSONException
+     * @throws JSONException Thrown on error converting to a string
      */
     public static String toString(JSONObject jo) throws JSONException {
         StringBuilder sb = new StringBuilder();
         int                 i;
         JSONArray           ja;
-        String              key;
-        Iterator<String>    keys;
         int                 length;
         Object              object;
         String              tagName;
-        String              value;
+        Object              value;
 
 //Emit <tagName
 
@@ -419,18 +495,17 @@ public class JSONML {
 
 //Emit the attributes
 
-        keys = jo.keys();
+        for (final Entry<String, ?> entry : jo.entrySet()) {
-        while (keys.hasNext()) {
+        	final String key = entry.getKey();
-            key = keys.next();
             if (!"tagName".equals(key) && !"childNodes".equals(key)) {
                 XML.noSpace(key);
-                value = jo.optString(key);
+                value = entry.getValue();
                 if (value != null) {
                     sb.append(' ');
                     sb.append(XML.escape(key));
                     sb.append('=');
                     sb.append('"');
-                    sb.append(XML.escape(value));
+                    sb.append(XML.escape(value.toString()));
                     sb.append('"');
                 }
             }

JSONPointer.java

@@ -0,0 +1,269 @@
+package org.json;
+
+import static java.lang.String.format;
+
+import java.io.UnsupportedEncodingException;
+import java.net.URLDecoder;
+import java.net.URLEncoder;
+import java.util.*;
+
+/*
+Copyright (c) 2002 JSON.org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+The Software shall be used for Good, not Evil.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+/**
+ * A JSON Pointer is a simple query language defined for JSON documents by
+ * <a href="https://tools.ietf.org/html/rfc6901">RFC 6901</a>.
+ * 
+ * In a nutshell, JSONPointer allows the user to navigate into a JSON document
+ * using strings, and retrieve targeted objects, like a simple form of XPATH.
+ * Path segments are separated by the '/' char, which signifies the root of
+ * the document when it appears as the first char of the string. Array 
+ * elements are navigated using ordinals, counting from 0. JSONPointer strings
+ * may be extended to any arbitrary number of segments. If the navigation
+ * is successful, the matched item is returned. A matched item may be a
+ * JSONObject, a JSONArray, or a JSON value. If the JSONPointer string building 
+ * fails, an appropriate exception is thrown. If the navigation fails to find
+ * a match, a JSONPointerException is thrown. 
+ * 
+ * @author JSON.org
+ * @version 2016-05-14
+ */
+public class JSONPointer {
+
+    // used for URL encoding and decoding
+    private static final String ENCODING = "utf-8";
+
+    /**
+     * This class allows the user to build a JSONPointer in steps, using
+     * exactly one segment in each step.
+     */
+    public static class Builder {
+
+        // Segments for the eventual JSONPointer string
+        private final List<String> refTokens = new ArrayList<String>();
+
+        /**
+         * Creates a {@code JSONPointer} instance using the tokens previously set using the
+         * {@link #append(String)} method calls.
+         */
+        public JSONPointer build() {
+            return new JSONPointer(this.refTokens);
+        }
+
+        /**
+         * Adds an arbitrary token to the list of reference tokens. It can be any non-null value.
+         * 
+         * Unlike in the case of JSON string or URI fragment representation of JSON pointers, the
+         * argument of this method MUST NOT be escaped. If you want to query the property called
+         * {@code "a~b"} then you should simply pass the {@code "a~b"} string as-is, there is no
+         * need to escape it as {@code "a~0b"}.
+         * 
+         * @param token the new token to be appended to the list
+         * @return {@code this}
+         * @throws NullPointerException if {@code token} is null
+         */
+        public Builder append(String token) {
+            if (token == null) {
+                throw new NullPointerException("token cannot be null");
+            }
+            this.refTokens.add(token);
+            return this;
+        }
+
+        /**
+         * Adds an integer to the reference token list. Although not necessarily, mostly this token will
+         * denote an array index. 
+         * 
+         * @param arrayIndex the array index to be added to the token list
+         * @return {@code this}
+         */
+        public Builder append(int arrayIndex) {
+            this.refTokens.add(String.valueOf(arrayIndex));
+            return this;
+        }
+    }
+
+    /**
+     * Static factory method for {@link Builder}. Example usage:
+     * 
+     * <pre><code>
+     * JSONPointer pointer = JSONPointer.builder()
+     *       .append("obj")
+     *       .append("other~key").append("another/key")
+     *       .append("\"")
+     *       .append(0)
+     *       .build();
+     * </code></pre>
+     * 
+     *  @return a builder instance which can be used to construct a {@code JSONPointer} instance by chained
+     *  {@link Builder#append(String)} calls.
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    // Segments for the JSONPointer string
+    private final List<String> refTokens;
+
+    /**
+     * Pre-parses and initializes a new {@code JSONPointer} instance. If you want to
+     * evaluate the same JSON Pointer on different JSON documents then it is recommended
+     * to keep the {@code JSONPointer} instances due to performance considerations.
+     * 
+     * @param pointer the JSON String or URI Fragment representation of the JSON pointer.
+     * @throws IllegalArgumentException if {@code pointer} is not a valid JSON pointer
+     */
+    public JSONPointer(final String pointer) {
+        if (pointer == null) {
+            throw new NullPointerException("pointer cannot be null");
+        }
+        if (pointer.isEmpty() || pointer.equals("#")) {
+            this.refTokens = Collections.emptyList();
+            return;
+        }
+        String refs;
+        if (pointer.startsWith("#/")) {
+            refs = pointer.substring(2);
+            try {
+                refs = URLDecoder.decode(refs, ENCODING);
+            } catch (UnsupportedEncodingException e) {
+                throw new RuntimeException(e);
+            }
+        } else if (pointer.startsWith("/")) {
+            refs = pointer.substring(1);
+        } else {
+            throw new IllegalArgumentException("a JSON pointer should start with '/' or '#/'");
+        }
+        this.refTokens = new ArrayList<String>();
+        for (String token : refs.split("/")) {
+            this.refTokens.add(unescape(token));
+        }
+    }
+
+    public JSONPointer(List<String> refTokens) {
+        this.refTokens = new ArrayList<String>(refTokens);
+    }
+
+    private String unescape(String token) {
+        return token.replace("~1", "/").replace("~0", "~")
+                .replace("\\\"", "\"")
+                .replace("\\\\", "\\");
+    }
+
+    /**
+     * Evaluates this JSON Pointer on the given {@code document}. The {@code document}
+     * is usually a {@link JSONObject} or a {@link JSONArray} instance, but the empty
+     * JSON Pointer ({@code ""}) can be evaluated on any JSON values and in such case the
+     * returned value will be {@code document} itself. 
+     * 
+     * @param document the JSON document which should be the subject of querying.
+     * @return the result of the evaluation
+     * @throws JSONPointerException if an error occurs during evaluation
+     */
+    public Object queryFrom(Object document) {
+        if (this.refTokens.isEmpty()) {
+            return document;
+        }
+        Object current = document;
+        for (String token : this.refTokens) {
+            if (current instanceof JSONObject) {
+                current = ((JSONObject) current).opt(unescape(token));
+            } else if (current instanceof JSONArray) {
+                current = readByIndexToken(current, token);
+            } else {
+                throw new JSONPointerException(format(
+                        "value [%s] is not an array or object therefore its key %s cannot be resolved", current,
+                        token));
+            }
+        }
+        return current;
+    }
+
+    /**
+     * Matches a JSONArray element by ordinal position
+     * @param current the JSONArray to be evaluated
+     * @param indexToken the array index in string form
+     * @return the matched object. If no matching item is found a
+     * JSONPointerException is thrown
+     */
+    @SuppressWarnings("boxing")
+    private Object readByIndexToken(Object current, String indexToken) {
+        try {
+            int index = Integer.parseInt(indexToken);
+            JSONArray currentArr = (JSONArray) current;
+            if (index >= currentArr.length()) {
+                throw new JSONPointerException(format("index %d is out of bounds - the array has %d elements", index,
+                        currentArr.length()));
+            }
+            return currentArr.get(index);
+        } catch (NumberFormatException e) {
+            throw new JSONPointerException(format("%s is not an array index", indexToken), e);
+        }
+    }
+
+    /**
+     * Returns a string representing the JSONPointer path value using string
+     * representation
+     */
+    @Override
+    public String toString() {
+        StringBuilder rval = new StringBuilder("");
+        for (String token: this.refTokens) {
+            rval.append('/').append(escape(token));
+        }
+        return rval.toString();
+    }
+
+    /**
+     * Escapes path segment values to an unambiguous form.
+     * The escape char to be inserted is '~'. The chars to be escaped 
+     * are ~, which maps to ~0, and /, which maps to ~1. Backslashes
+     * and double quote chars are also escaped.
+     * @param token the JSONPointer segment value to be escaped
+     * @return the escaped value for the token
+     */
+    private String escape(String token) {
+        return token.replace("~", "~0")
+                .replace("/", "~1")
+                .replace("\\", "\\\\")
+                .replace("\"", "\\\"");
+    }
+
+    /**
+     * Returns a string representing the JSONPointer path value using URI
+     * fragment identifier representation
+     */
+    public String toURIFragment() {
+        try {
+            StringBuilder rval = new StringBuilder("#");
+            for (String token : this.refTokens) {
+                rval.append('/').append(URLEncoder.encode(token, ENCODING));
+            }
+            return rval.toString();
+        } catch (UnsupportedEncodingException e) {
+            throw new RuntimeException(e);
+        }
+    }
+    
+}

JSONPointerException.java

@@ -0,0 +1,45 @@
+package org.json;
+
+/*
+Copyright (c) 2002 JSON.org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+The Software shall be used for Good, not Evil.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+/**
+ * The JSONPointerException is thrown by {@link JSONPointer} if an error occurs
+ * during evaluating a pointer.
+ * 
+ * @author JSON.org
+ * @version 2016-05-13
+ */
+public class JSONPointerException extends JSONException {
+    private static final long serialVersionUID = 8872944667561856751L;
+
+    public JSONPointerException(String message) {
+        super(message);
+    }
+
+    public JSONPointerException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+}

JSONStringer.java

@@ -54,7 +54,7 @@ import java.io.StringWriter;
  * <p>
  * This can sometimes be easier than using a JSONObject to build a string.
  * @author JSON.org
- * @version 2008-09-18
+ * @version 2015-12-09
  */
 public class JSONStringer extends JSONWriter {
     /**
@@ -72,6 +72,7 @@ public class JSONStringer extends JSONWriter {
      * <code>endArray</code>).
      * @return The JSON text.
      */
+    @Override
     public String toString() {
         return this.mode == 'd' ? this.writer.toString() : null;
     }

JSONTokener.java

@@ -29,7 +29,7 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-*/
+ */
 
 /**
  * A JSONTokener takes a source string and extracts characters and tokens from
@@ -39,18 +39,26 @@ SOFTWARE.
  * @version 2014-05-03
  */
 public class JSONTokener {
-
+    /** current read character position on the current line. */
     private long character;
+    /** flag to indicate if the end of the input has been found. */
     private boolean eof;
+    /** current read index of the input. */
     private long index;
+    /** current line of the input. */
     private long line;
+    /** previous character read from the input. */
     private char previous;
-    private Reader  reader;
+    /** Reader for the input. */
+    private final Reader reader;
+    /** flag to indicate that a previous character was requested. */
     private boolean usePrevious;
+    /** the number of characters read in the previous line. */
+    private long characterPreviousLine;
 
 
     /**
-     * Construct a JSONTokener from a Reader.
+     * Construct a JSONTokener from a Reader. The caller must close the Reader.
      *
      * @param reader     A reader.
      */
@@ -63,15 +71,16 @@ public class JSONTokener {
         this.previous = 0;
         this.index = 0;
         this.character = 1;
+        this.characterPreviousLine = 0;
         this.line = 1;
     }
 
 
     /**
-     * Construct a JSONTokener from an InputStream.
+     * Construct a JSONTokener from an InputStream. The caller must close the input stream.
      * @param inputStream The source.
      */
-    public JSONTokener(InputStream inputStream) throws JSONException {
+    public JSONTokener(InputStream inputStream) {
         this(new InputStreamReader(inputStream));
     }
 
@@ -90,17 +99,30 @@ public class JSONTokener {
      * Back up one character. This provides a sort of lookahead capability,
      * so that you can test for a digit or letter before attempting to parse
      * the next number or identifier.
+     * @throws JSONException Thrown if trying to step back more than 1 step
+     *  or if already at the start of the string
      */
     public void back() throws JSONException {
         if (this.usePrevious || this.index <= 0) {
             throw new JSONException("Stepping back two steps is not supported");
         }
-        this.index -= 1;
+        this.decrementIndexes();
-        this.character -= 1;
         this.usePrevious = true;
         this.eof = false;
     }
 
+    /**
+     * Decrements the indexes for the {@link #back()} method based on the previous character read.
+     */
+    private void decrementIndexes() {
+        this.index--;
+        if(this.previous=='\r' || this.previous == '\n') {
+            this.line--;
+            this.character=this.characterPreviousLine ;
+        } else if(this.character > 0){
+            this.character--;
+        }
+    }
 
     /**
      * Get the hex value of a character (base16).
@@ -121,6 +143,11 @@ public class JSONTokener {
         return -1;
     }
 
+    /**
+     * Checks if the end of the input has been reached.
+     *  
+     * @return true if at the end of the file and we didn't step back
+     */
     public boolean end() {
         return this.eof && !this.usePrevious;
     }
@@ -130,13 +157,28 @@ public class JSONTokener {
      * Determine if the source string still contains characters that next()
      * can consume.
      * @return true if not yet at the end of the source.
+     * @throws JSONException thrown if there is an error stepping forward
+     *  or backward while checking for more data.
      */
     public boolean more() throws JSONException {
-        this.next();
+        if(this.usePrevious) {
-        if (this.end()) {
+            return true;
+        }
+        try {
+            this.reader.mark(1);
+        } catch (IOException e) {
+            throw new JSONException("Unable to preserve stream position", e);
+        }
+        try {
+            // -1 is EOF, but next() can not consume the null character '\0'
+            if(this.reader.read() <= 0) {
+                this.eof = true;
                 return false;
             }
-        this.back();
+            this.reader.reset();
+        } catch (IOException e) {
+            throw new JSONException("Unable to read the next character from the stream", e);
+        }
         return true;
     }
 
@@ -145,6 +187,7 @@ public class JSONTokener {
      * Get the next character in the source string.
      *
      * @return The next character, or 0 if past the end of the source string.
+     * @throws JSONException Thrown if there is an error reading the source string.
      */
     public char next() throws JSONException {
         int c;
@@ -157,26 +200,39 @@ public class JSONTokener {
             } catch (IOException exception) {
                 throw new JSONException(exception);
             }
-
+        }
         if (c <= 0) { // End of stream
             this.eof = true;
-                c = 0;
+            return 0;
-            }
-        }
-        this.index += 1;
-        if (this.previous == '\r') {
-            this.line += 1;
-            this.character = c == '\n' ? 0 : 1;
-        } else if (c == '\n') {
-            this.line += 1;
-            this.character = 0;
-        } else {
-            this.character += 1;
         }
+        this.incrementIndexes(c);
         this.previous = (char) c;
         return this.previous;
     }
 
+    /**
+     * Increments the internal indexes according to the previous character
+     * read and the character passed as the current character.
+     * @param c the current character read.
+     */
+    private void incrementIndexes(int c) {
+        if(c > 0) {
+            this.index++;
+            if(c=='\r') {
+                this.line++;
+                this.characterPreviousLine = this.character;
+                this.character=0;
+            }else if (c=='\n') {
+                if(this.previous != '\r') {
+                    this.line++;
+                    this.characterPreviousLine = this.character;
+                }
+                this.character=0;
+            } else {
+                this.character++;
+            }
+        }
+    }
 
     /**
      * Consume the next character, and check that it matches a specified
@@ -188,9 +244,12 @@ public class JSONTokener {
     public char next(char c) throws JSONException {
         char n = this.next();
         if (n != c) {
+            if(n > 0) {
                 throw this.syntaxError("Expected '" + c + "' and instead saw '" +
                         n + "'");
             }
+            throw this.syntaxError("Expected '" + c + "' and instead saw ''");
+        }
         return n;
     }
 
@@ -225,7 +284,7 @@ public class JSONTokener {
 
     /**
      * Get the next char in the string, skipping whitespace.
-     * @throws JSONException
+     * @throws JSONException Thrown if there is an error reading the source string.
      * @return  A character, or 0 if there are no more characters.
      */
     public char nextClean() throws JSONException {
@@ -278,7 +337,11 @@ public class JSONTokener {
                     sb.append('\r');
                     break;
                 case 'u':
+                    try {
                         sb.append((char)Integer.parseInt(this.next(4), 16));
+                    } catch (NumberFormatException e) {
+                        throw this.syntaxError("Illegal escape.", e);
+                    }
                     break;
                 case '"':
                 case '\'':
@@ -305,6 +368,8 @@ public class JSONTokener {
      * end of line, whichever comes first.
      * @param  delimiter A delimiter character.
      * @return   A string.
+     * @throws JSONException Thrown if there is an error while searching
+     *  for the delimiter
      */
     public String nextTo(char delimiter) throws JSONException {
         StringBuilder sb = new StringBuilder();
@@ -326,6 +391,8 @@ public class JSONTokener {
      * characters or the end of line, whichever comes first.
      * @param delimiters A set of delimiter characters.
      * @return A string, trimmed.
+     * @throws JSONException Thrown if there is an error while searching
+     *  for the delimiter
      */
     public String nextTo(String delimiters) throws JSONException {
         char c;
@@ -397,6 +464,8 @@ public class JSONTokener {
      * @param to A character to skip to.
      * @return The requested character, or zero if the requested character
      * is not found.
+     * @throws JSONException Thrown if there is an error while searching
+     *  for the to character
      */
     public char skipTo(char to) throws JSONException {
         char c;
@@ -408,13 +477,17 @@ public class JSONTokener {
             do {
                 c = this.next();
                 if (c == 0) {
+                    // in some readers, reset() may throw an exception if
+                    // the remaining portion of the input is greater than
+                    // the mark size (1,000,000 above).
                     this.reader.reset();
                     this.index = startIndex;
                     this.character = startCharacter;
                     this.line = startLine;
-                    return c;
+                    return 0;
                 }
             } while (c != to);
+            this.reader.mark(1);
         } catch (IOException exception) {
             throw new JSONException(exception);
         }
@@ -422,7 +495,6 @@ public class JSONTokener {
         return c;
     }
 
-
     /**
      * Make a JSONException to signal a syntax error.
      *
@@ -433,12 +505,23 @@ public class JSONTokener {
         return new JSONException(message + this.toString());
     }
 
+    /**
+     * Make a JSONException to signal a syntax error.
+     *
+     * @param message The error message.
+     * @param causedBy The throwable that caused the error.
+     * @return  A JSONException object, suitable for throwing
+     */
+    public JSONException syntaxError(String message, Throwable causedBy) {
+        return new JSONException(message + this.toString(), causedBy);
+    }
 
     /**
      * Make a printable string of this JSONTokener.
      *
      * @return " at {index} [character {character} line {line}]"
      */
+    @Override
     public String toString() {
         return " at " + this.index + " [character " + this.character + " line " +
                 this.line + "]";

JSONWriter.java

@@ -1,7 +1,6 @@
 package org.json;
 
 import java.io.IOException;
-import java.io.Writer;
 
 /*
 Copyright (c) 2006 JSON.org
@@ -50,11 +49,11 @@ SOFTWARE.
  * <p>
  * The first method called must be <code>array</code> or <code>object</code>.
  * There are no methods for adding commas or colons. JSONWriter adds them for
- * you. Objects and arrays can be nested up to 20 levels deep.
+ * you. Objects and arrays can be nested up to 200 levels deep.
  * <p>
  * This can sometimes be easier than using a JSONObject to build a string.
  * @author JSON.org
- * @version 2011-11-24
+ * @version 2016-08-08
  */
 public class JSONWriter {
     private static final int maxdepth = 200;
@@ -88,12 +87,12 @@ public class JSONWriter {
     /**
      * The writer that will receive the output.
      */
-    protected Writer writer;
+    protected Appendable writer;
 
     /**
      * Make a fresh JSONWriter. It can be used to build one JSON text.
      */
-    public JSONWriter(Writer w) {
+    public JSONWriter(Appendable w) {
         this.comma = false;
         this.mode = 'i';
         this.stack = new JSONObject[maxdepth];
@@ -114,9 +113,9 @@ public class JSONWriter {
         if (this.mode == 'o' || this.mode == 'a') {
             try {
                 if (this.comma && this.mode == 'a') {
-                    this.writer.write(',');
+                    this.writer.append(',');
                 }
-                this.writer.write(string);
+                this.writer.append(string);
             } catch (IOException e) {
                 throw new JSONException(e);
             }
@@ -150,20 +149,20 @@ public class JSONWriter {
 
     /**
      * End something.
-     * @param mode Mode
+     * @param m Mode
      * @param c Closing character
      * @return this
      * @throws JSONException If unbalanced.
      */
-    private JSONWriter end(char mode, char c) throws JSONException {
+    private JSONWriter end(char m, char c) throws JSONException {
-        if (this.mode != mode) {
+        if (this.mode != m) {
-            throw new JSONException(mode == 'a'
+            throw new JSONException(m == 'a'
                 ? "Misplaced endArray."
                 : "Misplaced endObject.");
         }
-        this.pop(mode);
+        this.pop(m);
         try {
-            this.writer.write(c);
+            this.writer.append(c);
         } catch (IOException e) {
             throw new JSONException(e);
         }
@@ -207,10 +206,10 @@ public class JSONWriter {
             try {
                 this.stack[this.top - 1].putOnce(string, Boolean.TRUE);
                 if (this.comma) {
-                    this.writer.write(',');
+                    this.writer.append(',');
                 }
-                this.writer.write(JSONObject.quote(string));
+                this.writer.append(JSONObject.quote(string));
-                this.writer.write(':');
+                this.writer.append(':');
                 this.comma = false;
                 this.mode = 'o';
                 return this;

LICENSE

@@ -0,0 +1,23 @@
+============================================================================
+
+Copyright (c) 2002 JSON.org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+The Software shall be used for Good, not Evil.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Property.java

@@ -25,7 +25,7 @@ SOFTWARE.
 */
 
 import java.util.Enumeration;
-import java.util.Iterator;
+import java.util.Map.Entry;
 import java.util.Properties;
 
 /**
@@ -41,7 +41,7 @@ public class Property {
      * @throws JSONException
      */
     public static JSONObject toJSONObject(java.util.Properties properties) throws JSONException {
-        JSONObject jo = new JSONObject();
+        JSONObject jo = new JSONObject(properties == null ? 0 : properties.size());
         if (properties != null && !properties.isEmpty()) {
             Enumeration<?> enumProperties = properties.propertyNames();
             while(enumProperties.hasMoreElements()) {
@@ -61,10 +61,11 @@ public class Property {
     public static Properties toProperties(JSONObject jo)  throws JSONException {
         Properties  properties = new Properties();
         if (jo != null) {
-            Iterator<String> keys = jo.keys();
+            for (final Entry<String, ?> entry : jo.entrySet()) {
-            while (keys.hasNext()) {
+                Object value = entry.getValue();
-                String name = keys.next();
+                if (!JSONObject.NULL.equals(value)) {
-                properties.put(name, jo.getString(name));
+                	properties.put(entry.getKey(), value.toString());
+                }
             }
         }
         return properties;

README

@@ -15,14 +15,14 @@ The license includes this restriction: "The software shall be used for good,
 not evil." If your conscience cannot live with that, then choose a different
 package.
 
-The package compiles on Java 1.8.
+The package compiles on Java 1.6-1.8.
 
 
 JSONObject.java: The JSONObject can parse text from a String or a JSONTokener
 to produce a map-like object. The object provides methods for manipulating its
 contents, and for producing a JSON compliant object serialization.
 
-JSONArray.java: The JSONObject can parse text from a String or a JSONTokener
+JSONArray.java: The JSONArray can parse text from a String or a JSONTokener
 to produce a vector-like object. The object provides methods for manipulating
 its contents, and for producing a JSON compliant array serialization.
 
@@ -32,6 +32,10 @@ tokens. It can be constructed from a String, Reader, or InputStream.
 JSONException.java: The JSONException is the standard exception type thrown
 by this package.
 
+JSONPointer.java: Implementation of 
+[JSON Pointer (RFC 6901)](https://tools.ietf.org/html/rfc6901). Supports
+JSON Pointers both in the form of string representation and URI fragment
+representation.
 
 JSONString.java: The JSONString interface requires a toJSONString method,
 allowing an object to provide its own serialization.
@@ -61,14 +65,50 @@ JSONML.java: JSONML provides support for converting between JSONML and XML.
 
 XMLTokener.java: XMLTokener extends JSONTokener for parsing XML text.
 
-Unit tests are maintained in a separate project. Contributing developers can test JSON-java pull requests with the code in this project: https://github.com/stleary/JSON-Java-unit-test
+Unit tests are maintained in a separate project. Contributing developers can test 
+JSON-java pull requests with the code in this project: 
+https://github.com/stleary/JSON-Java-unit-test
+
+Numeric types in this package comply with ECMA-404: The JSON Data Interchange Format 
+(http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) and 
+RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format 
+(https://tools.ietf.org/html/rfc7159#section-6). 
+This package fully supports Integer, Long, and Double Java types. Partial support 
+for BigInteger and BigDecimal values in JSONObject and JSONArray objects is provided 
+in the form of get(), opt(), and put() API methods.
+
+Although 1.6 compatibility is currently supported, it is not a project goal and may be
+removed in some future release.
+
+In compliance with RFC7159 page 10 section 9, the parser is more lax with what is valid
+JSON than the Generator. For Example, the tab character (U+0009) is allowed when reading
+JSON Text strings, but when output by the Generator, tab is properly converted to \t in
+the string. Other instances may occur where reading invalid JSON text does not cause an
+error to be generated. Malformed JSON Texts such as missing end " (quote) on strings or
+invalid number formats (1.2e6.3) will cause errors as such documents can not be read
+ reliably.
 
 Release history:
+20171018    Checkpoint for recent commits.
+
+20170516    Roll up recent commits.
+
+20160810    Revert code that was breaking opt*() methods.
+
+20160807    This release contains a bug in the JSONObject.opt*() and JSONArray.opt*() methods, 
+it is not recommended for use.
+Java 1.6 compatability fixed, JSONArray.toList() and JSONObject.toMap(),
+RFC4180 compatibility, JSONPointer, some exception fixes, optional XML type conversion. 
+Contains the latest code as of 7 Aug, 2016
+
+20160212    Java 1.6 compatibility, OSGi bundle. Contains the latest code as of 12 Feb, 2016.
 
 20151123    JSONObject and JSONArray initialization with generics. Contains the
 latest code as of 23 Nov, 2015.
 
-20150729    Checkpoint for Maven central repository release. Contains the latest code as of 29 July, 2015. 
+20150729    Checkpoint for Maven central repository release. Contains the latest code 
+as of 29 July, 2015. 
 
-JSON-java releases can be found by searching the Maven repository for groupId "org.json" and artifactId "json". For example: 
+JSON-java releases can be found by searching the Maven repository for groupId "org.json" 
+and artifactId "json". For example: 
 https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.json%22%20AND%20a%3A%22json%22

XML.java

@@ -25,15 +25,17 @@ SOFTWARE.
 */
 
 import java.util.Iterator;
+import java.util.Map.Entry;
 
 /**
- * This provides static methods to convert an XML text into a JSONObject,
+ * This provides static methods to convert an XML text into a JSONObject, and to
- * and to covert a JSONObject into an XML text.
+ * covert a JSONObject into an XML text.
+ * 
  * @author JSON.org
- * @version 2015-10-18
+ * @version 2016-08-10
  */
+@SuppressWarnings("boxing")
 public class XML {
-
     /** The Character '&'. */
     public static final Character AMP = '&';
 
@@ -61,22 +63,65 @@ public class XML {
     /** The Character '/'. */
     public static final Character SLASH = '/';
     
+    /**
+     * Creates an iterator for navigating Code Points in a string instead of
+     * characters. Once Java7 support is dropped, this can be replaced with
+     * <code>
+     * string.codePoints()
+     * </code>
+     * which is available in Java8 and above.
+     * 
+     * @see <a href=
+     *      "http://stackoverflow.com/a/21791059/6030888">http://stackoverflow.com/a/21791059/6030888</a>
+     */
+    private static Iterable<Integer> codePointIterator(final String string) {
+        return new Iterable<Integer>() {
+            @Override
+            public Iterator<Integer> iterator() {
+                return new Iterator<Integer>() {
+                    private int nextIndex = 0;
+                    private int length = string.length();
+
+                    @Override
+                    public boolean hasNext() {
+                        return this.nextIndex < this.length;
+                    }
+
+                    @Override
+                    public Integer next() {
+                        int result = string.codePointAt(this.nextIndex);
+                        this.nextIndex += Character.charCount(result);
+                        return result;
+                    }
+
+                    @Override
+                    public void remove() {
+                        throw new UnsupportedOperationException();
+                    }
+                };
+            }
+        };
+    }
+
     /**
      * Replace special characters with XML escapes:
+     * 
      * <pre>
      * &amp; <small>(ampersand)</small> is replaced by &amp;amp;
      * &lt; <small>(less than)</small> is replaced by &amp;lt;
      * &gt; <small>(greater than)</small> is replaced by &amp;gt;
      * &quot; <small>(double quote)</small> is replaced by &amp;quot;
+     * &apos; <small>(single quote / apostrophe)</small> is replaced by &amp;apos;
      * </pre>
-     * @param string The string to be escaped.
+     * 
+     * @param string
+     *            The string to be escaped.
      * @return The escaped string.
      */
     public static String escape(String string) {
         StringBuilder sb = new StringBuilder(string.length());
-        for (int i = 0, length = string.length(); i < length; i++) {
+        for (final int cp : codePointIterator(string)) {
-            char c = string.charAt(i);
+            switch (cp) {
-            switch (c) {
             case '&':
                 sb.append("&amp;");
                 break;
@@ -93,6 +138,69 @@ public class XML {
                 sb.append("&apos;");
                 break;
             default:
+                if (mustEscape(cp)) {
+                    sb.append("&#x");
+                    sb.append(Integer.toHexString(cp));
+                    sb.append(';');
+                } else {
+                    sb.appendCodePoint(cp);
+                }
+            }
+        }
+        return sb.toString();
+    }
+    
+    /**
+     * @param cp code point to test
+     * @return true if the code point is not valid for an XML
+     */
+    private static boolean mustEscape(int cp) {
+        /* Valid range from https://www.w3.org/TR/REC-xml/#charsets
+         * 
+         * #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF] 
+         * 
+         * any Unicode character, excluding the surrogate blocks, FFFE, and FFFF. 
+         */
+        // isISOControl is true when (cp >= 0 && cp <= 0x1F) || (cp >= 0x7F && cp <= 0x9F)
+        // all ISO control characters are out of range except tabs and new lines
+        return (Character.isISOControl(cp)
+                && cp != 0x9
+                && cp != 0xA
+                && cp != 0xD
+            ) || !(
+                // valid the range of acceptable characters that aren't control
+                (cp >= 0x20 && cp <= 0xD7FF)
+                || (cp >= 0xE000 && cp <= 0xFFFD)
+                || (cp >= 0x10000 && cp <= 0x10FFFF)
+            )
+        ;
+    }
+
+    /**
+     * Removes XML escapes from the string.
+     * 
+     * @param string
+     *            string to remove escapes from
+     * @return string with converted entities
+     */
+    public static String unescape(String string) {
+        StringBuilder sb = new StringBuilder(string.length());
+        for (int i = 0, length = string.length(); i < length; i++) {
+            char c = string.charAt(i);
+            if (c == '&') {
+                final int semic = string.indexOf(';', i);
+                if (semic > i) {
+                    final String entity = string.substring(i + 1, semic);
+                    sb.append(XMLTokener.unescapeEntity(entity));
+                    // skip past the entity we just parsed.
+                    i += entity.length() + 1;
+                } else {
+                    // this shouldn't happen in most cases since the parser
+                    // errors on unclosed entries.
+                    sb.append(c);
+                }
+            } else {
+                // not part of an entity
                 sb.append(c);
             }
         }
@@ -100,10 +208,12 @@ public class XML {
     }
 
     /**
-     * Throw an exception if the string contains whitespace.
+     * Throw an exception if the string contains whitespace. Whitespace is not
-     * Whitespace is not allowed in tagNames and attributes.
+     * allowed in tagNames and attributes.
-     * @param string A string.
+     * 
-     * @throws JSONException
+     * @param string
+     *            A string.
+     * @throws JSONException Thrown if the string contains whitespace or is empty.
      */
     public static void noSpace(String string) throws JSONException {
         int i, length = string.length();
@@ -112,22 +222,26 @@ public class XML {
         }
         for (i = 0; i < length; i += 1) {
             if (Character.isWhitespace(string.charAt(i))) {
-                throw new JSONException("'" + string +
+                throw new JSONException("'" + string
-                        "' contains a space character.");
+                        + "' contains a space character.");
             }
         }
     }
 
     /**
      * Scan the content following the named tag, attaching it to the context.
-     * @param x       The XMLTokener containing the source string.
+     * 
-     * @param context The JSONObject that will include the new material.
+     * @param x
-     * @param name    The tag name.
+     *            The XMLTokener containing the source string.
+     * @param context
+     *            The JSONObject that will include the new material.
+     * @param name
+     *            The tag name.
      * @return true if the close tag is processed.
      * @throws JSONException
      */
-    private static boolean parse(XMLTokener x, JSONObject context,
+    private static boolean parse(XMLTokener x, JSONObject context, String name, boolean keepStrings)
-                                 String name) throws JSONException {
+            throws JSONException {
         char c;
         int i;
         JSONObject jsonobject = null;
@@ -135,19 +249,19 @@ public class XML {
         String tagName;
         Object token;
 
-// Test for and skip past these forms:
+        // Test for and skip past these forms:
-//      <!-- ... -->
+        // <!-- ... -->
-//      <!   ...   >
+        // <! ... >
-//      <![  ... ]]>
+        // <![ ... ]]>
-//      <?   ...  ?>
+        // <? ... ?>
-// Report errors for these forms:
+        // Report errors for these forms:
-//      <>
+        // <>
-//      <=
+        // <=
-//      <<
+        // <<
 
         token = x.nextToken();
 
-// <!
+        // <!
 
         if (token == BANG) {
             c = x.next();
@@ -184,13 +298,12 @@ public class XML {
             return false;
         } else if (token == QUEST) {
 
-// <?
+            // <?
-
             x.skipPast("?>");
             return false;
         } else if (token == SLASH) {
 
-// Close tag </
+            // Close tag </
 
             token = x.nextToken();
             if (name == null) {
@@ -207,21 +320,19 @@ public class XML {
         } else if (token instanceof Character) {
             throw x.syntaxError("Misshaped tag");
 
-// Open tag <
+            // Open tag <
 
         } else {
-            tagName = (String)token;
+            tagName = (String) token;
             token = null;
             jsonobject = new JSONObject();
             for (;;) {
                 if (token == null) {
                     token = x.nextToken();
                 }
-
+                // attribute = value
-// attribute = value
-
                 if (token instanceof String) {
-                    string = (String)token;
+                    string = (String) token;
                     token = x.nextToken();
                     if (token == EQ) {
                         token = x.nextToken();
@@ -229,15 +340,15 @@ public class XML {
                             throw x.syntaxError("Missing value");
                         }
                         jsonobject.accumulate(string,
-                                XML.stringToValue((String)token));
+                                keepStrings ? ((String)token) : stringToValue((String) token));
                         token = null;
                     } else {
                         jsonobject.accumulate(string, "");
                     }
 
-// Empty tag <.../>
 
                 } else if (token == SLASH) {
+                    // Empty tag <.../>
                     if (x.nextToken() != GT) {
                         throw x.syntaxError("Misshaped tag");
                     }
@@ -248,9 +359,8 @@ public class XML {
                     }
                     return false;
 
-// Content, between <...> and </...>
-
                 } else if (token == GT) {
+                    // Content, between <...> and </...>
                     for (;;) {
                         token = x.nextContent();
                         if (token == null) {
@@ -259,20 +369,19 @@ public class XML {
                             }
                             return false;
                         } else if (token instanceof String) {
-                            string = (String)token;
+                            string = (String) token;
                             if (string.length() > 0) {
                                 jsonobject.accumulate("content",
-                                        XML.stringToValue(string));
+                                        keepStrings ? string : stringToValue(string));
                             }
 
-// Nested element
-
                         } else if (token == LT) {
-                            if (parse(x, jsonobject, tagName)) {
+                            // Nested element
+                            if (parse(x, jsonobject, tagName,keepStrings)) {
                                 if (jsonobject.length() == 0) {
                                     context.accumulate(tagName, "");
-                                } else if (jsonobject.length() == 1 &&
+                                } else if (jsonobject.length() == 1
-                                       jsonobject.opt("content") != null) {
+                                        && jsonobject.opt("content") != null) {
                                     context.accumulate(tagName,
                                             jsonobject.opt("content"));
                                 } else {
@@ -289,159 +398,147 @@ public class XML {
         }
     }
     
-
     /**
-     * Try to convert a string into a number, boolean, or null. If the string
+     * This method is the same as {@link JSONObject#stringToValue(String)}
-     * can't be converted, return the string. This is much less ambitious than
+     * except that this also tries to unescape String values.
-     * JSONObject.stringToValue, especially because it does not attempt to
+     * 
-     * convert plus forms, octal forms, hex forms, or E forms lacking decimal
+     * @param string String to convert
-     * points.
+     * @return JSON value of this string or the string
-     * @param string A String.
-     * @return A simple JSON value.
      */
     public static Object stringToValue(String string) {
-        if ("true".equalsIgnoreCase(string)) {
+        return JSONObject.stringToValue(string);
-            return Boolean.TRUE;
-        }
-        if ("false".equalsIgnoreCase(string)) {
-            return Boolean.FALSE;
-        }
-        if ("null".equalsIgnoreCase(string)) {
-            return JSONObject.NULL;
     }
 
-// If it might be a number, try converting it, first as a Long, and then as a
+    /**
-// Double. If that doesn't work, return the string.
+     * Convert a well-formed (but not necessarily valid) XML string into a
-
+     * JSONObject. Some information may be lost in this transformation because
-        try {
+     * JSON is a data format and XML is a document format. XML uses elements,
-            char initial = string.charAt(0);
+     * attributes, and content text, while JSON uses unordered collections of
-            if (initial == '-' || (initial >= '0' && initial <= '9')) {
+     * name/value pairs and arrays of values. JSON does not does not like to
-                Long value = new Long(string);
+     * distinguish between elements and attributes. Sequences of similar
-                if (value.toString().equals(string)) {
+     * elements are represented as JSONArrays. Content text may be placed in a
-                    return value;
+     * "content" member. Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code>
-                }
+     * are ignored.
-            }
+     * 
-        }  catch (Exception ignore) {
+     * @param string
-            try {
+     *            The source string.
-                Double value = new Double(string);
+     * @return A JSONObject containing the structured data from the XML string.
-                if (value.toString().equals(string)) {
+     * @throws JSONException Thrown if there is an errors while parsing the string
-                    return value;
+     */
-                }
+    public static JSONObject toJSONObject(String string) throws JSONException {
-            }  catch (Exception ignoreAlso) {
+        return toJSONObject(string, false);
-            }
-        }
-        return string;
     }
 
 
     /**
      * Convert a well-formed (but not necessarily valid) XML string into a
-     * JSONObject. Some information may be lost in this transformation
+     * JSONObject. Some information may be lost in this transformation because
-     * because JSON is a data format and XML is a document format. XML uses
+     * JSON is a data format and XML is a document format. XML uses elements,
-     * elements, attributes, and content text, while JSON uses unordered
+     * attributes, and content text, while JSON uses unordered collections of
-     * collections of name/value pairs and arrays of values. JSON does not
+     * name/value pairs and arrays of values. JSON does not does not like to
-     * does not like to distinguish between elements and attributes.
+     * distinguish between elements and attributes. Sequences of similar
-     * Sequences of similar elements are represented as JSONArrays. Content
+     * elements are represented as JSONArrays. Content text may be placed in a
-     * text may be placed in a "content" member. Comments, prologs, DTDs, and
+     * "content" member. Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code>
-     * <code>&lt;[ [ ]]></code> are ignored.
+     * are ignored.
-     * @param string The source string.
+     * 
+     * All values are converted as strings, for 1, 01, 29.0 will not be coerced to
+     * numbers but will instead be the exact value as seen in the XML document.
+     * 
+     * @param string
+     *            The source string.
+     * @param keepStrings If true, then values will not be coerced into boolean
+     *  or numeric values and will instead be left as strings
      * @return A JSONObject containing the structured data from the XML string.
-     * @throws JSONException
+     * @throws JSONException Thrown if there is an errors while parsing the string
      */
-    public static JSONObject toJSONObject(String string) throws JSONException {
+    public static JSONObject toJSONObject(String string, boolean keepStrings) throws JSONException {
         JSONObject jo = new JSONObject();
         XMLTokener x = new XMLTokener(string);
         while (x.more() && x.skipPast("<")) {
-            parse(x, jo, null);
+            parse(x, jo, null, keepStrings);
         }
         return jo;
     }
-
-
     /**
      * Convert a JSONObject into a well-formed, element-normal XML string.
-     * @param object A JSONObject.
+     * 
+     * @param object
+     *            A JSONObject.
      * @return A string.
-     * @throws  JSONException
+     * @throws JSONException Thrown if there is an error parsing the string
      */
     public static String toString(Object object) throws JSONException {
         return toString(object, null);
     }
 
-
     /**
      * Convert a JSONObject into a well-formed, element-normal XML string.
-     * @param object A JSONObject.
+     * 
-     * @param tagName The optional name of the enclosing tag.
+     * @param object
+     *            A JSONObject.
+     * @param tagName
+     *            The optional name of the enclosing tag.
      * @return A string.
-     * @throws JSONException
+     * @throws JSONException Thrown if there is an error parsing the string
      */
-    public static String toString(Object object, String tagName)
+    public static String toString(final Object object, final String tagName)
             throws JSONException {
         StringBuilder sb = new StringBuilder();
-        int                 i;
         JSONArray ja;
         JSONObject jo;
-        String              key;
-        Iterator<String>    keys;
-        int                 length;
         String string;
-        Object              value;
+
         if (object instanceof JSONObject) {
 
-// Emit <tagName>
+            // Emit <tagName>
-
             if (tagName != null) {
                 sb.append('<');
                 sb.append(tagName);
                 sb.append('>');
             }
 
-// Loop thru the keys.
+            // Loop thru the keys.
-
+            jo = (JSONObject) object;
-            jo = (JSONObject)object;
+            for (final Entry<String, ?> entry : jo.entrySet()) {
-            keys = jo.keys();
+            	final String key = entry.getKey();
-            while (keys.hasNext()) {
+                Object value = entry.getValue();
-                key = keys.next();
-                value = jo.opt(key);
                 if (value == null) {
                     value = "";
+                } else if (value.getClass().isArray()) {
+                    value = new JSONArray(value);
                 }
-                string = value instanceof String ? (String)value : null;
-
-// Emit content in body
 
+                // Emit content in body
                 if ("content".equals(key)) {
                     if (value instanceof JSONArray) {
-                        ja = (JSONArray)value;
+                        ja = (JSONArray) value;
-                        length = ja.length();
+                        int i = 0;
-                        for (i = 0; i < length; i += 1) {
+                        for (Object val : ja) {
                             if (i > 0) {
                                 sb.append('\n');
                             }
-                            sb.append(escape(ja.get(i).toString()));
+                            sb.append(escape(val.toString()));
+                            i++;
                         }
                     } else {
                         sb.append(escape(value.toString()));
                     }
 
-// Emit an array of similar keys
+                    // Emit an array of similar keys
 
                 } else if (value instanceof JSONArray) {
-                    ja = (JSONArray)value;
+                    ja = (JSONArray) value;
-                    length = ja.length();
+                    for (Object val : ja) {
-                    for (i = 0; i < length; i += 1) {
+                        if (val instanceof JSONArray) {
-                        value = ja.get(i);
-                        if (value instanceof JSONArray) {
                             sb.append('<');
                             sb.append(key);
                             sb.append('>');
-                            sb.append(toString(value));
+                            sb.append(toString(val));
                             sb.append("</");
                             sb.append(key);
                             sb.append('>');
                         } else {
-                            sb.append(toString(value, key));
+                            sb.append(toString(val, key));
                         }
                     }
                 } else if ("".equals(value)) {
@@ -449,7 +546,7 @@ public class XML {
                     sb.append(key);
                     sb.append("/>");
 
-// Emit a new tag <k>
+                    // Emit a new tag <k>
 
                 } else {
                     sb.append(toString(value, key));
@@ -457,36 +554,34 @@ public class XML {
             }
             if (tagName != null) {
 
-// Emit the </tagname> close tag
+                // Emit the </tagname> close tag
-
                 sb.append("</");
                 sb.append(tagName);
                 sb.append('>');
             }
             return sb.toString();
 
-// XML does not have good support for arrays. If an array appears in a place
-// where XML is lacking, synthesize an <array> element.
-
-        }
-        if(object!=null){
-            if (object.getClass().isArray()) {
-                object = new JSONArray(object);
         }
 
-            if (object instanceof JSONArray) {
+        if (object != null && (object instanceof JSONArray ||  object.getClass().isArray())) {
-                ja = (JSONArray)object;
+            if(object.getClass().isArray()) {
-                length = ja.length();
+                ja = new JSONArray(object);
-                for (i = 0; i < length; i += 1) {
+            } else {
-                    sb.append(toString(ja.opt(i), tagName == null ? "array" : tagName));
+                ja = (JSONArray) object;
+            }
+            for (Object val : ja) {
+                // XML does not have good support for arrays. If an array
+                // appears in a place where XML is lacking, synthesize an
+                // <array> element.
+                sb.append(toString(val, tagName == null ? "array" : tagName));
             }
             return sb.toString();
         }
-        }
+
         string = (object == null) ? "null" : escape(object.toString());
-        return (tagName == null) ? "\"" + string + "\"" :
+        return (tagName == null) ? "\"" + string + "\""
-            (string.length() == 0) ? "<" + tagName + "/>" :
+                : (string.length() == 0) ? "<" + tagName + "/>" : "<" + tagName
-            "<" + tagName + ">" + string + "</" + tagName + ">";
+                        + ">" + string + "</" + tagName + ">";
 
     }
 }

XMLTokener.java

@@ -28,7 +28,7 @@ SOFTWARE.
  * The XMLTokener extends the JSONTokener to provide additional methods
  * for the parsing of XML texts.
  * @author JSON.org
- * @version 2014-05-03
+ * @version 2015-12-09
  */
 public class XMLTokener extends JSONTokener {
 
@@ -64,11 +64,8 @@ public class XMLTokener extends JSONTokener {
         char         c;
         int          i;
         StringBuilder sb = new StringBuilder();
-        for (;;) {
+        while (more()) {
             c = next();
-            if (end()) {
-                throw syntaxError("Unclosed CDATA");
-            }
             sb.append(c);
             i = sb.length() - 3;
             if (i >= 0 && sb.charAt(i) == ']' &&
@@ -77,6 +74,7 @@ public class XMLTokener extends JSONTokener {
                 return sb.toString();
             }
         }
+        throw syntaxError("Unclosed CDATA");
     }
 
 
@@ -103,7 +101,10 @@ public class XMLTokener extends JSONTokener {
         }
         sb = new StringBuilder();
         for (;;) {
-            if (c == '<' || c == 0) {
+            if (c == 0) {
+                return sb.toString().trim();
+            }
+            if (c == '<') {
                 back();
                 return sb.toString().trim();
             }
@@ -137,8 +138,37 @@ public class XMLTokener extends JSONTokener {
             }
         }
         String string = sb.toString();
-        Object object = entity.get(string);
+        return unescapeEntity(string);
-        return object != null ? object : ampersand + string + ";";
+    }
+    
+    /**
+     * Unescapes an XML entity encoding;
+     * @param e entity (only the actual entity value, not the preceding & or ending ;
+     * @return
+     */
+    static String unescapeEntity(String e) {
+        // validate
+        if (e == null || e.isEmpty()) {
+            return "";
+        }
+        // if our entity is an encoded unicode point, parse it.
+        if (e.charAt(0) == '#') {
+            int cp;
+            if (e.charAt(1) == 'x') {
+                // hex encoded unicode
+                cp = Integer.parseInt(e.substring(2), 16);
+            } else {
+                // decimal encoded unicode
+                cp = Integer.parseInt(e.substring(1));
+            }
+            return new String(new int[] {cp},0,1);
+        } 
+        Character knownEntity = entity.get(e);
+        if(knownEntity==null) {
+            // we don't know the entity so keep it encoded
+            return '&' + e + ';';
+        }
+        return knownEntity.toString();
     }