Simple Java toolkit for JSON (JSON.simple)

==========================================

1.Why the Simple Java toolkit (also named as JSON.simple) for JSON?

  When I use JSON as the data exchange format between the AJAX client and JSP 

  for the first time, what worry me mostly is how to encode Java strings and 

  numbers correctly in the server side so the AJAX client will receive a well

  formed JSON data. When I looked into the 'JSON in Java' directory in JSON

  website,I found that wrappers to JSONObject and JSONArray can be simpler, 

  due to the simplicity of JSON itself. So I wrote the JSON.simple package.

2.Is it simple,really?

  I think so. Take an example:

  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:

  {"nickname":null,"num":100,"balance":1000.21,"is_vip":true,"name":"foo"}

  The JSONObject.toString() will escape controls and specials correctly.

3.How to use JSON.simple in JSP?

  Take an example in 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();

  %>

  So the AJAX client will get the responseText.

4.Some details about JSONObject?

  JSONObject inherits java.util.HashMap,so it don't have to worry about the 

  mapping things between keys and values. Feel free to use the Map methods 

  like get(), put(), and remove() and others. JSONObject.toString() will 

  combine key value pairs to get the JSON data string. Values will be escaped

  into JSON quote string format if it's an instance of java.lang.String. Other

  type of instance like java.lang.Number,java.lang.Boolean,null,JSONObject and

  JSONArray will NOT escape, just take their java.lang.String.valueOf() result.

  null value will be the JSON 'null' in the result.

  It's still correct if you put an instance of JSONObject or JSONArray into an 

  instance of JSONObject or JSONArray. Take the example about:

  JSONObject obj2=new JSONObject();

  obj2.put("phone","123456");

  obj2.put("zip","7890");

  obj.put("contact",obj2);

  System.out.print(obj);

  Result:

  {"nickname":null,"num":100,"contact":{"phone":"123456","zip":"7890"},"balance":1000.21,"is_vip":true,"name":"foo"}

  The method JSONObject.escape() is used to escape Java string into JSON quote 

  string. Controls and specials will be escaped correctly into \b,\f,\r,\n,\t,

  \",\\,\/,\uhhhh.

5.Some detail about JSONArray?

  org.json.simple.JSONArray inherits java.util.ArrayList. Feel free to use the

  List methods like get(),add(),remove(),iterator() and so on. The rules of 

  JSONArray.toString() is similar to JSONObject.toString(). Here's the example:

  import org.json.simple.JSONArray;

  JSONArray array=new JSONArray();

  array.add("hello");

  array.add(new Integer(123));

  array.add(new Boolean(false));

  array.add(null);

  array.add(new Double(123.45));

  array.add(obj2);//see above

  System.out.print(array);

  Result:

  ["hello",123,false,null,123.45,{"phone":"123456","zip":"7890"}]

6.What is JSONValue for?  

  org.json.simple.JSONValue is use to parse JSON data into Java Object. 

  In JSON, the topmost entity is JSON value, not the JSON object. But

  it's not necessary to wrap JSON string,boolean,number and null again,

  for the Java has already had the according classes: java.lang.String,

  java.lang.Boolean,java.lang.Number and null. The mapping is:

  JSON			Java

  ------------------------------------------------

  string      <=>  	java.lang.String 

  number      <=>	java.lang.Number

  true|false  <=>	java.lang.Boolean

  null        <=>	null

  array	      <=>	org.json.simple.JSONArray

  object      <=>       org.json.simple.JSONObject

  ------------------------------------------------

  JSONValue has only one kind of method, JSONValue.parse(), which receives

  a java.io.Reader or java.lang.String. Return type of JSONValue.parse() 

  is according to the mapping above. If the input is incorrect in syntax or

  there's exceptions during the parsing, I choose to return null, ignoring 

  the exception: I have no idea if it's a serious implementaion, but I think

  it's convenient to the user.

  Here's the example:

  String s="[0,{\"1\":{\"2\":{\"3\":{\"4\":[5,{\"6\":7}]}}}}]";

  Object obj=JSONValue.parse(s);

  JSONArray array=(JSONArray)obj;

  System.out.println(array.get(1));

  JSONObject obj2=(JSONObject)array.get(1);

  System.out.println(obj2.get("1"));

  Result:

  {"1":{"2":{"3":{"4":[5,{"6":7}]}}}}

  {"2":{"3":{"4":[5,{"6":7}]}}}

7.About the author.

  I'm a Java EE developer on Linux. 

  I'm working on web systems and information retrieval systems.

  I also develop 3D games and Flash games. 

  You can contact me through: 

  Fang Yidong<fangyidong@yahoo.com.cn>

  Fang Yidong<fangyidng@gmail.com>