Advanced Features

Transforming key names

The JSON spec states that an object key is a String and
A string is a collection of zero or more Unicode characters, wrapped in double quotes, using backslash escapes. A character is represented as a single character string. A string is very much like a C or Java string.
This means that you may have a valid JSON key but and invalid Java identifier when transforming form JSON to Java. In order to avoid this problem, Json-lib defines a set of helpers of type JavaIdentifierTransformer that will handle the following cases:
  • JavaIdentifierTransformer.NOOP - will perform no transformation.
  • JavaIdentifierTransformer.STRICT - will throw JSONException if a non JavaIdentifier character is found.
  • JavaIdentifierTransformer.CAMEL_CASE - will use non JavaIdentifier and whitespace characters as word boundaries, capitalizing the first char of a new word.
  • JavaIdentifierTransformer.WHITESPACE - will trim all whitespace and non JavaIdentifier characters from the input string.
  • JavaIdentifierTransformer.UNDERSCORE - will transform all whitespace and non JavaIdentifier characters to '_'.
You may also create and register your own JavaIdentifierTransformers using JsonConfig.setJavaIdentifierTransformer()

Build events

You may recieve events while building an object with the JSONSerializer or the static builder fromObject of JSONObject&JSONArray, all you have to do is enabled event triggering on JsonConfig. The following is a list of events generated by the build process: start/end (object), start/end (array), propertySet( object), elementAdd (array), warning, error.

Skipping transient fields

When building a JSONObject with fromObject or with the JSONSerializer you may skip all transient fields of the source bean, provided that the name of the property returned from the PropertyDescriptor matches the name of the field, meaning that this option will not work if you have a BeanInfo that changes the name of a read method or provides a synthetic property.

Filtering properties

When serializing to JSON there may be some times where you would like to exclude some properties from being processed, the current exclusion mechanism matches the property name to a list of Strings, but what if you would like to filter out all properties that match a regex or extend a particular class? PropertyFilter will help you attain that goal with ease, and what's more, it will also work when converting back to Java. Here is an example filter that will exclude all properties that are a Number when serializing to JSON:

This is another filter example, this time converting back to Java, it will filter out any property named 'bool' or 'integer':

Please review the net.sf.json.filters package to find out more about default filters and composite filters.

Selecting the proper JsonBeanProcessor

JsonBeanProcessors are maped to classes but sometimes you'll like that some subclasses may be mapped to the same processor or perhaps you are serializing a recently hydrated instance coming from a database with Hibernate, because the instance's class is not exactly the one you expect (it actually is a cglib proxy class) the default class matching mechanism will not work. In order to solve these problems you may register a JsonBeanProcessorMatcher that will take care of the job of selecting the proper JsonBeanProcessor, just as you need it.

Instantiating non JavaBeans

When serializing from JSON to Java you have to keep one rule in mind, the target class must follow the JavaBeans convention of a no-args constructor but sometimes it won't be possible, as it is the case of java.sql.Timestamp. Json-lib has an option to overcome this "restriction", just register a NewBeanInstanceStrategy into JsonConfig and you are in business.

Changing the default value of a null reference

The JSON spec states that null values can only be assigned to objects, but in Java you can have null assigned to any reference, when Json-lib encounters a null reference it follows these rules
  • value is 0 if the reference is a number (wrapper or primitive)
  • value is '' if the reference is a String, Character or char
  • value is [] if the reference is a Collection or array
But sometimes it would be useful to change that rule, for example instead of assigning 'null' to a null reference of MyBean you would like to assign '{ "empty": true }' because that's what your client code expects. DefaultValueProcessor will let you change that rules, along with DefaultValueProcessorMatcher which will let you select the most appropriate processor, as it is done with JsonBeanProcessors.

Setting properties on beans

JSONObject knows how to set values on a Map or bean when transforming JSON to Java. For those rare ocasions wher you would want to handle the set by yourself you can register a PropertySetStrategy through JsonConfig. This feature comes in handy with map backed beans that are neither a Map nor a DynaBean.