fix: amend XMLParserConfiguration.clone() to include the new maxNestingDepth param.

Amend Javadoc for XML and XMLParserConfiguration classes.

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

@@ -98,7 +98,7 @@ public class XML {
     /**
      * Replace special characters with XML escapes:
      *
-     * <pre>{@code 
+     * <pre>{@code
      * &amp; (ampersand) is replaced by &amp;amp;
      * &lt; (less than) is replaced by &amp;lt;
      * &gt; (greater than) is replaced by &amp;gt;
@@ -229,8 +229,12 @@ public class XML {
      *            The JSONObject that will include the new material.
      * @param name
      *            The tag name.
+     * @param config
+     *            The XML parser configuration.
+     * @param currentNestingDepth
+     *            The current nesting depth.
      * @return true if the close tag is processed.
-     * @throws JSONException
+     * @throws JSONException Thrown if any parsing error occurs.
      */
     private static boolean parse(XMLTokener x, JSONObject context, String name, XMLParserConfiguration config, int currentNestingDepth)
             throws JSONException {
@@ -427,7 +431,7 @@ public class XML {
                                         context.accumulate(tagName, jsonObject);
                                     }
                                 }
-                                
+
                                 return false;
                             }
                         }
@@ -491,7 +495,7 @@ public class XML {
         }
         return string;
     }
-    
+
     /**
      * direct copy of {@link JSONObject#stringToNumber(String)} to maintain Android support.
      */
@@ -538,7 +542,7 @@ public class XML {
             // integer representation.
             // This will narrow any values to the smallest reasonable Object representation
             // (Integer, Long, or BigInteger)
-            
+
             // 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
@@ -554,7 +558,7 @@ public class XML {
         }
         throw new NumberFormatException("val ["+val+"] is not a valid number.");
     }
-    
+
     /**
      * direct copy of {@link JSONObject#isDecimalNotation(String)} to maintain Android support.
      */
