Update pom.xml

XMLParserConfiguration support for xml to json arrays

.github/workflows/pipeline.yml

@@ -12,7 +12,7 @@ on:
 jobs:
   # old-school build and jar method. No tests run or compiled.
   build-1_6: 
-    runs-on: ubuntu-16.04
+    runs-on: ubuntu-latest
     strategy:
       matrix:
         # build for java 1.6, however don't run any tests
@@ -38,7 +38,7 @@ jobs:
           path: target/org.json.jar
       
   build:
-    runs-on: ubuntu-16.04
+    runs-on: ubuntu-latest
     strategy:
       matrix:
         # build against supported Java LTS versions:

CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at jsonjava060@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contribution Guidelines
+
+Feel free to work on any issue with a #hacktoberfest label.
+
+If you discover an issue you would like to work on, you can add a new issue to the list. If it meets our criteria, a hacktoberfest label will be added.
+
+# Who is allowed to submit pull requests for this project?
+
+Anyone can submit pull requests for code, tests, or documentation.
+
+# How do you decide which pull requests to accept?
+
+* Does it call out a bug that needs to be fixed? If so, it goes to the top of the list.
+* Does it fix a major user inconvenience? These are given high priority as well.
+* Does it align with the specs? If not, it will probably not be accepted. It turns out there are gray areas in the specs. If this is in a gray area, it will likely be given the benefit of the doubt.
+* Does it break the existing behavior of the lib? If so, it will not be accepted, unless it fixes an egregious bug. This is happening less frequently now.
+
+# For more guidance, see these links:
+
+[README.md (includes build instructions)](https://github.com/stleary/JSON-java#readme)
+
+[FAQ - all your questions answered](https://github.com/stleary/JSON-java/wiki/FAQ)

README.md

@@ -30,7 +30,9 @@ The files in this package implement JSON encoders and decoders. The package can
 
 The license includes this restriction: ["The software shall be used for good, not evil."](https://en.wikipedia.org/wiki/Douglas_Crockford#%22Good,_not_Evil%22) If your conscience cannot live with that, then choose a different package.
 
-**If you would like to contribute to this project**
+# If you would like to contribute to this project
+
+For more information on contributions, please see [CONTRIBUTING.md](https://github.com/stleary/JSON-java/blob/master/docs/CONTRIBUTING.md)
 
 Bug fixes, code improvements, and unit test coverage changes are welcome! Because this project is currently in the maintenance phase, the kinds of changes that can be accepted are limited. For more information, please read the [FAQ](https://github.com/stleary/JSON-java/wiki/FAQ).
 
@@ -42,7 +44,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*
@@ -52,7 +54,8 @@ jar cf json-java.jar org/json/*.class
 
 *Compile a program that uses the jar (see example code below)*
 ````
-javac -cp .;json-java.jar Test.java 
+javac -cp .;json-java.jar Test.java (Windows)
+javac -cp .:json-java.jar Test.java (Unix Systems)
 ````
 
 *Test file contents*
@@ -69,7 +72,8 @@ public class Test {
 
 *Execute the Test file*
 ```` 
-java -cp .;json-java.jar Test
+java -cp .;json-java.jar Test (Windows)
+java -cp .:json-java.jar Test (Unix Systems)
 ````
 
 *Expected output*
@@ -94,192 +98,12 @@ gradlew clean build test
 
 # Notes
 
-**Recent directory structure change**
+For more information, please see [NOTES.md](https://github.com/stleary/JSON-java/blob/master/docs/NOTES.md)
-
-_Due to a recent commit - [#515 Merge tests and pom and code](https://github.com/stleary/JSON-java/pull/515) - the structure of the project has changed from a flat directory containing all of the Java files to a directory structure that includes unit tests and several tools used to build the project jar and run the unit tests. If you have difficulty using the new structure, please open an issue so we can work through it._
-
-**Implementation notes**
-
-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 might be
-removed in some future release.
-
-In compliance with RFC8259 page 10 section 9, the parser is more lax with what is valid
-JSON then the Generator. For Example, the tab character (U+0009) is allowed when reading
-JSON Text strings, but when output by the Generator, the 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.
-
-Some notable exceptions that the JSON Parser in this library accepts are:
-* Unquoted keys `{ key: "value" }`
-* Unquoted values `{ "key": value }`
-* Unescaped literals like "tab" in string values `{ "key": "value   with an unescaped tab" }`
-* Numbers out of range for `Double` or `Long` are parsed as strings
-
-Recent pull requests added a new method `putAll` on the JSONArray. The `putAll` method
-works similarly to other `put` methods in that it does not call `JSONObject.wrap` for items
-added. This can lead to inconsistent object representation in JSONArray structures.
-
-For example, code like this will create a mixed JSONArray, some items wrapped, others
-not:
-
-```java
-SomeBean[] myArr = new SomeBean[]{ new SomeBean(1), new SomeBean(2) };
-// these will be wrapped
-JSONArray jArr = new JSONArray(myArr);
-// these will not be wrapped
-jArr.putAll(new SomeBean[]{ new SomeBean(3), new SomeBean(4) });
-```
-
-For structure consistency, it would be recommended that the above code is changed
-to look like 1 of 2 ways.
-
-Option 1:
-```Java
-SomeBean[] myArr = new SomeBean[]{ new SomeBean(1), new SomeBean(2) };
-JSONArray jArr = new JSONArray();
-// these will not be wrapped
-jArr.putAll(myArr);
-// these will not be wrapped
-jArr.putAll(new SomeBean[]{ new SomeBean(3), new SomeBean(4) });
-// our jArr is now consistent.
-```
-
-Option 2:
-```Java
-SomeBean[] myArr = new SomeBean[]{ new SomeBean(1), new SomeBean(2) };
-// these will be wrapped
-JSONArray jArr = new JSONArray(myArr);
-// these will be wrapped
-jArr.putAll(new JSONArray(new SomeBean[]{ new SomeBean(3), new SomeBean(4) }));
-// our jArr is now consistent.
-```
-
-**Unit Test Conventions**
-
-Test filenames should consist of the name of the module being tested, with the suffix "Test". 
-For example, <b>Cookie.java</b> is tested by <b>CookieTest.java</b>.
-
-<b>The fundamental issues with JSON-Java testing are:</b><br>
-* <b>JSONObjects</b> are unordered, making simple string comparison ineffective. 
-* Comparisons via **equals()** is not currently supported. Neither <b>JSONArray</b> nor <b>JSONObject</b> override <b>hashCode()</b> or <b>equals()</b>, so comparison defaults to the <b>Object</b> equals(), which is not useful.
-* Access to the <b>JSONArray</b> and <b>JSONObject</b> internal containers for comparison is not currently available.
-
-<b>General issues with unit testing are:</b><br>
-* Just writing tests to make coverage goals tends to result in poor tests. 
-* Unit tests are a form of documentation - how a given method works is demonstrated by the test. So for a code reviewer or future developer looking at code a good test helps explain how a function is supposed to work according to the original author. This can be difficult if you are not the original developer.
-*   It is difficult to evaluate unit tests in a vacuum. You also need to see the code being tested to understand if a test is good. 
-* Without unit tests, it is hard to feel confident about the quality of the code, especially when fixing bugs or refactoring. Good tests prevent regressions and keep the intent of the code correct.
-* If you have unit test results along with pull requests, the reviewer has an easier time understanding your code and determining if it works as intended.
-
 
 # Files
 
-**JSONObject.java**: The `JSONObject` can parse text from a `String` or a `JSONTokener`
+For more information on files, please see [FILES.md](https://github.com/stleary/JSON-java/blob/master/docs/FILES.md)
-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`. It also can 
-parse text from a `String`, `Number`, `Boolean` or `null` like `"hello"`, `42`, `true`, 
-`null` to produce a simple json object.
-
-**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.
-
 
 # Release history:
 
-JSON-java releases can be found by searching the Maven repository for groupId "org.json"
+For the release history, please see [RELEASES.md](https://github.com/stleary/JSON-java/blob/master/docs/RELEASES.md)
-and artifactId "json". For example:
-[https://search.maven.org/search?q=g:org.json%20AND%20a:json&core=gav](https://search.maven.org/search?q=g:org.json%20AND%20a:json&core=gav)
-
-~~~
-20210307    Recent commits and potentially breaking fix to JSONPointer
-
-20201115    Recent commits and first release after project structure change
-
-20200518    Recent commits and snapshot before project structure change
-
-20190722    Recent commits
-
-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.
-~~~

docs/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contribution Guidelines
+
+Feel free to work on any issue with a #hacktoberfest label.
+
+If you discover an issue you would like to work on, you can add a new issue to the list. If it meets our criteria, a hacktoberfest label will be added.
+
+# Who is allowed to submit pull requests for this project?
+
+Anyone can submit pull requests for code, tests, or documentation.
+
+# How do you decide which pull requests to accept?
+
+* Does it call out a bug that needs to be fixed? If so, it goes to the top of the list.
+* Does it fix a major user inconvenience? These are given high priority as well.
+* Does it align with the specs? If not, it will probably not be accepted. It turns out there are gray areas in the specs. If this is in a gray area, it will likely be given the benefit of the doubt.
+* Does it break the existing behavior of the lib? If so, it will not be accepted, unless it fixes an egregious bug. This is happening less frequently now.
+
+# For more guidance, see these links:
+
+[README.md (includes build instructions)](https://github.com/stleary/JSON-java#readme)
+
+[FAQ - all your questions answered](https://github.com/stleary/JSON-java/wiki/FAQ)

docs/FILES.md

@@ -0,0 +1,62 @@
+# Files
+
+**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`. It also can 
+parse text from a `String`, `Number`, `Boolean` or `null` like `"hello"`, `42`, `true`, 
+`null` to produce a simple json object.
+
+**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.

docs/NOTES.md

@@ -0,0 +1,87 @@
+# Notes
+
+**Recent directory structure change**
+
+_Due to a recent commit - [#515 Merge tests and pom and code](https://github.com/stleary/JSON-java/pull/515) - the structure of the project has changed from a flat directory containing all of the Java files to a directory structure that includes unit tests and several tools used to build the project jar and run the unit tests. If you have difficulty using the new structure, please open an issue so we can work through it._
+
+**Implementation notes**
+
+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 might be
+removed in some future release.
+
+In compliance with RFC8259 page 10 section 9, the parser is more lax with what is valid
+JSON then the Generator. For Example, the tab character (U+0009) is allowed when reading
+JSON Text strings, but when output by the Generator, the 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.
+
+Some notable exceptions that the JSON Parser in this library accepts are:
+* Unquoted keys `{ key: "value" }`
+* Unquoted values `{ "key": value }`
+* Unescaped literals like "tab" in string values `{ "key": "value   with an unescaped tab" }`
+* Numbers out of range for `Double` or `Long` are parsed as strings
+
+Recent pull requests added a new method `putAll` on the JSONArray. The `putAll` method
+works similarly to other `put` methods in that it does not call `JSONObject.wrap` for items
+added. This can lead to inconsistent object representation in JSONArray structures.
+
+For example, code like this will create a mixed JSONArray, some items wrapped, others
+not:
+
+```java
+SomeBean[] myArr = new SomeBean[]{ new SomeBean(1), new SomeBean(2) };
+// these will be wrapped
+JSONArray jArr = new JSONArray(myArr);
+// these will not be wrapped
+jArr.putAll(new SomeBean[]{ new SomeBean(3), new SomeBean(4) });
+```
+
+For structure consistency, it would be recommended that the above code is changed
+to look like 1 of 2 ways.
+
+Option 1:
+```Java
+SomeBean[] myArr = new SomeBean[]{ new SomeBean(1), new SomeBean(2) };
+JSONArray jArr = new JSONArray();
+// these will not be wrapped
+jArr.putAll(myArr);
+// these will not be wrapped
+jArr.putAll(new SomeBean[]{ new SomeBean(3), new SomeBean(4) });
+// our jArr is now consistent.
+```
+
+Option 2:
+```Java
+SomeBean[] myArr = new SomeBean[]{ new SomeBean(1), new SomeBean(2) };
+// these will be wrapped
+JSONArray jArr = new JSONArray(myArr);
+// these will be wrapped
+jArr.putAll(new JSONArray(new SomeBean[]{ new SomeBean(3), new SomeBean(4) }));
+// our jArr is now consistent.
+```
+
+**Unit Test Conventions**
+
+Test filenames should consist of the name of the module being tested, with the suffix "Test". 
+For example, <b>Cookie.java</b> is tested by <b>CookieTest.java</b>.
+
+<b>The fundamental issues with JSON-Java testing are:</b><br>
+* <b>JSONObjects</b> are unordered, making simple string comparison ineffective. 
+* Comparisons via **equals()** is not currently supported. Neither <b>JSONArray</b> nor <b>JSONObject</b> override <b>hashCode()</b> or <b>equals()</b>, so comparison defaults to the <b>Object</b> equals(), which is not useful.
+* Access to the <b>JSONArray</b> and <b>JSONObject</b> internal containers for comparison is not currently available.
+
+<b>General issues with unit testing are:</b><br>
+* Just writing tests to make coverage goals tends to result in poor tests. 
+* Unit tests are a form of documentation - how a given method works is demonstrated by the test. So for a code reviewer or future developer looking at code a good test helps explain how a function is supposed to work according to the original author. This can be difficult if you are not the original developer.
+*   It is difficult to evaluate unit tests in a vacuum. You also need to see the code being tested to understand if a test is good. 
+* Without unit tests, it is hard to feel confident about the quality of the code, especially when fixing bugs or refactoring. Good tests prevent regressions and keep the intent of the code correct.
+* If you have unit test results along with pull requests, the reviewer has an easier time understanding your code and determining if it works as intended.

docs/RELEASES.md

@@ -0,0 +1,40 @@
+# Release history:
+
+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](https://search.maven.org/search?q=g:org.json%20AND%20a:json&core=gav)
+
+~~~
+20211205    Recent commits and some bug fixes for similar()
+
+20210307    Recent commits and potentially breaking fix to JSONPointer
+
+20201115    Recent commits and first release after project structure change
+
+20200518    Recent commits and snapshot before project structure change
+
+20190722    Recent commits
+
+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.
+~~~

docs/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.

pom.xml

@@ -3,7 +3,7 @@
 
     <groupId>org.json</groupId>
     <artifactId>json</artifactId>
-    <version>20210307</version>
+    <version>20211205</version>
     <packaging>bundle</packaging>
 
     <name>JSON in Java</name>

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

@@ -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 {

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

@@ -37,8 +37,10 @@ import java.lang.reflect.Modifier;
 import java.math.BigDecimal;
 import java.math.BigInteger;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.Enumeration;
 import java.util.HashMap;
+import java.util.IdentityHashMap;
 import java.util.Iterator;
 import java.util.Locale;
 import java.util.Map;
@@ -128,6 +130,7 @@ public class JSONObject {
          *         null.
          */
         @Override
+        @SuppressWarnings("lgtm[java/unchecked-cast-in-equals]")
         public boolean equals(Object object) {
             return object == null || object == this;
         }
@@ -364,6 +367,11 @@ public class JSONObject {
         this.populateMap(bean);
     }
 
+    private JSONObject(Object bean, Set<Object> objectsRecord) {
+        this();
+        this.populateMap(bean, objectsRecord);
+    }
+
     /**
      * Construct a JSONObject from an Object, using reflection to find the
      * public members. The resulting JSONObject's keys will be the strings from
@@ -644,7 +652,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.
      *
@@ -1519,6 +1527,10 @@ public class JSONObject {
      *            the bean
      */
     private void populateMap(Object bean) {
+        populateMap(bean, Collections.newSetFromMap(new IdentityHashMap<Object, Boolean>()));
+    }
+
+    private void populateMap(Object bean, Set<Object> objectsRecord) {
         Class<?> klass = bean.getClass();
 
         // If klass is a System class then set includeSuperClass to false.
@@ -1539,7 +1551,19 @@ public class JSONObject {
                     try {
                         final Object result = method.invoke(bean);
                         if (result != null) {
-                            this.map.put(key, wrap(result));
+                            // check cyclic dependency and throw error if needed
+                            // the wrap and populateMap combination method is 
+                            // itself DFS recursive
+                            if (objectsRecord.contains(result)) {
+                                throw recursivelyDefinedObjectException(key);
+                            }
+                            
+                            objectsRecord.add(result);
+
+                            this.map.put(key, wrap(result, objectsRecord));
+
+                            objectsRecord.remove(result);
+
                             // we don't use the result anywhere outside of wrap
                             // if it's a resource we should be sure to close it
                             // after calling toString 
@@ -1612,7 +1636,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
@@ -2235,7 +2259,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.
@@ -2430,6 +2454,10 @@ public class JSONObject {
      * @return The wrapped value
      */
     public static Object wrap(Object object) {
+        return wrap(object, null);
+    }
+
+    private static Object wrap(Object object, Set<Object> objectsRecord) {
         try {
             if (NULL.equals(object)) {
                 return NULL;
@@ -2464,7 +2492,15 @@ public class JSONObject {
                     || object.getClass().getClassLoader() == null) {
                 return object.toString();
             }
+            if (objectsRecord != null) {
+                return new JSONObject(object, objectsRecord);
+            }
+            else {
                 return new JSONObject(object);
+            }
+        }
+        catch (JSONException exception) {
+            throw exception;
         } catch (Exception exception) {
             return null;
         }
@@ -2675,4 +2711,15 @@ public class JSONObject {
                 "JSONObject[" + quote(key) + "] is not a " + valueType + " (" + value + ")."
                 , cause);
     }
+
+    /**
+     * Create a new JSONException in a common format for recursive object definition.
+     * @param key name of the key
+     * @return JSONException that can be thrown.
+     */
+    private static JSONException recursivelyDefinedObjectException(String key) {
+        return new JSONException(
+            "JavaBean object contains recursively defined member variable of key " + quote(key)
+        );
+    }
 }

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

@@ -380,6 +380,16 @@ public class XML {
                     if (x.nextToken() != GT) {
                         throw x.syntaxError("Misshaped tag");
                     }
+                    if (config.getForceList().contains(tagName)) {
+                        // Force the value to be an array
+                        if (nilAttributeFound) {
+                            context.append(tagName, JSONObject.NULL);
+                        } else if (jsonObject.length() > 0) {
+                            context.append(tagName, jsonObject);
+                        } else {
+                            context.put(tagName, new JSONArray());
+                        }
+                    } else {
                         if (nilAttributeFound) {
                             context.accumulate(tagName, JSONObject.NULL);
                         } else if (jsonObject.length() > 0) {
@@ -387,6 +397,7 @@ public class XML {
                         } else {
                             context.accumulate(tagName, "");
                         }
+                    }
                     return false;
 
                 } else if (token == GT) {
@@ -413,6 +424,17 @@ public class XML {
                         } else if (token == LT) {
                             // Nested element
                             if (parse(x, jsonObject, tagName, config)) {
+                                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(tagName, jsonObject.opt(config.getcDataTagName()));
+                                    } else {
+                                        context.append(tagName, jsonObject);
+                                    }
+                                } else {
                                     if (jsonObject.length() == 0) {
                                         context.accumulate(tagName, "");
                                     } else if (jsonObject.length() == 1
@@ -421,6 +443,8 @@ public class XML {
                                     } else {
                                         context.accumulate(tagName, jsonObject);
                                     }
+                                }
+                                
                                 return false;
                             }
                         }
@@ -532,7 +556,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

@@ -25,7 +25,9 @@ SOFTWARE.
 
 import java.util.Collections;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.Map;
+import java.util.Set;
 
 
 /**
@@ -66,6 +68,12 @@ public class XMLParserConfiguration {
      */
     private Map<String, XMLXsiTypeConverter<?>> xsiTypeMap;
 
+    /**
+     * When parsing the XML into JSON, specifies the tags whose values should be converted
+     * to arrays
+     */
+    private Set<String> forceList;
+
     /**
      * Default parser configuration. Does not keep strings (tries to implicitly convert
      * values), and the CDATA Tag Name is "content".
@@ -75,6 +83,7 @@ public class XMLParserConfiguration {
         this.cDataTagName = "content";
         this.convertNilAttributeToNull = false;
         this.xsiTypeMap = Collections.emptyMap();
+        this.forceList = Collections.emptySet();
     }
 
     /**
@@ -151,13 +160,15 @@ 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 
      */
     private XMLParserConfiguration (final boolean keepStrings, final String cDataTagName,
-            final boolean convertNilAttributeToNull, final Map<String, XMLXsiTypeConverter<?>> xsiTypeMap ) {
+            final boolean convertNilAttributeToNull, final Map<String, XMLXsiTypeConverter<?>> xsiTypeMap, final Set<String> forceList ) {
         this.keepStrings = keepStrings;
         this.cDataTagName = cDataTagName;
         this.convertNilAttributeToNull = convertNilAttributeToNull;
         this.xsiTypeMap = Collections.unmodifiableMap(xsiTypeMap);
+        this.forceList = Collections.unmodifiableSet(forceList);
     }
 
     /**
@@ -174,7 +185,8 @@ public class XMLParserConfiguration {
                 this.keepStrings,
                 this.cDataTagName,
                 this.convertNilAttributeToNull,
-                this.xsiTypeMap
+                this.xsiTypeMap,
+                this.forceList
         );
     }
     
@@ -283,4 +295,26 @@ public class XMLParserConfiguration {
         newConfig.xsiTypeMap = Collections.unmodifiableMap(cloneXsiTypeMap);
         return newConfig;
     }
+
+    /**
+     * 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 
+     * @return <code>forceList</code> unmodifiable configuration set.
+     */
+    public Set<String> getForceList() {
+        return this.forceList;
+    }
+
+    /**
+     * 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 
+     * @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) {
+        XMLParserConfiguration newConfig = this.clone();
+        Set<String> cloneForceList = new HashSet<String>(forceList);
+        newConfig.forceList = Collections.unmodifiableSet(cloneForceList);
+        return newConfig;
+    }
 }

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/JSONObjectTest.java

@@ -73,6 +73,8 @@ import org.json.junit.data.MyJsonString;
 import org.json.junit.data.MyNumber;
 import org.json.junit.data.MyNumberContainer;
 import org.json.junit.data.MyPublicClass;
+import org.json.junit.data.RecursiveBean;
+import org.json.junit.data.RecursiveBeanEquals;
 import org.json.junit.data.Singleton;
 import org.json.junit.data.SingletonEnum;
 import org.json.junit.data.WeirdList;
@@ -1678,7 +1680,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.)
 
     }
 
@@ -3218,6 +3220,114 @@ public class JSONObjectTest {
         jsonObject.put(null, new Object());
         fail("Expected an exception");
     }
+    @Test(expected=JSONException.class)
+    public void testSelfRecursiveObject() {
+        // A -> A ...
+        RecursiveBean ObjA = new RecursiveBean("ObjA");
+        ObjA.setRef(ObjA);
+        new JSONObject(ObjA);
+        fail("Expected an exception");
+    }
+    @Test(expected=JSONException.class)
+    public void testLongSelfRecursiveObject() {
+        // B -> A -> A ...
+        RecursiveBean ObjA = new RecursiveBean("ObjA");
+        RecursiveBean ObjB = new RecursiveBean("ObjB");
+        ObjB.setRef(ObjA);
+        ObjA.setRef(ObjA);
+        new JSONObject(ObjB);
+        fail("Expected an exception");
+    }
+    @Test(expected=JSONException.class)
+    public void testSimpleRecursiveObject() {
+        // B -> A -> B ...
+        RecursiveBean ObjA = new RecursiveBean("ObjA");
+        RecursiveBean ObjB = new RecursiveBean("ObjB");
+        ObjB.setRef(ObjA);
+        ObjA.setRef(ObjB);
+        new JSONObject(ObjA);
+        fail("Expected an exception");
+    }
+    @Test(expected=JSONException.class)
+    public void testLongRecursiveObject() {
+        // D -> C -> B -> A -> D ...
+        RecursiveBean ObjA = new RecursiveBean("ObjA");
+        RecursiveBean ObjB = new RecursiveBean("ObjB");
+        RecursiveBean ObjC = new RecursiveBean("ObjC");
+        RecursiveBean ObjD = new RecursiveBean("ObjD");
+        ObjC.setRef(ObjB);
+        ObjB.setRef(ObjA);
+        ObjD.setRef(ObjC);
+        ObjA.setRef(ObjD);
+        new JSONObject(ObjB);
+        fail("Expected an exception");
+    }
+    @Test(expected=JSONException.class)
+    public void testRepeatObjectRecursive() {
+        // C -> B -> A -> D -> C ...
+        //        -> D -> C ...
+        RecursiveBean ObjA = new RecursiveBean("ObjA");
+        RecursiveBean ObjB = new RecursiveBean("ObjB");
+        RecursiveBean ObjC = new RecursiveBean("ObjC");
+        RecursiveBean ObjD = new RecursiveBean("ObjD");
+        ObjC.setRef(ObjB);
+        ObjB.setRef(ObjA);
+        ObjB.setRef2(ObjD);
+        ObjA.setRef(ObjD);
+        ObjD.setRef(ObjC);
+        new JSONObject(ObjC);
+        fail("Expected an exception");
+    }
+    @Test
+    public void testRepeatObjectNotRecursive() {
+        // C -> B -> A
+        //        -> A
+        RecursiveBean ObjA = new RecursiveBean("ObjA");
+        RecursiveBean ObjB = new RecursiveBean("ObjB");
+        RecursiveBean ObjC = new RecursiveBean("ObjC");
+        ObjC.setRef(ObjA);
+        ObjB.setRef(ObjA);
+        ObjB.setRef2(ObjA);
+        new JSONObject(ObjC);
+        new JSONObject(ObjB);
+        new JSONObject(ObjA);
+    }
+    @Test
+    public void testLongRepeatObjectNotRecursive() {
+        // C -> B -> A -> D -> E
+        //        -> D -> E
+        RecursiveBean ObjA = new RecursiveBean("ObjA");
+        RecursiveBean ObjB = new RecursiveBean("ObjB");
+        RecursiveBean ObjC = new RecursiveBean("ObjC");
+        RecursiveBean ObjD = new RecursiveBean("ObjD");
+        RecursiveBean ObjE = new RecursiveBean("ObjE");
+        ObjC.setRef(ObjB);
+        ObjB.setRef(ObjA);
+        ObjB.setRef2(ObjD);
+        ObjA.setRef(ObjD);
+        ObjD.setRef(ObjE);
+        new JSONObject(ObjC);
+        new JSONObject(ObjB);
+        new JSONObject(ObjA);
+        new JSONObject(ObjD);
+        new JSONObject(ObjE);
+    }
+    @Test(expected=JSONException.class)
+    public void testRecursiveEquals() {
+        RecursiveBeanEquals a = new RecursiveBeanEquals("same");
+        a.setRef(a);
+        new JSONObject(a);
+    }
+    @Test
+    public void testNotRecursiveEquals() {
+        RecursiveBeanEquals a = new RecursiveBeanEquals("same");
+        RecursiveBeanEquals b = new RecursiveBeanEquals("same");
+        RecursiveBeanEquals c = new RecursiveBeanEquals("same");
+        a.setRef(b);
+        b.setRef(c);
+        new JSONObject(a);
+    }
+
 
     @Test
     public void testIssue548ObjectWithEmptyJsonArray() {

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

@@ -25,7 +25,6 @@ SOFTWARE.
 */
 
 import static org.junit.Assert.assertEquals;
-import static org.junit.Assert.assertSame;
 import static org.junit.Assert.assertTrue;
 import static org.junit.Assert.fail;
 
@@ -41,6 +40,11 @@ import org.junit.Test;
 public class JSONPointerTest {
 
     private static final JSONObject document;
+    private static final String EXPECTED_COMPLETE_DOCUMENT = "{\"\":0,\" \":7,\"g|h\":4,\"c%d\":2,\"k\\\"l\":6,\"a/b\":1,\"i\\\\j\":5," +
+    		"\"obj\":{\"\":{\"\":\"empty key of an object with an empty key\",\"subKey\":\"Some other value\"}," +
+            "\"other~key\":{\"another/key\":[\"val\"]},\"key\":\"value\"},\"foo\":[\"bar\",\"baz\"],\"e^f\":3," +
+            "\"m~n\":8}";
+
     
     static {
         @SuppressWarnings("resource")
@@ -57,7 +61,7 @@ public class JSONPointerTest {
 
     @Test
     public void emptyPointer() {
-        assertSame(document, query(""));
+        assertTrue(new JSONObject(EXPECTED_COMPLETE_DOCUMENT).similar(query("")));
     }
 
     @SuppressWarnings("unused")
@@ -68,12 +72,12 @@ public class JSONPointerTest {
 
     @Test
     public void objectPropertyQuery() {
-        assertSame(document.get("foo"), query("/foo"));
+        assertEquals("[\"bar\",\"baz\"]", query("/foo").toString());
     }
 
     @Test
     public void arrayIndexQuery() {
-        assertSame(document.getJSONArray("foo").get(0), query("/foo/0"));
+        assertEquals("bar", query("/foo/0"));
     }
 
     @Test(expected = JSONPointerException.class)
@@ -83,38 +87,33 @@ public class JSONPointerTest {
 
     @Test
     public void queryByEmptyKey() {
-        assertSame(document.get(""), query("/"));
+        assertEquals(0, query("/"));
     }
 
     @Test
     public void queryByEmptyKeySubObject() {
-        assertSame(document.getJSONObject("obj").getJSONObject(""), query("/obj/"));
+        assertEquals( "{\"\":\"empty key of an object with an empty key\",\"subKey\":\"Some" +
+                " other value\"}", query("/obj/").toString());
     }
 
     @Test
     public void queryByEmptyKeySubObjectSubOject() {
-        assertSame(
+        assertEquals("empty key of an object with an empty key", query("/obj//"));
-            document.getJSONObject("obj").getJSONObject("").get(""),
-            query("/obj//")
-        );
     }
     
     @Test
     public void queryByEmptyKeySubObjectValue() {
-        assertSame(
+        assertEquals("Some other value", query("/obj//subKey"));
-            document.getJSONObject("obj").getJSONObject("").get("subKey"),
-            query("/obj//subKey")
-        );
     }
 
     @Test
     public void slashEscaping() {
-        assertSame(document.get("a/b"), query("/a~1b"));
+        assertEquals(1, query("/a~1b"));
     }
 
     @Test
     public void tildeEscaping() {
-        assertSame(document.get("m~n"), query("/m~0n"));
+        assertEquals(8, query("/m~0n"));
     }
 
     /**
@@ -124,7 +123,7 @@ public class JSONPointerTest {
      */
     @Test
     public void backslashHandling() {
-        assertSame(document.get("i\\j"), query("/i\\j"));
+        assertEquals(5, query("/i\\j"));
     }
     
     /**
@@ -134,30 +133,30 @@ public class JSONPointerTest {
      */
     @Test
     public void quotationHandling() {
-        assertSame(document.get("k\"l"), query("/k\"l"));
+        assertEquals(6, query("/k\"l"));
     }
    
     @Test
     public void whitespaceKey() {
-        assertSame(document.get(" "), query("/ "));
+        assertEquals(7, query("/ "));
     }
 
     @Test
     public void uriFragmentNotation() {
-        assertSame(document.get("foo"), query("#/foo"));
+        assertEquals("[\"bar\",\"baz\"]", query("#/foo").toString());
     }
 
     @Test
     public void uriFragmentNotationRoot() {
-        assertSame(document, query("#"));
+        assertTrue(new JSONObject(EXPECTED_COMPLETE_DOCUMENT).similar(query("#")));
     }
 
     @Test
     public void uriFragmentPercentHandling() {
-        assertSame(document.get("c%d"), query("#/c%25d"));
+        assertEquals(2, query("#/c%25d"));
-        assertSame(document.get("e^f"), query("#/e%5Ef"));
+        assertEquals(3, query("#/e%5Ef"));
-        assertSame(document.get("g|h"), query("#/g%7Ch"));
+        assertEquals(4, query("#/g%7Ch"));
-        assertSame(document.get("m~n"), query("#/m~0n"));
+        assertEquals(8, query("#/m~0n"));
     }
 
     @SuppressWarnings("unused")
@@ -391,4 +390,28 @@ public class JSONPointerTest {
         obj = jsonArray.optQuery(new JSONPointer("/a/b/c"));
         assertTrue("Expected null", obj == null);
     }
+    
+    /**
+     * When creating a jsonObject we need to parse escaped characters "\\\\"
+     *  --> it's the string representation of  "\\", so when query'ing via the JSONPointer 
+     *  we DON'T escape them
+     *  
+     */
+    @Test
+    public void queryFromJSONObjectUsingPointer0() {
+    	String str = "{"+
+                "\"string\\\\\\\\Key\":\"hello world!\","+
+
+                "\"\\\\\":\"slash test\"," + 
+                "}"+
+                "}";
+            JSONObject jsonObject = new JSONObject(str);
+            //Summary of issue: When a KEY in the jsonObject is "\\\\" --> it's held
+            // as "\\" which means when querying, we need to use "\\"
+            Object twoBackslahObj = jsonObject.optQuery(new JSONPointer("/\\"));
+            assertEquals("slash test", twoBackslahObj);
+
+            Object fourBackslashObj = jsonObject.optQuery(new JSONPointer("/string\\\\Key"));
+            assertEquals("hello world!", fourBackslashObj);
+    }
 }

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

@@ -35,6 +35,8 @@ import java.io.FileWriter;
 import java.io.IOException;
 import java.io.Reader;
 import java.io.StringReader;
+import java.util.HashSet;
+import java.util.Set;
 
 import org.json.JSONArray;
 import org.json.JSONException;
@@ -904,6 +906,171 @@ public class XMLConfigurationTest {
 
     }
 
+    /**
+     * Test forceList parameter
+     */
+    @Test
+    public void testSimpleForceList() {
+        String xmlStr = 
+                "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"+
+                "<addresses>\n"+
+                "   <address>\n"+
+                "      <name>Sherlock Holmes</name>\n"+
+                "   </address>\n"+
+                "</addresses>";
+
+        String expectedStr = 
+                "{\"addresses\":[{\"address\":{\"name\":\"Sherlock Holmes\"}}]}";
+        
+        Set<String> forceList = new HashSet<String>();
+        forceList.add("addresses");
+
+        XMLParserConfiguration config = 
+                new XMLParserConfiguration()
+                        .withForceList(forceList);
+        JSONObject jsonObject = XML.toJSONObject(xmlStr, config);
+        JSONObject expetedJsonObject = new JSONObject(expectedStr);
+
+        Util.compareActualVsExpectedJsonObjects(jsonObject, expetedJsonObject);
+    }
+    @Test
+    public void testLongForceList() {
+        String xmlStr = 
+                "<servers>"+
+                    "<server>"+
+                        "<name>host1</name>"+
+                        "<os>Linux</os>"+
+                        "<interfaces>"+
+                            "<interface>"+
+                                "<name>em0</name>"+
+                                "<ip_address>10.0.0.1</ip_address>"+
+                            "</interface>"+
+                        "</interfaces>"+
+                    "</server>"+
+                "</servers>";
+
+        String expectedStr = 
+                "{"+
+                    "\"servers\": ["+
+                        "{"+
+                            "\"server\": {"+
+                            "\"name\": \"host1\","+
+                            "\"os\": \"Linux\","+
+                            "\"interfaces\": ["+
+                                "{"+
+                                    "\"interface\": {"+
+                                    "\"name\": \"em0\","+
+                                    "\"ip_address\": \"10.0.0.1\""+
+                                    "}}]}}]}";
+        
+        Set<String> forceList = new HashSet<String>();
+        forceList.add("servers");
+        forceList.add("interfaces");
+
+        XMLParserConfiguration config = 
+                new XMLParserConfiguration()
+                        .withForceList(forceList);
+        JSONObject jsonObject = XML.toJSONObject(xmlStr, config);
+        JSONObject expetedJsonObject = new JSONObject(expectedStr);
+
+        Util.compareActualVsExpectedJsonObjects(jsonObject, expetedJsonObject);
+    }
+    @Test
+    public void testMultipleTagForceList() {
+        String xmlStr = 
+                "<addresses>\n"+
+                "   <address>\n"+
+                "      <name>Sherlock Holmes</name>\n"+
+                "      <name>John H. Watson</name>\n"+
+                "   </address>\n"+
+                "</addresses>";
+
+        String expectedStr = 
+                "{"+
+                    "\"addresses\":["+
+                    "{"+
+                        "\"address\":["+
+                            "{"+
+                                "\"name\":["+
+                                "\"Sherlock Holmes\","+
+                                "\"John H. Watson\""+
+                                "]"+
+                            "}"+
+                        "]"+
+                    "}"+
+                    "]"+
+                "}";
+        
+        Set<String> forceList = new HashSet<String>();
+        forceList.add("addresses");
+        forceList.add("address");
+        forceList.add("name");
+
+        XMLParserConfiguration config = 
+                new XMLParserConfiguration()
+                        .withForceList(forceList);
+        JSONObject jsonObject = XML.toJSONObject(xmlStr, config);
+        JSONObject expetedJsonObject = new JSONObject(expectedStr);
+
+        Util.compareActualVsExpectedJsonObjects(jsonObject, expetedJsonObject);
+    }
+    @Test
+    public void testEmptyForceList() {
+        String xmlStr = 
+                "<addresses></addresses>";
+
+        String expectedStr = 
+                "{\"addresses\":[]}";
+        
+        Set<String> forceList = new HashSet<String>();
+        forceList.add("addresses");
+
+        XMLParserConfiguration config = 
+                new XMLParserConfiguration()
+                        .withForceList(forceList);
+        JSONObject jsonObject = XML.toJSONObject(xmlStr, config);
+        JSONObject expetedJsonObject = new JSONObject(expectedStr);
+
+        Util.compareActualVsExpectedJsonObjects(jsonObject, expetedJsonObject);
+    }
+    @Test
+    public void testContentForceList() {
+        String xmlStr = 
+                "<addresses>Baker Street</addresses>";
+
+        String expectedStr = 
+                "{\"addresses\":[\"Baker Street\"]}";
+        
+        Set<String> forceList = new HashSet<String>();
+        forceList.add("addresses");
+
+        XMLParserConfiguration config = 
+                new XMLParserConfiguration()
+                        .withForceList(forceList);
+        JSONObject jsonObject = XML.toJSONObject(xmlStr, config);
+        JSONObject expetedJsonObject = new JSONObject(expectedStr);
+
+        Util.compareActualVsExpectedJsonObjects(jsonObject, expetedJsonObject);
+    }
+    @Test
+    public void testEmptyTagForceList() {
+        String xmlStr = 
+                "<addresses />";
+
+        String expectedStr = 
+                "{\"addresses\":[]}";
+        
+        Set<String> forceList = new HashSet<String>();
+        forceList.add("addresses");
+
+        XMLParserConfiguration config = 
+                new XMLParserConfiguration()
+                        .withForceList(forceList);
+        JSONObject jsonObject = XML.toJSONObject(xmlStr, config);
+        JSONObject expetedJsonObject = new JSONObject(expectedStr);
+
+        Util.compareActualVsExpectedJsonObjects(jsonObject, expetedJsonObject);
+    }
     
     /**
      * Convenience method, given an input string and expected result,

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

@@ -0,0 +1,23 @@
+package org.json.junit.data;
+
+/**
+ * test class for verifying if recursively defined bean can be correctly identified
+ * @author Zetmas
+ *
+ */
+public class RecursiveBean {
+    private String name;
+    private Object reference;
+    private Object reference2;
+    public String getName() { return name; }
+    public Object getRef() {return reference;}
+    public Object getRef2() {return reference2;}
+    public void setRef(Object refObj) {reference = refObj;}
+    public void setRef2(Object refObj) {reference2 = refObj;}
+
+    public RecursiveBean(String name) {
+        this.name = name;
+        reference = null;
+        reference2 = null;
+    }
+}

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

@@ -0,0 +1,33 @@
+package org.json.junit.data;
+
+/** test class for verifying if recursively defined bean can be correctly identified */
+public class RecursiveBeanEquals {
+  private final String name;
+  private Object reference;
+
+  public RecursiveBeanEquals(String name) {
+    this.name = name;
+  }
+
+  public String getName() {
+    return name;
+  }
+
+  public Object getRef() {
+    return reference;
+  }
+
+  public void setRef(Object refObj) {
+    reference = refObj;
+  }
+
+  @Override
+  public boolean equals(Object other) {
+    return other instanceof RecursiveBeanEquals && name.equals(((RecursiveBeanEquals) other).name);
+  }
+
+  @Override
+  public int hashCode() {
+    return name.hashCode();
+  }
+}