Merge pull request #622 from pedrombmachado/patch-1

Update README.md

Examples.md

@@ -0,0 +1,433 @@
+<h1>Examples</h1>
+<p>Imports used in the examples: </p>
+
+```
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Properties;
+```
+
+<p>This document's intention is to explain to new-comers the basics of this project</p>
+
+	
+<h2>Part 1: Creating a JSON document</h2>
+
+<h3>Using JSONArray</h3>
+
+```
+	private static void JSONExampleArray1() {
+		//We create a JSONObject from a String containing an array using JSONArray
+		//Firstly, we declare an Array in a String
+
+		 String arrayStr = 
+		            "["+"true,"+"false,"+ "\"true\","+ "\"false\","+"\"hello\","+"23.45e-4,"+
+		                "\"23.45\","+"42,"+"\"43\","+"["+"\"world\""+"],"+
+		            		"{"+
+		                    "\"key1\":\"value1\","+
+		                    "\"key2\":\"value2\","+
+		                    "\"key3\":\"value3\","+
+		                    "\"key4\":\"value4\""+
+		                "},"+
+		                "0,"+"\"-1\""+
+		            "]";
+
+		 //Then, we initializate the JSONArray thanks to its constructor
+
+		  JSONArray array = new JSONArray(arrayStr);
+		  System.out.println("Values array: "+ array);
+
+		  //We convert that array into a JSONObject, but first, we need the labels, so we need another JSONArray with the labels.
+		  //Here we will use an auxiliary function to get one for the example.
+
+		  JSONArray list = listNumberArray(array.length());
+		  System.out.println("Label Array: "+ list.toString());
+		  //Now, we construct the JSONObject using both the  value array and the label array.
+		  JSONObject object = array.toJSONObject(list);
+		  System.out.println("Final JSONOBject: " + object);
+	}
+
+	//This method creates an JSONArray of labels in which those are generated by their positions
+
+	private static JSONArray listNumberArray(int max){
+		 JSONArray res = new JSONArray();
+		for (int i=0; i<max;i++) {
+			//The value of the labels must be an String in order to make it work
+			res.put(String.valueOf(i));
+		}
+		return res;
+	}
+```
+```
+	private static void JSONExampleArray2() {
+
+		//We can also create an Array without a String by creating an empty array and adding elements to it
+
+		  JSONArray array = new JSONArray();
+
+		//Adding elements with .put()
+
+		array.put("value");
+		array.put(5);
+		array.put(-23.45e67);
+		array.put(true);
+		
+		//We convert it to JSONObject providing a label arrray like last time
+
+		 JSONArray list = listNumberArray(array.length());
+		 JSONObject object = array.toJSONObject(list);
+		 System.out.println("Final JSONOBject: " + object);
+	}
+```
+
+<h3>Using JSONStringer</h3>
+
+```
+	private static void JSONExampleStringer() {
+
+		//We initializate the JSONStringer
+
+		JSONStringer jsonStringer = new JSONStringer();
+
+		//Now we start the process of adding elements with .object()
+
+        jsonStringer.object();
+
+        //We can now add elements as keys and values with .values () and .key()
+
+        jsonStringer.key("trueValue").value(true);
+        jsonStringer.key("falseValue").value(false);
+        jsonStringer.key("nullValue").value(null);
+        jsonStringer.key("stringValue").value("hello world!");
+        jsonStringer.key("complexStringValue").value("h\be\tllo w\u1234orld!");
+        jsonStringer.key("intValue").value(42);
+        jsonStringer.key("doubleValue").value(-23.45e67);
+
+        //We end this prcedure with .ednObject
+
+        jsonStringer.endObject();
+
+       //Once we have a JSONStringer, we convert it to JSONObject generating a String and using JSONObject's contructor.
+
+        String str = jsonStringer.toString();
+        JSONObject jsonObject = new JSONObject(str);
+        
+       System.out.println("Final JSONOBject: " + jsonObject);
+	}
+```
+<h3>Using JSONObject</h3>
+
+```
+	private static void JSONExampleObject1() {
+
+		//We can create a JSONObject from a String with the class builder
+
+		String string = "{\"0\":\"value\",\"1\":5,\"2\":-2.345E68,\"3\":true}";
+		JSONObject example = new JSONObject(string);
+		System.out.println("Final JSONObject: " + example);
+		
+	}
+```
+```
+	private static void JSONExampleObject2() {
+
+		//We can also create a JSONObject directly without messing around with any of the other functions.
+
+		JSONObject example = new JSONObject();
+
+
+		//Now we add the keys and values in a similar way as the Stringer method
+		example.put("key", "value");
+
+		//As you can see, the first entry is the key and the second would be its associeted value.
+
+		example.put("key2", 5);
+		example.put("key3", -23.45e67);
+		example.put("trueValue", true);
+
+		//We can't add null values thougth
+
+		//example.put("nullValue", null); //This is not possible
+		
+		 System.out.println("Final JSONOBject: " + example);
+	}
+```
+```
+	private static void JSONExampleObject3() {
+
+		//We can also create a JSONObject with a Java Map
+		//YoU will need a Map whose keys are Strings. The values can be whatever you want
+
+		Map<String,Double> map = new HashMap<String, Double>();
+		
+		map.put("key1", 1.0);
+		map.put("key2", -23.45e67);
+		
+		//We create the JSONObject with the map with its class builder
+
+		JSONObject example = new JSONObject(map);
+		 System.out.println("Final JSONOBject: " + example);
+	}
+```
+<h3>Using JSONWriter</h3>
+
+```	
+	private static void JSONExamplWriter() {
+
+		//This method works in a very similar way to Object  and Stringer in the construction of the JSON.
+		//The difference is that it needs a Java object called "Appendable" like StringBuilder
+
+		StringBuilder write = new StringBuilder();
+		JSONWriter jsonWriter = new JSONWriter(write);
+
+		//We behave now the same way as Stringer
+
+		jsonWriter.object();
+		
+		jsonWriter.key("trueValue").value(true);
+		jsonWriter.key("falseValue").value(false);
+		jsonWriter.key("nullValue").value(null);
+		jsonWriter.key("stringValue").value("hello world!");
+		jsonWriter.key("complexStringValue").value("h\be\tllo w\u1234orld!");
+		jsonWriter.key("intValue").value(42);
+		jsonWriter.key("doubleValue").value(-23.45e67);
+		
+		jsonWriter.endObject();
+		
+		//The resoult should be in the "write" object
+		
+		System.out.println("JSON: " + write.toString());
+		
+		//The difference is that we don't get a JSONObject in this one.
+		
+		
+	}
+```
+```	
+	private static void JSONExampleTokener() {
+
+		//A partir de una String podemos crear un JSONTokener, que lo podemos usar alternativamente para JSONArray,JSONObject
+
+		String string = "this is not a valid JSON string";
+		JSONTokener token = new JSONTokener(string);
+		
+		//Now you can use the token in JSONObject and Array the same way as a String
+
+		JSONObject object = new JSONObject(token);
+		JSONArray array = new JSONArray(token);
+		
+	}
+```	
+<h2>Part 2: Conversion methods</h2>
+<p>We don't need to have a JSON docuemnt to work. This project also admits conversions from other type of files.</p>
+<p>Secondly, we can also convert from JSON to those type of files.</p>
+	
+<h3>Extra: Conversion to JSONArray</h3>
+
+```
+	private static void JSONObjectToArray() {
+		//We start with a JSONObject
+
+		String string = "{\"0\":\"value\",\"1\":5,\"2\":-2.345E68,\"3\":true}";
+
+		JSONObject example = new JSONObject(string);
+		
+		//We need a list of key strings like the reverse operation
+		
+		JSONArray keyStrings = listNumberArray(example.length());
+		
+		//Then we convert to the Array using both elelements
+		
+		JSONArray array = example.toJSONArray(keyStrings);
+		
+		System.out.println("Final JSONArray: " + array);
+	}
+```
+<h3>XML Conversions</h3>
+
+```		
+	private static void XMLToExampleConversion() {
+
+		//We start with a JSONObject
+		
+		String string = "{\"0\":\"value\",\"1\":5,\"2\":-2.345E68,\"3\":true}";
+		JSONObject example = new JSONObject(string);
+
+		//We obtain a String with XML format with toString()
+
+		String output = XML.toString(example);
+		System.out.println("Final XML: " + output);
+	}
+```
+```	
+	private static void XMLFromExampleConversion() {
+
+		//We start with a string with  the XML format
+
+		String string = "<0>value</0><1>5</1><2>-2.345E+68</2><3>true</3>";
+
+		//We obtain a JSONObject with toJSONOBject()
+
+		JSONObject output = XML.toJSONObject(string);
+		
+		System.out.println("Final JSONObject: " + output);
+	}
+```
+<h3>Cookie Conversions</h3>
+
+```
+	private static void CookieToExampleConversion() {
+
+		//We start with a JSONObject
+		//The JSONOBject needs to entries that gives the cookie a name and gives the field "name" a name too.
+		//The Cokkie format doesn't support booleans
+
+		String string = "{\"name\":\"Cookie-Name\",\"value\":\"name\",\"1\":5,\"2\":-2.345E68,\"3\":'true'}";
+		JSONObject example = new JSONObject(string);
+		
+		//We obtain a String with Cookie format with toString()
+
+		String output = Cookie.toString(example);
+		System.out.println("Final Cookie: " + output);
+	}
+```
+```
+	private static void CookieFromExampleConversion() {
+
+		//We start with a string with  the Cookie format
+
+		String string = "Cookie-Name=name;1=5;2=-2.345E%2b68;3=true";
+
+		//We obtain a JSONObject with toJSONOBject()
+
+		JSONObject output = Cookie.toJSONObject(string);
+		System.out.println("Final JSONObject: " + output);
+	}
+```
+
+<h3>HTTP Conversions</h3>
+
+```
+	private static void HTTPToExampleConversion() {
+
+		//We start with a JSONObject
+		//The JSONObject must have the minimun header for a HTTP request or header
+
+		String string = "{\"Method\":\"POST\",\"Request-URI\":'/',\"HTTP-Version\":'HTTP/1.1',\"Value1\":true,\"Value2\":2,\"Value3\":-2.345E68}";
+
+		JSONObject example = new JSONObject(string);
+
+		//We obtain a String with HTTP format with toString()
+
+		String output = HTTP.toString(example);
+		System.out.println("Final HTTP: " + output);
+	}
+```
+```	
+	private static void HTTPFromExampleConversion() {
+
+		//We start with a string with  the HTTP format
+
+		String string = "Final HTTP: POST '/' HTTP/1.1 Value3: -2.345E+68 Value1: true Value2: 2";
+
+		//We obtain a JSONObject with toJSONOBject()
+
+		JSONObject output = HTTP.toJSONObject(string);
+		System.out.println("Final JSONObject: " + output);
+	}
+```
+<h3>CDL Conversions</h3>
+
+```	
+private static void CDLToExampleConversion() {
+
+		//We start with some JSONObjects with the same values in the keys but different values in the "values"
+
+		String string = "{\"0\":\"value\",\"1\":5,\"2\":-2.345E68,\"3\":true}";
+		JSONObject example = new JSONObject(string);
+		
+		String string2 = "{\"0\":\"value2\",\"1\":6,\"2\":-8.345E68,\"3\":false}";
+		JSONObject example2 = new JSONObject(string2);
+		
+		//We need now a JSONArray with those JSONObjects
+
+		JSONArray array = new JSONArray();
+		array.put(example);
+		array.put(example2);
+
+		//We obtain a String with XML format with toString()
+
+		String output = CDL.toString(array);
+		System.out.println("Final CDL: \r\n" + output);
+	}
+```	
+```	
+private static void CDLFromExampleConversion() {
+
+	//We start wtih a String with the CDL format
+
+	String string = "0,1,2,3\n"
+			+ "value,5,-2.345E+68,true\n"
+			+ "value2,6,-8.345E+68,false";
+	
+	//We obtain a JSONArray with toJSONOBject()
+
+	JSONArray output = CDL.toJSONArray(string);
+	System.out.println("Final JSONArray: " + output);
+}
+```
+<h3>Properties Conversions</h3>
+
+```
+	private static Properties PropertyToExampleConversion() {
+
+	//We start with a JSONObject
+
+	String string = "{\"0\":\"value\",\"1\":5,\"2\":-2.345E68,\"3\":true}";
+	JSONObject example = new JSONObject(string);
+
+	//We obtain a String with Properties format with toString()
+
+	Properties output = Property.toProperties(example);
+	System.out.println("Final Properties: " + output);
+
+	return output;
+	}
+```
+```	
+	private static void PropertyFromExampleConversion() {
+
+		//We start with a Properties object
+
+		Properties input = PropertyToExampleConversion();
+
+		//We obtain a JSONObject with toJSONOBject()
+
+		JSONObject output = Property.toJSONObject(input);
+		System.out.println("Final JSONObject: " + output);
+	}
+```
+<h2>List of all examples methods</h2>
+
+```
+	public static void main(String[] args) {
+		//JSONObjectToArray();
+		//JSONExampleArray1();
+		//JSONExampleArray2();
+		//JSONExampleStringer();
+		//JSONExampleObject1();
+		//JSONExampleObject2();
+		//JSONExampleObject3();
+		//JSONExamplWriter();
+		//XMLToExampleConversion();
+		//XMLFromExampleConversion();
+		//CookieToExampleConversion();
+		//CookieFromExampleConversion(); 
+		//HTTPToExampleConversion();
+		//HTTPFromExampleConversion();
+		//CDLToExampleConversion();
+		//CDLFromExampleConversion();
+		//PropertyToExampleConversion();
+		//PropertyFromExampleConversion();
+	}
+```
+

