--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.chromium.sdk/lib/json_simple/README.txt Wed Dec 23 17:13:18 2009 -0800
@@ -0,0 +1,144 @@
+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>