document behavior of content keyword

Author: stleary

XMLTest.java

@@ -328,7 +328,7 @@ public void shouldHandleNullNodeValue()
         JSONObject inputJSON = new JSONObject();
         inputJSON.put("nullValue", JSONObject.NULL);
         // This is a possible preferred result
-        String expectedXML = "<nullValue/>";
+        // String expectedXML = "<nullValue/>";
         /**
          * This is the current behavior. JSONObject.NULL is emitted as 
          * the string, "null".
@@ -337,4 +337,89 @@ public void shouldHandleNullNodeValue()
         String resultXML = XML.toString(inputJSON);
         assertEquals(actualXML, resultXML);
     }
-}
+
+    @Test
+    public void contentOperations() {
+        /**
+         * Make sure we understand exactly how the "content" keyword works
+         */
+
+        /**
+         * When a standalone <!CDATA[...]] structure is found while parsing XML into a
+         * JSONObject, the contents are placed in a string value with key="content".
+         */
+        String xmlStr = "<tag1></tag1><![CDATA[if (a < b && a > 0) then return]]><tag2></tag2>";
+        JSONObject jsonObject = XML.toJSONObject(xmlStr);
+        assertTrue("1. 3 items", 3 == jsonObject.length());
+        assertTrue("1. empty tag1", "".equals(jsonObject.get("tag1")));
+        assertTrue("1. empty tag2", "".equals(jsonObject.get("tag2")));
+        assertTrue("1. content found", "if (a < b && a > 0) then return".equals(jsonObject.get("content")));
+
+        // multiple consecutive standalone cdatas are accumulated into an array
+        xmlStr = "<tag1></tag1><![CDATA[if (a < b && a > 0) then return]]><tag2></tag2><![CDATA[here is another cdata]]>";
+        jsonObject = XML.toJSONObject(xmlStr);
+        assertTrue("2. 3 items", 3 == jsonObject.length());
+        assertTrue("2. empty tag1", "".equals(jsonObject.get("tag1")));
+        assertTrue("2. empty tag2", "".equals(jsonObject.get("tag2")));
+        assertTrue("2. content array found", jsonObject.get("content") instanceof JSONArray);
+        JSONArray jsonArray = jsonObject.getJSONArray("content");
+        assertTrue("2. array size", jsonArray.length() == 2);
+        assertTrue("2. content array entry 1", "if (a < b && a > 0) then return".equals(jsonArray.get(0)));
+        assertTrue("2. content array entry 2", "here is another cdata".equals(jsonArray.get(1)));
+
+        /**
+         * text content is accumulated in a "content" inside a local JSONObject.
+         * If there is only one instance, it is saved in the context (a different JSONObject 
+         * from the calling code. and the content element is discarded. 
+         */
+        xmlStr =  "<tag1>value 1</tag1>";
+        jsonObject = XML.toJSONObject(xmlStr);
+        assertTrue("3. 2 items", 1 == jsonObject.length());
+        assertTrue("3. value tag1", "value 1".equals(jsonObject.get("tag1")));
+
+        /**
+         * array-style text content (multiple tags with the same name) is 
+         * accumulated in a local JSONObject with key="content" and value=JSONArray,
+         * saved in the context, and then the local JSONObject is discarded.
+         */
+        xmlStr =  "<tag1>value 1</tag1><tag1>2</tag1><tag1>true</tag1>";
+        jsonObject = XML.toJSONObject(xmlStr);
+        assertTrue("4. 1 item", 1 == jsonObject.length());
+        assertTrue("4. content array found", jsonObject.get("tag1") instanceof JSONArray);
+        jsonArray = jsonObject.getJSONArray("tag1");
+        assertTrue("4. array size", jsonArray.length() == 3);
+        assertTrue("4. content array entry 1", "value 1".equals(jsonArray.get(0)));
+        assertTrue("4. content array entry 2", jsonArray.getInt(1) == 2);
+        assertTrue("4. content array entry 2", jsonArray.getBoolean(2) == true);
+
+        /**
+         * Complex content is accumulated in a "content" field. For example, an element
+         * may contain a mix of child elements and text. Each text segment is 
+         * accumulated to content. 
+         */
+        xmlStr =  "<tag1>val1<tag2/>val2</tag1>";
+        jsonObject = XML.toJSONObject(xmlStr);
+        assertTrue("5. 1 item", 1 == jsonObject.length());
+        assertTrue("5. jsonObject found", jsonObject.get("tag1") instanceof JSONObject);
+        jsonObject = jsonObject.getJSONObject("tag1");
+        assertTrue("5. 2 contained items", 2 == jsonObject.length());
+        assertTrue("5. contained tag", "".equals(jsonObject.get("tag2")));
+        assertTrue("5. contained content jsonArray found", jsonObject.get("content") instanceof JSONArray);
+        jsonArray = jsonObject.getJSONArray("content");
+        assertTrue("5. array size", jsonArray.length() == 2);
+        assertTrue("5. content array entry 1", "val1".equals(jsonArray.get(0)));
+        assertTrue("5. content array entry 2", "val2".equals(jsonArray.get(1)));
+
+        /**
+         * If there is only 1 complex text content, then it is accumulated in a 
+         * "content" field as a string.
+         */
+        xmlStr =  "<tag1>val1<tag2/></tag1>";
+        jsonObject = XML.toJSONObject(xmlStr);
+        assertTrue("6. 1 item", 1 == jsonObject.length());
+        assertTrue("6. jsonObject found", jsonObject.get("tag1") instanceof JSONObject);
+        jsonObject = jsonObject.getJSONObject("tag1");
+        assertTrue("6. contained content found", "val1".equals(jsonObject.get("content")));
+        assertTrue("6. contained tag2", "".equals(jsonObject.get("tag2")));
+    }
+}