Mirrors/json-simple
1
0
Fork 0
mirror of https://github.com/fangyidong/json-simple.git synced 2025-12-06 15:30:54 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

Migrating wiki contents from Google Code

Browse Source
This commit is contained in:
Google Code Exporter
2015-04-12 20:36:57 -04:00
commit 80aafe3541
13 changed files with 1010 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
BuildWithAnt.md Normal file
View File

@@ -0,0 +1,13 @@
The default target of [build.xml](http://code.google.com/p/json-simple/source/browse/trunk/build.xml) is to compile Java files and package classes into the final jar file in directory lib:
```
ant
```
You can also perform the JUnit testing by typing:
```
ant -f test.xml
```
You will find the results from TEST-

1
BuildWithEclipse.md Normal file
View File

@@ -0,0 +1 @@
Eclipse project files .project and .classpath locate in the top directory of the JSON.simple source tree. You can import the project from Eclipse. Please note that you need to add the JUNIT library to the CLASSPATH.

0
ChangeLog.md Normal file
View File

28
ComplianceTesting.md Normal file
View File

@@ -0,0 +1,28 @@
#### Introduction ####
JSON.simple uses [json-test-suite](http://code.google.com/p/json-test-suite/) to do compliance testing. Please follow [The mapping between JSON and Java](MappingBetweenJSONAndJavaEntities.md) to get the result compliant to JSON spec. Please note that interface JSONAware and JSONStreamAware is to provide the flexibility and freedom to the user so that he can render the result in any way and make any extensions (such as comments that are not supported by JSON spec), so the user should know what he's doing when he implements these interfaces.
#### Steps ####
1. Download the [latest json-test-suite package](http://code.google.com/p/json-test-suite/downloads/list) from the home page of json-test-suite
1. Unzip and run the following command in the directory of the package:
```
ant -f test.xml compliance
```
1. You may need to wait for a few minutes and then check the results from the following files:
```
TEST-org.json.simple.compliance.EncoderTest.txt
TEST-org.json.simple.compliance.DecoderTest.txt
```
#### Results ####
Both of the encoder and decoder have passed tens of thousands randomly generated samples. No errors found so far. In real world applications, JSON.simple has been used in [quite a few projects](http://code.google.com/p/json-simple/#JSON.simple_in_Projects) in the past years.
| **Module** | **Result** |
|:-----------|:-----------|
| Encoder | 100,000+ samples passed, no errors found. |
| Streaming Encoder | 100,000+ samples passed, no errors found. |
| Decoder | 100,000+ samples passed, no errors found. |
| Decoder with SAX-like content handler | 100,000+ samples passed, no errors found. |
#### How does it work? ####
TBD

377
DecodingExamples.md Normal file
View File

@@ -0,0 +1,377 @@
#### Example 1 - Convenient way: Use JSONValue ####
```
System.out.println("=======decode=======");
String s="[0,{\"1\":{\"2\":{\"3\":{\"4\":[5,{\"6\":7}]}}}}]";
Object obj=JSONValue.parse(s);
JSONArray array=(JSONArray)obj;
System.out.println("======the 2nd element of array======");
System.out.println(array.get(1));
System.out.println();
JSONObject obj2=(JSONObject)array.get(1);
System.out.println("======field \"1\"==========");
System.out.println(obj2.get("1"));
s="{}";
obj=JSONValue.parse(s);
System.out.println(obj);
s="[5,]";
obj=JSONValue.parse(s);
System.out.println(obj);
s="[5,,2]";
obj=JSONValue.parse(s);
System.out.println(obj);
```
JSONObject is a java.util.Map and JSONArray is a java.util.List, so you can access them with standard operations of Map or List. Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information on entity mapping while parsing.
#### Example 2 - Faster way: Reuse instance of JSONParser ####
```
JSONParser parser=new JSONParser();
System.out.println("=======decode=======");
String s="[0,{\"1\":{\"2\":{\"3\":{\"4\":[5,{\"6\":7}]}}}}]";
Object obj=parser.parse(s);
JSONArray array=(JSONArray)obj;
System.out.println("======the 2nd element of array======");
System.out.println(array.get(1));
System.out.println();
JSONObject obj2=(JSONObject)array.get(1);
System.out.println("======field \"1\"==========");
System.out.println(obj2.get("1"));
s="{}";
obj=parser.parse(s);
System.out.println(obj);
s="[5,]";
obj=parser.parse(s);
System.out.println(obj);
s="[5,,2]";
obj=parser.parse(s);
System.out.println(obj);
```
JSONObject is a java.util.Map and JSONArray is a java.util.List, so you can access them
with standard operations of Map or List. Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information on entity mapping while parsing.
#### Example 3 - Exception handling ####
```
String jsonText = "[[null, 123.45, \"a\\tb c\"]}, true";
JSONParser parser = new JSONParser();
try{
parser.parse(jsonText);
}
catch(ParseException pe){
System.out.println("position: " + pe.getPosition());
System.out.println(pe);
}
```
Result:
```
position: 25
Unexpected token RIGHT BRACE(}) at position 25.
```
Please refer [ParseException.java](http://code.google.com/p/json-simple/source/browse/trunk/src/org/json/simple/parser/ParseException.java) for more information.
#### Example 4 - Container factory ####
You can use [ContainerFactory](http://code.google.com/p/json-simple/source/browse/trunk/src/org/json/simple/parser/ContainerFactory.java) to create containers for parsed JSON objects and JSON arrays:
```
String jsonText = "{\"first\": 123, \"second\": [4, 5, 6], \"third\": 789}";
JSONParser parser = new JSONParser();
ContainerFactory containerFactory = new ContainerFactory(){
public List creatArrayContainer() {
return new LinkedList();
}
public Map createObjectContainer() {
return new LinkedHashMap();
}
};
try{
Map json = (Map)parser.parse(jsonText, containerFactory);
Iterator iter = json.entrySet().iterator();
System.out.println("==iterate result==");
while(iter.hasNext()){
Map.Entry entry = (Map.Entry)iter.next();
System.out.println(entry.getKey() + "=>" + entry.getValue());
}
System.out.println("==toJSONString()==");
System.out.println(JSONValue.toJSONString(json));
}
catch(ParseException pe){
System.out.println(pe);
}
```
Result:
```
==iterate result==
first=>123
second=>[4, 5, 6]
third=>789
==toJSONString()==
{"first":123,"second":[4,5,6],"third":789}
```
If you don't specify a container factory, org.json.simple.JSONObject is used for a Map and org.json.simple.JSONArray is used for a List. Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information on entity mapping while parsing.
#### Example 5 - Stoppable SAX-like content handler ####
JSON.simple introduces a simplified and stoppable SAX-like content handler to process JSON text stream. The user can pause at any point of the logical input stream, processing other logic, then resume parsing if needed, or abort parsing if he gets the desired result, without having to wait for the whole input stream to finish. Then we have a very fast parser without sacrificing the flexibility. Here's an example of finding values of any object entry that matches a desired key:
KeyFinder.java:
```
class KeyFinder implements ContentHandler{
private Object value;
private boolean found = false;
private boolean end = false;
private String key;
private String matchKey;
public void setMatchKey(String matchKey){
this.matchKey = matchKey;
}
public Object getValue(){
return value;
}
public boolean isEnd(){
return end;
}
public void setFound(boolean found){
this.found = found;
}
public boolean isFound(){
return found;
}
public void startJSON() throws ParseException, IOException {
found = false;
end = false;
}
public void endJSON() throws ParseException, IOException {
end = true;
}
public boolean primitive(Object value) throws ParseException, IOException {
if(key != null){
if(key.equals(matchKey)){
found = true;
this.value = value;
key = null;
return false;
}
}
return true;
}
public boolean startArray() throws ParseException, IOException {
return true;
}
public boolean startObject() throws ParseException, IOException {
return true;
}
public boolean startObjectEntry(String key) throws ParseException, IOException {
this.key = key;
return true;
}
public boolean endArray() throws ParseException, IOException {
return false;
}
public boolean endObject() throws ParseException, IOException {
return true;
}
public boolean endObjectEntry() throws ParseException, IOException {
return true;
}
}
```
Main logic:
```
String jsonText = "{\"first\": 123, \"second\": [{\"k1\":{\"id\":\"id1\"}}, 4, 5, 6, {\"id\": 123}], \"third\": 789, \"id\": null}";
JSONParser parser = new JSONParser();
KeyFinder finder = new KeyFinder();
finder.setMatchKey("id");
try{
while(!finder.isEnd()){
parser.parse(jsonText, finder, true);
if(finder.isFound()){
finder.setFound(false);
System.out.println("found id:");
System.out.println(finder.getValue());
}
}
}
catch(ParseException pe){
pe.printStackTrace();
}
```
Result:
```
found id:
id1
found id:
123
found id:
null
```
Please refer [ContentHandler.java](http://code.google.com/p/json-simple/source/browse/trunk/src/org/json/simple/parser/ContentHandler.java) for more information.
#### Example 6 - Build whole object graph on top of SAX-like content handler ####
Please note that JSON.simple has provided the build in functionality to do the same work. Please refer above examples for more information. Here is just an example to show how to use the SAX-like interface in a slightly more complex scenario.
Transformer.java:
```
class Transformer implements ContentHandler{
private Stack valueStack;
public Object getResult(){
if(valueStack == null || valueStack.size() == 0)
return null;
return valueStack.peek();
}
public boolean endArray () throws ParseException, IOException {
trackBack();
return true;
}
public void endJSON () throws ParseException, IOException {}
public boolean endObject () throws ParseException, IOException {
trackBack();
return true;
}
public boolean endObjectEntry () throws ParseException, IOException {
Object value = valueStack.pop();
Object key = valueStack.pop();
Map parent = (Map)valueStack.peek();
parent.put(key, value);
return true;
}
private void trackBack(){
if(valueStack.size() > 1){
Object value = valueStack.pop();
Object prev = valueStack.peek();
if(prev instanceof String){
valueStack.push(value);
}
}
}
private void consumeValue(Object value){
if(valueStack.size() == 0)
valueStack.push(value);
else{
Object prev = valueStack.peek();
if(prev instanceof List){
List array = (List)prev;
array.add(value);
}
else{
valueStack.push(value);
}
}
}
public boolean primitive (Object value) throws ParseException, IOException {
consumeValue(value);
return true;
}
public boolean startArray () throws ParseException, IOException {
List array = new JSONArray();
consumeValue(array);
valueStack.push(array);
return true;
}
public void startJSON () throws ParseException, IOException {
valueStack = new Stack();
}
public boolean startObject () throws ParseException, IOException {
Map object = new JSONObject();
consumeValue(object);
valueStack.push(object);
return true;
}
public boolean startObjectEntry (String key) throws ParseException, IOException {
valueStack.push(key);
return true;
}
}
```
Main logic:
```
String jsonString = <Input JSON text>;
Object value = null;
JSONParser parser = new JSONParser();
Transformer transformer = new Transformer();
parser.parse(jsonString, transformer);
value = transformer.getResult();
```
The result is similar to one return from the following code:
```
String jsonString = <Input JSON text>;
Object value = null;
JSONParser parser = new JSONParser();
value = parser.parse(jsonString);
```
#### Notes - Multithreading and extensions ####
JSONParser is NOT thread-safe. And please note that JSON string such as `[5,,,2]` is accepted by the parser and is treated as `[5,2]`. This doesn't violate the [JSON specification](http://www.ietf.org/rfc/rfc4627.txt), and it increases the error toleration of the input data. Some JSON grammar checker may need a 'strict' mode. Considering adding this feature.
Since it's a bit controversial on the extension of the parser (see comments of this wiki page), I'd like to make some clarifications on this topic here.
Some users may concern about exchanging important data, say medical information or financial data, between applications. I think you need to make sure the following things in such scenarios:
1. You need to make sure you are using a reliable and full compliant encoder on the side of the source;
1. Or if you also accept data from a non-trusted source, even a 'strict' decoder is inadequate. You may need extra validation rules to verify the source. For example, a user may send totally compliant `[5,2]` even though you expect `[5,0,2]`.
In both cases, a liberal parser will do nothing harmful to your application.
The reason of accepting something like `[5,,2]` is that:
1. A careless user or an encoder may repeat a comma (such as by pressing the key too long :-), which is harmless;
1. The comma is actually redundant syntactically, if two adjacent entities are recognized.
I know some users may be FUD in front of a liberal parser, but as I mentioned above, it's harmless and is allowed in RFC4627 (actually the author of RFC4627 adopts this feature in the reference implementation).
Please feel free to leave a comment or post in the discussion group if you have further concerns. Thanks.

341
EncodingExamples.md Normal file
View File

@@ -0,0 +1,341 @@
#### Example 1-1 - Encode a JSON object ####
```
//import org.json.simple.JSONObject;
JSONObject obj=new JSONObject();
obj.put("name","foo");
obj.put("num",new Integer(100));
obj.put("balance",new Double(1000.21));
obj.put("is_vip",new Boolean(true));
obj.put("nickname",null);
System.out.print(obj);
```
> Result: {"balance":1000.21,"num":100,"nickname":null,"is\_vip":true,"name":"foo"}
> JSONObject is subclass of java.util.HashMap. No ordering is provided. If you need strict ordering of elements use JSONValue.toJSONString( map ) method with ordered map implementation such as java.util.LinkedHashMap (see example 1-3).
> > Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information.
#### Example 1-2 - Encode a JSON object - Streaming ####
```
//import org.json.simple.JSONObject;
JSONObject obj=new JSONObject();
obj.put("name","foo");
obj.put("num",new Integer(100));
obj.put("balance",new Double(1000.21));
obj.put("is_vip",new Boolean(true));
obj.put("nickname",null);
StringWriter out = new StringWriter();
obj.writeJSONString(out);
String jsonText = out.toString();
System.out.print(jsonText);
```
> Result: {"balance":1000.21,"num":100,"nickname":null,"is\_vip":true,"name":"foo"}
> JSONObject is subclass of java.util.HashMap. No ordering is provided. If you need strict ordering of elements use JSONValue.toJSONString( map ) method with ordered map implementation such as java.util.LinkedHashMap (see example 1-3).
> Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information.
#### Example 1-3 - Encode a JSON object - Using Map ####
```
//import java.util.LinkedHashMap;
//import java.util.Map;
//import org.json.simple.JSONValue;
Map obj=new LinkedHashMap();
obj.put("name","foo");
obj.put("num",new Integer(100));
obj.put("balance",new Double(1000.21));
obj.put("is_vip",new Boolean(true));
obj.put("nickname",null);
String jsonText = JSONValue.toJSONString(obj);
System.out.print(jsonText);
```
> Result: {"name":"foo","num":100,"balance":1000.21,"is\_vip":true,"nickname":null}
> Now the order of the object entries is preserved, which is different from example 1-1.
> Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information.
#### Example 1-4 - Encode a JSON object - Using Map and streaming ####
```
//import java.util.LinkedHashMap;
//import java.util.Map;
//import org.json.simple.JSONValue;
Map obj=new LinkedHashMap();
obj.put("name","foo");
obj.put("num",new Integer(100));
obj.put("balance",new Double(1000.21));
obj.put("is_vip",new Boolean(true));
obj.put("nickname",null);
StringWriter out = new StringWriter();
JSONValue.writeJSONString(obj, out);
String jsonText = out.toString();
System.out.print(jsonText);
```
> Result: {"name":"foo","num":100,"balance":1000.21,"is\_vip":true,"nickname":null}
> Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information.
#### Example 2-1 - Encode a JSON array ####
```
//import org.json.simple.JSONArray;
JSONArray list = new JSONArray();
list.add("foo");
list.add(new Integer(100));
list.add(new Double(1000.21));
list.add(new Boolean(true));
list.add(null);
System.out.print(list);
```
> Result: ["foo",100,1000.21,true,null]
#### Example 2-2 - Encode a JSON array - Streaming ####
```
//import org.json.simple.JSONArray;
JSONArray list = new JSONArray();
list.add("foo");
list.add(new Integer(100));
list.add(new Double(1000.21));
list.add(new Boolean(true));
list.add(null);
StringWriter out = new StringWriter();
list.writeJSONString(out);
String jsonText = out.toString();
System.out.print(jsonText);
```
> Result: ["foo",100,1000.21,true,null]
> Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information.
#### Example 2-3 - Encode a JSON array - Using List ####
```
//import org.json.simple.JSONValue;
LinkedList list = new LinkedList();
list.add("foo");
list.add(new Integer(100));
list.add(new Double(1000.21));
list.add(new Boolean(true));
list.add(null);
String jsonText = JSONValue.toJSONString(list);
System.out.print(jsonText);
```
> Result: ["foo",100,1000.21,true,null]
> Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information.
#### Example 2-4 - Encode a JSON array - Using List and streaming ####
```
//import org.json.simple.JSONValue;
LinkedList list = new LinkedList();
list.add("foo");
list.add(new Integer(100));
list.add(new Double(1000.21));
list.add(new Boolean(true));
list.add(null);
StringWriter out = new StringWriter();
JSONValue.writeJSONString(list, out);
String jsonText = out.toString();
System.out.print(jsonText);
```
> Result: ["foo",100,1000.21,true,null]
> Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information.
#### Example 3 - Merge two JSON objects ####
```
//import org.json.simple.JSONObject;
JSONObject obj1 = new JSONObject();
obj1.put("name","foo");
obj1.put("num",new Integer(100));
obj1.put("balance",new Double(1000.21));
JSONObject obj2 = new JSONObject();
obj2.put("is_vip",new Boolean(true));
obj2.put("nickname",null);
obj2.putAll(obj1);
System.out.print(obj2);
```
> Result: {"balance":1000.21,"num":100,"nickname":null,"is\_vip":true,"name":"foo"}, the same as the one of Example 1.
#### Example 4 - Merge two JSON arrays ####
```
JSONArray list1 = new JSONArray();
list1.add("foo");
list1.add(new Integer(100));
list1.add(new Double(1000.21));
JSONArray list2 = new JSONArray();
list2.add(new Boolean(true));
list2.add(null);
list2.addAll(list1);
System.out.print(list2);
```
> Result: [true,null,"foo",100,1000.21], the order of which is different from the one of Example 2.
#### Example 5-1 - Combination of JSON primitives, JSON object and JSON arrays ####
```
JSONArray list1 = new JSONArray();
list1.add("foo");
list1.add(new Integer(100));
list1.add(new Double(1000.21));
JSONArray list2 = new JSONArray();
list2.add(new Boolean(true));
list2.add(null);
JSONObject obj = new JSONObject();
obj.put("name","foo");
obj.put("num",new Integer(100));
obj.put("balance",new Double(1000.21));
obj.put("is_vip",new Boolean(true));
obj.put("nickname",null);
obj.put("list1", list1);
obj.put("list2", list2);
System.out.println(obj);
```
> Result: {"balance":1000.21,"list2":[true,null],"num":100,"list1":["foo",100,1000.21],"nickname":null,"is\_vip":true,"name":"foo"}
#### Example 5-2 - Combination of JSON primitives, Map and List ####
```
Map m1 = new LinkedHashMap();
Map m2 = new HashMap();
List l1 = new LinkedList();
m1.put("k11","v11");
m1.put("k12","v12");
m1.put("k13", "v13");
m2.put("k21","v21");
m2.put("k22","v22");
m2.put("k23","v23");
l1.add(m1);
l1.add(m2);
String jsonString = JSONValue.toJSONString(l1);
System.out.println(jsonString);
```
> Result: [{"k11":"v11","k12":"v12","k13":"v13"},{"k22":"v22","k21":"v21","k23":"v23"}]
#### Example 5-3 - Combination of JSON primitives, JSONObject, Map and List, and streaming ####
```
StringWriter out = new StringWriter();
JSONObject obj = new JSONObject();
LinkedHashMap m1 = new LinkedHashMap();
LinkedList l1 = new LinkedList();
obj.put("k1", "v1");
obj.put("k2", m1);
obj.put("k3", l1);
m1.put("mk1", "mv1");
l1.add("lv1");
l1.add("lv2");
m1.put("mk2", l1);
obj.writeJSONString(out);
System.out.println("jsonString:");
System.out.println(out.toString());
String jsonString = obj.toJSONString();
System.out.println(jsonString);
```
> Result:
```
jsonString:
{"k3":["lv1","lv2"],"k1":"v1","k2":{"mk1":"mv1","mk2":["lv1","lv2"]}}
{"k3":["lv1","lv2"],"k1":"v1","k2":{"mk1":"mv1","mk2":["lv1","lv2"]}}
```
#### Example 6-1 - Customize JSON outputs ####
```
/*class User implements JSONAware{
private int id;
private String name;
private String password;
public User(int id, String name, String password){
this.id = id;
this.name = name;
this.password = password;
}
public String toJSONString(){
StringBuffer sb = new StringBuffer();
sb.append("{");
sb.append(JSONObject.escape("userName"));
sb.append(":");
sb.append("\"" + JSONObject.escape(name) + "\"");
sb.append(",");
sb.append(JSONObject.escape("ID"));
sb.append(":");
sb.append(id);
sb.append("}");
return sb.toString();
}
}*/
JSONArray users = new JSONArray();
users.add(new User(123,"foo1", "secret1"));
users.add(new User(124,"foo2", "secret2"));
users.add(new User(125,"\"foo2\"", "secret2"));
System.out.println(users);
```
> Result: [{userName:"foo1",ID:123},{userName:"foo2",ID:124},{userName:"\"foo2\"",ID:125}]
> User.toJSONString() seems to be a bit complicated. The purpose is to demonstrate the usage of JSONObject.escape(). It can be simpler:
```
public String toJSONString(){
JSONObject obj = new JSONObject();
obj.put("userName", name);
obj.put("ID", new Integer(id));
return obj.toString();
}
```
> Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information. (Note: If you are using version 1.0.2 or earlier, you need to override Object.toString() of your bean to get customized output.)
#### Example 6-2 - Customize JSON outputs - Streaming ####
```
/*class User implements JSONStreamAware{
private int id;
private String name;
private String password;
public User(int id, String name, String password){
this.id = id;
this.name = name;
this.password = password;
}
public void writeJSONString (Writer out) throws IOException{
LinkedHashMap obj = new LinkedHashMap();
obj.put("userName", name);
obj.put("ID", new Integer(id));
JSONValue.writeJSONString(obj, out);
}
}*/
JSONArray users = new JSONArray();
users.add(new User(123,"foo1", "secret1"));
users.add(new User(124,"foo2", "secret2"));
users.add(new User(125,"\"foo2\"", "secret2"));
StringWriter out = new StringWriter();
users.writeJSONString(out);
System.out.println(out.toString());
```
> Result: [{"userName":"foo1","ID":123},{"userName":"foo2","ID":124},{"userName":"\"foo2\"","ID":125}]
> Please note that you don't have to implement JSONStreamAware to support streaming output of your bean, you can only implement JSONAware instead of JSONStreamAware. In the latter case, JSONAware.toString() is called and the result is written to the output stream. You can implement JSONStreamAware for better performance. If a class implements both JSONStreamAware and JSONAware, JSONStreamAware is given precedence while streaming. Please refer [Mapping Between JSON and Java Entities](MappingBetweenJSONAndJavaEntities.md) for more information.

15
EscapingExamples.md Normal file
View File

@@ -0,0 +1,15 @@
#### Escaping text that contains special characters ####
JSONObject.escape() escapes quotes,\, /, \r, \n, \b, \f, \t and other control characters. It can be used to escape JavaScript codes.
```
String s = "\"foo\" is not \"bar\". specials: \b\r\n\f\t\\/";
s = JSONObject.escape(s);
System.out.println(s);
```
Result:
```
\"foo\" is not \"bar\". specials: \b\r\n\f\t\\\/
```

14
JSONSimpleInCentralMavenRepository.md Normal file
View File

@@ -0,0 +1,14 @@
Maven repository URL:
http://repo1.maven.org/maven2/
GroupId:
com.googlecode.json-simple
ArtifactId:
json-simple
Current version:
1.1
Here's the POM:
[json-simple-1.1.pom](http://repo1.maven.org/maven2/com/googlecode/json-simple/json-simple/1.1/json-simple-1.1.pom)

67
JSPAndAJAXExamples.md Normal file
View File

@@ -0,0 +1,67 @@
#### Example 1 - Server side JSP encoding ####
service.jsp:
```
<%@page contentType="text/html; charset=UTF-8"%>
<%@page import="org.json.simple.JSONObject"%>
<%
JSONObject obj=new JSONObject();
obj.put("name","foo");
obj.put("num",new Integer(100));
obj.put("balance",new Double(1000.21));
obj.put("is_vip",new Boolean(true));
obj.put("nickname",null);
out.print(obj);
out.flush();
%>
```
Please note that you need to place [json\_simple-1.1.jar](http://json-simple.googlecode.com/files/json_simple-1.1.jar) in WEB-INF/lib before running the JSP. Then the client side will get the resulting JSON text.
#### Example 2 - Client side XMLHttpRequest ####
client.html:
```
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<script type="text/javascript">
function createXMLHttpRequest(){
// See http://en.wikipedia.org/wiki/XMLHttpRequest
// Provide the XMLHttpRequest class for IE 5.x-6.x:
if( typeof XMLHttpRequest == "undefined" ) XMLHttpRequest = function() {
try { return new ActiveXObject("Msxml2.XMLHTTP.6.0") } catch(e) {}
try { return new ActiveXObject("Msxml2.XMLHTTP.3.0") } catch(e) {}
try { return new ActiveXObject("Msxml2.XMLHTTP") } catch(e) {}
try { return new ActiveXObject("Microsoft.XMLHTTP") } catch(e) {}
throw new Error( "This browser does not support XMLHttpRequest." )
};
return new XMLHttpRequest();
}
var AJAX = createXMLHttpRequest();
function handler() {
if(AJAX.readyState == 4 && AJAX.status == 200) {
var json = eval('(' + AJAX.responseText +')');
alert('Success. Result: name => ' + json.name + ',' + 'balance => ' + json.balance);
}else if (AJAX.readyState == 4 && AJAX.status != 200) {
alert('Something went wrong...');
}
}
function show(){
AJAX.onreadystatechange = handler;
AJAX.open("GET", "service.jsp");
AJAX.send("");
};
</script>
<body>
<a href="#" onclick="javascript:show();"> Click here to get JSON data from the server side</a>
</html>
```
Please place client.html and service.jsp (see [Example 1](http://code.google.com/p/json-simple/wiki/JSPAndAJAXExamples#Example_1_-_Server_side_JSP_encoding)) in the same directory and then open client.html in IE or Firefox, click the link and you'll get result.

1
Lexer.md Normal file
View File

@@ -0,0 +1 @@
The lexer file [json.lex](http://code.google.com/p/json-simple/source/browse/trunk/doc/json.lex) locates in directory doc of the source tree. JSON.simple uses [JFlex](http://jflex.de/) to generate src/org/json/simple/parser/Yylex.java from this lexer file.

10
MappingBetweenJSONAndJavaEntities.md Normal file
View File

@@ -0,0 +1,10 @@
| **JSON** | **Java** |
|:---------|:---------|
| string | java.lang.String |
| number | java.lang.Number |
| true|false | java.lang.Boolean |
| null | null |
| array | java.util.List |
| object | java.util.Map |
JSON.simple maps entities from the left side to the right side while decoding or parsing, and maps entities from the right to the left while encoding. While decoding, default concrete class of java.util.List is org.json.simple.JSONArray and default concrete class of java.util.Map is org.json.simple.JSONObject. While encoding, other classes that are not listed on the right side of the table need to implement [JSONAware](http://code.google.com/p/json-simple/source/browse/trunk/src/org/json/simple/JSONAware.java) or [JSONStreamAware](http://code.google.com/p/json-simple/source/browse/trunk/src/org/json/simple/JSONStreamAware.java) (streaming only) to [customize](http://code.google.com/p/json-simple/wiki/EncodingExamples#Example_6-1_-_Customize_JSON_outputs) JSON outputs. In such cases, JSON.simple calls JSONAware.toJSONString() or JSONStreamAware.writeJSONString() to determine the resulting JSON text.

27
PerformanceTesting.md Normal file
View File

@@ -0,0 +1,27 @@
#### Introduction ####
JSON.simple uses [json-test-suite](http://code.google.com/p/json-test-suite/) to do performance testing. This is a simple performance testing against the reference implementation of JSON.org in a very simple scenario. It does not cover all aspects of applications in the real world. Its purpose is to provide a reference point to the user.
#### Steps ####
1. Download the [latest json-test-suite package](http://code.google.com/p/json-test-suite/downloads/list) from the home page of json-test-suite
1. Unzip and run the following command in the directory of the package:
```
ant -f test.xml perf
```
1. You may need to wait for a few minutes and then check the results from the following files:
```
TEST-org.json.test.perf.SimpleTest.txt
```
#### Results ####
The following is an arbitrarily selected result of ones generated by the above command. The millisecond value after each parser is measured by the time needed by parsing and retrieving the desired value from the sample data. The length of the [sample data](http://json-test-suite.googlecode.com/files/sample.zip) is about 620K characters (more precisely, UTF-16 code units) and the value '6.908319653520691E8' is a randomly generated value used for validating of the parsing result.
```
==sample==
len:621807
org.json.JSONObject :: 103.1 ms 6.908319653520691E8
org.json.simple.JSONParser :: 14.1 ms 6.908319653520691E8
org.json.simple.JSONParser with ContentHandler :: 5.5 ms 6.908319653520691E8
```
#### How does it work? ####
Please refer [SimpleTest.java](http://code.google.com/p/json-test-suite/source/browse/trunk/src_perf/org/json/test/perf/SimpleTest.java) for details. You can also test JSON.simple against other libraries by removing the comment tags of SimpleTest.java. You may need to put their jar files and dependencies in directory 'lib' before running the command above.

116
ProjectHome.md Normal file
View File

@@ -0,0 +1,116 @@
### Overview ###
JSON.simple is a simple Java toolkit for JSON. You can use JSON.simple to encode or decode JSON text.
### Features ###
* Full compliance with [JSON specification](http://www.ietf.org/rfc/rfc4627.txt) (RFC4627) and reliable (see [compliance testing](ComplianceTesting.md))
* Provides multiple functionalities such as encode, decode/parse and escape JSON text while keeping the library lightweight
* Flexible, simple and easy to use by reusing Map and List interfaces
* Supports streaming output of JSON text
* Stoppable SAX-like interface for streaming input of JSON text (learn [more](http://code.google.com/p/json-simple/wiki/DecodingExamples#Example_5_-_Stoppable_SAX-like_content_handler))
* Heap based parser
* High performance (see [performance testing](PerformanceTesting.md))
* No dependency on external libraries
* Both of the source code and the binary are JDK1.2 compatible
### Getting Started ###
Note: You need to put the latest [json-simple-1.1.1.jar](http://json-simple.googlecode.com/files/json-simple-1.1.1.jar) in your CLASSPATH before compiling and running the example codes.
* [Encoding Examples](EncodingExamples.md)
* [Decoding Examples](DecodingExamples.md)
* [Escaping Examples](EscapingExamples.md)
* [JSP and AJAX Examples](JSPAndAJAXExamples.md)
### Mapping Between JSON and Java Entities ###
| **JSON** | **Java** |
|:---------|:---------|
| string | java.lang.String |
| number | java.lang.Number |
| true|false | java.lang.Boolean |
| null | null |
| array | java.util.List |
| object | java.util.Map |
JSON.simple maps entities from the left side to the right side while decoding or parsing, and maps entities from the right to the left while encoding. While decoding, default concrete class of java.util.List is org.json.simple.JSONArray and default concrete class of java.util.Map is org.json.simple.JSONObject. While encoding, other classes that are not listed on the right side of the table need to implement [JSONAware](http://code.google.com/p/json-simple/source/browse/trunk/src/org/json/simple/JSONAware.java) or [JSONStreamAware](http://code.google.com/p/json-simple/source/browse/trunk/src/org/json/simple/JSONStreamAware.java) (streaming only) to [customize](http://code.google.com/p/json-simple/wiki/EncodingExamples#Example_6-1_-_Customize_JSON_outputs) JSON outputs. In such cases, JSON.simple calls JSONAware.toJSONString() or JSONStreamAware.writeJSONString() to determine the resulting JSON text.
### Maven Repository ###
* [JSON.simple in central maven repository](JSONSimpleInCentralMavenRepository.md)
### Developer's Guide ###
* [Build With Ant](BuildWithAnt.md)
* [Build With Eclipse](BuildWithEclipse.md)
* [The JSON Lexer](Lexer.md)
### JSON.simple in Projects/Products ###
* [Vuze (Azureus)](http://azureus.sourceforge.net/)
* [Apache Cassandra](http://incubator.apache.org/cassandra/)
* [Apache Clerezza](http://incubator.apache.org/clerezza/)
* [Apache MyFaces](http://myfaces.apache.org/)
* [Apache Oozie(TM) Workflow Scheduler for Hadoop](http://incubator.apache.org/oozie/)
* [Apusic OperaMasks](http://www.operamasks.org)
* [Chartle.net](http://www.chartle.net/)
* [co-ode-owl-plugins](http://code.google.com/p/co-ode-owl-plugins/)
* [google-caja](http://code.google.com/p/google-caja/)
* [Google Chrome Developer Tools for Java](http://code.google.com/p/chromedevtools/)
* [GV](http://www.evancharlton.com/projects/gv)
* [Hula from Novell](http://developer.novell.com/wiki/index.php/Hula)
* [jmx4perl](http://search.cpan.org/~roland/jmx4perl/lib/JMX/Jmx4Perl/Manual.pod)
* [Json2Ldap](http://software.dzhuvinov.com/ldap-gateway.html)
* [Kindle3](http://www.amazon.com/Kindle-Wireless-Reader-Wifi-Graphite/dp/B002Y27P3M)
* [LabKey Server](http://www.labkey.com/)
* [Log4Ant](http://jwaresoftware.org/wiki/log4ant/home)
* [Mozilla Bespin](https://bespin.mozilla.com/)
* [MTS](http://chcr.umich.edu/mts/)
* [MUSCLE](http://muscle.berlios.de/)
* [NoiseTube](http://www.noisetube.net/)
* [NuGram Platform](http://nugram.nuecho.com/welcome)
* [PhyloWidget](http://www.phylowidget.org/)
* [Renren.com Open API](http://wiki.dev.renren.com/wiki/%E5%9C%A8%E4%BD%A0%E7%9A%84Web%E5%BA%94%E7%94%A8%E4%B8%AD%E6%98%BE%E7%A4%BA%E7%94%A8%E6%88%B7%E5%A7%93%E5%90%8D%E5%92%8C%E5%A4%B4%E5%83%8F)
* [Sonar](http://www.sonarsource.org/)
* [Teiid](http://www.jboss.org/teiid)
* [Twitter elephant-bird](https://github.com/kevinweil/elephant-bird)
* [TopQuadrant TopBraid Suite™](http://www.topquadrant.com/products/TB_Suite.html)
* [vtiger CRM Web Services Client Library](http://forge.vtiger.com/projects/vtwsclib)
* [XBrain](http://sig.biostr.washington.edu/projects/xbrain/)
* [ZK.forge](http://sourceforge.net/projects/zkforge/)
### JSON.simple in Fedora ###
* [Fedora 12, Fedora 11 and Fedora EPEL 5](https://admin.fedoraproject.org/pkgdb/packages/name/json_simple)
### JSON.simple in Ubuntu ###
* [Ubuntu Oneiric](http://packages.ubuntu.com/oneiric/libjson-simple-java)
### JSON.simple in Publications ###
* [O'Reilly - Ajax On Java](http://oreilly.com/catalog/9780596101879/)
* [Ajax development case study](http://www.tup.tsinghua.edu.cn/book/SHOWBOOK.asp?cpbh=025070-01)
* [Tutorial from webucator](http://www.webucator.com/WebDesign/JSC401.cfm)
* [A Review of 5 Java JSON Libraries (Rob@Rojotek)](http://www.rojotek.com/blog/2009/05/07/a-review-of-5-java-json-libraries/)
* [PeopleSoft PeopleTools Tips & Techniques](http://mhprofessional.com/product.php?isbn=0071664939) by Jim J. Marion
* [JSON.simple in Jim's Blog](http://jjmpsj.blogspot.com/2010/04/json-encoding-in-peoplecode.html)
* [Tutorial: Using Ext JS, Servlets, JSON, MySQL and Tomcat on Fedora](http://java.sys-con.com/node/1201109)
* [Interesting blog on JSON numeric types from Public Object](http://blog.publicobject.com/2010/04/json-javascript-and-numeric-types.html)
* [Android as SOA player](http://blogs.eteration.com/blog/?p=978)
### Next Steps ###
* Auto marshalling and unmarshalling utils for Java Beans
### Links ###
* [JSON.org](http://json.org)
* [Initial version of JSON.simple](http://json-simple.googlecode.com/files/json_simple.zip)
### About me ###
[Yidong Fang](http://www.linkedin.com/pub/yidong-fang/12/4b7/b2a)
### Acknowledgment ###
> ![http://www.yourkit.com/images/yklogo.png](http://www.yourkit.com/images/yklogo.png)<br>
YourKit is kindly supporting this open source project with its full-featured Java Profiler.<br>
YourKit, LLC is the creator of innovative and intelligent tools for profiling Java and .NET applications. Take a look at YourKit's leading software products:<br>
</li></ul><ul><li><a href='http://www.yourkit.com/java/profiler/index.jsp'>YourKit Java Profiler</a>
</li><li><a href='http://www.yourkit.com/.net/profiler/index.jsp'>YourKit .NET Profiler</a>