Update README.md

New RFC8259, no changes to in-doc references.

.gitignore

@@ -0,0 +1,6 @@
+# ignore eclipse project files
+.project
+.classpath
+# ignore Intellij Idea project files
+.idea
+*.iml

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
@@ -70,9 +70,12 @@ public class CDL {
                 c = x.next();
                 if (c == q) {
                     //Handle escaped double-quote
-                    if(x.next() != '\"')
+                    char nextC = x.next();
-                    {
+                    if(nextC != '\"') {
-                        x.back();
+                        // if our quote was the end of the file, don't step
+                        if(nextC > 0) {
+                            x.back();
+                        }
                         break;
                     }
                 }

CookieList.java

@@ -22,9 +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.
-*/
+ */
-
-import java.util.Iterator;
 
 /**
  * Convert a web browser cookie list string to a JSONObject and back.
@@ -39,7 +37,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 +67,17 @@ public class CookieList {
      */
     public static String toString(JSONObject jo) throws JSONException {
         boolean             b = false;
-        Iterator<String>    keys = jo.keys();
+        final StringBuilder sb = new StringBuilder();
-        String              string;
+        // Don't use the new entrySet API to maintain Android support
-        StringBuilder sb = new StringBuilder();
+        for (final String key : jo.keySet()) {
-        while (keys.hasNext()) {
+            final Object value = jo.opt(key);
-            string = keys.next();
+            if (!JSONObject.NULL.equals(value)) {
-            if (!jo.isNull(string)) {
                 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,7 +24,6 @@ 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;
 
 /**
@@ -126,8 +125,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"));
@@ -147,14 +144,15 @@ public class HTTP {
             throw new JSONException("Not enough material for an HTTP header.");
         }
         sb.append(CRLF);
-        while (keys.hasNext()) {
+        // Don't use the new entrySet API to maintain Android support
-            string = keys.next();
+        for (final String key : jo.keySet()) {
-            if (!"HTTP-Version".equals(string)      && !"Status-Code".equals(string) &&
+            String value = jo.optString(key);
-                    !"Reason-Phrase".equals(string) && !"Method".equals(string) &&
+            if (!"HTTP-Version".equals(key)      && !"Status-Code".equals(key) &&
-                    !"Request-URI".equals(string)   && !jo.isNull(string)) {
+                    !"Reason-Phrase".equals(key) && !"Method".equals(key) &&
-                sb.append(string);
+                    !"Request-URI".equals(key)   && !JSONObject.NULL.equals(value)) {
+                sb.append(key);
                 sb.append(": ");
-                sb.append(jo.getString(string));
+                sb.append(jo.optString(key));
                 sb.append(CRLF);
             }
         }

JSONArray.java

@@ -36,6 +36,7 @@ import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 
+
 /**
  * A JSONArray is an ordered sequence of values. Its external text form is a
  * string wrapped in square brackets with commas separating the values. The
@@ -107,7 +108,13 @@ public class JSONArray implements Iterable<Object> {
         if (x.nextClean() != '[') {
             throw x.syntaxError("A JSONArray text must start with '['");
         }
-        if (x.nextClean() != ']') {
+        
+        char nextChar = x.nextClean();
+        if (nextChar == 0) {
+            // array is unclosed. No ']' found, instead EOF
+            throw x.syntaxError("Expected a ',' or ']'");
+        }
+        if (nextChar != ']') {
             x.back();
             for (;;) {
                 if (x.nextClean() == ',') {
@@ -118,8 +125,16 @@ public class JSONArray implements Iterable<Object> {
                     this.myArrayList.add(x.nextValue());
                 }
                 switch (x.nextClean()) {
+                case 0:
+                    // array is unclosed. No ']' found, instead EOF
+                    throw x.syntaxError("Expected a ',' or ']'");
                 case ',':
-                    if (x.nextClean() == ']') {
+                    nextChar = x.nextClean();
+                    if (nextChar == 0) {
+                        // array is unclosed. No ']' found, instead EOF
+                        throw x.syntaxError("Expected a ',' or ']'");
+                    }
+                    if (nextChar == ']') {
                         return;
                     }
                     x.back();
@@ -154,8 +169,10 @@ public class JSONArray implements Iterable<Object> {
      *            A Collection.
      */
     public JSONArray(Collection<?> collection) {
-        this.myArrayList = new ArrayList<Object>();
+        if (collection == null) {
-        if (collection != null) {
+            this.myArrayList = new ArrayList<Object>();
+        } else {
+            this.myArrayList = new ArrayList<Object>(collection.size());
         	for (Object o: collection){
         		this.myArrayList.add(JSONObject.wrap(o));
         	}
@@ -163,15 +180,22 @@ public class JSONArray implements Iterable<Object> {
     }
 
     /**
-     * Construct a JSONArray from an array
+     * Construct a JSONArray from an array.
+     *
+     * @param array
+     *            Array. If the parameter passed is null, or not an array, an
+     *            exception will be thrown.
      *
      * @throws JSONException
-     *             If not an array.
+     *            If not an array or if an array value is non-finite number.
+     * @throws NullPointerException
+     *            Thrown if the array parameter is null.
      */
     public JSONArray(Object array) throws JSONException {
         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)));
             }
@@ -183,7 +207,7 @@ public class JSONArray implements Iterable<Object> {
 
     @Override
     public Iterator<Object> iterator() {
-        return myArrayList.iterator();
+        return this.myArrayList.iterator();
     }
 
     /**
@@ -239,42 +263,76 @@ public class JSONArray implements Iterable<Object> {
      *             to a number.
      */
     public double getDouble(int index) throws JSONException {
+        return this.getNumber(index).doubleValue();
+    }
+
+    /**
+     * 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 {
+        return this.getNumber(index).floatValue();
+    }
+
+    /**
+     * 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 {
-            return object instanceof Number ? ((Number) object).doubleValue()
+            if (object instanceof Number) {
-                    : Double.parseDouble((String) object);
+                return (Number)object;
+            }
+            return JSONObject.stringToNumber(object.toString());
         } catch (Exception e) {
-            throw new JSONException("JSONArray[" + index + "] is not a number.");
+            throw new JSONException("JSONArray[" + index + "] is not a number.", e);
         }
     }
 
     /**
-    * Get the enum value associated with an index.
+     * Get the enum value associated with an index.
-    * 
+     * 
-    * @param clazz
+     * @param <E>
-    *            The type of enum to retrieve.
+     *            Enum Type
-    * @param index
+     * @param clazz
-    *            The index must be between 0 and length() - 1.
+     *            The type of enum to retrieve.
-    * @return The enum value at the index location
+     * @param index
-    * @throws JSONException
+     *            The index must be between 0 and length() - 1.
-    *            if the key is not found or if the value cannot be converted
+     * @return The enum value at the index location
-    *            to an enum.
+     * @throws JSONException
-    */
+     *            if the key is not found or if the value cannot be converted
+     *            to an enum.
+     */
     public <E extends Enum<E>> E getEnum(Class<E> clazz, int index) throws JSONException {
         E val = optEnum(clazz, index);
         if(val==null) {
             // 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;
     }
 
     /**
-     * Get the BigDecimal value associated with an index.
+     * Get the BigDecimal value associated with an index. If the value is float
+     * or double, the the {@link BigDecimal#BigDecimal(double)} constructor
+     * will be used. See notes on the constructor for conversion issues that
+     * may arise.
      *
      * @param index
      *            The index must be between 0 and length() - 1.
@@ -285,12 +343,12 @@ public class JSONArray implements Iterable<Object> {
      */
     public BigDecimal getBigDecimal (int index) throws JSONException {
         Object object = this.get(index);
-        try {
+        BigDecimal val = JSONObject.objectToBigDecimal(object, null);
-            return new BigDecimal(object.toString());
+        if(val == null) {
-        } catch (Exception e) {
             throw new JSONException("JSONArray[" + index +
-                    "] could not convert to BigDecimal.");
+                    "] could not convert to BigDecimal ("+ object + ").");
         }
+        return val;
     }
 
     /**
@@ -305,12 +363,12 @@ public class JSONArray implements Iterable<Object> {
      */
     public BigInteger getBigInteger (int index) throws JSONException {
         Object object = this.get(index);
-        try {
+        BigInteger val = JSONObject.objectToBigInteger(object, null);
-            return new BigInteger(object.toString());
+        if(val == null) {
-        } catch (Exception e) {
             throw new JSONException("JSONArray[" + index +
-                    "] could not convert to BigInteger.");
+                    "] could not convert to BigDecimal ("+ object + ").");
         }
+        return val;
     }
 
     /**
@@ -323,13 +381,7 @@ public class JSONArray implements Iterable<Object> {
      *             If the key is not found or if the value is not a number.
      */
     public int getInt(int index) throws JSONException {
-        Object object = this.get(index);
+        return this.getNumber(index).intValue();
-        try {
-            return object instanceof Number ? ((Number) object).intValue()
-                    : Integer.parseInt((String) object);
-        } catch (Exception e) {
-            throw new JSONException("JSONArray[" + index + "] is not a number.");
-        }
     }
 
     /**
@@ -379,13 +431,7 @@ public class JSONArray implements Iterable<Object> {
      *             to a number.
      */
     public long getLong(int index) throws JSONException {
-        Object object = this.get(index);
+        return this.getNumber(index).longValue();
-        try {
-            return object instanceof Number ? ((Number) object).longValue()
-                    : Long.parseLong((String) object);
-        } catch (Exception e) {
-            throw new JSONException("JSONArray[" + index + "] is not a number.");
-        }
     }
 
     /**
@@ -406,11 +452,11 @@ public class JSONArray implements Iterable<Object> {
     }
 
     /**
-     * Determine if the value is null.
+     * Determine if the value is <code>null</code>.
      *
      * @param index
      *            The index must be between 0 and length() - 1.
-     * @return true if the value at the index is null, or if there is no value.
+     * @return true if the value at the index is <code>null</code>, or if there is no value.
      */
     public boolean isNull(int index) {
         return JSONObject.NULL.equals(this.opt(index));
@@ -429,13 +475,16 @@ public class JSONArray implements Iterable<Object> {
      */
     public String join(String separator) throws JSONException {
         int len = this.length();
-        StringBuilder sb = new StringBuilder();
+        if (len == 0) {
+            return "";
+        }
         
-        for (int i = 0; i < len; i += 1) {
+        StringBuilder sb = new StringBuilder(
-            if (i > 0) {
+                   JSONObject.valueToString(this.myArrayList.get(0)));
-                sb.append(separator);
+
-            }
+        for (int i = 1; i < len; i++) {
-            sb.append(JSONObject.valueToString(this.myArrayList.get(i)));
+            sb.append(separator)
+              .append(JSONObject.valueToString(this.myArrayList.get(i)));
         }
         return sb.toString();
     }
@@ -453,7 +502,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) {
@@ -518,11 +567,51 @@ public class JSONArray implements Iterable<Object> {
      * @return The value.
      */
     public double optDouble(int index, double defaultValue) {
-        try {
+        final Number val = this.optNumber(index, null);
-            return this.getDouble(index);
+        if (val == null) {
-        } catch (Exception e) {
             return defaultValue;
         }
+        final double doubleValue = val.doubleValue();
+        // if (Double.isNaN(doubleValue) || Double.isInfinite(doubleValue)) {
+        // return defaultValue;
+        // }
+        return doubleValue;
+    }
+
+    /**
+     * 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) {
+        final Number val = this.optNumber(index, null);
+        if (val == null) {
+            return defaultValue;
+        }
+        final float floatValue = val.floatValue();
+        // if (Float.isNaN(floatValue) || Float.isInfinite(floatValue)) {
+        // return floatValue;
+        // }
+        return floatValue;
     }
 
     /**
@@ -550,16 +639,18 @@ public class JSONArray implements Iterable<Object> {
      * @return The value.
      */
     public int optInt(int index, int defaultValue) {
-        try {
+        final Number val = this.optNumber(index, null);
-            return this.getInt(index);
+        if (val == null) {
-        } catch (Exception e) {
             return defaultValue;
         }
+        return val.intValue();
     }
 
     /**
      * Get the enum value associated with a key.
      * 
+     * @param <E>
+     *            Enum Type
      * @param clazz
      *            The type of enum to retrieve.
      * @param index
@@ -573,6 +664,8 @@ public class JSONArray implements Iterable<Object> {
     /**
      * Get the enum value associated with a key.
      * 
+     * @param <E>
+     *            Enum Type
      * @param clazz
      *            The type of enum to retrieve.
      * @param index
@@ -602,7 +695,6 @@ public class JSONArray implements Iterable<Object> {
         }
     }
 
-
     /**
      * Get the optional BigInteger value associated with an index. The 
      * defaultValue is returned if there is no value for the index, or if the 
@@ -615,17 +707,17 @@ public class JSONArray implements Iterable<Object> {
      * @return The value.
      */
     public BigInteger optBigInteger(int index, BigInteger defaultValue) {
-        try {
+        Object val = this.opt(index);
-            return this.getBigInteger(index);
+        return JSONObject.objectToBigInteger(val, defaultValue);
-        } catch (Exception e) {
-            return defaultValue;
-        }
     }
 
     /**
      * Get the optional BigDecimal 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.
+     * value is not a number and cannot be converted to a number. If the value
+     * is float or double, the the {@link BigDecimal#BigDecimal(double)}
+     * constructor will be used. See notes on the constructor for conversion
+     * issues that may arise.
      *
      * @param index
      *            The index must be between 0 and length() - 1.
@@ -634,11 +726,8 @@ public class JSONArray implements Iterable<Object> {
      * @return The value.
      */
     public BigDecimal optBigDecimal(int index, BigDecimal defaultValue) {
-        try {
+        Object val = this.opt(index);
-            return this.getBigDecimal(index);
+        return JSONObject.objectToBigDecimal(val, defaultValue);
-        } catch (Exception e) {
-            return defaultValue;
-        }
     }
 
     /**
@@ -693,17 +782,62 @@ public class JSONArray implements Iterable<Object> {
      * @return The value.
      */
     public long optLong(int index, long defaultValue) {
-        try {
+        final Number val = this.optNumber(index, null);
-            return this.getLong(index);
+        if (val == null) {
-        } catch (Exception e) {
             return defaultValue;
         }
+        return val.longValue();
+    }
+
+    /**
+     * 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.
@@ -737,8 +871,7 @@ public class JSONArray implements Iterable<Object> {
      * @return this.
      */
     public JSONArray put(boolean value) {
-        this.put(value ? Boolean.TRUE : Boolean.FALSE);
+        return this.put(value ? Boolean.TRUE : Boolean.FALSE);
-        return this;
     }
 
     /**
@@ -748,10 +881,11 @@ public class JSONArray implements Iterable<Object> {
      * @param value
      *            A Collection value.
      * @return this.
+     * @throws JSONException
+     *            If the value is non-finite number.
      */
     public JSONArray put(Collection<?> value) {
-        this.put(new JSONArray(value));
+        return this.put(new JSONArray(value));
-        return this;
     }
 
     /**
@@ -759,15 +893,25 @@ public class JSONArray implements Iterable<Object> {
      *
      * @param value
      *            A double value.
+     * @return this.
      * @throws JSONException
      *             if the value is not finite.
-     * @return this.
      */
     public JSONArray put(double value) throws JSONException {
-        Double d = new Double(value);
+        return this.put(Double.valueOf(value));
-        JSONObject.testValidity(d);
+    }
-        this.put(d);
+    
-        return this;
+    /**
+     * Append a float value. This increases the array's length by one.
+     *
+     * @param value
+     *            A float value.
+     * @return this.
+     * @throws JSONException
+     *             if the value is not finite.
+     */
+    public JSONArray put(float value) throws JSONException {
+        return this.put(Float.valueOf(value));
     }
 
     /**
@@ -778,8 +922,7 @@ public class JSONArray implements Iterable<Object> {
      * @return this.
      */
     public JSONArray put(int value) {
-        this.put(new Integer(value));
+        return this.put(Integer.valueOf(value));
-        return this;
     }
 
     /**
@@ -790,8 +933,7 @@ public class JSONArray implements Iterable<Object> {
      * @return this.
      */
     public JSONArray put(long value) {
-        this.put(new Long(value));
+        return this.put(Long.valueOf(value));
-        return this;
     }
 
     /**
@@ -801,10 +943,13 @@ public class JSONArray implements Iterable<Object> {
      * @param value
      *            A Map value.
      * @return this.
+     * @throws JSONException
+     *            If a value in the map is non-finite number.
+     * @throws NullPointerException
+     *            If a key in the map is <code>null</code>
      */
     public JSONArray put(Map<?, ?> value) {
-        this.put(new JSONObject(value));
+        return this.put(new JSONObject(value));
-        return this;
     }
 
     /**
@@ -815,8 +960,11 @@ public class JSONArray implements Iterable<Object> {
      *            Integer, JSONArray, JSONObject, Long, or String, or the
      *            JSONObject.NULL object.
      * @return this.
+     * @throws JSONException
+     *            If the value is non-finite number.
      */
     public JSONArray put(Object value) {
+        JSONObject.testValidity(value);
         this.myArrayList.add(value);
         return this;
     }
@@ -835,8 +983,7 @@ public class JSONArray implements Iterable<Object> {
      *             If the index is negative.
      */
     public JSONArray put(int index, boolean value) throws JSONException {
-        this.put(index, value ? Boolean.TRUE : Boolean.FALSE);
+        return this.put(index, value ? Boolean.TRUE : Boolean.FALSE);
-        return this;
     }
 
     /**
@@ -849,11 +996,10 @@ public class JSONArray implements Iterable<Object> {
      *            A Collection value.
      * @return this.
      * @throws JSONException
-     *             If the index is negative or if the value is not finite.
+     *             If the index is negative or if the value is non-finite.
      */
     public JSONArray put(int index, Collection<?> value) throws JSONException {
-        this.put(index, new JSONArray(value));
+        return this.put(index, new JSONArray(value));
-        return this;
     }
 
     /**
@@ -867,11 +1013,27 @@ public class JSONArray implements Iterable<Object> {
      *            A double value.
      * @return this.
      * @throws JSONException
-     *             If the index is negative or if the value is not finite.
+     *             If the index is negative or if the value is non-finite.
      */
     public JSONArray put(int index, double value) throws JSONException {
-        this.put(index, new Double(value));
+        return this.put(index, Double.valueOf(value));
-        return this;
+    }
+
+    /**
+     * Put or replace a float value. If the index is greater than the length of
+     * the JSONArray, then null elements will be added as necessary to pad it
+     * out.
+     *
+     * @param index
+     *            The subscript.
+     * @param value
+     *            A float value.
+     * @return this.
+     * @throws JSONException
+     *             If the index is negative or if the value is non-finite.
+     */
+    public JSONArray put(int index, float value) throws JSONException {
+        return this.put(index, Float.valueOf(value));
     }
 
     /**
@@ -888,8 +1050,7 @@ public class JSONArray implements Iterable<Object> {
      *             If the index is negative.
      */
     public JSONArray put(int index, int value) throws JSONException {
-        this.put(index, new Integer(value));
+        return this.put(index, Integer.valueOf(value));
-        return this;
     }
 
     /**
@@ -906,8 +1067,7 @@ public class JSONArray implements Iterable<Object> {
      *             If the index is negative.
      */
     public JSONArray put(int index, long value) throws JSONException {
-        this.put(index, new Long(value));
+        return this.put(index, Long.valueOf(value));
-        return this;
     }
 
     /**
@@ -922,6 +1082,8 @@ public class JSONArray implements Iterable<Object> {
      * @throws JSONException
      *             If the index is negative or if the the value is an invalid
      *             number.
+     * @throws NullPointerException
+     *             If a key in the map is <code>null</code>
      */
     public JSONArray put(int index, Map<?, ?> value) throws JSONException {
         this.put(index, new JSONObject(value));
@@ -945,19 +1107,26 @@ public class JSONArray implements Iterable<Object> {
      *             number.
      */
     public JSONArray put(int index, Object value) throws JSONException {
-        JSONObject.testValidity(value);
         if (index < 0) {
             throw new JSONException("JSONArray[" + index + "] not found.");
         }
         if (index < this.length()) {
+            JSONObject.testValidity(value);
             this.myArrayList.set(index, value);
-        } else {
+            return this;
-            while (index != this.length()) {
-                this.put(JSONObject.NULL);
-            }
-            this.put(value);
         }
-        return this;
+        if(index == this.length()){
+            // simple append
+            return this.put(value);
+        }
+        // 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()) {
+            // we don't need to test validity of NULL objects
+            this.myArrayList.add(JSONObject.NULL);
+        }
+        return this.put(value);
     }
     
     /**
@@ -984,8 +1153,8 @@ public class JSONArray implements Iterable<Object> {
     }
     
     /**
-     * Uses a uaer initialized JSONPointer  and tries to 
+     * Uses a user initialized JSONPointer  and tries to 
-     * match it to an item whithin this JSONArray. For example, given a
+     * match it to an item within this JSONArray. For example, given a
      * JSONArray initialized with this document:
      * <pre>
      * [
@@ -1022,7 +1191,7 @@ public class JSONArray implements Iterable<Object> {
      * Queries and returns a value from this object using {@code jsonPointer}, or
      * returns null if the query fails due to a missing key.
      * 
-     * @param The JSON pointer
+     * @param jsonPointer The JSON pointer
      * @return the queried value or {@code null}
      * @throws IllegalArgumentException if {@code jsonPointer} has invalid syntax
      */
@@ -1064,8 +1233,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) {
+            	continue;
+            }
+            if(valueThis == null) {
+            	return false;
+            }
             if (valueThis instanceof JSONObject) {
                 if (!((JSONObject)valueThis).similar(valueOther)) {
                     return false;
@@ -1094,10 +1269,10 @@ public class JSONArray implements Iterable<Object> {
      *             If any of the names are null.
      */
     public JSONObject toJSONObject(JSONArray names) throws JSONException {
-        if (names == null || names.length() == 0 || this.length() == 0) {
+        if (names == null || names.isEmpty() || this.isEmpty()) {
             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));
         }
@@ -1109,12 +1284,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);
@@ -1124,8 +1301,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.
@@ -1145,8 +1337,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
@@ -1156,17 +1349,30 @@ 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>
+     * <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
      */
@@ -1178,8 +1384,12 @@ public class JSONArray implements Iterable<Object> {
             writer.write('[');
 
             if (length == 1) {
-                JSONObject.writeValue(writer, this.myArrayList.get(0),
+                try {
-                        indentFactor, indent);
+                    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;
 
@@ -1191,8 +1401,12 @@ public class JSONArray implements Iterable<Object> {
                         writer.write('\n');
                     }
                     JSONObject.indent(writer, newindent);
-                    JSONObject.writeValue(writer, this.myArrayList.get(i),
+                    try {
-                            indentFactor, newindent);
+                        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) {
@@ -1231,4 +1445,14 @@ public class JSONArray implements Iterable<Object> {
         }
         return results;
     }
+
+    /**
+     * Check if JSONArray is empty.
+     *
+     * @return true if JSONArray is empty, otherwise false.
+     */
+    public boolean isEmpty() {
+        return this.myArrayList.isEmpty();
+    }
+
 }

JSONML.java

@@ -24,9 +24,6 @@ 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
@@ -42,7 +39,7 @@ public class JSONML {
      * @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 attibute values
+     * @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
      */
@@ -175,7 +172,7 @@ public class JSONML {
                             if (!(token instanceof String)) {
                                 throw x.syntaxError("Missing value");
                             }
-                            newjo.accumulate(attribute, keepStrings ? XML.unescape((String)token) :XML.stringToValue((String)token));
+                            newjo.accumulate(attribute, keepStrings ? ((String)token) :XML.stringToValue((String)token));
                             token = null;
                         } else {
                             newjo.accumulate(attribute, "");
@@ -397,13 +394,10 @@ public class JSONML {
     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
 
@@ -420,17 +414,16 @@ public class JSONML {
 
 // Emit the attributes
 
-            keys = jo.keys();
+            // Don't use the new entrySet API to maintain Android support
-            while (keys.hasNext()) {
+            for (final String key : jo.keySet()) {
-                key = keys.next();
+                final Object value = jo.opt(key);
                 XML.noSpace(key);
-                value = jo.optString(key);
                 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('"');
                 }
             }
@@ -482,12 +475,10 @@ public class JSONML {
         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
 
@@ -502,18 +493,17 @@ public class JSONML {
 
 //Emit the attributes
 
-        keys = jo.keys();
+        // Don't use the new entrySet API to maintain Android support
-        while (keys.hasNext()) {
+        for (final String key : jo.keySet()) {
-            key = keys.next();
             if (!"tagName".equals(key) && !"childNodes".equals(key)) {
                 XML.noSpace(key);
-                value = jo.optString(key);
+                value = jo.opt(key);
                 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

@@ -5,7 +5,9 @@ import static java.lang.String.format;
 import java.io.UnsupportedEncodingException;
 import java.net.URLDecoder;
 import java.net.URLEncoder;
-import java.util.*;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
 
 /*
 Copyright (c) 2002 JSON.org
@@ -68,11 +70,11 @@ public class JSONPointer {
          * {@link #append(String)} method calls.
          */
         public JSONPointer build() {
-            return new JSONPointer(refTokens);
+            return new JSONPointer(this.refTokens);
         }
 
         /**
-         * Adds an arbitary token to the list of reference tokens. It can be any non-null value.
+         * 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
@@ -87,7 +89,7 @@ public class JSONPointer {
             if (token == null) {
                 throw new NullPointerException("token cannot be null");
             }
-            refTokens.add(token);
+            this.refTokens.add(token);
             return this;
         }
 
@@ -99,7 +101,7 @@ public class JSONPointer {
          * @return {@code this}
          */
         public Builder append(int arrayIndex) {
-            refTokens.add(String.valueOf(arrayIndex));
+            this.refTokens.add(String.valueOf(arrayIndex));
             return this;
         }
     }
@@ -134,30 +136,50 @@ public class JSONPointer {
      * @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(String pointer) {
+    public JSONPointer(final String pointer) {
         if (pointer == null) {
             throw new NullPointerException("pointer cannot be null");
         }
         if (pointer.isEmpty() || pointer.equals("#")) {
-            refTokens = Collections.emptyList();
+            this.refTokens = Collections.emptyList();
             return;
         }
+        String refs;
         if (pointer.startsWith("#/")) {
-            pointer = pointer.substring(2);
+            refs = pointer.substring(2);
             try {
-                pointer = URLDecoder.decode(pointer, ENCODING);
+                refs = URLDecoder.decode(refs, ENCODING);
             } catch (UnsupportedEncodingException e) {
                 throw new RuntimeException(e);
             }
         } else if (pointer.startsWith("/")) {
-            pointer = pointer.substring(1);
+            refs = pointer.substring(1);
         } else {
             throw new IllegalArgumentException("a JSON pointer should start with '/' or '#/'");
         }
-        refTokens = new ArrayList<String>();
+        this.refTokens = new ArrayList<String>();
-        for (String token : pointer.split("/")) {
+        int slashIdx = -1;
-            refTokens.add(unescape(token));
+        int prevSlashIdx = 0;
-        }
+        do {
+            prevSlashIdx = slashIdx + 1;
+            slashIdx = refs.indexOf('/', prevSlashIdx);
+            if(prevSlashIdx == slashIdx || prevSlashIdx == refs.length()) {
+                // found 2 slashes in a row ( obj//next )
+                // or single slash at the end of a string ( obj/test/ )
+                this.refTokens.add("");
+            } else if (slashIdx >= 0) {
+                final String token = refs.substring(prevSlashIdx, slashIdx);
+                this.refTokens.add(unescape(token));
+            } else {
+                // last item after separator, or no separator at all.
+                final String token = refs.substring(prevSlashIdx);
+                this.refTokens.add(unescape(token));
+            }
+        } while (slashIdx >= 0);
+        // using split does not take into account consecutive separators or "ending nulls"
+        //for (String token : refs.split("/")) {
+        //    this.refTokens.add(unescape(token));
+        //}
     }
 
     public JSONPointer(List<String> refTokens) {
@@ -180,12 +202,12 @@ public class JSONPointer {
      * @return the result of the evaluation
      * @throws JSONPointerException if an error occurs during evaluation
      */
-    public Object queryFrom(Object document) {
+    public Object queryFrom(Object document) throws JSONPointerException {
-        if (refTokens.isEmpty()) {
+        if (this.refTokens.isEmpty()) {
             return document;
         }
         Object current = document;
-        for (String token : refTokens) {
+        for (String token : this.refTokens) {
             if (current instanceof JSONObject) {
                 current = ((JSONObject) current).opt(unescape(token));
             } else if (current instanceof JSONArray) {
@@ -204,17 +226,21 @@ public class JSONPointer {
      * @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
+     * @throws JSONPointerException is thrown if the index is out of bounds
      */
-    private Object readByIndexToken(Object current, String indexToken) {
+    private Object readByIndexToken(Object current, String indexToken) throws JSONPointerException {
         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,
+                throw new JSONPointerException(format("index %s is out of bounds - the array has %d elements", indexToken,
-                        currentArr.length()));
+                        Integer.valueOf(currentArr.length())));
             }
-            return currentArr.get(index);
+            try {
+				return currentArr.get(index);
+			} catch (JSONException e) {
+				throw new JSONPointerException("Error reading value at index position " + index, e);
+			}
         } catch (NumberFormatException e) {
             throw new JSONPointerException(format("%s is not an array index", indexToken), e);
         }
@@ -227,7 +253,7 @@ public class JSONPointer {
     @Override
     public String toString() {
         StringBuilder rval = new StringBuilder("");
-        for (String token: refTokens) {
+        for (String token: this.refTokens) {
             rval.append('/').append(escape(token));
         }
         return rval.toString();
@@ -255,7 +281,7 @@ public class JSONPointer {
     public String toURIFragment() {
         try {
             StringBuilder rval = new StringBuilder("#");
-            for (String token : refTokens) {
+            for (String token : this.refTokens) {
                 rval.append('/').append(URLEncoder.encode(token, ENCODING));
             }
             return rval.toString();

JSONPropertyIgnore.java

@@ -0,0 +1,43 @@
+package org.json;
+
+/*
+Copyright (c) 2018 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.
+*/
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+@Documented
+@Retention(RUNTIME)
+@Target({METHOD})
+/**
+ * Use this annotation on a getter method to override the Bean name
+ * parser for Bean -> JSONObject mapping. If this annotation is
+ * present at any level in the class hierarchy, then the method will
+ * not be serialized from the bean into the JSONObject.
+ */
+public @interface JSONPropertyIgnore { }

JSONPropertyName.java

@@ -0,0 +1,47 @@
+package org.json;
+
+/*
+Copyright (c) 2018 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.
+*/
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+@Documented
+@Retention(RUNTIME)
+@Target({METHOD})
+/**
+ * Use this annotation on a getter method to override the Bean name
+ * parser for Bean -&gt; JSONObject mapping. A value set to empty string <code>""</code>
+ * will have the Bean parser fall back to the default field name processing.
+ */
+public @interface JSONPropertyName {
+    /**
+     * @return The name of the property as to be used in the JSON Object.
+     */
+    String value();
+}

JSONStringer.java

@@ -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,36 +39,45 @@ SOFTWARE.
  * @version 2014-05-03
  */
 public class JSONTokener {
-
+    /** current read character position on the current line. */
-    private long    character;
+    private long character;
+    /** flag to indicate if the end of the input has been found. */
     private boolean eof;
-    private long    index;
+    /** current read index of the input. */
-    private long    line;
+    private long index;
-    private char    previous;
+    /** current line of the input. */
-    private Reader  reader;
+    private long line;
+    /** previous character read from the input. */
+    private char previous;
+    /** 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.
      */
     public JSONTokener(Reader reader) {
         this.reader = reader.markSupported()
-            ? reader
+                ? reader
-            : new BufferedReader(reader);
+                        : new BufferedReader(reader);
         this.eof = false;
         this.usePrevious = false;
         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) {
@@ -97,12 +106,23 @@ public class JSONTokener {
         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).
@@ -124,6 +144,8 @@ public class JSONTokener {
     }
 
     /**
+     * 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() {
@@ -139,11 +161,24 @@ public class JSONTokener {
      *  or backward while checking for more data.
      */
     public boolean more() throws JSONException {
-        this.next();
+        if(this.usePrevious) {
-        if (this.end()) {
+            return true;
-            return false;
+        }
+        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.reader.reset();
+        } catch (IOException e) {
+            throw new JSONException("Unable to read the next character from the stream", e);
         }
-        this.back();
         return true;
     }
 
@@ -165,26 +200,39 @@ public class JSONTokener {
             } catch (IOException exception) {
                 throw new JSONException(exception);
             }
-
-            if (c <= 0) { // End of stream
-                this.eof = true;
-                c = 0;
-            }
         }
-        this.index += 1;
+        if (c <= 0) { // End of stream
-        if (this.previous == '\r') {
+            this.eof = true;
-            this.line += 1;
+            return 0;
-            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
@@ -196,8 +244,11 @@ public class JSONTokener {
     public char next(char c) throws JSONException {
         char n = this.next();
         if (n != c) {
-            throw this.syntaxError("Expected '" + c + "' and instead saw '" +
+            if(n > 0) {
-                    n + "'");
+                throw this.syntaxError("Expected '" + c + "' and instead saw '" +
+                        n + "'");
+            }
+            throw this.syntaxError("Expected '" + c + "' and instead saw ''");
         }
         return n;
     }
@@ -212,23 +263,23 @@ public class JSONTokener {
      *   Substring bounds error if there are not
      *   n characters remaining in the source string.
      */
-     public String next(int n) throws JSONException {
+    public String next(int n) throws JSONException {
-         if (n == 0) {
+        if (n == 0) {
-             return "";
+            return "";
-         }
+        }
 
-         char[] chars = new char[n];
+        char[] chars = new char[n];
-         int pos = 0;
+        int pos = 0;
 
-         while (pos < n) {
+        while (pos < n) {
-             chars[pos] = this.next();
+            chars[pos] = this.next();
-             if (this.end()) {
+            if (this.end()) {
-                 throw this.syntaxError("Substring bounds error");
+                throw this.syntaxError("Substring bounds error");
-             }
+            }
-             pos += 1;
+            pos += 1;
-         }
+        }
-         return new String(chars);
+        return new String(chars);
-     }
+    }
 
 
     /**
@@ -372,15 +423,15 @@ public class JSONTokener {
         String string;
 
         switch (c) {
-            case '"':
+        case '"':
-            case '\'':
+        case '\'':
-                return this.nextString(c);
+            return this.nextString(c);
-            case '{':
+        case '{':
-                this.back();
+            this.back();
-                return new JSONObject(this);
+            return new JSONObject(this);
-            case '[':
+        case '[':
-                this.back();
+            this.back();
-                return new JSONArray(this);
+            return new JSONArray(this);
         }
 
         /*
@@ -397,7 +448,9 @@ public class JSONTokener {
             sb.append(c);
             c = this.next();
         }
-        this.back();
+        if (!this.eof) {
+            this.back();
+        }
 
         string = sb.toString().trim();
         if ("".equals(string)) {
@@ -426,13 +479,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);
         }
@@ -440,7 +497,6 @@ public class JSONTokener {
         return c;
     }
 
-
     /**
      * Make a JSONException to signal a syntax error.
      *
@@ -470,6 +526,6 @@ public class JSONTokener {
     @Override
     public String toString() {
         return " at " + this.index + " [character " + this.character + " line " +
-            this.line + "]";
+                this.line + "]";
     }
 }

JSONWriter.java

@@ -1,6 +1,8 @@
 package org.json;
 
 import java.io.IOException;
+import java.util.Collection;
+import java.util.Map;
 
 /*
 Copyright (c) 2006 JSON.org
@@ -117,6 +119,9 @@ public class JSONWriter {
                 }
                 this.writer.append(string);
             } catch (IOException e) {
+            	// Android as of API 25 does not support this exception constructor
+            	// however we won't worry about it. If an exception is happening here
+            	// it will just throw a "Method not found" exception instead.
                 throw new JSONException(e);
             }
             if (this.mode == 'o') {
@@ -149,21 +154,24 @@ 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.append(c);
         } catch (IOException e) {
+        	// Android as of API 25 does not support this exception constructor
+        	// however we won't worry about it. If an exception is happening here
+        	// it will just throw a "Method not found" exception instead.
             throw new JSONException(e);
         }
         this.comma = true;
@@ -204,7 +212,12 @@ public class JSONWriter {
         }
         if (this.mode == 'k') {
             try {
-                this.stack[this.top - 1].putOnce(string, Boolean.TRUE);
+                JSONObject topObject = this.stack[this.top - 1];
+                // don't use the built in putOnce method to maintain Android support
+				if(topObject.has(string)) {
+					throw new JSONException("Duplicate key \"" + string + "\"");
+				}
+                topObject.put(string, true);
                 if (this.comma) {
                     this.writer.append(',');
                 }
@@ -214,6 +227,9 @@ public class JSONWriter {
                 this.mode = 'o';
                 return this;
             } catch (IOException e) {
+            	// Android as of API 25 does not support this exception constructor
+            	// however we won't worry about it. If an exception is happening here
+            	// it will just throw a "Method not found" exception instead.
                 throw new JSONException(e);
             }
         }
@@ -280,6 +296,77 @@ public class JSONWriter {
         this.top += 1;
     }
 
+    /**
+     * Make a JSON text of an Object value. If the object has an
+     * value.toJSONString() method, then that method will be used to produce the
+     * JSON text. The method is required to produce a strictly conforming text.
+     * If the object does not contain a toJSONString method (which is the most
+     * common case), then a text will be produced by other means. If the value
+     * is an array or Collection, then a JSONArray will be made from it and its
+     * toJSONString method will be called. If the value is a MAP, then a
+     * JSONObject will be made from it and its toJSONString method will be
+     * called. Otherwise, the value's toString method will be called, and the
+     * result will be quoted.
+     *
+     * <p>
+     * Warning: This method assumes that the data structure is acyclical.
+     *
+     * @param value
+     *            The value to be serialized.
+     * @return a printable, displayable, transmittable representation of the
+     *         object, beginning with <code>{</code>&nbsp;<small>(left
+     *         brace)</small> and ending with <code>}</code>&nbsp;<small>(right
+     *         brace)</small>.
+     * @throws JSONException
+     *             If the value is or contains an invalid number.
+     */
+    public static String valueToString(Object value) throws JSONException {
+        if (value == null || value.equals(null)) {
+            return "null";
+        }
+        if (value instanceof JSONString) {
+            String object;
+            try {
+                object = ((JSONString) value).toJSONString();
+            } catch (Exception e) {
+                throw new JSONException(e);
+            }
+            if (object != null) {
+                return object;
+            }
+            throw new JSONException("Bad value from toJSONString: " + object);
+        }
+        if (value instanceof Number) {
+            // not all Numbers may match actual JSON Numbers. i.e. Fractions or Complex
+            final String numberAsString = JSONObject.numberToString((Number) value);
+            if(JSONObject.NUMBER_PATTERN.matcher(numberAsString).matches()) {
+                // Close enough to a JSON number that we will return it unquoted
+                return numberAsString;
+            }
+            // The Number value is not a valid JSON number.
+            // Instead we will quote it as a string
+            return JSONObject.quote(numberAsString);
+        }
+        if (value instanceof Boolean || value instanceof JSONObject
+                || value instanceof JSONArray) {
+            return value.toString();
+        }
+        if (value instanceof Map) {
+            Map<?, ?> map = (Map<?, ?>) value;
+            return new JSONObject(map).toString();
+        }
+        if (value instanceof Collection) {
+            Collection<?> coll = (Collection<?>) value;
+            return new JSONArray(coll).toString();
+        }
+        if (value.getClass().isArray()) {
+            return new JSONArray(value).toString();
+        }
+        if(value instanceof Enum<?>){
+            return JSONObject.quote(((Enum<?>)value).name());
+        }
+        return JSONObject.quote(value.toString());
+    }
 
     /**
      * Append either the value <code>true</code> or the value
@@ -299,7 +386,7 @@ public class JSONWriter {
      * @throws JSONException If the number is not finite.
      */
     public JSONWriter value(double d) throws JSONException {
-        return this.value(new Double(d));
+        return this.value(Double.valueOf(d));
     }
 
     /**
@@ -321,6 +408,6 @@ public class JSONWriter {
      * @throws JSONException If the value is out of sequence.
      */
     public JSONWriter value(Object object) throws JSONException {
-        return this.append(JSONObject.valueToString(object));
+        return this.append(valueToString(object));
     }
 }

Property.java

@@ -25,7 +25,6 @@ SOFTWARE.
 */
 
 import java.util.Enumeration;
-import java.util.Iterator;
 import java.util.Properties;
 
 /**
@@ -41,6 +40,8 @@ public class Property {
      * @throws JSONException
      */
     public static JSONObject toJSONObject(java.util.Properties properties) throws JSONException {
+        // can't use the new constructor for Android support
+        // JSONObject jo = new JSONObject(properties == null ? 0 : properties.size());
         JSONObject jo = new JSONObject();
         if (properties != null && !properties.isEmpty()) {
             Enumeration<?> enumProperties = properties.propertyNames();
@@ -61,10 +62,12 @@ public class Property {
     public static Properties toProperties(JSONObject jo)  throws JSONException {
         Properties  properties = new Properties();
         if (jo != null) {
-            Iterator<String> keys = jo.keys();
+        	// Don't use the new entrySet API to maintain Android support
-            while (keys.hasNext()) {
+            for (final String key : jo.keySet()) {
-                String name = keys.next();
+                Object value = jo.opt(key);
-                properties.put(name, jo.getString(name));
+                if (!JSONObject.NULL.equals(value)) {
+                    properties.put(key, value.toString());
+                }
             }
         }
         return properties;

README

@@ -1,112 +0,0 @@
-JSON in Java [package org.json]
-
-JSON is a light-weight, language independent, data interchange format.
-See http://www.JSON.org/
-
-The files in this package implement JSON encoders/decoders in Java.
-It also includes the capability to convert between JSON and XML, HTTP
-headers, Cookies, and CDL.
-
-This is a reference implementation. There is a large number of JSON packages
-in Java. Perhaps someday the Java community will standardize on one. Until
-then, choose carefully.
-
-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.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 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.
-
-JSONTokener.java: The JSONTokener breaks a text into a sequence of individual
-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.
-
-JSONStringer.java: The JSONStringer provides a convenient facility for
-building JSON strings.
-
-JSONWriter.java: The JSONWriter provides a convenient facility for building
-JSON text through a writer.
-
-
-CDL.java: CDL provides support for converting between JSON and comma
-delimited lists.
-
-Cookie.java: Cookie provides support for converting between JSON and cookies.
-
-CookieList.java: CookieList provides support for converting between JSON and
-cookie lists.
-
-HTTP.java: HTTP provides support for converting between JSON and HTTP headers.
-
-HTTPTokener.java: HTTPTokener extends JSONTokener for parsing HTTP headers.
-
-XML.java: XML provides support for converting between JSON and XML.
-
-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
-
-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:
-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. 
-
-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

README.md

@@ -0,0 +1,138 @@
+JSON in Java [package org.json]
+===============================
+
+[![Maven Central](https://img.shields.io/maven-central/v/org.json/json.svg)](https://mvnrepository.com/artifact/org.json/json)
+
+**[Click here if you just want the latest release jar file.](http://central.maven.org/maven2/org/json/json/20180813/json-20180813.jar)**
+
+JSON is a light-weight, language independent, data interchange format.
+See http://www.JSON.org/
+
+The files in this package implement JSON encoders/decoders in Java.
+It also includes the capability to convert between JSON and XML, HTTP
+headers, Cookies, and CDL.
+
+This is a reference implementation. There is a large number of JSON packages
+in Java. Perhaps someday the Java community will standardize on one. Until
+then, choose carefully.
+
+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.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 `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.
+
+**JSONTokener.java**: The `JSONTokener` breaks a text into a sequence of individual
+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.
+
+**JSONPropertyIgnore.java**: Annotation class that can be used on Java Bean getter methods.
+When used on a bean method that would normally be serialized into a `JSONObject`, it
+overrides the getter-to-key-name logic and forces the property to be excluded from the
+resulting `JSONObject`.
+
+**JSONPropertyName.java**: Annotation class that can be used on Java Bean getter methods.
+When used on a bean method that would normally be serialized into a `JSONObject`, it
+overrides the getter-to-key-name logic and uses the value of the annotation. The Bean
+processor will look through the class hierarchy. This means you can use the annotation on
+a base class or interface and the value of the annotation will be used even if the getter
+is overridden in a child class.   
+
+**JSONString.java**: The `JSONString` interface requires a `toJSONString` method,
+allowing an object to provide its own serialization.
+
+**JSONStringer.java**: The `JSONStringer` provides a convenient facility for
+building JSON strings.
+
+**JSONWriter.java**: The `JSONWriter` provides a convenient facility for building
+JSON text through a writer.
+
+
+**CDL.java**: `CDL` provides support for converting between JSON and comma
+delimited lists.
+
+**Cookie.java**: `Cookie` provides support for converting between JSON and cookies.
+
+**CookieList.java**: `CookieList` provides support for converting between JSON and
+cookie lists.
+
+**HTTP.java**: `HTTP` provides support for converting between JSON and HTTP headers.
+
+**HTTPTokener.java**: `HTTPTokener` extends `JSONTokener` for parsing HTTP headers.
+
+**XML.java**: `XML` provides support for converting between JSON and XML.
+
+**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
+
+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 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259#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 RFC8259 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:
+
+~~~
+20180813    POM change to include Automatic-Module-Name (#431)
+
+20180130    Recent commits
+
+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.
+~~~
+
+
+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?q=g:org.json%20AND%20a:json&core=gav

XML.java

@@ -24,6 +24,8 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+import java.io.Reader;
+import java.io.StringReader;
 import java.util.Iterator;
 
 /**
@@ -35,6 +37,7 @@ import java.util.Iterator;
  */
 @SuppressWarnings("boxing")
 public class XML {
+
     /** The Character '&'. */
     public static final Character AMP = '&';
 
@@ -62,6 +65,11 @@ public class XML {
     /** The Character '/'. */
     public static final Character SLASH = '/';
 
+    /**
+     * Null attrubute name
+     */
+    public static final String NULL_ATTR = "xsi:nil";
+
     /**
      * Creates an iterator for navigating Code Points in a string instead of
      * characters. Once Java7 support is dropped, this can be replaced with
@@ -140,7 +148,7 @@ public class XML {
                 if (mustEscape(cp)) {
                     sb.append("&#x");
                     sb.append(Integer.toHexString(cp));
-                    sb.append(";");
+                    sb.append(';');
                 } else {
                     sb.appendCodePoint(cp);
                 }
@@ -190,36 +198,12 @@ public class XML {
                 final int semic = string.indexOf(';', i);
                 if (semic > i) {
                     final String entity = string.substring(i + 1, semic);
-                    if (entity.charAt(0) == '#') {
+                    sb.append(XMLTokener.unescapeEntity(entity));
-                        int cp;
-                        if (entity.charAt(1) == 'x') {
-                            // hex encoded unicode
-                            cp = Integer.parseInt(entity.substring(2), 16);
-                        } else {
-                            // decimal encoded unicode
-                            cp = Integer.parseInt(entity.substring(1));
-                        }
-                        sb.appendCodePoint(cp);
-                    } else {
-                        if ("quot".equalsIgnoreCase(entity)) {
-                            sb.append('"');
-                        } else if ("amp".equalsIgnoreCase(entity)) {
-                            sb.append('&');
-                        } else if ("apos".equalsIgnoreCase(entity)) {
-                            sb.append('\'');
-                        } else if ("lt".equalsIgnoreCase(entity)) {
-                            sb.append('<');
-                        } else if ("gt".equalsIgnoreCase(entity)) {
-                            sb.append('>');
-                        } else {
-                            sb.append('&').append(entity).append(';');
-                        }
-                    }
                     // 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 enties.
+                    // errors on unclosed entries.
                     sb.append(c);
                 }
             } else {
@@ -263,7 +247,7 @@ public class XML {
      * @return true if the close tag is processed.
      * @throws JSONException
      */
-    private static boolean parse(XMLTokener x, JSONObject context, String name, boolean keepStrings)
+    private static boolean parse(XMLTokener x, JSONObject context, String name, XMLParserConfiguration config)
             throws JSONException {
         char c;
         int i;
@@ -300,7 +284,7 @@ public class XML {
                     if (x.next() == '[') {
                         string = x.nextCDATA();
                         if (string.length() > 0) {
-                            context.accumulate("content", string);
+                            context.accumulate(config.cDataTagName, string);
                         }
                         return false;
                     }
@@ -349,6 +333,7 @@ public class XML {
             tagName = (String) token;
             token = null;
             jsonobject = new JSONObject();
+            boolean nilAttributeFound = false;
             for (;;) {
                 if (token == null) {
                     token = x.nextToken();
@@ -362,8 +347,17 @@ public class XML {
                         if (!(token instanceof String)) {
                             throw x.syntaxError("Missing value");
                         }
-                        jsonobject.accumulate(string,
+
-                                keepStrings ? unescape((String)token) : stringToValue((String) token));
+                        if (config.convertNilAttributeToNull
+                                && NULL_ATTR.equals(string)
+                                && Boolean.parseBoolean((String) token)) {
+                            nilAttributeFound = true;
+                        } else if (!nilAttributeFound) {
+                            jsonobject.accumulate(string,
+                                    config.keepStrings
+                                            ? ((String) token)
+                                            : stringToValue((String) token));
+                        }
                         token = null;
                     } else {
                         jsonobject.accumulate(string, "");
@@ -375,7 +369,9 @@ public class XML {
                     if (x.nextToken() != GT) {
                         throw x.syntaxError("Misshaped tag");
                     }
-                    if (jsonobject.length() > 0) {
+                    if (nilAttributeFound) {
+                        context.accumulate(tagName, JSONObject.NULL);
+                    } else if (jsonobject.length() > 0) {
                         context.accumulate(tagName, jsonobject);
                     } else {
                         context.accumulate(tagName, "");
@@ -394,19 +390,19 @@ public class XML {
                         } else if (token instanceof String) {
                             string = (String) token;
                             if (string.length() > 0) {
-                                jsonobject.accumulate("content",
+                                jsonobject.accumulate(config.cDataTagName,
-                                        keepStrings ? unescape(string) : stringToValue(string));
+                                        config.keepStrings ? string : stringToValue(string));
                             }
 
                         } else if (token == LT) {
                             // Nested element
-                            if (parse(x, jsonobject, tagName,keepStrings)) {
+                            if (parse(x, jsonobject, tagName, config)) {
                                 if (jsonobject.length() == 0) {
                                     context.accumulate(tagName, "");
                                 } else if (jsonobject.length() == 1
-                                        && jsonobject.opt("content") != null) {
+                                        && jsonobject.opt(config.cDataTagName) != null) {
                                     context.accumulate(tagName,
-                                            jsonobject.opt("content"));
+                                            jsonobject.opt(config.cDataTagName));
                                 } else {
                                     context.accumulate(tagName, jsonobject);
                                 }
@@ -422,18 +418,56 @@ public class XML {
     }
 
     /**
-     * This method is the same as {@link JSONObject.stringToValue(String)}
+     * This method is the same as {@link JSONObject#stringToValue(String)}.
-     * except that this also tries to unescape String values.
      *
      * @param string String to convert
      * @return JSON value of this string or the string
      */
+    // To maintain compatibility with the Android API, this method is a direct copy of
+    // the one in JSONObject. Changes made here should be reflected there.
     public static Object stringToValue(String string) {
-        Object ret = JSONObject.stringToValue(string);
+        if (string.equals("")) {
-        if(ret instanceof String){
+            return string;
-            return unescape((String)ret);
         }
-        return ret;
+        if (string.equalsIgnoreCase("true")) {
+            return Boolean.TRUE;
+        }
+        if (string.equalsIgnoreCase("false")) {
+            return Boolean.FALSE;
+        }
+        if (string.equalsIgnoreCase("null")) {
+            return JSONObject.NULL;
+        }
+
+        /*
+         * If it might be a number, try converting it. If a number cannot be
+         * produced, then the value will just be a string.
+         */
+
+        char initial = string.charAt(0);
+        if ((initial >= '0' && initial <= '9') || initial == '-') {
+            try {
+                // if we want full Big Number support this block can be replaced with:
+                // return stringToNumber(string);
+                if (string.indexOf('.') > -1 || string.indexOf('e') > -1
+                        || string.indexOf('E') > -1 || "-0".equals(string)) {
+                    Double d = Double.valueOf(string);
+                    if (!d.isInfinite() && !d.isNaN()) {
+                        return d;
+                    }
+                } else {
+                    Long myLong = Long.valueOf(string);
+                    if (string.equals(myLong.toString())) {
+                        if (myLong.longValue() == myLong.intValue()) {
+                            return Integer.valueOf(myLong.intValue());
+                        }
+                        return myLong;
+                    }
+                }
+            } catch (Exception ignore) {
+            }
+        }
+        return string;
     }
 
     /**
@@ -453,9 +487,85 @@ public class XML {
      * @throws JSONException Thrown if there is an errors while parsing the string
      */
     public static JSONObject toJSONObject(String string) throws JSONException {
-        return toJSONObject(string, false);
+        return toJSONObject(string, XMLParserConfiguration.ORIGINAL);
     }
 
+    /**
+     * Convert a well-formed (but not necessarily valid) XML into a
+     * JSONObject. Some information may be lost in this transformation because
+     * JSON is a data format and XML is a document format. XML uses elements,
+     * attributes, and content text, while JSON uses unordered collections of
+     * name/value pairs and arrays of values. JSON does not does not like to
+     * distinguish between elements and attributes. Sequences of similar
+     * elements are represented as JSONArrays. Content text may be placed in a
+     * "content" member. Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code>
+     * are ignored.
+     *
+     * @param reader The XML source reader.
+     * @return A JSONObject containing the structured data from the XML string.
+     * @throws JSONException Thrown if there is an errors while parsing the string
+     */
+    public static JSONObject toJSONObject(Reader reader) throws JSONException {
+        return toJSONObject(reader, XMLParserConfiguration.ORIGINAL);
+    }
+
+    /**
+     * Convert a well-formed (but not necessarily valid) XML into a
+     * JSONObject. Some information may be lost in this transformation because
+     * JSON is a data format and XML is a document format. XML uses elements,
+     * attributes, and content text, while JSON uses unordered collections of
+     * name/value pairs and arrays of values. JSON does not does not like to
+     * distinguish between elements and attributes. Sequences of similar
+     * elements are represented as JSONArrays. Content text may be placed in a
+     * "content" member. Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code>
+     * are ignored.
+     *
+     * 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 reader The XML source reader.
+     * @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 if there is an errors while parsing the string
+     */
+    public static JSONObject toJSONObject(Reader reader, boolean keepStrings) throws JSONException {
+        if(keepStrings) {
+            return toJSONObject(reader, XMLParserConfiguration.KEEP_STRINGS);
+        }
+        return toJSONObject(reader, XMLParserConfiguration.ORIGINAL);
+    }
+
+    /**
+     * Convert a well-formed (but not necessarily valid) XML into a
+     * JSONObject. Some information may be lost in this transformation because
+     * JSON is a data format and XML is a document format. XML uses elements,
+     * attributes, and content text, while JSON uses unordered collections of
+     * name/value pairs and arrays of values. JSON does not does not like to
+     * distinguish between elements and attributes. Sequences of similar
+     * elements are represented as JSONArrays. Content text may be placed in a
+     * "content" member. Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code>
+     * are ignored.
+     *
+     * 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 reader The XML source reader.
+     * @param config Configuration options for the parser
+     * @return A JSONObject containing the structured data from the XML string.
+     * @throws JSONException Thrown if there is an errors while parsing the string
+     */
+    public static JSONObject toJSONObject(Reader reader, XMLParserConfiguration config) throws JSONException {
+        JSONObject jo = new JSONObject();
+        XMLTokener x = new XMLTokener(reader);
+        while (x.more()) {
+            x.skipPast("<");
+            if(x.more()) {
+                parse(x, jo, null, config);
+            }
+        }
+        return jo;
+    }
 
     /**
      * Convert a well-formed (but not necessarily valid) XML string into a
@@ -479,13 +589,33 @@ public class XML {
      * @throws JSONException Thrown if there is an errors while parsing the string
      */
     public static JSONObject toJSONObject(String string, boolean keepStrings) throws JSONException {
-        JSONObject jo = new JSONObject();
+        return toJSONObject(new StringReader(string), keepStrings);
-        XMLTokener x = new XMLTokener(string);
-        while (x.more() && x.skipPast("<")) {
-            parse(x, jo, null, keepStrings);
-        }
-        return jo;
     }
+
+    /**
+     * Convert a well-formed (but not necessarily valid) XML string into a
+     * JSONObject. Some information may be lost in this transformation because
+     * JSON is a data format and XML is a document format. XML uses elements,
+     * attributes, and content text, while JSON uses unordered collections of
+     * name/value pairs and arrays of values. JSON does not does not like to
+     * distinguish between elements and attributes. Sequences of similar
+     * elements are represented as JSONArrays. Content text may be placed in a
+     * "content" member. Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code>
+     * are ignored.
+     *
+     * 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 config Configuration options for the parser.
+     * @return A JSONObject containing the structured data from the XML string.
+     * @throws JSONException Thrown if there is an errors while parsing the string
+     */
+    public static JSONObject toJSONObject(String string, XMLParserConfiguration config) throws JSONException {
+        return toJSONObject(new StringReader(string), config);
+    }
+
     /**
      * Convert a JSONObject into a well-formed, element-normal XML string.
      *
@@ -495,7 +625,7 @@ public class XML {
      * @throws JSONException Thrown if there is an error parsing the string
      */
     public static String toString(Object object) throws JSONException {
-        return toString(object, null);
+        return toString(object, null, XMLParserConfiguration.ORIGINAL);
     }
 
     /**
@@ -508,15 +638,28 @@ public class XML {
      * @return A string.
      * @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) {
+        return toString(object, tagName, XMLParserConfiguration.ORIGINAL);
+    }
+
+    /**
+     * 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 config
+     *            Configuration that can control output to XML.
+     * @return A string.
+     * @throws JSONException Thrown if there is an error parsing the string
+     */
+    public static String toString(final Object object, final String tagName, final XMLParserConfiguration config)
             throws JSONException {
         StringBuilder sb = new StringBuilder();
         JSONArray ja;
         JSONObject jo;
-        String key;
-        Iterator<String> keys;
         String string;
-        Object value;
 
         if (object instanceof JSONObject) {
 
@@ -528,29 +671,28 @@ public class XML {
             }
 
             // Loop thru the keys.
+            // don't use the new entrySet accessor to maintain Android Support
             jo = (JSONObject) object;
-            keys = jo.keys();
+            for (final String key : jo.keySet()) {
-            while (keys.hasNext()) {
+                Object value = jo.opt(key);
-                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
-                if ("content".equals(key)) {
+                if (key.equals(config.cDataTagName)) {
                     if (value instanceof JSONArray) {
                         ja = (JSONArray) value;
-                        int i = 0;
+                        int jaLength = ja.length();
-                        for (Object val : ja) {
+                        // don't use the new iterator API to maintain support for Android
+						for (int i = 0; i < jaLength; i++) {
                             if (i > 0) {
                                 sb.append('\n');
                             }
+                            Object val = ja.opt(i);
                             sb.append(escape(val.toString()));
-                            i++;
                         }
                     } else {
                         sb.append(escape(value.toString()));
@@ -560,17 +702,20 @@ public class XML {
 
                 } else if (value instanceof JSONArray) {
                     ja = (JSONArray) value;
-                    for (Object val : ja) {
+                    int jaLength = ja.length();
+                    // don't use the new iterator API to maintain support for Android
+					for (int i = 0; i < jaLength; i++) {
+                        Object val = ja.opt(i);
                         if (val instanceof JSONArray) {
                             sb.append('<');
                             sb.append(key);
                             sb.append('>');
-                            sb.append(toString(val));
+                            sb.append(toString(val, null, config));
                             sb.append("</");
                             sb.append(key);
                             sb.append('>');
                         } else {
-                            sb.append(toString(val, key));
+                            sb.append(toString(val, key, config));
                         }
                     }
                 } else if ("".equals(value)) {
@@ -581,7 +726,7 @@ public class XML {
                     // Emit a new tag <k>
 
                 } else {
-                    sb.append(toString(value, key));
+                    sb.append(toString(value, key, config));
                 }
             }
             if (tagName != null) {
@@ -595,21 +740,22 @@ public class XML {
 
         }
 
-        if (object != null) {
+        if (object != null && (object instanceof JSONArray ||  object.getClass().isArray())) {
-            if (object.getClass().isArray()) {
+            if(object.getClass().isArray()) {
-                object = new JSONArray(object);
+                ja = new JSONArray(object);
-            }
+            } else {
-
-            if (object instanceof JSONArray) {
                 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();
             }
+            int jaLength = ja.length();
+            // don't use the new iterator API to maintain support for Android
+			for (int i = 0; i < jaLength; i++) {
+                Object val = ja.opt(i);
+                // 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, config));
+            }
+            return sb.toString();
         }
 
         string = (object == null) ? "null" : escape(object.toString());

XMLParserConfiguration.java

@@ -0,0 +1,107 @@
+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.
+*/
+
+/**
+ * Configuration object for the XML parser.
+ * @author AylwardJ
+ *
+ */
+public class XMLParserConfiguration {
+    /** Original Configuration of the XML Parser. */
+    public static final XMLParserConfiguration ORIGINAL = new XMLParserConfiguration();
+    /** Original configuration of the XML Parser except that values are kept as strings. */
+    public static final XMLParserConfiguration KEEP_STRINGS = new XMLParserConfiguration(true);
+    /**
+     * When parsing the XML into JSON, specifies if values should be kept as strings (true), or if
+     * they should try to be guessed into JSON values (numeric, boolean, string)
+     */
+    public final boolean keepStrings;
+    /**
+     * The name of the key in a JSON Object that indicates a CDATA section. Historically this has
+     * been the value "content" but can be changed. Use <code>null</code> to indicate no CDATA
+     * processing.
+     */
+    public final String cDataTagName;
+    /**
+     * When parsing the XML into JSON, specifies if values with attribute xsi:nil="true"
+     * should be kept as attribute(false), or they should be converted to null(true)
+     */
+    public final boolean convertNilAttributeToNull;
+
+    /**
+     * Default parser configuration. Does not keep strings, and the CDATA Tag Name is "content".
+     */
+    public XMLParserConfiguration () {
+        this(false, "content", false);
+    }
+
+    /**
+     * Configure the parser string processing and use the default CDATA Tag Name as "content".
+     * @param keepStrings <code>true</code> to parse all values as string.
+     *      <code>false</code> to try and convert XML string values into a JSON value.
+     */
+    public XMLParserConfiguration (final boolean keepStrings) {
+        this(keepStrings, "content", false);
+    }
+
+    /**
+     * Configure the parser string processing to try and convert XML values to JSON values and
+     * use the passed CDATA Tag Name the processing value. Pass <code>null</code> to
+     * disable CDATA processing
+     * @param cDataTagName<code>null</code> to disable CDATA processing. Any other value
+     *      to use that value as the JSONObject key name to process as CDATA.
+     */
+    public XMLParserConfiguration (final String cDataTagName) {
+        this(false, cDataTagName, false);
+    }
+
+    /**
+     * Configure the parser to use custom settings.
+     * @param keepStrings <code>true</code> to parse all values as string.
+     *      <code>false</code> to try and convert XML string values into a JSON value.
+     * @param cDataTagName<code>null</code> to disable CDATA processing. Any other value
+     *      to use that value as the JSONObject key name to process as CDATA.
+     */
+    public XMLParserConfiguration (final boolean keepStrings, final String cDataTagName) {
+        this.keepStrings = keepStrings;
+        this.cDataTagName = cDataTagName;
+        this.convertNilAttributeToNull = false;
+    }
+
+    /**
+     * Configure the parser to use custom settings.
+     * @param keepStrings <code>true</code> to parse all values as string.
+     *      <code>false</code> to try and convert XML string values into a JSON value.
+     * @param cDataTagName <code>null</code> to disable CDATA processing. Any other value
+     *      to use that value as the JSONObject key name to process as CDATA.
+     * @param convertNilAttributeToNull <code>true</code> to parse values with attribute xsi:nil="true" as null.
+     *                                  <code>false</code> to parse values with attribute xsi:nil="true" as {"xsi:nil":true}.
+     */
+    public XMLParserConfiguration (final boolean keepStrings, final String cDataTagName, final boolean convertNilAttributeToNull) {
+        this.keepStrings = keepStrings;
+        this.cDataTagName = cDataTagName;
+        this.convertNilAttributeToNull = convertNilAttributeToNull;
+    }
+}

XMLTokener.java

@@ -24,6 +24,8 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+import java.io.Reader;
+
 /**
  * The XMLTokener extends the JSONTokener to provide additional methods
  * for the parsing of XML texts.
@@ -47,6 +49,14 @@ public class XMLTokener extends JSONTokener {
        entity.put("quot", XML.QUOT);
    }
 
+    /**
+     * Construct an XMLTokener from a Reader.
+     * @param r A source reader.
+     */
+    public XMLTokener(Reader r) {
+        super(r);
+    }
+
     /**
      * Construct an XMLTokener from a string.
      * @param s A source string.
@@ -64,11 +74,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 +84,7 @@ public class XMLTokener extends JSONTokener {
                 return sb.toString();
             }
         }
+        throw syntaxError("Unclosed CDATA");
     }
 
 
@@ -103,7 +111,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();
             }
@@ -124,7 +135,7 @@ public class XMLTokener extends JSONTokener {
      * @return  A Character or an entity String if the entity is not recognized.
      * @throws JSONException If missing ';' in XML entity.
      */
-    public Object nextEntity(char ampersand) throws JSONException {
+    public Object nextEntity(@SuppressWarnings("unused") char ampersand) throws JSONException {
         StringBuilder sb = new StringBuilder();
         for (;;) {
             char c = next();
@@ -137,8 +148,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();
     }
 
 
@@ -296,9 +336,11 @@ public class XMLTokener extends JSONTokener {
      * Skip characters until past the requested string.
      * If it is not found, we are left at the end of the source with a result of false.
      * @param to A string to skip past.
-     * @throws JSONException
      */
-    public boolean skipPast(String to) throws JSONException {
+    // The Android implementation of JSONTokener has a public method of public void skipPast(String to)
+    // even though ours does not have that method, to have API compatibility, our method in the subclass
+    // should match.
+    public void skipPast(String to) {
         boolean b;
         char c;
         int i;
@@ -315,7 +357,7 @@ public class XMLTokener extends JSONTokener {
         for (i = 0; i < length; i += 1) {
             c = next();
             if (c == 0) {
-                return false;
+                return;
             }
             circle[i] = c;
         }
@@ -342,14 +384,14 @@ public class XMLTokener extends JSONTokener {
             /* If we exit the loop with b intact, then victory is ours. */
 
             if (b) {
-                return true;
+                return;
             }
 
             /* Get the next character. If there isn't one, then defeat is ours. */
 
             c = next();
             if (c == 0) {
-                return false;
+                return;
             }
             /*
              * Shove the character in the circle buffer and advance the