README.md

@@ -1,9 +1,15 @@
+![Json-Java logo](https://github.com/stleary/JSON-java/blob/master/images/JsonJava.png?raw=true)
+
+<sub><sup>image credit: Ismael Pérez Ortiz</sup></sub>
+
+
 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.](https://repo1.maven.org/maven2/org/json/json/20201115/json-20201115.jar)**
+**[Click here if you just want the latest release jar file.](https://search.maven.org/remotecontent?filepath=org/json/json/20210307/json-20210307.jar)**
+
 
 # Overview
 
@@ -36,7 +42,7 @@ The org.json package can be built from the command line, Maven, and Gradle. The
 
 *Build the class files from the package root directory src/main/java*
 ````
-javac org\json\*.java
+javac org/json/*.java
 ````
 
 *Create the jar file in the current directory*

SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please follow the instructions in the ["How are vulnerabilities and exploits handled?"](https://github.com/stleary/JSON-java/wiki/FAQ#how-are-vulnerabilities-and-exploits-handled) section in the FAQ.

src/main/java/org/json/Cookie.java

@@ -109,7 +109,7 @@ public class Cookie {
         // parse the remaining cookie attributes
         while (x.more()) {
             name = unescape(x.nextTo("=;")).trim().toLowerCase(Locale.ROOT);
-            // don't allow a cookies attributes to overwrite it's name or value.
+            // don't allow a cookies attributes to overwrite its name or value.
             if("name".equalsIgnoreCase(name)) {
                 throw new JSONException("Illegal attribute name: 'name'");
             }

src/main/java/org/json/JSONArray.java

@@ -326,7 +326,7 @@ public class JSONArray implements Iterable<Object> {
     public float getFloat(int index) throws JSONException {
         final Object object = this.get(index);
         if(object instanceof Number) {
-            return ((Float)object).floatValue();
+            return ((Number)object).floatValue();
         }
         try {
             return Float.parseFloat(object.toString());
@@ -385,7 +385,7 @@ public class JSONArray implements Iterable<Object> {
 
     /**
      * Get the BigDecimal value associated with an index. If the value is float
-     * or double, the the {@link BigDecimal#BigDecimal(double)} constructor
+     * or double, the {@link BigDecimal#BigDecimal(double)} constructor
      * will be used. See notes on the constructor for conversion issues that
      * may arise.
      *
@@ -792,7 +792,7 @@ public class JSONArray implements Iterable<Object> {
      * 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. If the value
-     * is float or double, the the {@link BigDecimal#BigDecimal(double)}
+     * is float or double, the {@link BigDecimal#BigDecimal(double)}
      * constructor will be used. See notes on the constructor for conversion
      * issues that may arise.
      *
@@ -1157,7 +1157,7 @@ public class JSONArray implements Iterable<Object> {
      *            The Map value.
      * @return this.
      * @throws JSONException
-     *             If the index is negative or if the the value is an invalid
+     *             If the index is negative or if the value is an invalid
      *             number.
      * @throws NullPointerException
      *             If a key in the map is <code>null</code>
@@ -1180,7 +1180,7 @@ public class JSONArray implements Iterable<Object> {
      *            String, or the JSONObject.NULL object.
      * @return this.
      * @throws JSONException
-     *             If the index is negative or if the the value is an invalid
+     *             If the index is negative or if the value is an invalid
      *             number.
      */
     public JSONArray put(int index, Object value) throws JSONException {
@@ -1383,7 +1383,9 @@ public class JSONArray implements Iterable<Object> {
                     return false;
                 }
             } else if (valueThis instanceof Number && valueOther instanceof Number) {
-                return JSONObject.isNumberSimilar((Number)valueThis, (Number)valueOther);
+                if (!JSONObject.isNumberSimilar((Number)valueThis, (Number)valueOther)) {
+                	return false;
+                }
             } else if (!valueThis.equals(valueOther)) {
                 return false;
             }

src/main/java/org/json/JSONObject.java

@@ -128,6 +128,7 @@ public class JSONObject {
          *         null.
          */
         @Override
+        @SuppressWarnings("lgtm[java/unchecked-cast-in-equals]")
         public boolean equals(Object object) {
             return object == null || object == this;
         }
@@ -644,7 +645,7 @@ public class JSONObject {
 
     /**
      * Get the BigDecimal value associated with a key. If the value is float or
-     * double, the the {@link BigDecimal#BigDecimal(double)} constructor will
+     * double, the {@link BigDecimal#BigDecimal(double)} constructor will
      * be used. See notes on the constructor for conversion issues that may
      * arise.
      *
@@ -1159,6 +1160,18 @@ public class JSONObject {
      *          to convert.
      */
     static BigDecimal objectToBigDecimal(Object val, BigDecimal defaultValue) {
+        return objectToBigDecimal(val, defaultValue, true);
+    }
+    
+    /**
+     * @param val value to convert
+     * @param defaultValue default value to return is the conversion doesn't work or is null.
+     * @param exact When <code>true</code>, then {@link Double} and {@link Float} values will be converted exactly.
+     *      When <code>false</code>, they will be converted to {@link String} values before converting to {@link BigDecimal}.
+     * @return BigDecimal conversion of the original value, or the defaultValue if unable
+     *          to convert.
+     */
+    static BigDecimal objectToBigDecimal(Object val, BigDecimal defaultValue, boolean exact) {
         if (NULL.equals(val)) {
             return defaultValue;
         }
@@ -1172,7 +1185,14 @@ public class JSONObject {
             if (!numberIsFinite((Number)val)) {
                 return defaultValue;
             }
-            return new BigDecimal(((Number) val).doubleValue());
+            if (exact) {
+                return new BigDecimal(((Number)val).doubleValue());
+            }else {
+                // use the string constructor so that we maintain "nice" values for doubles and floats
+                // the double constructor will translate doubles to "exact" values instead of the likely
+                // intended representation
+                return new BigDecimal(val.toString());
+            }
         }
         if (val instanceof Long || val instanceof Integer
                 || val instanceof Short || val instanceof Byte){
@@ -1370,9 +1390,21 @@ public class JSONObject {
      *            A key string.
      * @return A JSONObject which is the value.
      */
-    public JSONObject optJSONObject(String key) {
+    public JSONObject optJSONObject(String key) { return this.optJSONObject(key, null); }
+
+    /**
+     * Get an optional JSONObject associated with a key, or the default if there
+     * is no such key or if the value is not a JSONObject.
+     *
+     * @param key
+     *            A key string.
+     * @param defaultValue
+     *            The default.
+     * @return An JSONObject which is the value.
+     */
+    public JSONObject optJSONObject(String key, JSONObject defaultValue) {
         Object object = this.opt(key);
-        return object instanceof JSONObject ? (JSONObject) object : null;
+        return object instanceof JSONObject ? (JSONObject) object : defaultValue;
     }
 
     /**
@@ -1581,7 +1613,7 @@ public class JSONObject {
      * @param annotationClass
      *            annotation to look for
      * @return the {@link Annotation} if the annotation exists on the current method
-     *         or one of it's super class definitions
+     *         or one of its super class definitions
      */
     private static <A extends Annotation> A getAnnotation(final Method m, final Class<A> annotationClass) {
         // if we have invalid data the result is null
@@ -1627,9 +1659,6 @@ public class JSONObject {
      * implementations and interfaces has the annotation. Returns the depth of the
      * annotation in the hierarchy.
      *
-     * @param <A>
-     *            type of the annotation
-     *
      * @param m
      *            method to check
      * @param annotationClass
@@ -2080,7 +2109,9 @@ public class JSONObject {
                         return false;
                     }
                 } else if (valueThis instanceof Number && valueOther instanceof Number) {
-                    return isNumberSimilar((Number)valueThis, (Number)valueOther);
+                    if (!isNumberSimilar((Number)valueThis, (Number)valueOther)) {
+                    	return false;
+                    };
                 } else if (!valueThis.equals(valueOther)) {
                     return false;
                 }
@@ -2123,8 +2154,8 @@ public class JSONObject {
         // BigDecimal should be able to handle all of our number types that we support through
         // documentation. Convert to BigDecimal first, then use the Compare method to
         // decide equality.
-        final BigDecimal lBigDecimal = objectToBigDecimal(l, null);
+        final BigDecimal lBigDecimal = objectToBigDecimal(l, null, false);
-        final BigDecimal rBigDecimal = objectToBigDecimal(r, null);
+        final BigDecimal rBigDecimal = objectToBigDecimal(r, null, false);
         if (lBigDecimal == null || rBigDecimal == null) {
             return false;
         }
@@ -2205,7 +2236,7 @@ public class JSONObject {
             // This will narrow any values to the smallest reasonable Object representation
             // (Integer, Long, or BigInteger)
 
-            // BigInteger down conversion: We use a similar bitLenth compare as
+            // BigInteger down conversion: We use a similar bitLength compare as
             // BigInteger#intValueExact uses. Increases GC, but objects hold
             // only what they need. i.e. Less runtime overhead if the value is
             // long lived.

src/main/java/org/json/JSONPointer.java

@@ -188,7 +188,7 @@ public class JSONPointer {
     }
 
     /**
-     * @see https://tools.ietf.org/html/rfc6901#section-3
+     * @see <a href="https://tools.ietf.org/html/rfc6901#section-3">rfc6901 section 3</a>
      */
     private static String unescape(String token) {
         return token.replace("~1", "/").replace("~0", "~");
@@ -268,7 +268,7 @@ public class JSONPointer {
      * @param token the JSONPointer segment value to be escaped
      * @return the escaped value for the token
      * 
-     * @see https://tools.ietf.org/html/rfc6901#section-3
+     * @see <a href="https://tools.ietf.org/html/rfc6901#section-3">rfc6901 section 3</a>
      */
     private static String escape(String token) {
         return token.replace("~", "~0")

src/main/java/org/json/JSONStringer.java

@@ -50,7 +50,7 @@ import java.io.StringWriter;
  * <p>
  * The first method called must be <code>array</code> or <code>object</code>.
  * There are no methods for adding commas or colons. JSONStringer adds them for
- * you. Objects and arrays can be nested up to 20 levels deep.
+ * you. Objects and arrays can be nested up to 200 levels deep.
  * <p>
  * This can sometimes be easier than using a JSONObject to build a string.
  * @author JSON.org

src/main/java/org/json/XML.java

@@ -532,7 +532,7 @@ public class XML {
             // This will narrow any values to the smallest reasonable Object representation
             // (Integer, Long, or BigInteger)
             
-            // BigInteger down conversion: We use a similar bitLenth compare as
+            // BigInteger down conversion: We use a similar bitLength compare as
             // BigInteger#intValueExact uses. Increases GC, but objects hold
             // only what they need. i.e. Less runtime overhead if the value is
             // long lived.

src/main/java/org/json/XMLParserConfiguration.java

@@ -94,7 +94,7 @@ public class XMLParserConfiguration {
      * 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
+     * @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.
      * @deprecated This constructor has been deprecated in favor of using the new builder
      *      pattern for the configuration.
@@ -109,7 +109,7 @@ public class XMLParserConfiguration {
      * 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
+     * @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.
      * @deprecated This constructor has been deprecated in favor of using the new builder
      *      pattern for the configuration.
@@ -182,7 +182,7 @@ public class XMLParserConfiguration {
      * When parsing the XML into JSON, specifies if values should be kept as strings (<code>true</code>), or if
      * they should try to be guessed into JSON values (numeric, boolean, string)
      * 
-     * @return The {@link #keepStrings} configuration value.
+     * @return The <code>keepStrings</code> configuration value.
      */
     public boolean isKeepStrings() {
         return this.keepStrings;
@@ -193,7 +193,7 @@ public class XMLParserConfiguration {
      * they should try to be guessed into JSON values (numeric, boolean, string)
      * 
      * @param newVal
-     *      new value to use for the {@link #keepStrings} configuration option.
+     *      new value to use for the <code>keepStrings</code> configuration option.
      * 
      * @return The existing configuration will not be modified. A new configuration is returned.
      */
@@ -208,7 +208,7 @@ public class XMLParserConfiguration {
      * been the value "content" but can be changed. Use <code>null</code> to indicate no CDATA
      * processing.
      * 
-     * @return The {@link #cDataTagName} configuration value.
+     * @return The <code>cDataTagName</code> configuration value.
      */
     public String getcDataTagName() {
         return this.cDataTagName;
@@ -220,7 +220,7 @@ public class XMLParserConfiguration {
      * processing.
      * 
      * @param newVal
-     *      new value to use for the {@link #cDataTagName} configuration option.
+     *      new value to use for the <code>cDataTagName</code> configuration option.
      * 
      * @return The existing configuration will not be modified. A new configuration is returned.
      */
@@ -235,7 +235,7 @@ public class XMLParserConfiguration {
      * should be kept as attribute(<code>false</code>), or they should be converted to
      * <code>null</code>(<code>true</code>)
      * 
-     * @return The {@link #convertNilAttributeToNull} configuration value.
+     * @return The <code>convertNilAttributeToNull</code> configuration value.
      */
     public boolean isConvertNilAttributeToNull() {
         return this.convertNilAttributeToNull;
@@ -247,7 +247,7 @@ public class XMLParserConfiguration {
      * <code>null</code>(<code>true</code>)
      * 
      * @param newVal
-     *      new value to use for the {@link #convertNilAttributeToNull} configuration option.
+     *      new value to use for the <code>convertNilAttributeToNull</code> configuration option.
      * 
      * @return The existing configuration will not be modified. A new configuration is returned.
      */
@@ -262,7 +262,7 @@ public class XMLParserConfiguration {
      * will be converted to target type defined to client in this configuration
      * {@code Map<String, XMLXsiTypeConverter<?>>} to parse values with attribute
      * xsi:type="integer" as integer,  xsi:type="string" as string
-     * @return {@link #xsiTypeMap} unmodifiable configuration map.
+     * @return <code>xsiTypeMap</code> unmodifiable configuration map.
      */
     public Map<String, XMLXsiTypeConverter<?>> getXsiTypeMap() {
         return this.xsiTypeMap;

src/test/java/org/json/junit/EnumTest.java

@@ -93,7 +93,7 @@ public class EnumTest {
 
     /**
      * To serialize an enum by its set of allowed values, use getNames()
-     * and the the JSONObject Object with names constructor. 
+     * and the JSONObject Object with names constructor.
      */
     @Test
     public void jsonObjectFromEnumWithNames() {

src/test/java/org/json/junit/JSONArrayTest.java

@@ -87,6 +87,7 @@ public class JSONArrayTest {
     @Test
     public void verifySimilar() {
         final String string1 = "HasSameRef";
+        final String string2 = "HasDifferentRef";
         JSONArray obj1 = new JSONArray()
                 .put("abc")
                 .put(string1)
@@ -102,9 +103,19 @@ public class JSONArrayTest {
                 .put(new String(string1))
                 .put(2);
 
-        assertFalse("Should eval to false", obj1.similar(obj2));
+        JSONArray obj4 = new JSONArray()
+                .put("abc")
+                .put(2.0)
+        		.put(new String(string1));
 
-        assertTrue("Should eval to true", obj1.similar(obj3));
+        JSONArray obj5 = new JSONArray()
+                .put("abc")
+                .put(2.0)
+        		.put(new String(string2));
+        
+        assertFalse("obj1-obj2 Should eval to false", obj1.similar(obj2));
+        assertTrue("obj1-obj3 Should eval to true", obj1.similar(obj3));
+        assertFalse("obj4-obj5 Should eval to false", obj4.similar(obj5));
     }
         
     /**
@@ -364,6 +375,8 @@ public class JSONArrayTest {
                 new Double(23.45e-4).equals(jsonArray.getDouble(5)));
         assertTrue("Array string double",
                 new Double(23.45).equals(jsonArray.getDouble(6)));
+        assertTrue("Array double can be float",
+                new Float(23.45e-4f).equals(jsonArray.getFloat(5)));
         // ints
         assertTrue("Array value int",
                 new Integer(42).equals(jsonArray.getInt(7)));

src/test/java/org/json/junit/JSONObjectTest.java

@@ -100,6 +100,7 @@ public class JSONObjectTest {
     @Test
     public void verifySimilar() {
         final String string1 = "HasSameRef";
+        final String string2 = "HasDifferentRef";
         JSONObject obj1 = new JSONObject()
                 .put("key1", "abc")
                 .put("key2", 2)
@@ -120,12 +121,22 @@ public class JSONObjectTest {
                 .put("key2", 2.0)
                 .put("key3", new String(string1));
 
-        assertFalse("Should eval to false", obj1.similar(obj2));
+        JSONObject obj5 = new JSONObject()
-
+                .put("key1", "abc")
-        assertTrue("Should eval to true", obj1.similar(obj3));
+                .put("key2", 2.0)
-        
+                .put("key3", new String(string2));
-        assertTrue("Should eval to true", obj1.similar(obj4));
         
+        assertFalse("obj1-obj2 Should eval to false", obj1.similar(obj2));
+        assertTrue("obj1-obj3 Should eval to true", obj1.similar(obj3));
+        assertTrue("obj1-obj4 Should eval to true", obj1.similar(obj4));
+        assertFalse("obj1-obj5 Should eval to false", obj1.similar(obj5));
+        // verify that a double and big decimal are "similar"
+        assertTrue("should eval to true",new JSONObject().put("a",1.1d).similar(new JSONObject("{\"a\":1.1}")));
+        // Confirm #618 is fixed (compare should not exit early if similar numbers are found)
+        // Note that this test may not work if the JSONObject map entry order changes
+        JSONObject first = new JSONObject("{\"a\": 1, \"b\": 2, \"c\": 3}");
+        JSONObject second = new JSONObject("{\"a\": 1, \"b\": 2.0, \"c\": 4}");
+        assertFalse("first-second should eval to false", first.similar(second));
     }
     
     @Test
@@ -940,7 +951,7 @@ public class JSONObjectTest {
         assertTrue("-0 Should be a Double!",JSONObject.stringToValue("-0")  instanceof Double);
         assertTrue("-0.0 Should be a Double!",JSONObject.stringToValue("-0.0") instanceof Double);
         assertTrue("'-' Should be a String!",JSONObject.stringToValue("-") instanceof String);
-        assertTrue( "0.2 should be a Double!",
+        assertTrue( "0.2 should be a BigDecimal!",
                 JSONObject.stringToValue( "0.2" ) instanceof BigDecimal );
         assertTrue( "Doubles should be BigDecimal, even when incorrectly converting floats!",
                 JSONObject.stringToValue( new Double( "0.2f" ).toString() ) instanceof BigDecimal );
@@ -1667,7 +1678,7 @@ public class JSONObjectTest {
         // correct implementation (with change of behavior) would be:
         // this.put(key, new Float((Float) value + 1)); 
         // Probably it would be better to deprecate the method and remove some day, while convenient processing the "payload" is not
-        // really in the the scope of a JSON-library (IMHO.)
+        // really in the scope of a JSON-library (IMHO.)
 
     }
 
@@ -2404,8 +2415,8 @@ public class JSONObjectTest {
                 MyEnum.VAL1.equals(jsonObject.optEnum(MyEnum.class, "myKey", MyEnum.VAL1)));
         assertTrue("optJSONArray() should return null ",
                 null==jsonObject.optJSONArray("myKey"));
-        assertTrue("optJSONObject() should return null ",
+        assertTrue("optJSONObject() should return default JSONObject ",
-                null==jsonObject.optJSONObject("myKey"));
+                jsonObject.optJSONObject("myKey", new JSONObject("{\"testKey\":\"testValue\"}")).getString("testKey").equals("testValue"));
         assertTrue("optLong() should return default long",
                 42l == jsonObject.optLong("myKey", 42l));
         assertTrue("optDouble() should return default double",
@@ -2440,8 +2451,8 @@ public class JSONObjectTest {
                  MyEnum.VAL1.equals(jsonObject.optEnum(MyEnum.class, "myKey", MyEnum.VAL1)));
          assertTrue("optJSONArray() should return null ",
                  null==jsonObject.optJSONArray("myKey"));
-         assertTrue("optJSONObject() should return null ",
+         assertTrue("optJSONObject() should return default JSONObject ",
-                 null==jsonObject.optJSONObject("myKey"));
+                jsonObject.optJSONObject("myKey", new JSONObject("{\"testKey\":\"testValue\"}")).getString("testKey").equals("testValue"));
          assertTrue("optLong() should return default long",
                  42l == jsonObject.optLong("myKey", 42l));
          assertTrue("optDouble() should return default double",

src/test/java/org/json/junit/JSONPointerTest.java

@@ -120,7 +120,7 @@ public class JSONPointerTest {
     /**
      * We pass backslashes as-is
      * 
-     * @see https://tools.ietf.org/html/rfc6901#section-3
+     * @see <a href="https://tools.ietf.org/html/rfc6901#section-3">rfc6901 section 3</a>
      */
     @Test
     public void backslashHandling() {
@@ -130,7 +130,7 @@ public class JSONPointerTest {
     /**
      * We pass quotations as-is
      * 
-     * @see https://tools.ietf.org/html/rfc6901#section-3
+     * @see <a href="https://tools.ietf.org/html/rfc6901#section-3">rfc6901 section 3</a>
      */
     @Test
     public void quotationHandling() {

src/test/java/org/json/junit/XMLTest.java

@@ -65,6 +65,7 @@ public class XMLTest {
     @Rule
     public TemporaryFolder testFolder = new TemporaryFolder();
 
+    
     /**
      * JSONObject from a null XML string.
      * Expects a NullPointerException

src/test/java/org/json/junit/data/ExceptionalBean.java

@@ -8,7 +8,7 @@ import java.io.IOException;
 import java.lang.reflect.InvocationTargetException;
 
 /**
- * Object for testing the exception handling in {@link JSONObject#populateMap}.
+ * Object for testing the exception handling in {@link org.json.JSONObject#populateMap}.
  * 
  * @author John Aylward
  */