@@ -572,7 +576,7 @@ public class XML {
      * 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 <pre>{@code 
+     * "content" member. Comments, prologs, DTDs, and <pre>{@code
      * &lt;[ [ ]]>}</pre>
      * are ignored.
      *
@@ -593,7 +597,7 @@ public class XML {
      * 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 <pre>{@code 
+     * "content" member. Comments, prologs, DTDs, and <pre>{@code
      * &lt;[ [ ]]>}</pre>
      * are ignored.
      *
@@ -673,7 +677,7 @@ public class XML {
      * 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 <pre>{@code 
+     * "content" member. Comments, prologs, DTDs, and <pre>{@code
      * &lt;[ [ ]]>}</pre>
      * are ignored.
      *
@@ -699,7 +703,7 @@ public class XML {
      * 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 <pre>{@code 
+     * "content" member. Comments, prologs, DTDs, and <pre>{@code
      * &lt;[ [ ]]>}</pre>
      * are ignored.
      *

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

@@ -39,14 +39,14 @@ public class XMLParserConfiguration {
      * they should try to be guessed into JSON values (numeric, boolean, string)
      */
     private 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.
      */
     private String cDataTagName;
-    
+
     /**
      * When parsing the XML into JSON, specifies if values with attribute xsi:nil="true"
      * should be kept as attribute(<code>false</code>), or they should be converted to
@@ -66,8 +66,7 @@ public class XMLParserConfiguration {
     private Set<String> forceList;
 
     /**
-     * When parsing the XML into JSON, specifies the tags whose values should be converted
+     * The maximum nesting depth when parsing a XML document to JSON.
-     * to arrays
      */
     private int maxNestingDepth = DEFAULT_MAXIMUM_NESTING_DEPTH;
 
@@ -157,15 +156,18 @@ public class XMLParserConfiguration {
      *                                  <code>false</code> to parse values with attribute xsi:nil="true" as {"xsi:nil":true}.
      * @param xsiTypeMap  <code>new HashMap<String, XMLXsiTypeConverter<?>>()</code> to parse values with attribute
      *                   xsi:type="integer" as integer,  xsi:type="string" as string
-     * @param forceList  <code>new HashSet<String>()</code> to parse the provided tags' values as arrays 
+     * @param forceList  <code>new HashSet<String>()</code> to parse the provided tags' values as arrays
+     * @param maxNestingDepth <code>int</code> to limit the nesting depth
      */
     private XMLParserConfiguration (final boolean keepStrings, final String cDataTagName,
-            final boolean convertNilAttributeToNull, final Map<String, XMLXsiTypeConverter<?>> xsiTypeMap, final Set<String> forceList ) {
+            final boolean convertNilAttributeToNull, final Map<String, XMLXsiTypeConverter<?>> xsiTypeMap, final Set<String> forceList,
+            final int maxNestingDepth) {
         this.keepStrings = keepStrings;
         this.cDataTagName = cDataTagName;
         this.convertNilAttributeToNull = convertNilAttributeToNull;
         this.xsiTypeMap = Collections.unmodifiableMap(xsiTypeMap);
         this.forceList = Collections.unmodifiableSet(forceList);
+        this.maxNestingDepth = maxNestingDepth;
     }
 
     /**
@@ -183,14 +185,15 @@ public class XMLParserConfiguration {
                 this.cDataTagName,
                 this.convertNilAttributeToNull,
                 this.xsiTypeMap,
-                this.forceList
+                this.forceList,
+                this.maxNestingDepth
         );
     }
-    
+
     /**
      * 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 <code>keepStrings</code> configuration value.
      */
     public boolean isKeepStrings() {
@@ -200,10 +203,10 @@ 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)
-     * 
+     *
      * @param newVal
      *      new value to use for the <code>keepStrings</code> configuration option.
-     * 
+     *
      * @return The existing configuration will not be modified. A new configuration is returned.
      */
     public XMLParserConfiguration withKeepStrings(final boolean newVal) {
@@ -216,7 +219,7 @@ public class XMLParserConfiguration {
      * 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.
-     * 
+     *
      * @return The <code>cDataTagName</code> configuration value.
      */
     public String getcDataTagName() {
@@ -227,10 +230,10 @@ public class XMLParserConfiguration {
      * 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.
-     * 
+     *
      * @param newVal
      *      new value to use for the <code>cDataTagName</code> configuration option.
-     * 
+     *
      * @return The existing configuration will not be modified. A new configuration is returned.
      */
     public XMLParserConfiguration withcDataTagName(final String newVal) {
@@ -243,7 +246,7 @@ public class XMLParserConfiguration {
      * When parsing the XML into JSON, specifies if values with attribute xsi:nil="true"
      * should be kept as attribute(<code>false</code>), or they should be converted to
      * <code>null</code>(<code>true</code>)
-     * 
+     *
      * @return The <code>convertNilAttributeToNull</code> configuration value.
      */
     public boolean isConvertNilAttributeToNull() {
@@ -254,10 +257,10 @@ public class XMLParserConfiguration {
      * When parsing the XML into JSON, specifies if values with attribute xsi:nil="true"
      * should be kept as attribute(<code>false</code>), or they should be converted to
      * <code>null</code>(<code>true</code>)
-     * 
+     *
      * @param newVal
      *      new value to use for the <code>convertNilAttributeToNull</code> configuration option.
-     * 
+     *
      * @return The existing configuration will not be modified. A new configuration is returned.
      */
     public XMLParserConfiguration withConvertNilAttributeToNull(final boolean newVal) {
@@ -295,7 +298,7 @@ public class XMLParserConfiguration {
 
     /**
      * When parsing the XML into JSON, specifies that tags that will be converted to arrays
-     * in this configuration {@code Set<String>} to parse the provided tags' values as arrays 
+     * in this configuration {@code Set<String>} to parse the provided tags' values as arrays
      * @return <code>forceList</code> unmodifiable configuration set.
      */
     public Set<String> getForceList() {
@@ -304,8 +307,8 @@ public class XMLParserConfiguration {
 
     /**
      * When parsing the XML into JSON, specifies that tags that will be converted to arrays
-     * in this configuration {@code Set<String>} to parse the provided tags' values as arrays 
+     * in this configuration {@code Set<String>} to parse the provided tags' values as arrays
-     * @param forceList  {@code new HashSet<String>()} to parse the provided tags' values as arrays 
+     * @param forceList  {@code new HashSet<String>()} to parse the provided tags' values as arrays
      * @return The existing configuration will not be modified. A new configuration is returned.
      */
     public XMLParserConfiguration withForceList(final Set<String> forceList) {
@@ -327,8 +330,9 @@ public class XMLParserConfiguration {
     /**
      * Defines the maximum nesting depth that the parser will descend before throwing an exception
      * when parsing the XML into JSON. The default max nesting depth is 512, which means the parser
-     * will go as deep as the maximum call stack size allows. Using any negative value as a
+     * will throw a JsonException if the maximum depth is reached.
-     * parameter is equivalent to setting no limit to the nesting depth.
+     * Using any negative value as a parameter is equivalent to setting no limit to the nesting depth,
+     * which means the parses will go as deep as the maximum call stack size allows.
      * @param maxNestingDepth the maximum nesting depth allowed to the XML parser
      * @return The existing configuration will not be modified. A new configuration is returned.
      */