fix bugs and document readme

Author: wsw-stack

README-M3.md

@@ -0,0 +1,19 @@
+# Milestone 3
+
+For the Milestone 3 of SWE262P, the following new functions was added:
+
+```java
+static JSONObject toJSONObject(Reader reader, Function func) 
+```
+
+This function takes in 3 parameters, a `Reader` object which contains some XML input and a `Function` object that includes a function for converting a `String` (expected type of input: a `String`, and is expected to return another `String`), and a `JSONObject` for replacement. And returns a new `JSONObject` object with tag names replaced, or throw an error if the `Reader` object gives an invalid XML.
+
+The new function is placed in the `XML.java` file.
+
+The test cases of the functions are placed under the `org.json.junit.milestone3.tests` package, and to run the test case, run the following command:
+
+`mvn -Dtest=XMLKeyTransformerTest test`
+
+By implementing the code in the original library code, the function is able to complete the task in one-pass, as the function is writing to a new `JSONObject` while parsing the input XML String. However, in milestone 1, the client code is only able to convert the whole XML String to a `JSONObject`, then convert the keys of this `JSONObject` object.
+
+Thus, implementing this function inside the library code is able to reduce the execution time in half (one-pass vs two-pass), and also resulting in optimization of memory usage. 

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

@@ -483,9 +483,17 @@ private static boolean parse(XMLTokener x, JSONObject context, String name, XMLP
         }
     }
 
-    // overwritten method of parse which allows to pass a prefix tag
-    /* Milestone3
-    overwritten new method of parse
+    /**
+     * Compared to the original parse function, this function adds the function (String Convertor) as an input
+     * @param x
+     * @param context
+     * @param name
+     * @param config
+     * @param currentNestingDepth
+     * @param keyTransformer
+     *      The function which takes in a single String parameter, and returns another converted String
+     * @return
+     * @throws JSONException
      */
     private static boolean parseMilestone3(XMLTokener x, JSONObject context, String name, XMLParserConfiguration config, int currentNestingDepth,Function<String, String> keyTransformer)
             throws JSONException {
@@ -604,29 +612,6 @@ private static boolean parseMilestone3(XMLTokener x, JSONObject context, String
                     } else {
                         jsonObject.accumulate(keyTransformer.apply(string), "");
                     }
-                        /*} else if (!nilAttributeFound) {
-                            Object obj = stringToValue((String) token);
-                            if (obj instanceof Boolean) {
-                                jsonObject.accumulate(prefix + string,
-                                        config.isKeepBooleanAsString()
-                                                ? ((String) token)
-                                                : obj);
-                            } else if (obj instanceof Number) {
-                                jsonObject.accumulate(prefix + string,
-                                        config.isKeepNumberAsString()
-                                                ? ((String) token)
-                                                : obj);
-                            } else {
-                                jsonObject.accumulate(prefix + string, stringToValue((String) token));
-                            }
-                        }
-                        token = null;
-                    } else {
-                        jsonObject.accumulate(prefix + string, "");
-                    }
-                         */
-
-
                 } else if (token == SLASH) {
                     // Empty tag <.../>
                     if (x.nextToken() != GT) {
@@ -735,52 +720,6 @@ private static boolean parseMilestone3(XMLTokener x, JSONObject context, String
             }
         }
     }
-                        }
-
-
-                            // Nested element
-                            /*
-                            if (currentNestingDepth == config.getMaxNestingDepth()) {
-                                throw x.syntaxError("Maximum nesting depth of " + config.getMaxNestingDepth() + " reached");
-                            }
-
-                            if (parse(x, jsonObject, tagName, prefix, config, currentNestingDepth + 1)) {
-                                if (config.getForceList().contains(tagName)) {
-                                    // Force the value to be an array
-                                    if (jsonObject.length() == 0) {
-                                        context.put(tagName, new JSONArray());
-                                    } else if (jsonObject.length() == 1
-                                            && jsonObject.opt(config.getcDataTagName()) != null) {
-                                        context.append(prefix + tagName, jsonObject.opt(config.getcDataTagName()));
-                                    } else {
-                                        context.append(prefix + tagName, jsonObject);
-                                    }
-                                } else {
-                                    if (jsonObject.length() == 0) {
-                                        context.accumulate(prefix + tagName, "");
-                                    } else if (jsonObject.length() == 1
-                                            && jsonObject.opt(config.getcDataTagName()) != null) {
-                                        context.accumulate(prefix + tagName, jsonObject.opt(config.getcDataTagName()));
-                                    } else {
-                                        if (!config.shouldTrimWhiteSpace()) {
-                                            removeEmpty(jsonObject, config);
-                                        }
-                                        context.accumulate(prefix + tagName, jsonObject);
-                                    }
-                                }
-
-                                return false;
-                            }
-                        }
-                    }
-                } else {
-                    throw x.syntaxError("Misshaped tag");
-                }
-            }
-        }
-    }
-
-                             */
     /**
      * This method removes any JSON entry which has the key set by XMLParserConfiguration.cDataTagName
      * and contains whitespace as this is caused by whitespace between tags. See test XMLTest.testNestedWithWhitespaceTrimmingDisabled.

src/test/java/org/json/junit/milestone3/tests/XMLKeyTransformerTest.java

@@ -14,7 +14,7 @@
 public class XMLKeyTransformerTest {
     // define some customized functions for testing
     @Test
-    public void keyTransformerSimpleTest() {
+    public void keyTransformerAddPrefixTest() {
         String xml = "<book><title>Title</title><author>John</author></book>";
         Function<String, String> prefixer = key -> "swe262_" + key;
 
@@ -39,37 +39,3 @@ public void nullReaderTest() {
         XML.toJSONObject(null, key -> "x_" + key);
     }
 }
-
-/*
-    @Test
-    public void testXML01() {
-        String xml = "<book><title><content>Old Title</content></title><author>John</author></book>";
-        StringReader reader = new StringReader(xml);
-
-        JSONObject result = XML.toJSONObject(reader, "swe_262p");
-
-        System.out.println(result);
-    }
-
-    @Test
-    public void testXML02() {
-        String xmlString = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"+
-                "<contact>\n"+
-                "  <nick>Crista </nick>\n"+
-                "  <name>Crista Lopes</name>\n" +
-                "  <address>\n" +
-                "    <street>Ave of Nowhere</street>\n" +
-                "    <zipcode>92614</zipcode>\n" +
-                "  </address>\n" +
-                "</contact>";
-
-        try {
-            JSONObject jobj = XML.toJSONObject(new StringReader(xmlString), "swe_262p");
-            System.out.println(jobj);
-        } catch (JSONException e) {
-            System.out.println(e);
-        }
-    }
-}
-*/
-