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