flexjson
Class JSONSerializer

java.lang.Object
  flexjson.JSONSerializer

public class JSONSerializer
extends java.lang.Object

JSONSerializer is the main class for performing serialization of Java objects to JSON. JSONSerializer by default performs a shallow serialization. While this might seem strange there is a method to this madness. Shallow serialization allows the developer to control what is serialized out of the object graph. This helps with performance, but more importantly makes good OO possible, fixes the circular reference problem, and doesn't require boiler plate translation code. You don't have to change your object model to make JSON work so it reduces your work load, and keeps you DRY.

Let's go through a simple example:

    JSONSerializer serializer = new JSONSerializer();
    return serializer.serialize( person );

 

What this statement does is output the json from the instance of person. So the JSON we might see for this could look like:

    { "class": "com.mysite.Person",
      "firstname": "Charlie",
      "lastname": "Rose",
      "age", 23
      "birthplace": "Big Sky, Montanna"
    }

 

In this case it's look like it's pretty standard stuff. But, let's say Person had many hobbies (i.e. Person.hobbies is a java.util.List). In this case if we executed the code above we'd still get the same output. This is a very important feature of flexjson, and that is any instance variable that is a Collection, Map, or Object reference won't be serialized by default. This is what gives flexjson the shallow serialization.

How would we include the hobbies field? Using the include(java.lang.String...) method allows us to include these fields in the serialization process. Here is how we'd do that:

    return new JSONSerializer().include("hobbies").serialize( person );

 

That would produce output like:

    { "class": "com.mysite.Person",
      "firstname": "Charlie",
      "lastname": "Rose",
      "age", 23
      "birthplace": "Big Sky, Montanna",
      "hobbies", [
          "poker",
          "snowboarding",
          "kite surfing",
          "bull riding"
      ]
    }

 

If the hobbies field contained objects, say Hobby instances, then a shallow copy of those objects would be performed. Let's go further and say hobbies had a List of all the people who enjoyed this hobby. This would create a circular reference between Person and Hobby. Since the shallow copy is being performed on Hobby JSONSerialize won't serialize the people field when serializing Hobby instances thus breaking the chain of circular references.

But, for the sake of argument and illustration let's say we wanted to send the people field in Hobby. We can do the following:

    return new JSONSerializer().include("hobbies.people").serialize( person );

 

JSONSerializer is smart enough to know that you want hobbies field included and the people field inside hobbies' instances too. The dot notation allows you do traverse the object graph specifying instance fields. But, remember a shallow copy will stop the code from getting into an infinte loop.

You can also use the exclude method to exclude fields that would be included. Say we have a User object. It would be a serious security risk if we sent the password over the network. We can use the exclude method to prevent the password field from being sent.

   return new JSONSerialize().exclude("password").serialize(user);

 

JSONSerializer will also pay attention to any method or field annotated by JSON. You can include and exclude fields permenantly using the annotation. This is good like in the case of User.password which should never ever be sent through JSON. However, fields like hobbies or favoriteMovies depends on the situation so it's best NOT to annotate those fields, and use the include(java.lang.String...) method.

In a shallow copy only these types of instance fields will be sent: String, Date, Number, Boolean, Character, Enum, Object and null. Subclasses of Object will be serialized except for Collection or Arrays. Anything that would cause a N objects would not be sent. All types will be excluded by default. Fields marked static or transient are not serialized.

Includes and excludes can include wildcards. Wildcards allow you to do things like exclude all class attributes. For example *.class would remove the class attribute that all objects have when serializing. A open ended wildcard like * would cause deep serialization to take place. Be careful with that one. Although you can limit it's depth with an exclude like *.foo. The order of evaluation of includes and excludes is the order in which you called their functions. First call to those functions will cause those expressions to be evaluated first. The first expression to match a path that action will be taken thus short circuiting all other expressions defined later.

Transforers are a new addition that allow you to modify the values that are being serialized. This allows you to create different output for certain conditions. This is very important in web applications. Say you are saving your text to the DB that could contain < and >. If you plan to add that content to your HTML page you'll need to escape those characters. Transformers allow you to do this. Flexjson ships with a simple HTML encoder HTMLEncoder. Transformers are specified in dot notation just like include and exclude methods, but it doesn't support wildcards.

JSONSerializer is safe to use the serialize() methods from two seperate threads. It is NOT safe to use combination of include(String[]) transform(Transformer, String[]), or exclude(String[]) from multiple threads at the same time. It is also NOT safe to use serialize(String, Object) and include/exclude/transform from multiple threads. The reason for not making them more thread safe is to boost performance. Typical use case won't call for two threads to modify the JSONSerializer at the same type it's trying to serialize.

Field Summary

static char[]

HEX

Constructor Summary

JSONSerializer()
Create a serializer instance.

Method Summary

java.lang.String	deepSerialize(java.lang.Object target) This performs a deep serialization of the target instance.
java.lang.String	deepSerialize(java.lang.String rootName, java.lang.Object target) This performs a deep serialization of target instance.
JSONSerializer	exclude(java.lang.String... fields) This takes in a dot expression representing fields to exclude when serialize method is called.
java.util.List<PathExpression>	getExcludes() Return the fields excluded from serialization.
java.util.List<PathExpression>	getIncludes() Return the fields included in serialization.
JSONSerializer	include(java.lang.String... fields) This takes in a dot expression representing fields to include when serialize method is called.
java.lang.String	prettyPrint(java.lang.Object target) This will do a serialize the target and pretty print the output so it's easier to read.
java.lang.String	prettyPrint(java.lang.String rootName, java.lang.Object target) This will do a serialize with root name and pretty print the output so it's easier to read.
java.lang.String	serialize(java.lang.Object target) This performs a shallow serialization of the target instance.
java.lang.String	serialize(java.lang.String rootName, java.lang.Object target) This performs a shallow serialization of target instance.
void	setExcludes(java.util.List fields) Sets the fields excluded in serialization.
void	setIncludes(java.util.List fields) Sets the fields included in serialization.
JSONSerializer	transform(Transformer transformer, java.lang.String... fields) This adds a Transformer used to manipulate the value of all the fields you give it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HEX

