json-io consists of two classes, a reader (JsonReader) and a writer (JsonWriter). There is a 3rd rigorous test class (TestJsonReaderWriter). json-io eliminates the need for using ObjectInputStream / ObjectOutputStream to serialize Java and instead uses the JSON format.

Featured on http://json.org.

json-io does not require that Java classes implement Serializable or Externalizable. It will serialize any Java object graph into JSON and retain complete graph semantics and object types. This includes supporting private fields, private inner classes (static or non-static), of any depth. It also includes handling cyclic references. Objects do not need to have public constructors to be serialized.

The JsonReader / JsonWriter code does not depend on any native or 3rd party libraries.

Format

json-io uses proper JSON format. As little type information is included in the JSON format to keep it compact as possible. When an object's class can be inferred from a field type or array type, the object's type information is left out of the stream. For example, a String[] looks like ["abc", "xyz"].

When an object's type must be emitted, it is emitted as a meta-object field "@type":"package.class" in the object. When read, this tells the JsonReader what class to instantiate.

If an object is referenced more than once, or references an object that has not yet been defined, (say A points to B, and B points to C, and C points to A), it emits a "@ref":n where 'n' is the object's integer identity (with a corresponding meta entry "@id":n defined on the referenced object).

Performance

json-io was written with performance in mind. In most cases json-io is faster than the JDK's ObjectInputStream / ObjectOutputStream. As the tests run, a log is written of the time it takes to serialize / deserialize and compares it to ObjectInputStream / ObjectOutputStream (if the static variable _debug is true in TestJsonReaderWriter).

Usage

json-io can be used directly on JSON Strings or with Java's Streams.

Example 1: String to Java object

    Object obj = JsonReader.toJava("[\"Hello, World\"]");

This will convert the JSON String to a Java Object graph. In this case, it would consist of an Object[] of one String element.

Example 2: Java object to JSON String

    Employee emp;
    // Emp fetched from database
    String json = JsonWriter.toJson(emp);

This example will convert the Employee instance to a JSON String. If the JsonReader were used on this String, it would reconstitute a Java Employee instance.

Example 3: InputStream to Java object

    JsonReader jr = new JsonReader(inputStream);
    Employee emp = (Employee) jr.readObject();

In this example, an InputStream (could be from a File, the Network, etc.) is supplying an unknown amount of JSON. The JsonReader is used to wrap the stream to parse it, and return the Java object graph it represents.

Example 4: Java Object to OutputStream

    Employee emp;
    // emp obtained from database
    JsonWriter jw = new JsonWriter(outputStream);
    jw.write(emp);
    jw.close();

In this example, a Java object is written to an output stream in JSON format.

Non-typed Usage

json-io provides the choice to use the generic "Map of Maps" representation of an object, akin to a Javascript associative array. When reading from a JSON String or InputStream of JSON, the JsonReader can be constructed like this:

    Map graph = JsonReader.toMaps(String json);

-- or --

    JsonReader jr = new JsonReader(InputStream, true);
    Map map = (Map) jr.readObject();

This will return an untyped object representation of the JSON String as a Map of Maps, where the fields are the Map keys (Strings), and the field values are the associated Map's values. In this representation: All integer value types (byte, short, int, long) are stored as java.lang.Long objects. All floating point numbers (float, double) are stored as java.lang.Double instances. Booleans are stored as java.lang.Boolean. Object associations (references to other objects) store a reference to the other Map as the value. All other values are stored as Strings.

Customization

If you want to have particular object read / write itself in a custom way in JSON, then you can add a public method void _readJson(Map map) and void _writeJson(Writer writer). If these methods are found on a class, they will be called for reading / writing the object. See the TestJsonReaderWriter for an example.

Javascript

Included is a small Javascript utility that will take a JSON output stream created by the JSON writer and substitute all @ref's for the actual pointed to object. It's a one-line call - resolveRefs(json). This will completely fix up the @ref's to point to the appropriate objects.

What's next?

Even though json-io is perfect for Java / Javascript serialization, there are other great uses for it: Debugging. Instead of doing System.out.println debugging, call JsonWriter.toJson(obj) and dump that String out. It will reveal the object in all it's glory. Take that output and paste it into a JSON lint / formatter so you can can easily read it: See http://jsonformatter.curiousconcept.com/ and http://www.jsonlint.com/

json-io can be used as the fundamental data transfer method between a Javascript / JQuery / Ajax client and a web server in a RESTful fashion. Used this way, you can create more active sites like Google's GMail, MyOtherDrive online backup, etc.

by John DeRegnaucourt