swingjs/api, javajs/async
[jalview.git] / src / org / json / README.md
1 JSON in Java [package org.json]
2 ===============================
3
4 [![Maven Central](https://img.shields.io/maven-central/v/org.json/json.svg)](https://mvnrepository.com/artifact/org.json/json)
5
6 JSON is a light-weight, language independent, data interchange format.
7 See http://www.JSON.org/
8
9 The files in this package implement JSON encoders/decoders in Java.
10 It also includes the capability to convert between JSON and XML, HTTP
11 headers, Cookies, and CDL.
12
13 This is a reference implementation. There is a large number of JSON packages
14 in Java. Perhaps someday the Java community will standardize on one. Until
15 then, choose carefully.
16
17 The license includes this restriction: "The software shall be used for good,
18 not evil." If your conscience cannot live with that, then choose a different
19 package.
20
21 The package compiles on Java 1.6-1.8.
22
23
24 **JSONObject.java**: The `JSONObject` can parse text from a `String` or a `JSONTokener`
25 to produce a map-like object. The object provides methods for manipulating its
26 contents, and for producing a JSON compliant object serialization.
27
28 **JSONArray.java**: The `JSONArray` can parse text from a String or a `JSONTokener`
29 to produce a vector-like object. The object provides methods for manipulating
30 its contents, and for producing a JSON compliant array serialization.
31
32 **JSONTokener.java**: The `JSONTokener` breaks a text into a sequence of individual
33 tokens. It can be constructed from a `String`, `Reader`, or `InputStream`.
34
35 **JSONException.java**: The `JSONException` is the standard exception type thrown
36 by this package.
37
38 **JSONPointer.java**: Implementation of
39 [JSON Pointer (RFC 6901)](https://tools.ietf.org/html/rfc6901). Supports
40 JSON Pointers both in the form of string representation and URI fragment
41 representation.
42
43 **JSONPropertyIgnore.java**: Annotation class that can be used on Java Bean getter methods.
44 When used on a bean method that would normally be serialized into a `JSONObject`, it
45 overrides the getter-to-key-name logic and forces the property to be excluded from the
46 resulting `JSONObject`.
47
48 **JSONPropertyName.java**: Annotation class that can be used on Java Bean getter methods.
49 When used on a bean method that would normally be serialized into a `JSONObject`, it
50 overrides the getter-to-key-name logic and uses the value of the annotation. The Bean
51 processor will look through the class hierarchy. This means you can use the annotation on
52 a base class or interface and the value of the annotation will be used even if the getter
53 is overridden in a child class.   
54
55 **JSONString.java**: The `JSONString` interface requires a `toJSONString` method,
56 allowing an object to provide its own serialization.
57
58 **JSONStringer.java**: The `JSONStringer` provides a convenient facility for
59 building JSON strings.
60
61 **JSONWriter.java**: The `JSONWriter` provides a convenient facility for building
62 JSON text through a writer.
63
64
65 **CDL.java**: `CDL` provides support for converting between JSON and comma
66 delimited lists.
67
68 **Cookie.java**: `Cookie` provides support for converting between JSON and cookies.
69
70 **CookieList.java**: `CookieList` provides support for converting between JSON and
71 cookie lists.
72
73 **HTTP.java**: `HTTP` provides support for converting between JSON and HTTP headers.
74
75 **HTTPTokener.java**: `HTTPTokener` extends `JSONTokener` for parsing HTTP headers.
76
77 **XML.java**: `XML` provides support for converting between JSON and XML.
78
79 **JSONML.java**: `JSONML` provides support for converting between JSONML and XML.
80
81 **XMLTokener.java**: `XMLTokener` extends `JSONTokener` for parsing XML text.
82
83 Unit tests are maintained in a separate project. Contributing developers can test
84 JSON-java pull requests with the code in this project:
85 https://github.com/stleary/JSON-Java-unit-test
86
87 Numeric types in this package comply with
88 [ECMA-404: The JSON Data Interchange Format](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) and
89 [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc7159#section-6).
90 This package fully supports `Integer`, `Long`, and `Double` Java types. Partial support
91 for `BigInteger` and `BigDecimal` values in `JSONObject` and `JSONArray` objects is provided
92 in the form of `get()`, `opt()`, and `put()` API methods.
93
94 Although 1.6 compatibility is currently supported, it is not a project goal and may be
95 removed in some future release.
96
97 In compliance with RFC7159 page 10 section 9, the parser is more lax with what is valid
98 JSON than the Generator. For Example, the tab character (U+0009) is allowed when reading
99 JSON Text strings, but when output by the Generator, tab is properly converted to \t in
100 the string. Other instances may occur where reading invalid JSON text does not cause an
101 error to be generated. Malformed JSON Texts such as missing end " (quote) on strings or
102 invalid number formats (1.2e6.3) will cause errors as such documents can not be read
103  reliably.
104
105 Release history:
106
107 ~~~
108 20180813    POM change to include Automatic-Module-Name (#431)
109
110 20180130    Recent commits
111
112 20171018    Checkpoint for recent commits.
113
114 20170516    Roll up recent commits.
115
116 20160810    Revert code that was breaking opt*() methods.
117
118 20160807    This release contains a bug in the JSONObject.opt*() and JSONArray.opt*() methods,
119 it is not recommended for use.
120 Java 1.6 compatability fixed, JSONArray.toList() and JSONObject.toMap(),
121 RFC4180 compatibility, JSONPointer, some exception fixes, optional XML type conversion.
122 Contains the latest code as of 7 Aug, 2016
123
124 20160212    Java 1.6 compatibility, OSGi bundle. Contains the latest code as of 12 Feb, 2016.
125
126 20151123    JSONObject and JSONArray initialization with generics. Contains the
127 latest code as of 23 Nov, 2015.
128
129 20150729    Checkpoint for Maven central repository release. Contains the latest code
130 as of 29 July, 2015.
131 ~~~
132
133
134 JSON-java releases can be found by searching the Maven repository for groupId "org.json"
135 and artifactId "json". For example:
136 https://search.maven.org/search?q=g:org.json%20AND%20a:json&core=gav