About
JSONator is a light-weight java library that allows the serialization and deserialization
of java objects to and from JSON.
JSONator is built to provide the basic functionality for JSON conversions
with the focus on performance, ease of use, and extensibility.
Features
- Ability to write your own JSON formats such as dates, calendars, and objects.
- Aliasing makes the JSON a little bit more pretty.
- Amazing performance. 2-10 times faster than many other similar solutions.
- The api is easy to use and self-explanatory.
- Compatible with the Javascript library JSONUtils (json.org)
Limitations
- Developed and tested with Java 1.5. Unknown behavior with previous versions of java.
- For deserialization, the SecurityManager must allow access to private class members through reflection. This is allowed by default and should not effect the majority of users.
News
Getting Started
Quick Start
We will start with a simple Person class to serialize into a JSON:
package test.example1;
public class Person {
private String firstName;
private String lastName;
private int age;
private boolean male;
//setters/getters
...
}
Instantiate the JSONator and serialize the Person class:
Person person = new Person();
person.setFirstName("John");
person.setLastName("Doe");
person.setMale(true);
person.setAge(21);
//instantiate JSONator and serialize person
Json json = new Json();
System.out.println( json.toJson( person ) );
The result output of the JSONator is:
{"test.example1.Person":{
"age":21,
"male":true,
"firstName":"John",
"lastName":"Doe"
}}
Now lets deserialize the JSON back into a java object:
String jsonString = "{\"test.example1.Person\":{\"age\":21,\"male\":true,\"firstName\":\"John\",\"lastName\":\"Doe\"}}";
Person p = (Person) json.fromJson(jsonString);
You might have noticed that the class fully qualified name is
used, "test.example1.Person." For deserialization, the JSONator has
to know where the class is located. If you don't want the fully qualified name's in your JSON,
use an alias:
//instantiate JSONator and serialize person
Json json = new Json();
json.addClassAlias("Person", Person.class);
System.out.println(json.toJson( person ));
The result JSON after specifying an alias is:
{"Person":{
"age":21,
"male":true,
"firstName":"John",
"lastName":"Doe"
}}
Documentation
Alias (top↑)
Users often question why we display the fully qualified name of classes when we serialize:
{"com.foo.Account": { ... }}
{"com.foo.AccountPlanHistory": { ... }}
{"com.foo.Plan": { ... }}
{"com.foo.PlanTerms": { ... }}
{"com.foo.User": { ... }}
{"com.foo.Transaction": { ... }}
The answer is when we deserialize, we need to know where that class is in the package structure. If we don't find it, then we can't instantiate and deserialize. However, there is a way to avoid the fully qualified name by using alias's.
Example:
json = new Json();
//Keep in alphabetical order!
json.addClassAlias("Account", Account.class);
json.addClassAlias("AccountPlanHistory", AccountPlanHistory.class);
json.addClassAlias("Plan", Plan.class);
json.addClassAlias("PlanTerms", PlanTerms.class);
json.addClassAlias("User", User.class);
json.addClassAlias("Transaction", Transaction.class);
{"Account": { ... }}
{"AccountPlanHistory": { ... }}
{"Plan": { ... }}
{"PlanTerms": { ... }}
{"User": { ... }}
{"Transaction": { ... }}
By specifying the alias and the class, JSONater is able to convert an alias to the fully quailifed name during deserialization.
Converter (top↑)
Unavailable this release.
JSONator Helper Class (top↑)
You can improve performance and conserve memory by instantiating JSONator only once during runtime. This can be accomplished with a singleton class. Here is an example you can use for your own project:
public class JsonHelper {
private static JsonHelper instance = null;
private Json json = null;
/**
* Private constructor suppresses generation of a (public)
* default constructor
*/
private JsonHelper() {
json = new Json();
//Keep in alphabetical order!
json.addClassAlias("Account", Account.class);
json.addClassAlias("AccountPlanHistory", AccountPlanHistory.class);
json.addClassAlias("Plan", Plan.class);
json.addClassAlias("PlanTerms", PlanTerms.class);
json.addClassAlias("User", User.class);
json.addClassAlias("Transaction", Transaction.class);
}
public static JsonHelper getInstance() {
if(instance == null) {
instance = new JsonHelper();
}
return instance;
}
public String toJson(Object obj) throws JsonConversionException{
return json.toJson(obj);
}
public Object fromJson(String str) throws JsonConversionException{
return json.fromJson(str);
}
}
Circular References (top↑)
An example of a circular reference is an object that has a reference to its self:
class Person{
String name;
Person favoritePerson; //this person enters himself
}
Currently not supported.
Arrays (top↑)
Examples:
one item: {"fooArray":["A"]}
mulitple items: {"fooArray":["A","B","C"]}
no items in Array[4]: {"fooArray":[null, null, null, null]}
null: {"fooArray":null}
Collections (top↑)
Examples:
one item: {"collection":[1]}
multiple items:{"collection":[1,2,3,4,5]}
multiple items:{"collection":[{Transaction:{....} }, {Transaction:{....} } ] }
Heterogeneous: {"collection":[{Proposal:{....} }, {Transaction:{....} } ] }
no items: {"collection":[]}
null: {"collection":null}
For heterogeneous lists, anonymous obect elements are NOT allowed.
Maps (top↑)
Examples:
multiple items: {"foomap":{"key" :"Refi" , "key2":"Purchase"}}
one item: {"foomap":{"key" :"Refi"}}
no items: {"foomap":{}}
null: {"foomap":null}
Numbers (top↑)
JSONator can serialize/deseialize the following numerical types:
- BigDecimal
- BigInteger
- Byte
- Doube
- Float
- Integer
- Long
Examples:
"foocost":454.444
"foocost":null
Booleans (top↑)
Null's and empty strings are defaulted to false.
Examples:
"foobool":true
"foobool":false
Characters (top↑)
JSON does not allow single quotes('), so we resorted to double quotes for character types. Also, null's are translated
to the character '\0' upon deserialization.
Examples:
"foochar":"c"
"foochar":null
Dates/Calendars (top↑)
Examples:
{"foodate": {"Date":{"time":34543345, "timezone":"America/Los_Angeles"}}}
{"foodate": null}
If you would like to change this format, write your own converter!
Enum's (top↑)
The enum constant is used as the value. Of course, nulls are not allowed for enums.
Examples:
"fooenum":"INACTIVE"
Java Classes(top↑)
Examples:
no members: {"test.Person": {}}
members: {"test.Person":{"ssn":"1234567","childern":"1","male":true}}
null object:{"test.Person":null}
Strings/String Buffers(top↑)
Examples:
"fooField":"this is the buffer contents"
"fooField":null
URL's(top↑)
Examples:
"fooUrl":"url"
"fooUrl":null
FAQ
Getting and IllegalAccessException error when deserializing.
The class being accessed during deserialization is probably not public.