public static final char[] HEX

Constructor Detail

JSONSerializer

public JSONSerializer()

Create a serializer instance. It's unconfigured in terms of fields it should include or exclude.

Method Detail

serialize

public java.lang.String serialize(java.lang.String rootName,
                                  java.lang.Object target)

This performs a shallow serialization of target instance. It wraps the resulting JSON in a javascript object that contains a single field named rootName. This is great to use in conjunction with other libraries like EXTJS whose data models require them to be wrapped in a JSON object.

Parameters:

rootName - the name of the field to assign the resulting JSON.

target - the instance to serialize to JSON.

Returns:

the JSON object with one field named rootName and the value being the JSON of target.

serialize

public java.lang.String serialize(java.lang.Object target)

This performs a shallow serialization of the target instance.

Parameters:

target - the instance to serialize to JSON

Returns:

the JSON representing the target instance.

deepSerialize

public java.lang.String deepSerialize(java.lang.Object target)

This performs a deep serialization of the target instance. It will include all collections, maps, and arrays by default so includes are ignored except if you want to include something being excluded by an annotation. Excludes are honored. However, cycles in the target's graph are NOT followed. This means some members won't be included in the JSON if they would create a cycle. Rather than throwing an exception the cycle creating members are simply not followed.

Parameters:

target - the instance to serialize to JSON.

Returns:

the JSON representing the target instance deep serialization.

deepSerialize

public java.lang.String deepSerialize(java.lang.String rootName,
                                      java.lang.Object target)

This performs a deep serialization of target instance. It wraps the resulting JSON in a javascript object that contains a single field named rootName. This is great to use in conjunction with other libraries like EXTJS whose data models require them to be wrapped in a JSON object. See deepSerialize(Object) for more in depth explaination.

Parameters:

rootName - the name of the field to assign the resulting JSON.

target - the instance to serialize to JSON.

Returns:

the JSON object with one field named rootName and the value being the JSON of target.

exclude

public JSONSerializer exclude(java.lang.String... fields)

This takes in a dot expression representing fields to exclude when serialize method is called. You can hand it one or more fields. Example are: "password", "bankaccounts.number", "people.socialsecurity", or "people.medicalHistory". In exclude method dot notations will only exclude the final field (i.e. rightmost field). All the fields to the left of the last field will be included. In order to exclude the medicalHistory field we have to include the people field since people would've been excluded anyway since it's a Collection of Person objects. The order of evaluation is the order in which you call the exclude method. The first call to exclude will be evaluated before other calls to include or exclude. The field expressions are evaluated in order you pass to this method.

Parameters:

fields - one or more field expressions to exclude.

Returns:

this instance for method chaining.

include

public JSONSerializer include(java.lang.String... fields)

This takes in a dot expression representing fields to include when serialize method is called. You can hand it one or more fields. Examples are: "hobbies", "hobbies.people", "people.emails", or "character.inventory". When using dot notation each field between the dots will be included in the serialization process. The order of evaluation is the order in which you call the include method. The first call to include will be evaluated before other calls to include or exclude. The field expressions are evaluated in order you pass to this method.

Parameters:

fields - one or more field expressions to include.

Returns:

this instance for method chaining.

transform

public JSONSerializer transform(Transformer transformer,
                                java.lang.String... fields)

This adds a Transformer used to manipulate the value of all the fields you give it. Fields can be in dot notation just like include(java.lang.String...) and exclude(java.lang.String...) methods. However, transform doesn't support wildcards. Specifying more than one field allows you to add a single instance to multiple fields. It's there for handiness. :-)

Parameters:

transformer - the instance used to transform values

fields - the paths to the fields you want to transform. They can be in dot notation.

Returns:

Hit you back with the JSONSerializer for method chain goodness.

getIncludes

public java.util.List<PathExpression> getIncludes()

Return the fields included in serialization. These fields will be in dot notation.

Returns:

A List of dot notation fields included in serialization.

getExcludes

public java.util.List<PathExpression> getExcludes()

Return the fields excluded from serialization. These fields will be in dot notation.

Returns:

A List of dot notation fields excluded from serialization.

setIncludes

public void setIncludes(java.util.List fields)

Sets the fields included in serialization. These fields must be in dot notation. This is just here so that JSONSerializer can be treated like a bean so it will integrate with Spring or other frameworks. This is not ment to be used in code use include method for that.

Parameters:

fields - the list of fields to be included for serialization. The fields arg should be a list of strings in dot notation.

setExcludes

public void setExcludes(java.util.List fields)

Sets the fields excluded in serialization. These fields must be in dot notation. This is just here so that JSONSerializer can be treated like a bean so it will integrate with Spring or other frameworks. This is not ment to be used in code use exclude method for that.

Parameters:

fields - the list of fields to be excluded for serialization. The fields arg should be a list of strings in dot notation.

prettyPrint

public java.lang.String prettyPrint(java.lang.Object target)

This will do a serialize the target and pretty print the output so it's easier to read.

Parameters:

target - of the serialization.

Returns:

the serialized representation of the target in pretty print form.

prettyPrint

public java.lang.String prettyPrint(java.lang.String rootName,
                                    java.lang.Object target)

This will do a serialize with root name and pretty print the output so it's easier to read.

Parameters:

rootName - the name of the field to assign the resulting JSON.

target - of the serialization.

Returns:

the serialized representation of the target in pretty print form.