From 879fba3f7f84bc160695abf140e9d8323493638f Mon Sep 17 00:00:00 2001 From: stleary Date: Sat, 25 Jul 2020 12:27:20 -0500 Subject: [PATCH 1/9] rewrite - first commit --- README.md | 178 +++++++++++++++++++++++++----------------------------- 1 file changed, 81 insertions(+), 97 deletions(-) diff --git a/README.md b/README.md index b8c2214ce..727947ed4 100644 --- a/README.md +++ b/README.md @@ -5,25 +5,29 @@ JSON in Java [package org.json] **[Click here if you just want the latest release jar file.](https://repo1.maven.org/maven2/org/json/json/20200518/json-20200518.jar)** -JSON is a light-weight, language independent, data interchange format. -See http://www.JSON.org/ +# Overview -The files in this package implement JSON encoders/decoders in Java. -It also includes the capability to convert between JSON and XML, HTTP -headers, Cookies, and CDL. +[JSON](http://www.JSON.org/) is a light-weight, language independent, data interchange format. -This is a reference implementation. There are a large number of JSON packages -in Java. Perhaps someday the Java community will standardize on one. Until -then, choose carefully. +The JSON-Java package is a reference implementation that demonstrates how to parse JSON documents into Java objects, and generate new JSON documents from the Java classes. -The license includes this restriction: "The software shall be used for good, -not evil." If your conscience cannot live with that, then choose a different -package. +Project goals include: +* Reliable and consistent results +* Adhere to the JSON specification +* Easy to build, use, and include in other projects +* No external dependencies +* Fast execution, low memory footprint +* Maintain backwards compatibility +* Designed and tested to use on Java 1.6 - 1.11 -The package compiles on Java 1.6-1.8. +The files in this package implement JSON encoders and decoders. The package can also convert between JSON and XML, HTTP headers, Cookies, and CDL. -Recently [#515 Merge tests and pom and code](https://github.com/stleary/JSON-java/pull/515), the structure of the project changed from a flat directory containing all of the Java files to a directory structure that includes unit tests and several build tools 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. +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. +# Build Instructions + +The org.json package can be built from the command line, Maven, and Gradle. The unit tests can be executed from Maven, Gradle, or individually in an IDE e.g. Eclipse. + **Building from the command line** *Build the class files from the package root directory src/main/java* @@ -31,7 +35,7 @@ Recently [#515 Merge tests and pom and code](https://github.com/stleary/JSON-jav javac org\json\*.java ```` -*Build the jar file* +*Create the jar file in the current directory* ```` jar cf json-java.jar org/json/*.class ```` @@ -66,6 +70,65 @@ java -cp .;json-java.jar Test *You can only run the unit tests with Maven or Gradlew.* +# Unit tests +The test suite can be executed with Maven by running: +``` +mvn clean test +``` +The test suite can be executed with Gradlew by running: +``` +gradlew clean build test +``` + + + + + +# 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 may be +removed in some future release. + +In compliance with RFC8259 page 10 section 9, the parser is more lax with what is valid +JSON than the Generator. For Example, the tab character (U+0009) is allowed when reading +JSON Text strings, but when output by the Generator, 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 + +**Unit Test Conventions** +Test filenames should consist of the name of the module being tested, with the suffix "Test". +For example, Cookie.java is tested by CookieTest.java. + +The fundamental issues with JSON-Java testing are:
+* JSONObjects are unordered, making simple string comparison ineffective. +* Comparisons via **equals()** is not currently supported. Neither JSONArray nor JSONObject override hashCode() or equals(), so comparison defaults to the Object equals(), which is not useful. +* Access to the JSONArray and JSONObject internal containers for comparison is not currently available. + +General issues with unit testing are:
+* Just writing tests to make coverage goals tends to result in poor tests. +* Unit tests are a form of documentation - how a given method actually 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 prevents regressions and keeps 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 the it works as intended. # Files @@ -131,33 +194,12 @@ cookie lists. **XMLTokener.java**: `XMLTokener` extends `JSONTokener` for parsing XML text. -Unit tests are now included in the project, but require Java 1.8 at the present time. This will be fixed in a forthcoming commit. - -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 may be -removed in some future release. -In compliance with RFC8259 page 10 section 9, the parser is more lax with what is valid -JSON than the Generator. For Example, the tab character (U+0009) is allowed when reading -JSON Text strings, but when output by the Generator, 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 +# Release history: -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 ~~~ 20200518 Recent commits and snapshot before project structure change @@ -190,62 +232,4 @@ as of 29 July, 2015. ~~~ -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 - -# Unit tests -The test suite can be executed with Maven by running: -``` -mvn clean test -``` -The test suite can be executed with Gradlew by running: -``` -gradlew clean build test -``` - - - -## Conventions -Test filenames should consist of the name of the module being tested, with the suffix "Test". -For example, Cookie.java is tested by CookieTest.java. - -The fundamental issues with JSON-Java testing are:
-* JSONObjects are unordered, making simple string comparison ineffective. -* Comparisons via **equals()** is not currently supported. Neither JSONArray nor JSONObject override hashCode() or equals(), so comparison defaults to the Object equals(), which is not useful. -* Access to the JSONArray and JSONObject internal containers for comparison is not currently available. - -General issues with unit testing are:
-* Just writing tests to make coverage goals tends to result in poor tests. -* Unit tests are a form of documentation - how a given method actually 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 prevents regressions and keeps 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 the it works as intended. - - -**Caveats:** -JSON-Java is Java 1.6-compatible, but JSON-Java-unit-tests requires Java 1.8. If you see this error when building JSON-Java-unit-test, make sure you have 1.8 installed, on your path, and set in JAVA_HOME: -``` -Execution failed for task ':compileJava'. -> invalid flag: -parameters -``` - - -| Resource files used in test | -| ------------- | -| EnumTest.java | -| MyBean.java | -| MyBigNumberBean.java | -| MyEnum.java | -| MyEnumClass.java | -| MyEnumField.java | -| MyJsonString.java | -| MyPublicClass.java | -| PropertyTest.java | -| JunitTestSuite.java | -| StringsResourceBundle.java | -| TestRunner.java | -| Util.java | - - From 26cd17687f449aea2a4731c67f008b7baec07495 Mon Sep 17 00:00:00 2001 From: Sean Leary Date: Sat, 25 Jul 2020 12:31:02 -0500 Subject: [PATCH 2/9] Update README.md --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 727947ed4..11088d325 100644 --- a/README.md +++ b/README.md @@ -9,16 +9,16 @@ JSON in Java [package org.json] [JSON](http://www.JSON.org/) is a light-weight, language independent, data interchange format. -The JSON-Java package is a reference implementation that demonstrates how to parse JSON documents into Java objects, and generate new JSON documents from the Java classes. +The JSON-Java package is a reference implementation that demonstrates how to parse JSON documents into Java objects and how to generate new JSON documents from the Java classes. Project goals include: * Reliable and consistent results -* Adhere to the JSON specification +* Adherence to the JSON specification * Easy to build, use, and include in other projects * No external dependencies -* Fast execution, low memory footprint +* Fast execution and low memory footprint * Maintain backwards compatibility -* Designed and tested to use on Java 1.6 - 1.11 +* Designed and tested to use on Java versions 1.6 - 1.11 The files in this package implement JSON encoders and decoders. The package can also convert between JSON and XML, HTTP headers, Cookies, and CDL. From 46fe58e912db4d34caac0e961eb56549c056d5dc Mon Sep 17 00:00:00 2001 From: Sean Leary Date: Sat, 25 Jul 2020 12:31:20 -0500 Subject: [PATCH 3/9] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 11088d325..b498683be 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ JSON in Java [package org.json] # Overview -[JSON](http://www.JSON.org/) is a light-weight, language independent, data interchange format. +[JSON](http://www.JSON.org/) is a light-weight language independent data interchange format. The JSON-Java package is a reference implementation that demonstrates how to parse JSON documents into Java objects and how to generate new JSON documents from the Java classes. From 0de8d0d2e0316c416cca049e948a23ddebdc0490 Mon Sep 17 00:00:00 2001 From: Sean Leary Date: Sat, 25 Jul 2020 12:34:01 -0500 Subject: [PATCH 4/9] Update README.md --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index b498683be..58c382e46 100644 --- a/README.md +++ b/README.md @@ -69,21 +69,19 @@ java -cp .;json-java.jar Test ```` -*You can only run the unit tests with Maven or Gradlew.* -# Unit tests +**Unit tests** + The test suite can be executed with Maven by running: ``` mvn clean test ``` + The test suite can be executed with Gradlew by running: + ``` gradlew clean build test ``` - - - - # Notes **Recent directory structure change** From 8f0c3b0bf8786a440b80076dddac6f4c11fa7680 Mon Sep 17 00:00:00 2001 From: Sean Leary Date: Sat, 25 Jul 2020 12:35:12 -0500 Subject: [PATCH 5/9] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 58c382e46..272a0392e 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ java -cp .;json-java.jar Test ```` -**Unit tests** +**Build tools for building the package and executing the unit tests** The test suite can be executed with Maven by running: ``` From 896674ae36905b249ad760dce506448a6d087903 Mon Sep 17 00:00:00 2001 From: Sean Leary Date: Sat, 25 Jul 2020 12:35:58 -0500 Subject: [PATCH 6/9] Update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 272a0392e..eacf04b1f 100644 --- a/README.md +++ b/README.md @@ -85,9 +85,11 @@ gradlew clean build test # 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). From 650f52501ac9f8118022fe37e2873aa95da90c1e Mon Sep 17 00:00:00 2001 From: Sean Leary Date: Sat, 25 Jul 2020 12:36:53 -0500 Subject: [PATCH 7/9] Update README.md --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index eacf04b1f..09f242023 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,7 @@ Some notable exceptions that the JSON Parser in this library accepts are: * Numbers out of range for `Double` or `Long` are parsed as strings **Unit Test Conventions** + Test filenames should consist of the name of the module being tested, with the suffix "Test". For example, Cookie.java is tested by CookieTest.java. @@ -199,7 +200,7 @@ cookie lists. 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](https://search.maven.org/search?q=g:org.json%20AND%20a:json&core=gav) ~~~ 20200518 Recent commits and snapshot before project structure change From db2d1714def042b931c624da81fae529da03e21f Mon Sep 17 00:00:00 2001 From: Sean Leary Date: Sat, 25 Jul 2020 12:40:41 -0500 Subject: [PATCH 8/9] Update README.md --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 09f242023..1262a301e 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,10 @@ 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** + +Bug fixes, code improvements, and unit test coverage changes are welcome! Because this project is currrently in 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) + # Build Instructions The org.json package can be built from the command line, Maven, and Gradle. The unit tests can be executed from Maven, Gradle, or individually in an IDE e.g. Eclipse. From 555f712a8c838fc0cf72d97458839778b412d7de Mon Sep 17 00:00:00 2001 From: Sean Leary Date: Sat, 25 Jul 2020 12:41:03 -0500 Subject: [PATCH 9/9] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1262a301e..237df9f1a 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ The license includes this restriction: ["The software shall be used for good, no **If you would like to contribute to this project** -Bug fixes, code improvements, and unit test coverage changes are welcome! Because this project is currrently in 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) +Bug fixes, code improvements, and unit test coverage changes are welcome! Because this project is currrently in 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). # Build Instructions