You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+87-98Lines changed: 87 additions & 98 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,33 +5,41 @@ JSON in Java [package org.json]
5
5
6
6
**[Click here if you just want the latest release jar file.](https://repo1.maven.org/maven2/org/json/json/20200518/json-20200518.jar)**
7
7
8
-
JSON is a light-weight, language independent, data interchange format.
9
-
See http://www.JSON.org/
8
+
# Overview
10
9
11
-
The files in this package implement JSON encoders/decoders in Java.
12
-
It also includes the capability to convert between JSON and XML, HTTP
13
-
headers, Cookies, and CDL.
10
+
[JSON](http://www.JSON.org/) is a light-weight language independent data interchange format.
14
11
15
-
This is a reference implementation. There are a large number of JSON packages
16
-
in Java. Perhaps someday the Java community will standardize on one. Until
17
-
then, choose carefully.
12
+
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.
18
13
19
-
The license includes this restriction: "The software shall be used for good,
20
-
not evil." If your conscience cannot live with that, then choose a different
21
-
package.
14
+
Project goals include:
15
+
* Reliable and consistent results
16
+
* Adherence to the JSON specification
17
+
* Easy to build, use, and include in other projects
18
+
* No external dependencies
19
+
* Fast execution and low memory footprint
20
+
* Maintain backwards compatibility
21
+
* Designed and tested to use on Java versions 1.6 - 1.11
22
22
23
-
The package compiles on Java 1.6-1.8.
23
+
The files in this package implement JSON encoders and decoders. The package can also convert between JSON and XML, HTTP headers, Cookies, and CDL.
24
24
25
-
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.
25
+
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.
26
26
27
+
**If you would like to contribute to this project**
28
+
29
+
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).
30
+
31
+
# Build Instructions
32
+
33
+
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.
34
+
27
35
**Building from the command line**
28
36
29
37
*Build the class files from the package root directory src/main/java*
30
38
````
31
39
javac org\json\*.java
32
40
````
33
41
34
-
*Build the jar file*
42
+
*Create the jar file in the current directory*
35
43
````
36
44
jar cf json-java.jar org/json/*.class
37
45
````
@@ -65,7 +73,67 @@ java -cp .;json-java.jar Test
65
73
````
66
74
67
75
68
-
*You can only run the unit tests with Maven or Gradlew.*
76
+
**Build tools for building the package and executing the unit tests**
77
+
78
+
The test suite can be executed with Maven by running:
79
+
```
80
+
mvn clean test
81
+
```
82
+
83
+
The test suite can be executed with Gradlew by running:
84
+
85
+
```
86
+
gradlew clean build test
87
+
```
88
+
89
+
# Notes
90
+
91
+
**Recent directory structure change**
92
+
93
+
_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._
94
+
95
+
**Implementation notes**
96
+
97
+
Numeric types in this package comply with
98
+
[ECMA-404: The JSON Data Interchange Format](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) and
99
+
[RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259#section-6).
100
+
This package fully supports `Integer`, `Long`, and `Double` Java types. Partial support
101
+
for `BigInteger` and `BigDecimal` values in `JSONObject` and `JSONArray` objects is provided
102
+
in the form of `get()`, `opt()`, and `put()` API methods.
103
+
104
+
Although 1.6 compatibility is currently supported, it is not a project goal and may be
105
+
removed in some future release.
106
+
107
+
In compliance with RFC8259 page 10 section 9, the parser is more lax with what is valid
108
+
JSON than the Generator. For Example, the tab character (U+0009) is allowed when reading
109
+
JSON Text strings, but when output by the Generator, tab is properly converted to \t in
110
+
the string. Other instances may occur where reading invalid JSON text does not cause an
111
+
error to be generated. Malformed JSON Texts such as missing end " (quote) on strings or
112
+
invalid number formats (1.2e6.3) will cause errors as such documents can not be read
113
+
reliably.
114
+
115
+
Some notable exceptions that the JSON Parser in this library accepts are:
116
+
* Unquoted keys `{ key: "value" }`
117
+
* Unquoted values `{ "key": value }`
118
+
* Unescaped literals like "tab" in string values `{ "key": "value with an unescaped tab" }`
119
+
* Numbers out of range for `Double` or `Long` are parsed as strings
120
+
121
+
**Unit Test Conventions**
122
+
123
+
Test filenames should consist of the name of the module being tested, with the suffix "Test".
124
+
For example, <b>Cookie.java</b> is tested by <b>CookieTest.java</b>.
125
+
126
+
<b>The fundamental issues with JSON-Java testing are:</b><br>
127
+
* <b>JSONObjects</b> are unordered, making simple string comparison ineffective.
128
+
* 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.
129
+
* Access to the <b>JSONArray</b> and <b>JSONObject</b> internal containers for comparison is not currently available.
130
+
131
+
<b>General issues with unit testing are:</b><br>
132
+
* Just writing tests to make coverage goals tends to result in poor tests.
133
+
* 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.
134
+
* 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.
135
+
* 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.
136
+
* 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.
69
137
70
138
71
139
# Files
@@ -131,33 +199,12 @@ cookie lists.
131
199
132
200
**XMLTokener.java**: `XMLTokener` extends `JSONTokener` for parsing XML text.
133
201
134
-
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.
135
-
136
-
Numeric types in this package comply with
137
-
[ECMA-404: The JSON Data Interchange Format](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) and
138
-
[RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259#section-6).
139
-
This package fully supports `Integer`, `Long`, and `Double` Java types. Partial support
140
-
for `BigInteger` and `BigDecimal` values in `JSONObject` and `JSONArray` objects is provided
141
-
in the form of `get()`, `opt()`, and `put()` API methods.
142
-
143
-
Although 1.6 compatibility is currently supported, it is not a project goal and may be
144
-
removed in some future release.
145
-
146
-
In compliance with RFC8259 page 10 section 9, the parser is more lax with what is valid
147
-
JSON than the Generator. For Example, the tab character (U+0009) is allowed when reading
148
-
JSON Text strings, but when output by the Generator, tab is properly converted to \t in
149
-
the string. Other instances may occur where reading invalid JSON text does not cause an
150
-
error to be generated. Malformed JSON Texts such as missing end " (quote) on strings or
151
-
invalid number formats (1.2e6.3) will cause errors as such documents can not be read
152
-
reliably.
153
202
154
-
Some notable exceptions that the JSON Parser in this library accepts are:
155
-
* Unquoted keys `{ key: "value" }`
156
-
* Unquoted values `{ "key": value }`
157
-
* Unescaped literals like "tab" in string values `{ "key": "value with an unescaped tab" }`
158
-
* Numbers out of range for `Double` or `Long` are parsed as strings
203
+
# Release history:
159
204
160
-
Release history:
205
+
JSON-java releases can be found by searching the Maven repository for groupId "org.json"
The test suite can be executed with Maven by running:
199
-
```
200
-
mvn clean test
201
-
```
202
-
The test suite can be executed with Gradlew by running:
203
-
```
204
-
gradlew clean build test
205
-
```
206
-
207
-
208
-
209
-
## Conventions
210
-
Test filenames should consist of the name of the module being tested, with the suffix "Test".
211
-
For example, <b>Cookie.java</b> is tested by <b>CookieTest.java</b>.
212
-
213
-
<b>The fundamental issues with JSON-Java testing are:</b><br>
214
-
* <b>JSONObjects</b> are unordered, making simple string comparison ineffective.
215
-
* 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.
216
-
* Access to the <b>JSONArray</b> and <b>JSONObject</b> internal containers for comparison is not currently available.
217
-
218
-
<b>General issues with unit testing are:</b><br>
219
-
* Just writing tests to make coverage goals tends to result in poor tests.
220
-
* 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.
221
-
* 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.
222
-
* 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.
223
-
* 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.
224
-
225
-
226
-
**Caveats:**
227
-
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:
0 commit comments